API Reference

Everything cl-atlas exports. Every function's docstring says the same: (describe 'cl-atlas:atlas-find-or-add).

Thread rules for all of it: an atlas, its pages and its regions may be used from any number of threads at once. See Threads.

Atlases

atlas (class)

Images packed into pages of one size, made by make-atlas.

make-atlas

(make-atlas &key (page-size 1024) (channels 1) (padding 1) data) => atlas

Returns an empty atlas of pages page-size texels square, each texel channels bytes, from 1 to 4, with padding empty texels kept right of and below each image. data rides along as atlas-data. See Atlases and Regions.

Atlas accessors

Function	Returns
(atlas-page-size atlas)	The width and height of each page, in texels.
(atlas-channels atlas)	The bytes of each texel.
(atlas-padding atlas)	The empty texels kept right of and below each image.
(atlas-data atlas)	What it was made with as :data.

atlas-add

(atlas-add atlas pixels &key data) => region

Packs the image pixels, a 2D array of octets indexed by row, then byte, and returns its region, carrying data. An empty image gets a region with no page. Signals atlas-error for an image larger than a page, or whose rows hold no whole number of texels; an image that is no 2D array of octets is a type-error.

atlas-find-or-add

(atlas-find-or-add atlas key function) => region

Returns the region for key, compared with equal. The first time key is asked for, calls function with no arguments, without the atlas's lock, to make the image; it returns the image and, optionally, the region's data as a second value. If two threads make an image for the same key, the first packed is kept. Signals atlas-error for an image that atlas-add would refuse, one that is no 2D array of octets included. See Atlases and Regions.

atlas-find

(atlas-find atlas key) => region or nil

Returns the region atlas-find-or-add packed for key, or nil. Allocates nothing and keeps no reference to key, which may be allocated on the stack.

atlas-clear

(atlas-clear atlas) => (no values)

Forgets every page and key. Regions handed out before keep their pages, which the atlas no longer lists; the pages after count from 0 again.

atlas-pages, atlas-page-count, atlas-page

(atlas-pages atlas) => list of pages
(atlas-page-count atlas) => count
(atlas-page atlas index) => page

The pages by index, as a fresh list; how many there are; and the page at index, counting from 0, which signals atlas-error if there is no such page. atlas-page-count and atlas-page allocate nothing.

Pages

page (struct)

A page of an atlas: a square of texels held row by row from the top left.

Page accessors

Function	Returns
(page-atlas page)	The atlas it belongs to, which it keeps alive.
(page-index page)	Its place among the atlas's pages, from 0.
(page-size page)	Its width and height, in texels.
(page-channels page)	The bytes of each texel.

take-page-changes

(take-page-changes page) => x, y, width, height   ; or NIL, NIL, NIL, NIL

Returns the column, row, width and height of the rectangle that changed since the last call, and forgets it; or nil four times if nothing changed. Allocates nothing when nothing changed. See Uploading Pages.

copy-page-region

(copy-page-region page x y width height &optional into) => octets

Returns the texels of the rectangle row by row, without padding, page-channels bytes each: what a texture upload takes. They are copied into into if it is given and long enough, and the vector returned may then be longer than the texels; otherwise into a new vector of exactly the texels. Allocates nothing with into. Signals atlas-error for a rectangle outside the page.

Regions

region (struct)

Where an image went. A region never moves and never changes.

Region accessors

Function	Returns
(region-page region)	The page it is on, or nil for an empty image.
(region-x region), (region-y region)	Its column and row on the page, from the top left.
(region-width region), (region-height region)	Its size in texels.
(region-data region)	What was given with it.

region-uv

(region-uv region) => u0, v0, u1, v1

The texture coordinates of its top left and bottom right corners, from 0 to 1 across its page, as single floats. Zeros for an empty image.

Conditions

atlas-error

The base of every error cl-atlas signals. (atlas-error-message condition) returns what went wrong and what to do about it. See Errors.