Andrew Kesterson
3a262bee54
Closes internal-consistency items 7 through 15. Nineteen non-static functions were in the ABI with no declaration anywhere, so no consumer could call them and any consumer could collide with them. The four gamepad_handle_* functions are the ones that mattered: controller.h declared akgl_controller_handle_button_down and three siblings that did not exist, so anything compiled against the header alone failed to link. The definitions carry the declared names now, which also closes Defects -> Known and still open item 10, and their documentation moved to the header. The rest are either declared under a "part of the internal API" block -- akgl_game_save_actors and akgl_game_load_versioncmp, which tests/game.c had to declare for itself, plus six tilemap loader helpers the untested-loader work wants to reach -- or static, which is what the four save iterators and load_objectnamemap should always have been. akgl_path_relative_from is deleted: declared nowhere, called from nowhere, never wrote its output, and leaked a pooled string on every call, so it closes Known and still open item 4 and item 40 by ceasing to exist. scripts/check_api_surface.sh keeps it closed. It reads the built library's dynamic symbol table and every public header with comments stripped, and fails on an exported akgl_* symbol that is declared nowhere. Stripping comments is the whole point -- four of these were mentioned in controller.h prose, which is how they went unnoticed. The pool-size ceilings are defined once, in heap.h, so the #ifndef override hook fires for the first time; actor.h, sprite.h and character.h were defining the same four unconditionally from headers heap.h includes above its own guard. tests/header_pool_override.c fails the compile if that regresses. Also here: (void) rather than () on the twelve no-argument entry points, AKERR_NOIGNORE only on declarations, static helpers with the akgl_ prefix dropped, and the six parameter-name mismatches. akgl_get_json_with_default had its two contexts swapped rather than merely misspelled -- the incoming one was `err` and its own was `e`, which is the name reserved for an incoming one. 24/24 pass, reindent --check clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
170 lines
10 KiB
C
170 lines
10 KiB
C
/**
|
|
* @file sprite.h
|
|
* @brief Spritesheets (one texture, many frames) and the animations cut out of them.
|
|
*
|
|
* The split is deliberate: an akgl_SpriteSheet owns the `SDL_Texture` and the
|
|
* frame grid, and any number of akgl_Sprite animations point at the same sheet
|
|
* and name the frame indices they use. Loading two sprites from the same image
|
|
* loads the image once -- akgl_sprite_load_json looks the sheet up in
|
|
* #AKGL_REGISTRY_SPRITESHEET by resolved path before creating one.
|
|
*
|
|
* Both are pool objects (akgl_heap_next_sprite, akgl_heap_next_spritesheet) and
|
|
* both publish themselves in a registry under their name, which is how
|
|
* akgl_character_sprite_add and the tilemap loader find them. Because loading a
|
|
* sheet uploads a texture, the renderer has to exist first -- so
|
|
* akgl_render_2d_init, or akgl_game_init, before any of this.
|
|
*/
|
|
|
|
#ifndef _AKGL_SPRITE_H_
|
|
#define _AKGL_SPRITE_H_
|
|
|
|
#include <SDL3/SDL_properties.h>
|
|
#include <SDL3/SDL.h>
|
|
#include <akerror.h>
|
|
|
|
|
|
#define AKGL_SPRITE_MAX_FRAMES 16
|
|
#define AKGL_SPRITE_MAX_NAME_LENGTH 128
|
|
#define AKGL_SPRITE_MAX_REGISTRY_SIZE 1024
|
|
#define AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH 512
|
|
|
|
|
|
/** @brief Stores a loaded spritesheet texture and frame geometry. */
|
|
typedef struct {
|
|
uint8_t refcount; /**< Pool bookkeeping; 0 means the slot is free. Destroys the texture when it reaches 0. */
|
|
SDL_Texture *texture; /**< The whole sheet as one GPU texture. Owned by this struct. */
|
|
char name[AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH]; /**< Registry key: the resolved path the image was loaded from. */
|
|
uint16_t sprite_w; /**< Frame width. Vestigial: nothing in the library writes or reads it; the grid comes from akgl_Sprite::width. */
|
|
uint16_t sprite_h; /**< Frame height. Vestigial, same as sprite_w. */
|
|
} akgl_SpriteSheet;
|
|
|
|
/** @brief Describes an animated sprite and its spritesheet reference. */
|
|
typedef struct {
|
|
uint8_t refcount; /**< Pool bookkeeping; 0 means the slot is free. One reference per character that maps it. */
|
|
uint8_t frameids[AKGL_SPRITE_MAX_FRAMES]; /**< Frame numbers on the sheet, in playback order. Counted left to right, then wrapping to the next row. */
|
|
uint32_t frames; /**< How many entries of frameids are in use. */
|
|
uint32_t width; /**< Frame width in pixels; also the horizontal stride used to find a frame on the sheet. */
|
|
uint32_t height; /**< Frame height in pixels; the vertical stride once frames wrap to the next row. */
|
|
uint32_t speed; /**< Nanoseconds one frame is held. Read from JSON in milliseconds and scaled by #AKGL_TIME_ONEMS_NS. */
|
|
bool loop; /**< Restart from frame 0 when the last frame is reached, instead of holding it. */
|
|
bool loopReverse; /**< Play back down to frame 0 instead of jumping to it -- a ping-pong loop. */
|
|
char name[AKGL_SPRITE_MAX_NAME_LENGTH]; /**< Registry key, from the JSON `name` field. */
|
|
akgl_SpriteSheet *sheet; /**< The sheet these frames are cut from. Borrowed, not owned. */
|
|
} akgl_Sprite;
|
|
|
|
// initializes a new sprite to use the given sheet and otherwise sets to zero
|
|
/**
|
|
* @brief Zero a pooled sprite, bind it to a sheet, and publish it in the sprite registry.
|
|
*
|
|
* Sets the name and the sheet and takes the first reference; everything else --
|
|
* frame list, geometry, speed, loop flags -- is left at zero for the caller, or
|
|
* akgl_sprite_load_json, to fill in. The sheet is borrowed, so this does *not*
|
|
* take a reference on it: releasing the sheet out from under a live sprite
|
|
* leaves a dangling pointer.
|
|
*
|
|
* @param spr Pooled sprite to initialize, normally from akgl_heap_next_sprite.
|
|
* Required. Any previous contents are discarded.
|
|
* @param name Registry key, NUL-terminated. Required. Copied at a fixed
|
|
* #AKGL_SPRITE_MAX_NAME_LENGTH bytes, so a shorter string reads
|
|
* past its end -- pass a name from an akgl_String or another
|
|
* buffer of at least that size. An existing entry with the same
|
|
* name is silently replaced.
|
|
* @param sheet The spritesheet this sprite's frames come from. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p spr, @p name, or @p sheet is `NULL`.
|
|
* @throws AKERR_KEY If the sprite cannot be written into #AKGL_REGISTRY_SPRITE
|
|
* -- in practice, because akgl_registry_init has not run.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_sprite_initialize(akgl_Sprite *spr, char *name, akgl_SpriteSheet *sheet);
|
|
// loads a given image file into a new spritesheet
|
|
/**
|
|
* @brief Load an image file as a texture and publish it as a spritesheet.
|
|
*
|
|
* Uploads @p filename through SDL_image using the global `akgl_renderer`, so the
|
|
* renderer must already be initialized. The sheet is registered in
|
|
* #AKGL_REGISTRY_SPRITESHEET under @p filename, which is the key
|
|
* akgl_sprite_load_json looks it up by to avoid loading the same image twice.
|
|
*
|
|
* @param sheet Pooled spritesheet to initialize, normally from
|
|
* akgl_heap_next_spritesheet. Required. Zeroed first, so a
|
|
* texture it already held is leaked rather than destroyed.
|
|
* @param sprite_w Frame width in pixels. Accepted and currently discarded --
|
|
* the frame grid actually used at draw time comes from the
|
|
* akgl_Sprite's `width`/`height`, not from here.
|
|
* @param sprite_h Frame height in pixels. Same caveat as @p sprite_w.
|
|
* @param filename Path to the image, in any format SDL_image can decode.
|
|
* Required. Doubles as the registry key, so callers should pass
|
|
* an already-resolved path; two spellings of the same file are
|
|
* two sheets. Truncated at
|
|
* #AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p sheet or @p filename is `NULL`.
|
|
* @throws AKGL_ERR_SDL If the image cannot be loaded -- missing, unreadable, or
|
|
* a format SDL_image was not built with. The message carries
|
|
* `SDL_GetError()`.
|
|
* @throws AKERR_KEY If the sheet cannot be written into
|
|
* #AKGL_REGISTRY_SPRITESHEET.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_spritesheet_initialize(akgl_SpriteSheet *sheet, int sprite_w, int sprite_h, char *filename);
|
|
/**
|
|
* @brief Build a sprite -- and, if needed, its spritesheet -- from a JSON definition file.
|
|
*
|
|
* Reads `name`, `width`, `height`, `speed` (seconds, scaled to milliseconds),
|
|
* `loop`, `loopReverse`, a `frames` array of frame indices, and a `spritesheet`
|
|
* object holding `filename`, `frame_width`, and `frame_height`. The sheet's
|
|
* `filename` is resolved *relative to the directory of @p filename*, so a sprite
|
|
* definition can sit next to its image and move with it.
|
|
*
|
|
* If a spritesheet with that resolved path is already registered it is reused;
|
|
* otherwise one is claimed from the pool and loaded. On failure both the sprite
|
|
* and any sheet loaded for it are released again.
|
|
*
|
|
* @param filename Path to the JSON document. Required. Must be shorter than
|
|
* #AKGL_MAX_STRING_LENGTH -- it is copied into a pooled string
|
|
* so `dirname` can be taken without modifying the caller's
|
|
* buffer.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p filename is `NULL`, or if the file cannot be
|
|
* opened or does not parse. The message carries jansson's line number
|
|
* and text.
|
|
* @throws AKERR_OUTOFBOUNDS If @p filename is at least #AKGL_MAX_STRING_LENGTH
|
|
* bytes long, or if the `frames` array is indexed past its end.
|
|
* @throws AKERR_KEY If a required key is absent, or if the sprite or sheet
|
|
* cannot be added to its registry. The message names the key.
|
|
* @throws AKERR_TYPE If a key is present with the wrong JSON type -- `speed` as
|
|
* a string, `frames` as an object.
|
|
* @throws AKGL_ERR_SDL If the spritesheet image fails to load.
|
|
* @throws AKGL_ERR_HEAP If the sprite, spritesheet, or string pool is exhausted.
|
|
*
|
|
* @note The `frames` array is not bounded against #AKGL_SPRITE_MAX_FRAMES. A
|
|
* definition with more than 16 frames writes past `frameids` into the
|
|
* rest of the struct.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_sprite_load_json(char *filename);
|
|
|
|
/**
|
|
* @brief Work out where one animation frame sits on its spritesheet.
|
|
*
|
|
* Frames are numbered in reading order across the sheet: multiply the frame
|
|
* number by the sprite width, then wrap whole rows off the right-hand edge of
|
|
* the texture and step down by the sprite height for each. Callers use the
|
|
* result as the source rectangle for `SDL_RenderTexture`.
|
|
*
|
|
* @param self The sprite whose sheet and frame geometry to use. Required,
|
|
* along with its `sheet`.
|
|
* @param srccoords Receives the frame's rectangle on the sheet, in pixels.
|
|
* Required -- the return value is the error context.
|
|
* @param frameid Index into the sprite's `frameids` array, not a frame number
|
|
* on the sheet. Not bounds-checked against `frames` or
|
|
* #AKGL_SPRITE_MAX_FRAMES; an out-of-range index reads a
|
|
* neighbouring struct member and yields a nonsense rectangle
|
|
* rather than an error.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p self, @p srccoords, or `self->sheet` is
|
|
* `NULL`. Note that `sheet->texture` is dereferenced without a check,
|
|
* so a registered-but-unloaded sheet is a crash rather than an error.
|
|
*/
|
|
akerr_ErrorContext *akgl_spritesheet_coords_for_frame(akgl_Sprite *self, SDL_FRect *srccoords, uint8_t frameid);
|
|
|
|
#endif //_AKGL_SPRITE_H_
|