GRAPHICS: multi-page sprite atlas, random-access cells

Structures

	Name
struct	N_ATLAS_PAGE one atlas page: a bitmap holding cols*rows equally sized cells
struct	N_ATLAS a set of atlas pages addressed as (page, cell index)

Functions

	Name
N_ATLAS *	new_n_atlas(size_t npages) allocate an atlas holding npages empty pages
int	n_atlas_set_page(N_ATLAS * atlas, size_t page, const void * bytes, size_t len, const char * ext, uint16_t cols, uint16_t rows) decode bytes into one atlas page
int	n_atlas_page_ready(const N_ATLAS * atlas, size_t page) test whether a page holds a usable bitmap
int	n_atlas_max_bitmap_size(void ) get the largest bitmap dimension this display can hold
int	n_atlas_draw_cell(N_ATLAS * atlas, size_t page, size_t index, float x, float y, float size) draw one cell as a size x size square
void	n_atlas_destroy(N_ATLAS ** atlas) destroy an atlas and every bitmap it owns
int	n_atlas_cell_rect(const N_ATLAS * atlas, size_t page, size_t index, float * sx, float * sy, float * sw, float * sh) compute the source rectangle of one cell

Functions Documentation

function new_n_atlas

N_ATLAS * new_n_atlas(
    size_t npages
)

allocate an atlas holding npages empty pages

Parameters:

• npages number of pages, must be > 0

Return: a new N_ATLAS or NULL on error

function n_atlas_set_page

int n_atlas_set_page(
    N_ATLAS * atlas,
    size_t page,
    const void * bytes,
    size_t len,
    const char * ext,
    uint16_t cols,
    uint16_t rows
)

decode bytes into one atlas page

Parameters:

• atlas the atlas
• page page index, < npages
• bytes encoded image data (PNG, JPEG, ... per the loaded image addon)
• len size of bytes
• ext extension hint for the decoder, e.g. ".png"
• cols grid width in cells, must be > 0
• rows grid height in cells, must be > 0

Return: TRUE on success, FALSE on a decode failure or an oversized page

The bytes are decoded from memory, so a caller that verified them (a hash, a signature) can hand over the exact buffer it checked rather than a path that could change underneath. A page larger than n_atlas_max_bitmap_size() is REFUSED, not uploaded: an oversized texture renders blank with no error, and failing loudly lets the caller keep whatever it had before.

Replacing a page destroys the bitmap it held. On failure the previous page is left untouched.

function n_atlas_page_ready

int n_atlas_page_ready(
    const N_ATLAS * atlas,
    size_t page
)

test whether a page holds a usable bitmap

Parameters:

• atlas the atlas
• page page index

Return: TRUE when the page can be drawn from, FALSE otherwise

function n_atlas_max_bitmap_size

int n_atlas_max_bitmap_size(
    void 
)

get the largest bitmap dimension this display can hold

Return: the GPU texture limit in pixels, or the GL ES 2.0 guaranteed floor of 2048 when it cannot be queried

Older mobile GPUs cap textures at 2048x2048. A page above the limit uploads blank rather than failing, which renders as nothing at all with no error, so callers are expected to REFUSE an oversized page instead of showing an empty grid. n_atlas_set_page does that for you.

function n_atlas_draw_cell

int n_atlas_draw_cell(
    N_ATLAS * atlas,
    size_t page,
    size_t index,
    float x,
    float y,
    float size
)

draw one cell as a size x size square

Parameters:

• atlas the atlas
• page page index
• index cell index
• x destination left edge
• y destination top edge
• size destination width and height in pixels

Return: TRUE when drawn, FALSE when the cell does not exist

Returning FALSE rather than drawing nothing lets a text layout fall back to literal text for a glyph its atlas does not have.

function n_atlas_destroy

void n_atlas_destroy(
    N_ATLAS ** atlas
)

destroy an atlas and every bitmap it owns

Parameters:

• atlas pointer to the atlas to destroy, set to NULL on return

function n_atlas_cell_rect

int n_atlas_cell_rect(
    const N_ATLAS * atlas,
    size_t page,
    size_t index,
    float * sx,
    float * sy,
    float * sw,
    float * sh
)

compute the source rectangle of one cell

Parameters:

• atlas the atlas
• page page index
• index cell index, counted left to right then top to bottom
• sx filled with the cell's left edge in page pixels, may be NULL
• sy filled with the cell's top edge in page pixels, may be NULL
• sw filled with the cell width in pixels, may be NULL
• sh filled with the cell height in pixels, may be NULL

Return: TRUE when the cell exists, FALSE otherwise

Cell size is DERIVED from the page bitmap and its grid rather than declared separately, so an atlas cannot disagree with its own artwork.