Andrew Kesterson
549b27d3eb
Add file, structure, global, and function documentation across all libakgl-owned headers and sources, including parameter contracts and likely AKERR/AKGL_ERR exceptions. Add a strict Doxyfile and build the generated API documentation in Gitea CI with warnings treated as failures. Co-authored-by: Codex (GPT-5) <noreply@openai.com>
89 lines
3.7 KiB
C
89 lines
3.7 KiB
C
/**
|
|
* @file sprite.h
|
|
* @brief Declares the public sprite API.
|
|
*/
|
|
|
|
#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
|
|
|
|
#define AKGL_MAX_HEAP_SPRITE (AKGL_MAX_HEAP_ACTOR * 16)
|
|
#define AKGL_MAX_HEAP_SPRITESHEET AKGL_MAX_HEAP_SPRITE
|
|
|
|
/** @brief Stores a loaded spritesheet texture and frame geometry. */
|
|
typedef struct {
|
|
uint8_t refcount;
|
|
SDL_Texture *texture;
|
|
char name[AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH];
|
|
uint16_t sprite_w;
|
|
uint16_t sprite_h;
|
|
} akgl_SpriteSheet;
|
|
|
|
/** @brief Describes an animated sprite and its spritesheet reference. */
|
|
typedef struct {
|
|
uint8_t refcount;
|
|
uint8_t frameids[AKGL_SPRITE_MAX_FRAMES]; // which IDs on the spritesheet belong to our frames
|
|
uint32_t frames; // how many frames are in this animation
|
|
uint32_t width;
|
|
uint32_t height;
|
|
uint32_t speed; // how many milliseconds a given sprite frame should be visible before cycling
|
|
bool loop; // when this sprite is done playing, it should immediately start again
|
|
bool loopReverse; // when this sprite is done playing, it should go in reverse order through its frames
|
|
char name[AKGL_SPRITE_MAX_NAME_LENGTH];
|
|
akgl_SpriteSheet *sheet;
|
|
} akgl_Sprite;
|
|
|
|
// initializes a new sprite to use the given sheet and otherwise sets to zero
|
|
/**
|
|
* @brief Sprite initialize.
|
|
* @param spr Sprite object to initialize.
|
|
* @param name Registry key or human-readable object name.
|
|
* @param sheet Spritesheet used by the sprite.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_KEY When the corresponding validation or operation fails.
|
|
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
|
|
*/
|
|
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 Spritesheet initialize.
|
|
* @param sheet Spritesheet used by the sprite.
|
|
* @param sprite_w Width of one sprite frame in pixels.
|
|
* @param sprite_h Height of one sprite frame in pixels.
|
|
* @param filename Path to the source asset or JSON document.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_KEY When the corresponding validation or operation fails.
|
|
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
|
|
* @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_spritesheet_initialize(akgl_SpriteSheet *sheet, int sprite_w, int sprite_h, char *filename);
|
|
/**
|
|
* @brief Sprite load json.
|
|
* @param filename Path to the source asset or JSON document.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
|
|
* @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_sprite_load_json(char *filename);
|
|
|
|
/**
|
|
* @brief Sprite sheet coords for frame.
|
|
* @param self Backend or object instance to operate on.
|
|
* @param srccoords Output source rectangle for the selected frame.
|
|
* @param frameid Sprite frame index to resolve.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
|
|
*/
|
|
akerr_ErrorContext *akgl_sprite_sheet_coords_for_frame(akgl_Sprite *self, SDL_FRect *srccoords, uint8_t frameid);
|
|
|
|
#endif //_AKGL_SPRITE_H_
|