Cauldron2D.Surface (Cauldron2D v0.2.2)

Composites a grid of cells into one FrenchCurve.Raster.

Cells

:void                       nothing here
{base, overlays, tint}      a tile, what is on it in paint order, and how it is shaded

overlays is ordered bottom to top and may be empty. tint is nil or the name of a tint registered on the atlas.

base must be an art of the atlas's tile size. An overlay may be any size: one the tile's size is blended into its cell; any other stands on its cell, its bottom edge on the cell's bottom edge and centred across it, drawn over every cell and tinted with its cell's tint.

Overlays and movers are composited source-over: a half-transparent sprite on a half-transparent base leaves the result more opaque than either, not as opaque as the more opaque of the two. Over an opaque base — which most tiles are — this is the same arithmetic as a straight weighted mix.

Movers

compose/3 also takes sprites placed at arbitrary pixel offsets rather than on the grid, as [{art, {x, y}}] where {x, y} is the sprite's top-left corner in the raster's own pixel coordinates. A mover is drawn at its art's own size, over the grid and its standing overlays, in list order, and clipped to the raster's edges. blit/4 draws one onto an existing raster.

A mover may also be {art, {x, y}, tint}, or {art, {x, y}, tint, pose, flip} to draw one of the art's poses — :front, :back, :side — mirrored when flip is true, so a view that knows which way a mover faces can show it.

Labels

compose/4 also takes :labels, text drawn in Linocut.Font over everything else: [{text, {x, y}, colour}] or [{text, {x, y}, colour, opts}], positioned by the text's top-left corner in the raster's pixel coordinates, with opts of :scale (default 1) and :background, a colour filled behind the text (default none).

Volumes

compose/4 also takes :volumes, coloured regions of space as Cauldron2D.Projection.Volume describes them, seen from directly above. A volume's :at is in tiles from the grid's top-left corner, and its shape is in tiles. Each tints the grid and everything drawn on it, by how much of it a viewer looking straight down has to see through.

Caching

Each distinct cell is blended once and the result kept in the atlas's ETS table, keyed by the sprite ids of its base and overlays together with the tint name. Two art names with byte-identical rasters share one entry.

The cache outlives Cauldron2D.Atlas.install/1 when the atlas installed is the same one. Installing a changed atlas — new art, a redefined tint, a different void colour — empties it, so a tint re-registered under a name it already had takes effect rather than serving tiles as they used to look.

Summary

Types

cell()

Functions

blit(atlas, raster, art, arg)

Draw the sprite art onto raster with its top-left corner at {x, y} in pixels.

compose(atlas, rows, movers \\ [], opts \\ [])

Compose rows — a list of equal-length rows of cells — into a raster.

magnify(raster, times)

The raster times as wide and tall, every pixel repeated that many times each way; the raster itself at 1.

shade_color(atlas, rgb, tint)

Apply the tint named tint to a plain RGB colour, for renderers that draw characters.

sprite_rgba(atlas, art, scale \\ 1, at \\ 0)

One art's pixels as {rgba, width, height}, at 1 / scale of the atlas's resolution and at the frame showing at at milliseconds.

stack(beneath, above)

above composited over beneath, two rasters of the same width and height.

tile_binary(atlas, cell, scale \\ 1, at \\ 0, void \\ :opaque)

The flat RGBA binary for one cell, tile * tile * 4 bytes long, with animated arts at the frame showing at at milliseconds.

Types

cell()

@type cell() ::
  :void
  | {Cauldron2D.Atlas.art(), [Cauldron2D.Atlas.art()],
     Cauldron2D.Atlas.tint() | nil}

Functions

blit(atlas, raster, art, arg)

@spec blit(
  Cauldron2D.Atlas.name() | Cauldron2D.Atlas.t(),
  FrenchCurve.Raster.t(),
  Cauldron2D.Atlas.art(),
  {number(), number()}
) :: FrenchCurve.Raster.t()

Draw the sprite art onto raster with its top-left corner at {x, y} in pixels.

Coordinates may be fractional and are rounded; parts falling outside the raster are clipped. Returns a new raster; raster is unchanged.

compose(atlas, rows, movers \\ [], opts \\ [])

@spec compose(
  Cauldron2D.Atlas.name() | Cauldron2D.Atlas.t(),
  [[cell()]],
  [{Cauldron2D.Atlas.art(), {number(), number()}}],
  keyword()
) :: FrenchCurve.Raster.t()

Compose rows — a list of equal-length rows of cells — into a raster.

The raster is columns * tile pixels wide by length(rows) * tile tall, where columns is the length of the first row. Every row must be that same length.

movers are [{art, {x, y}}] drawn over the grid in list order, positioned by their top-left corner in the raster's pixel coordinates rather than snapped to the grid. Coordinates may be fractional and are rounded; parts falling outside the raster are clipped. Default [].

An empty rows yields a tile by tile raster rather than a zero-sized one.

Options

:scale — a positive integer dividing the tile size; the raster is composed at 1 / scale of the atlas's resolution, every tile and sprite sampled once and kept in the atlas's cache table. Mover coordinates stay in full-resolution pixels. Default 1
:at — the time in milliseconds an animated art's frame is chosen for. Default 0, the first frame of everything
:labels — text drawn over the grid and the movers, as the module documentation describes. Default []
:volumes — coloured regions tinting everything beneath them, as the module documentation describes. Default []
:void — :opaque, filling an empty tile with the atlas's void colour, or :transparent, leaving it clear so whatever is under the raster shows through. Default :opaque
:under — a raster of the same size composited beneath the result, which is how Cauldron2D.Parallax puts a background behind the world. Default nil