sprite.h

#include <modkit/sprite.h>36 functions · 2 structs · 3 typedefs · 3 macros

Context-based 2D sprite and texture atlas system.

Provides sprite rendering, texture atlases, and frame-based animation. Built on top of draw2d for efficient batched rendering. Usage:

Functions

mk_anim_createfunction

mk_anim_t mk_anim_create(const mk_sprite_t *frames, uint16_t count, float fps, bool loop)

Create an animation from an array of sprites.

Parameter	Type	Description
frames	const mk_sprite_t *	Array of sprite frames (copied internally)
count	uint16_t	Number of frames
fps	float	Frames per second
loop	bool	Whether to loop the animation

Returns Animation structure

mk_anim_destroyfunction

void mk_anim_destroy(mk_anim_t *anim)

Destroy an animation and free frame array.

Parameter	Type	Description
anim	mk_anim_t *	Value for anim.

mk_anim_drawfunction

void mk_anim_draw(mk_sprite_ctx_t ctx, const mk_anim_t *anim, float time, float x, float y)

Draw an animation at current time.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
anim	const mk_anim_t *	Animation to draw
time	float	Current time in seconds
x	float	Position
y	float	Position

mk_anim_draw_exfunction

void mk_anim_draw_ex(mk_sprite_ctx_t ctx, const mk_anim_t *anim, float time, float x, float y, float scale_x, float scale_y, float angle, float origin_x, float origin_y, uint32_t tint)

Draw an animation with full transformation.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.
anim	const mk_anim_t *	Value for anim.
time	float	Value for time.
x	float	Value for x.
y	float	Value for y.
scale_x	float	Value for scale x.
scale_y	float	Value for scale y.
angle	float	Value for angle.
origin_x	float	Value for origin x.
origin_y	float	Value for origin y.
tint	uint32_t	Value for tint.

mk_anim_durationfunction

float mk_anim_duration(const mk_anim_t *anim)

Get total duration of an animation.

Parameter	Type	Description
anim	const mk_anim_t *	Value for anim.

Returns Duration in seconds

mk_anim_finishedfunction

bool mk_anim_finished(const mk_anim_t *anim, float time)

Check if a non-looping animation has finished.

Parameter	Type	Description
anim	const mk_anim_t *	Animation
time	float	Current time in seconds

Returns true if animation has played through

mk_anim_framefunction

mk_sprite_t mk_anim_frame(const mk_anim_t *anim, float time)

Get the current frame of an animation.

Parameter	Type	Description
anim	const mk_anim_t *	Animation
time	float	Current time in seconds

Returns Current sprite frame

mk_anim_frame_indexfunction

int mk_anim_frame_index(const mk_anim_t *anim, float time)

Get the current frame index of an animation.

Parameter	Type	Description
anim	const mk_anim_t *	Animation
time	float	Current time in seconds

Returns Frame index (0 to frame_count-1)

mk_anim_from_prefixfunction

mk_anim_t mk_anim_from_prefix(mk_atlas_t atlas, const char *prefix, float fps, bool loop)

Create an animation from sprites matching a name prefix.

Sprites are sorted alphanumerically by name.

Parameter	Type	Description
atlas	mk_atlas_t	Atlas containing the sprites
prefix	const char *	Name prefix to match (e.g., "walk_" matches "walk_0", "walk_1", etc.)
fps	float	Frames per second
loop	bool	Whether to loop

Returns Animation structure

mk_atlas_createfunction

mk_atlas_t mk_atlas_create(mk_texture_t texture)

Create an atlas from an existing texture (for manual sprite definitions).

Parameter	Type	Description
texture	mk_texture_t	Texture to use as atlas

Returns Atlas handle, or MK_ATLAS_INVALID on failure

mk_atlas_destroyfunction

void mk_atlas_destroy(mk_atlas_t atlas)

Destroy an atlas and free resources.

Note: Does NOT destroy the underlying texture.

Parameter	Type	Description
atlas	mk_atlas_t	Value for atlas.

mk_atlas_getfunction

mk_sprite_t mk_atlas_get(mk_atlas_t atlas, const char *name)

Get a sprite from an atlas by name.

Parameter	Type	Description
atlas	mk_atlas_t	Atlas handle
name	const char *	Sprite name (as defined in the JSON)

Returns Sprite, or MK_SPRITE_INVALID if not found

mk_atlas_get_idxfunction

mk_sprite_t mk_atlas_get_idx(mk_atlas_t atlas, uint32_t index)

Get a sprite from an atlas by index.

Parameter	Type	Description
atlas	mk_atlas_t	Atlas handle
index	uint32_t	Zero-based sprite index

Returns Sprite, or MK_SPRITE_INVALID if index out of range

mk_atlas_get_namefunction

const char * mk_atlas_get_name(mk_atlas_t atlas, uint32_t index)

Get the name of a sprite by index.

Parameter	Type	Description
atlas	mk_atlas_t	Atlas handle
index	uint32_t	Zero-based sprite index

Returns Sprite name, or NULL if index out of range

mk_atlas_get_texturefunction

mk_texture_t mk_atlas_get_texture(mk_atlas_t atlas)

Get the texture used by an atlas.

Parameter	Type	Description
atlas	mk_atlas_t	Value for atlas.

Returns The resulting handle or value.

mk_atlas_is_validfunction

bool mk_atlas_is_valid(mk_atlas_t atlas)

Check if atlas handle is valid.

Parameter	Type	Description
atlas	mk_atlas_t	Value for atlas.

Returns True when the condition holds.

mk_atlas_loadfunction

mk_atlas_t mk_atlas_load(const char *image_path, const char *json_path)

Load a texture atlas from image and JSON files.

Supports TexturePacker JSON (hash or array format). Uses point filtering by default (best for pixel art).

Parameter	Type	Description
image_path	const char *	Path to the atlas image (PNG, etc.)
json_path	const char *	Path to the atlas JSON metadata

Returns Atlas handle, or MK_ATLAS_INVALID on failure

mk_atlas_load_exfunction

mk_atlas_t mk_atlas_load_ex(const char *image_path, const char *json_path, uint32_t texture_flags)

Load a texture atlas with custom texture flags.

Parameter	Type	Description
image_path	const char *	Path to the atlas image (PNG, etc.)
json_path	const char *	Path to the atlas JSON metadata
texture_flags	uint32_t	Texture flags (MK_TEXTURE_POINT, MK_TEXTURE_CLAMP_U, etc.)

Returns Atlas handle, or MK_ATLAS_INVALID on failure

mk_atlas_load_memoryfunction

mk_atlas_t mk_atlas_load_memory(const void *image_data, uint32_t image_size, const void *json_data, uint32_t json_size, uint32_t texture_flags)

Load a TexturePacker atlas from image and JSON byte spans.

The atlas owns the uploaded texture. Input bytes are read during the call only and may be released immediately afterward.

Parameter	Type	Description
image_data	const void *	Value for image data.
image_size	uint32_t	Image size in bytes.
json_data	const void *	Value for JSON data.
json_size	uint32_t	JSON size in bytes.
texture_flags	uint32_t	Value for texture flags.

Returns The resulting handle or value.

mk_atlas_sprite_countfunction

uint32_t mk_atlas_sprite_count(mk_atlas_t atlas)

Get the number of sprites in an atlas.

Parameter	Type	Description
atlas	mk_atlas_t	Value for atlas.

Returns The resulting value.

mk_sprite_beginfunction

void mk_sprite_begin(mk_sprite_ctx_t ctx, mk_encoder_t encoder, mk_view_id_t view, uint16_t screen_w, uint16_t screen_h)

Begin sprite batch rendering.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
encoder	mk_encoder_t	Encoder from mk_render_ctx_encoder() or mk_encoder_begin()
view	mk_view_id_t	View ID for rendering
screen_w	uint16_t	Screen dimensions for orthographic projection
screen_h	uint16_t	Screen dimensions for orthographic projection

mk_sprite_begin_exfunction

bool mk_sprite_begin_ex(mk_sprite_ctx_t ctx, const mk_canvas_begin_desc *desc)

Begin sprite rendering with independent logical and framebuffer sizes.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.
desc	const mk_canvas_begin_desc *	Configuration descriptor.

Returns True when the operation succeeds.

mk_sprite_ctx_createfunction

mk_sprite_ctx_t mk_sprite_ctx_create(void)

Create a new sprite context.

Internally creates a draw2d context for batched rendering.

Returns Context handle, or MK_SPRITE_CTX_INVALID on failure

mk_sprite_ctx_destroyfunction

void mk_sprite_ctx_destroy(mk_sprite_ctx_t ctx)

Destroy a sprite context.

Context must not be in draw mode.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.

mk_sprite_drawfunction

void mk_sprite_draw(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y)

Draw a sprite at a position.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
sprite	mk_sprite_t	Sprite to draw
x	float	Position (top-left corner)
y	float	Position (top-left corner)

mk_sprite_draw_exfunction

void mk_sprite_draw_ex(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y, float scale_x, float scale_y, float angle, float origin_x, float origin_y, uint32_t tint)

Draw a sprite with full transformation.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
sprite	mk_sprite_t	Sprite to draw
x	float	Position
y	float	Position
scale_x	float	Scale factors
scale_y	float	Scale factors
angle	float	Rotation in radians
origin_x	float	Origin point (0-1, relative to sprite size)
origin_y	float	Origin point (0-1, relative to sprite size)
tint	uint32_t	Color tint (0xRRGGBBAA)

mk_sprite_draw_flipfunction

void mk_sprite_draw_flip(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y, mk_flip_t flip)

Draw a sprite with a texture-space flip.

Use this rather than negative scale when you need MK_FLIP_DIAG (the transpose), which negative scale cannot express. Tilemaps use it to apply the flip bits Tiled packs into each GID.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
sprite	mk_sprite_t	Sprite to draw
x	float	Position
y	float	Position
flip	mk_flip_t	Bitmask of mk_flip_t

mk_sprite_draw_rotatedfunction

void mk_sprite_draw_rotated(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y, float angle)

Draw a sprite with rotation.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle
sprite	mk_sprite_t	Sprite to draw
x	float	Position (center of rotation)
y	float	Position (center of rotation)
angle	float	Rotation in radians

mk_sprite_draw_scaledfunction

void mk_sprite_draw_scaled(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y, float scale)

Draw a sprite with uniform scaling.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.
sprite	mk_sprite_t	Value for sprite.
x	float	Value for x.
y	float	Value for y.
scale	float	Value for scale.

mk_sprite_draw_scaled_xyfunction

void mk_sprite_draw_scaled_xy(mk_sprite_ctx_t ctx, mk_sprite_t sprite, float x, float y, float scale_x, float scale_y)

Draw a sprite with non-uniform scaling.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.
sprite	mk_sprite_t	Value for sprite.
x	float	Value for x.
y	float	Value for y.
scale_x	float	Value for scale x.
scale_y	float	Value for scale y.

mk_sprite_endfunction

void mk_sprite_end(mk_sprite_ctx_t ctx)

End sprite batch rendering and flush to GPU.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Context handle

mk_sprite_from_gridfunction

uint32_t mk_sprite_from_grid(mk_texture_t texture, int cols, int rows, mk_sprite_t *out_sprites)

Create sprites from a uniform grid (sprite sheet).

Parameter	Type	Description
texture	mk_texture_t	Source texture
cols	int	Number of columns in grid
rows	int	Number of rows in grid
out_sprites	mk_sprite_t *	Output array (must have space for cols*rows sprites)

Returns Number of sprites created

mk_sprite_from_regionfunction

mk_sprite_t mk_sprite_from_region(mk_texture_t texture, int x, int y, int w, int h)

Create a sprite from a region of a texture.

Parameter	Type	Description
texture	mk_texture_t	Source texture
x	int	Top-left corner of region
y	int	Top-left corner of region
w	int	Size of region
h	int	Size of region

Returns Sprite referencing the region

mk_sprite_from_texturefunction

mk_sprite_t mk_sprite_from_texture(mk_texture_t texture)

Create a sprite from an entire texture.

Parameter	Type	Description
texture	mk_texture_t	Value for texture.

Returns The resulting handle or value.

mk_sprite_is_validfunction

bool mk_sprite_is_valid(mk_sprite_t sprite)

Check if sprite is valid (has a texture).

Parameter	Type	Description
sprite	mk_sprite_t	Value for sprite.

Returns True when the condition holds.

mk_sprite_set_blend_modefunction

void mk_sprite_set_blend_mode(mk_sprite_ctx_t ctx, mk_blend_mode_t mode)

Set the blend mode used by subsequent sprites.

Parameter	Type	Description
ctx	mk_sprite_ctx_t	Active operation context.
mode	mk_blend_mode_t	Value for mode.

Structs

mk_animstruct

Animation - a sequence of sprites played over time.

Field	Type	Description
frames	mk_sprite_t *	Array of sprite frames.
frame_count	uint16_t	Number of frames.
fps	float	Frames per second.
loop	bool	Whether to loop.

mk_spritestruct

Sprite - a reference to a rectangular region in a texture.

Lightweight value type that can be copied freely.

Field	Type	Description
texture	mk_texture_t	Source texture.
x	uint16_t	Source rectangle X position in the texture.
y	uint16_t	Source rectangle Y position in the texture.
w	uint16_t	Source rectangle width.
h	uint16_t	Source rectangle height.
offset_x	int16_t	Horizontal offset for a trimmed sprite.
offset_y	int16_t	Vertical offset for a trimmed sprite.
orig_w	uint16_t	Original untrimmed width.
orig_h	uint16_t	Original untrimmed height.

Typedefs

mk_anim_ttypedef

typedef struct mk_anim mk_anim_t

Animation - a sequence of sprites played over time.

mk_atlas_ttypedef

typedef mk_atlas_handle_t mk_atlas_t

Texture atlas handle - generational handle for safe resource management.

mk_sprite_ctx_ttypedef

typedef struct mk_sprite_ctx* mk_sprite_ctx_t

Opaque sprite context handle.

Each context wraps a draw2d context for batched sprite rendering.

Macros

MK_ATLAS_INVALIDdefine

MK_ATLAS_INVALID

Invalid sentinel for atlas.

MK_SPRITE_CTX_INVALIDdefine

MK_SPRITE_CTX_INVALID

Invalid sentinel for sprite ctx.

MK_SPRITE_INVALIDdefine

MK_SPRITE_INVALID

Invalid/empty sprite constant.