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

Functions
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
void	n_atlas_destroy (N_ATLAS **atlas)
	destroy an atlas and every bitmap it owns
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
int	n_atlas_max_bitmap_size (void)
	get the largest bitmap dimension this display can hold
int	n_atlas_page_ready (const N_ATLAS *atlas, size_t page)
	test whether a page holds a usable bitmap
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
N_ATLAS *	new_n_atlas (size_t npages)
	allocate an atlas holding npages empty pages

Detailed Description

Data Structure Documentation

◆ N_ATLAS

struct N_ATLAS

a set of atlas pages addressed as (page, cell index)

Examples: ex_atlas.c.

Definition at line 55 of file n_atlas.h.

Collaboration diagram for N_ATLAS:

Data Fields
size_t	npages	number of pages
N_ATLAS_PAGE *	pages	page array, npages entries

◆ N_ATLAS_PAGE

struct N_ATLAS_PAGE

one atlas page: a bitmap holding cols*rows equally sized cells

Definition at line 45 of file n_atlas.h.

Collaboration diagram for N_ATLAS_PAGE:

Data Fields
ALLEGRO_BITMAP *	bmp	the decoded page bitmap, NULL until set
uint16_t	cols	grid width in cells
uint16_t	rows	grid height in cells

Function Documentation

◆ 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

Returns: 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.

Definition at line 183 of file n_atlas.c.

References N_ATLAS_PAGE::bmp, N_ATLAS_PAGE::cols, n_atlas_page_ready(), N_ATLAS::pages, row(), and N_ATLAS_PAGE::rows.

Referenced by main(), and n_atlas_draw_cell().

Here is the call graph for this function:

Here is the caller graph for this 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

Definition at line 75 of file n_atlas.c.

References __n_assert, and Free.

Referenced by main().

Here is the caller graph for this 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

Returns: 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.

Definition at line 226 of file n_atlas.c.

References __n_assert, N_ATLAS_PAGE::bmp, n_atlas_cell_rect(), and N_ATLAS::pages.

Here is the call graph for this function:

◆ n_atlas_max_bitmap_size()

int n_atlas_max_bitmap_size ( void )

get the largest bitmap dimension this display can hold

Returns: 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.

Definition at line 43 of file n_atlas.c.

Referenced by main(), and n_atlas_set_page().

Here is the caller graph for this 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

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

Definition at line 160 of file n_atlas.c.

References __n_assert, N_ATLAS_PAGE::bmp, N_ATLAS_PAGE::cols, N_ATLAS::npages, N_ATLAS::pages, and N_ATLAS_PAGE::rows.

Referenced by main(), and n_atlas_cell_rect().

Here is the caller graph for this 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

Returns: 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.

Definition at line 112 of file n_atlas.c.

References __n_assert, N_ATLAS_PAGE::bmp, N_ATLAS_PAGE::cols, LOG_ERR, n_atlas_max_bitmap_size(), n_log, N_ATLAS::pages, and N_ATLAS_PAGE::rows.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this 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

Returns: a new N_ATLAS or NULL on error

Definition at line 54 of file n_atlas.c.

References __n_assert, Free, Malloc, N_ATLAS::npages, and N_ATLAS::pages.

Referenced by main().

Here is the caller graph for this function:

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ N_ATLAS

◆ N_ATLAS_PAGE

Function Documentation

◆ n_atlas_cell_rect()

◆ n_atlas_destroy()

◆ n_atlas_draw_cell()

◆ n_atlas_max_bitmap_size()

◆ n_atlas_page_ready()

◆ n_atlas_set_page()

◆ new_n_atlas()