A sprite: an image with alpha, run-length encoded, blended onto a canvas. More...

#include <stdbool.h>
#include <stdint.h>
#include "gfx.h"

Data Structures
struct	gfx_sprite_t
	An encoded image with alpha. More...

Macros
#define	GFX_RUN_MAX 64
	The longest run, 64 pixels.

Enumerations
enum	{ GFX_RUN_SKIP = 0 , GFX_RUN_FILL = 1 , GFX_RUN_COPY = 2 , GFX_RUN_BLEND = 3 }
	The kinds of a run, in the top two bits of its first byte. More...

Functions
bool	gfx_sprite_draw (gfx_canvas_t c, int x, int y, const gfx_sprite_t sp)
	Blend `sp` onto `c` with its top-left corner at (x, y).
static gfx_rect_t	gfx_sprite_rect (const gfx_sprite_t *sp, int x, int y)
	The sprite's box with its top-left corner at (x, y).

Detailed Description

A sprite: an image with alpha, run-length encoded, blended onto a canvas.

The table is what tools/gen_cats.py writes: row by row from the top, each row exactly the sprite's width, as runs. A run starts with one byte, its top two bits the kind and its low six bits the length less one (1 to 64 pixels):

GFX_RUN_SKIP n transparent pixels; no data GFX_RUN_FILL n opaque pixels of one colour; 2 bytes, RGB565 little-endian GFX_RUN_COPY n opaque pixels; 2n bytes GFX_RUN_BLEND n partly covered pixels; ceil(n/2) bytes of 4-bit alpha (1 to 14 of 15), the first pixel in the low nibble, then 2n bytes of RGB565 premultiplied by that alpha

A partly covered pixel is out = src + dst x (15 - a) / 15 per channel, the destination's weight rounded down to 32nds so no channel carries into the next. Opaque runs are stored and copied; a transparent run reads nothing. Drawing the same sprite twice on the same pixels gives a darker edge than once: a screen draws it once onto a background it has just filled.

Clipping is to canvas->clip, as for every primitive (gfx.h). The area written is reported to the damage record once (gfx_damage.h) and to the fit check as a shape (GFX_TEXT_TRACE), so a string under a sprite shows there as painted over.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

The kinds of a run, in the top two bits of its first byte.

Enumerator
GFX_RUN_SKIP	transparent pixels, no data
GFX_RUN_FILL	one opaque colour, 2 bytes
GFX_RUN_COPY	opaque pixels, 2 bytes each
GFX_RUN_BLEND	partly covered pixels, alpha nibbles then premultiplied colours

Function Documentation

◆ gfx_sprite_draw()

bool gfx_sprite_draw	(	gfx_canvas_t *	c,
		int	x,
		int	y,
		const gfx_sprite_t *	sp )

Blend sp onto c with its top-left corner at (x, y).

Stops at the end of the table, or at a run that would cross the end of its row, so a short or damaged table draws less and reads nothing past its bytes.

Parameters

c	the canvas
x	the sprite's left edge on the canvas
y	its top edge
sp	the sprite, or NULL for none

Returns: true when the whole table was read, row by row, to its last byte; false for NULL, an empty sprite or a table that does not hold w x h pixels in exactly bytes

◆ gfx_sprite_rect()

gfx_rect_t gfx_sprite_rect	(	const gfx_sprite_t *	sp,
		int	x,
		int	y )

inlinestatic

The sprite's box with its top-left corner at (x, y).

Parameters

sp	the sprite
x	its left edge
y	its top edge

Returns: the box, empty for NULL

Data Structures

Macros