Graphics utilities is primarily responsible for managing and decoding assets such as images, fonts, and strings. It provides the means for interacting with asset data, complex data decoding, data decompression, and string asset lookup. The library also abstractly handles the accessing of external memory sources during asset decoding.

• Anti-aliasing – Uses transparency to achieve a less jagged look when rasterizing pixel information.
• ASCII – The standard 8-bit-per-character text representation.
• Asset – A generic term for any resource that consists of blocks of binary data. Can be images, raw files, fonts, strings, and so on.
• Binary Asset – A chunk of raw data.
• Codepoint – The numerical ID of a glyph, typically four bytes in size
• External Asset – An asset that is stored on an external storage peripheral not directly accessible from the CPU.
• Font – A collection of images that represent linguistic characters. Each font has a distinct look and feel.
• Glyph – A linguistic character.
• Image Asset – A collection of pixel data that, when rendered, forms a visual image.
• Index Map – An image that is stored as a series of lookup table indices, rather than raw pixel data.
• Palette Asset – A form of image compression. Palettes are lookup tables of color information.
• Run-length Encoding (RLE) – A simple form of data compression that indexes long strings of duplicate bytes into a single value with an associated length value. Data blocks with long runs of duplicate characters are good candidates for RLE compression. Poor candidates will see the data size increase rather than decrease.
• String – A series of characters often used to form linguistic sentences.
• UTF8 – The encoding format for Unicode characters that favors space over decoding speed.
• UTF16 – The encoding format for Unicode characters that favors decoding speed over space.

The library serves four main purposes:

• Provides a common definition for asset description.
• Provides APIs for asset indexing, decoding, and rendering.
• Provides an abstract API for asset decoders.
• Provides state machines for accessing assets located in external memory locations.

All assets share a common header “GFXU_AssetHeader”. This header is defined as follows:

typedef struct GFXU_AssetHeader_t
{
 uint32_t type;
 uint32_t dataLocation;
 void* dataAddress;
 uint32_t dataSize;
} GFXU_AssetHeader;

• type – the type of an asset
• dataLocation – The location ID for the asset. A location of “0” always indicates internal flash memory.
• dataAddress – The address of the asset. Depending on memory location, this address may not be accessible from the CPU.
• dataSize – The size of the asset in bytes.

Image Asset Descriptor 

The image asset descriptor is defined as follows:

typedef struct GFXU_ImageAsset_t
{
 GFXU_AssetHeader header;
 GFXU_ImageFormat format;
 uint32_t width;
 uint32_t height;
 GFX_ColorMode colorMode;
 GFXU_ImageCompressionType compType;
 GFX_Bool useMask;
 GFX_Color mask;
 GFXU_PaletteAsset* palette;
} GFXU_ImageAsset;

• header – The common asset header.
• format – The format of the image data.
• width – The width of the image.
• height – The height of the image.
• colorMode – The format of the image's pixel data.
• compType – If compressed, indicates the compression type.
• useMask – Indicates whether the image specifies a pixel transparency mask.
• mask – The value of the image transparency mask.
• palette – If the color mode is an index format, then this is the address of the lookup table to reference.

Image decoding with the GFX Utilities library is meant to be simple and straightforward. The library provides a single API that clients can use to render image assets.

GFX_Result GFXU_DrawImage(GFXU_ImageAsset* img,
 int32_t src_x,
 int32_t src_y,
 int32_t src_width,
 int32_t src_height,
 int32_t dest_x,
 int32_t dest_y,
 GFXU_MemoryIntf* read_cb,
 GFXU_ExternalAssetReader** reader);

This function accepts a pointer to an image header and rendering dimensions for rendering sub-sections of the image. The last two arguments refer to external memory access and will be described later. If the type of an image specifies an image decoder, then that decoder is automatically invoked by the library. If an image is stored as an index map, then its associated palette is referenced during decoding. 

Image Palette Asset 

Palette assets are color lookup tables that can be referenced when decoding indexed images. The index format can be 1bpp, 4bpp, or 8bpp large, resulting in a maximum of 1, 16, or 256 colors, respectively. 

The palette descriptor is defined as follows:

typedef struct GFXU_PaletteAsset_t
{
 GFXU_AssetHeader header;
 uint32_t colorCount;
 GFX_ColorMode colorMode;
} GFXU_PaletteAsset;

• header – The common asset header.
• colorCount – The number of colors in this palette.
• colorMode – The color format of this palette.

Font Assets 

Fonts are chunks of data that contain color information for drawing individual linguistic characters. Font glyph data can either be stored by using a 1bpp or 8bpp format. The larger format is for storing transparency information for use in drawing anti-aliased characters. 

The font descriptor is as follows:

typedef struct GFXU_FontAsset_t
{
 GFXU_AssetHeader header;
 uint32_t height;
 uint32_t ascent;
 uint32_t descent;
 uint32_t baseline;
 GFXU_FontAssetBPP bpp;
 GFXU_FontGlyphIndexTable* indexTable;
} GFXU_FontAsset;

• header – The common asset header.
• height – The height of the font.
• ascent – The ascent of the font.
• descent – The descent of the font.
• baseline – The baseline of the font.
• bpp – The size of the per-pixel font data.
• indexTable – The pointer to the font index table.

Font Index Table 

Each font provides an index table for quickly locating pixel data inside the font data chunk. The index table specifies the number of individual ranges or series of glyphs that it provides, followed by the actual range data. 

A typical font range table entry is as follows:

typedef struct GFXU_FontGlyphRange_t
{
 uint32_t glyphCount;
 uint32_t startID;
 uint32_t endID;
 uint8_t* lookupTable;
} GFXU_FontGlyphRange;

• glyphCount – The number of glyphs in this range.
• startID – The starting glyph codepoint.
• endID – The ending glyph codepoint.
• lookupTable – The pointer to the lookup table for this range.

Font Lookup Table 

The font lookup table contains location and size data for referencing glyphs in the font data chunk. This table provides with values to allow geometric analysis of font glyphs without having to render any data. 

The data in a font lookup table is defined as follows:

• Byte 1 – The size of the offset values in the lookup table. 1-4 bytes possible depending on the max size of the font data chunk.
• Byte 2 – The size of the width values in the lookup table. This depends on the font size. The maximum size is 0xFFFF.

Repeating 'glyphCount' number of times:

• Offset value – Read offset value of 1-4 bytes, depending on the header.
• Width value – Read width value of 1-2 bytes, depending on the header

Font Glyph Raster Data 

Font raster data is stored in a single chunk of memory and is referenced through the previously mentioned lookup tables. When rendering a font, the decoder uses the code point to find the appropriate lookup table and then uses that table to get the offset of the glyph. The width value says how large the glyph is in pixels, which could be 1bpp or 8bpp, depending on the anti-alias setting. The decoder then reads "width" number of pixels starting at "offset". The pixel data offsets are always byte-aligned. 

String Table 

The graphics utilities library defines a special asset called the "String Table". This table is a predefined lookup table of strings, languages, and their associated fonts. This construct makes runtime localization possible for user interface libraries.