andrew/libakgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document the libakgl API with Doxygen

Browse Source 
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>
This commit is contained in:
Andrew Kesterson
2026-07-30 01:10:31 -04:00
parent a2995e81df
commit 549b27d3eb
38 changed files with 1323 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
include/akgl/actor.h
View File

@@ -1,3 +1,8 @@
/**
* @file actor.h
* @brief Declares the public actor API.
*/
#ifndef _AKGL_ACTOR_H_
#define _AKGL_ACTOR_H_
@@ -48,6 +53,7 @@
// This is an array of strings equal to actor states from 1-32.
// This is built by a utility script and not kept in git, see
// the Makefile for lib_src/actor_state_string_names.c
/** @brief Maps actor-state bit positions to symbolic names. */
extern char *AKGL_ACTOR_STATE_STRING_NAMES[AKGL_ACTOR_MAX_STATES+1];
#define AKGL_ACTOR_STATE_FACE_ALL (AKGL_ACTOR_STATE_FACE_DOWN | AKGL_ACTOR_STATE_FACE_LEFT | AKGL_ACTOR_STATE_FACE_RIGHT | AKGL_ACTOR_STATE_FACE_UP)
@@ -58,6 +64,7 @@ extern char *AKGL_ACTOR_STATE_STRING_NAMES[AKGL_ACTOR_MAX_STATES+1];
#define AKGL_MAX_HEAP_ACTOR 64
/** @brief Represents a live actor, including state, motion, hierarchy, and behavior callbacks. */
typedef struct akgl_Actor {
uint8_t refcount;
char name[AKGL_ACTOR_MAX_NAME_LENGTH];
@@ -110,24 +117,146 @@ typedef struct akgl_Actor {
akerr_ErrorContext AKERR_NOIGNORE *(*addchild)(struct akgl_Actor *obj, struct akgl_Actor *child);
} akgl_Actor;
/**
* @brief Actor initialize.
* @param obj Object to initialize, inspect, or modify.
* @param name Registry key or human-readable object name.
* @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_actor_initialize(akgl_Actor *obj, char *name);
/**
* @brief Actor set character.
* @param obj Object to initialize, inspect, or modify.
* @param basecharname Registry name of the character to assign.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_set_character(akgl_Actor *obj, char *basecharname);
/**
* @brief Actor render.
* @param obj Object to initialize, inspect, or modify.
* @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 AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_render(akgl_Actor *obj);
/**
* @brief Actor update.
* @param obj Object to initialize, inspect, or modify.
* @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_actor_update(akgl_Actor *obj);
/**
* @brief Actor logic movement.
* @param obj Object to initialize, inspect, or modify.
* @param dt Elapsed simulation time in seconds.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_logic_movement(akgl_Actor *obj, float32_t dt);
/**
* @brief Actor logic changeframe.
* @param obj Object to initialize, inspect, or modify.
* @param curSprite Sprite currently selected for the actor.
* @param curtimems Current frame-clock value.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_logic_changeframe(akgl_Actor *obj, akgl_Sprite *curSprite, SDL_Time curtimems);
/**
* @brief Actor automatic face.
* @param obj Object to initialize, inspect, or modify.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_automatic_face(akgl_Actor *obj);
/**
* @brief Actor add child.
* @param obj Object to initialize, inspect, or modify.
* @param child Actor to attach as a child.
* @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.
* @throws AKERR_RELATIONSHIP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_actor_add_child(akgl_Actor *obj, akgl_Actor *child);
/**
* @brief Actor cmhf left on.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_left_on(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf left off.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_left_off(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf right on.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_right_on(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf right off.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_right_off(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf up on.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_up_on(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf up off.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_up_off(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf down on.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_down_on(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Actor cmhf down off.
* @param obj Object to initialize, inspect, or modify.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_Actor_cmhf_down_off(akgl_Actor *obj, SDL_Event *event);
/**
* @brief Registry iterate actor.
* @param userdata Caller data supplied to the SDL property iterator.
* @param registry SDL property registry being queried.
* @param name Registry key or human-readable object name.
*/
void akgl_registry_iterate_actor(void *userdata, SDL_PropertiesID registry, const char *name);
#endif // _AKGL_ACTOR_H_

12
include/akgl/assets.h
View File

@@ -1,8 +1,20 @@
/**
* @file assets.h
* @brief Declares the public assets API.
*/
#ifndef _ASSETS_H_
#define _ASSETS_H_
#include <akerror.h>
/**
* @brief Load start bgm.
* @param fname Path to the input or output file.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @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_load_start_bgm(char *fname);
#endif //_ASSETS_H_

43
include/akgl/character.h
View File

@@ -1,3 +1,8 @@
/**
* @file character.h
* @brief Declares the public character API.
*/
#ifndef _AKGL_CHARACTER_H_
#define _AKGL_CHARACTER_H_
@@ -8,6 +13,7 @@
#define AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH 128
#define AKGL_MAX_HEAP_CHARACTER 256
/** @brief Defines reusable movement parameters and actor-state sprite bindings. */
typedef struct akgl_Character {
uint8_t refcount;
char name[AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH];
@@ -24,13 +30,50 @@ typedef struct akgl_Character {
} akgl_Character;
/**
* @brief Character initialize.
* @param basechar Character whose state-to-sprite map is accessed.
* @param name Registry key or human-readable object name.
* @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_character_initialize(akgl_Character *basechar, char *name);
/**
* @brief Character sprite add.
* @param basechar Character whose state-to-sprite map is accessed.
* @param ref Sprite reference to associate with the character.
* @param state Actor-state bit mask used as a sprite-map key.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_sprite_add(akgl_Character *basechar, akgl_Sprite *ref, int state);
/**
* @brief Character sprite get.
* @param basechar Character whose state-to-sprite map is accessed.
* @param state Actor-state bit mask used as a sprite-map key.
* @param dest Output destination populated by the function.
* @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_character_sprite_get(akgl_Character *basechar, int state, akgl_Sprite **dest);
// This is an SDL iterator so we can't return our error state from it.
/**
* @brief Character state sprites iterate.
* @param userdata Caller data supplied to the SDL property iterator.
* @param props SDL property collection being iterated.
* @param name Registry key or human-readable object name.
*/
void akgl_character_state_sprites_iterate(void *userdata, SDL_PropertiesID props, const char *name);
/**
* @brief Character 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.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_load_json(char *filename);
#endif // _AKGL_CHARACTER_H_

71
include/akgl/controller.h
View File

@@ -1,3 +1,8 @@
/**
* @file controller.h
* @brief Declares the public controller API.
*/
#ifndef _CONTROLLER_H_
#define _CONTROLLER_H_
@@ -8,6 +13,7 @@
#define AKGL_MAX_CONTROL_MAPS 8
#define AKGL_MAX_CONTROLS 32
/** @brief Maps one SDL input to pressed and released callbacks. */
typedef struct {
uint32_t event_on;
uint32_t event_off;
@@ -20,6 +26,7 @@ typedef struct {
akerr_ErrorContext AKERR_NOIGNORE *(*handler_off)(akgl_Actor *obj, SDL_Event *event);
} akgl_Control;
/** @brief Groups input bindings for one actor and its input devices. */
typedef struct {
akgl_Actor *target;
uint16_t nextMap;
@@ -30,20 +37,84 @@ typedef struct {
SDL_PenID penid;
} akgl_ControlMap;
/** @brief Stores all process-wide actor input maps. */
extern akgl_ControlMap GAME_ControlMaps[AKGL_MAX_CONTROL_MAPS];
/**
* @brief Controller list keyboards.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_list_keyboards(void);
/**
* @brief Controller handle event.
* @param appstate Application state supplied by SDL.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_event(void *appstate, SDL_Event *event);
/**
* @brief Controller handle button down.
* @param appstate Application state supplied by SDL.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_button_down(void *appstate, SDL_Event *event);
/**
* @brief Controller handle button up.
* @param appstate Application state supplied by SDL.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_button_up(void *appstate, SDL_Event *event);
/**
* @brief Controller handle added.
* @param appstate Application state supplied by SDL.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_added(void *appstate, SDL_Event *event);
/**
* @brief Controller handle removed.
* @param appstate Application state supplied by SDL.
* @param event SDL input event to process.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_handle_removed(void *appstate, SDL_Event *event);
/**
* @brief Controller pushmap.
* @param controlmapid Index of the control map to update.
* @param control Control binding to append to the selected map.
* @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_controller_pushmap(int controlmapid, akgl_Control *control);
/**
* @brief Controller default.
* @param controlmapid Index of the control map to update.
* @param actorname Registry name of the controlled actor.
* @param kbid SDL keyboard identifier assigned to the map.
* @param jsid SDL joystick or gamepad identifier assigned to the map.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
* @throws AKGL_ERR_REGISTRY When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_default(int controlmapid, char *actorname, int kbid, int jsid);
/**
* @brief Controller open gamepads.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_open_gamepads(void);
#endif // _CONTROLLER_H_

10
include/akgl/draw.h
View File

@@ -1,6 +1,16 @@
/**
* @file draw.h
* @brief Declares the public draw API.
*/
#ifndef _DRAW_H_
#define _DRAW_H_
/**
* @brief Draw background.
* @param w Destination width.
* @param h Destination height.
*/
void akgl_draw_background(int w, int h);
#endif //_DRAW_H_

5
include/akgl/error.h
View File

@@ -1,3 +1,8 @@
/**
* @file error.h
* @brief Declares the public error API.
*/
#ifndef _ERROR_H_
#define _ERROR_H_

67
include/akgl/game.h
View File

@@ -1,3 +1,8 @@
/**
* @file game.h
* @brief Declares the public game API.
*/
#ifndef _AKGL_GAME_H_
#define _AKGL_GAME_H_
@@ -18,16 +23,19 @@
/* ==================== GAME STATE VARIABLES =================== */
/** @brief Describes a renderable frame. */
typedef struct {
float32_t w;
float32_t h;
SDL_Texture *texture;
} akgl_Frame;
/** @brief Stores application-defined game-state flags. */
typedef struct {
int32_t flags;
} akgl_GameState;
/** @brief Stores game metadata, timing, synchronization, and FPS accounting. */
typedef struct {
char libversion[32];
char version[32];
@@ -43,19 +51,32 @@ typedef struct {
void (*lowfpsfunc)(void);
} akgl_Game;
/** @brief SDL window used by the active renderer. */
extern SDL_Window *window;
/** @brief Loaded background-music resource. */
extern MIX_Audio *bgm;
/** @brief Mixer used for game audio playback. */
extern MIX_Mixer *akgl_mixer;
/** @brief Process-wide audio-track table. */
extern MIX_Track *akgl_tracks[AKGL_GAME_AUDIO_MAX_TRACKS];
/** @brief Storage for the default camera. */
extern SDL_FRect _akgl_camera;
/** @brief Process-wide game metadata and timing state. */
extern akgl_Game game;
/** @brief Storage for the default renderer. */
extern akgl_RenderBackend _akgl_renderer;
/** @brief Storage for the default physics backend. */
extern akgl_PhysicsBackend _akgl_physics;
/** @brief Storage for the default tilemap. */
extern akgl_Tilemap _akgl_gamemap;
/** @brief Currently active tilemap. */
extern akgl_Tilemap *gamemap;
/** @brief Currently active renderer. */
extern akgl_RenderBackend *renderer;
/** @brief Currently active physics backend. */
extern akgl_PhysicsBackend *physics;
/** @brief Currently active camera. */
extern SDL_FRect *camera;
#define AKGL_BITMASK_HAS(x, y) (x & y) == y
@@ -64,14 +85,60 @@ extern SDL_FRect *camera;
#define AKGL_BITMASK_DEL(x, y) x &= ~(y)
#define AKGL_BITMASK_CLEAR(x) x = 0;
/**
* @brief Game init.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @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_game_init();
/**
* @brief Game init screen.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_init_screen();
/**
* @brief Game updatefps.
*/
void akgl_game_updateFPS();
/**
* @brief Game save.
* @param fpath Path to the input or output file.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_save(char *fpath);
/**
* @brief Game load.
* @param fpath Path to the input or output file.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_API When the corresponding validation or operation fails.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load(char *fpath);
/**
* @brief Game lowfps.
*/
void akgl_game_lowfps(void);
/**
* @brief Game state lock.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_state_lock(void);
/**
* @brief Game state unlock.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_state_unlock(void);
/**
* @brief Game update.
* @param opflags Optional iterator operation flags; `NULL` selects defaults.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_game_update(akgl_Iterator *opflags);
#endif //_AKGL_GAME_H_

84
include/akgl/heap.h
View File

@@ -1,3 +1,8 @@
/**
* @file heap.h
* @brief Declares the public heap API.
*/
#ifndef _AKGL_HEAP_H_
#define _AKGL_HEAP_H_
@@ -23,24 +28,103 @@
#define AKGL_MAX_HEAP_STRING 256
#endif
/** @brief Fixed-capacity actor object pool. */
extern akgl_Actor HEAP_ACTOR[AKGL_MAX_HEAP_ACTOR];
/** @brief Fixed-capacity sprite object pool. */
extern akgl_Sprite HEAP_SPRITE[AKGL_MAX_HEAP_SPRITE];
/** @brief Fixed-capacity spritesheet object pool. */
extern akgl_SpriteSheet HEAP_SPRITESHEET[AKGL_MAX_HEAP_SPRITESHEET];
/** @brief Fixed-capacity character object pool. */
extern akgl_Character HEAP_CHARACTER[AKGL_MAX_HEAP_CHARACTER];
/** @brief Fixed-capacity static-string object pool. */
extern akgl_String HEAP_STRING[AKGL_MAX_HEAP_STRING];
/**
* @brief Heap init.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_BEHAVIOR When the corresponding validation or operation fails.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
* @throws AKGL_ERR_LOGICINTERRUPT When the corresponding validation or operation fails.
* @throws AKGL_ERR_REGISTRY When the corresponding validation or operation fails.
* @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_init();
/**
* @brief Heap init actor.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_init_actor();
/**
* @brief Heap next actor.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_actor(akgl_Actor **dest);
/**
* @brief Heap next sprite.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_sprite(akgl_Sprite **dest);
/**
* @brief Heap next spritesheet.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_spritesheet(akgl_SpriteSheet **dest);
/**
* @brief Heap next character.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_character(akgl_Character **dest);
/**
* @brief Heap next string.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKGL_ERR_HEAP When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_string(akgl_String **dest);
/**
* @brief Heap release actor.
* @param ptr Heap object whose reference count is decremented.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_actor(akgl_Actor *ptr);
/**
* @brief Heap release sprite.
* @param ptr Heap object whose reference count is decremented.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_sprite(akgl_Sprite *ptr);
/**
* @brief Heap release spritesheet.
* @param ptr Heap object whose reference count is decremented.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_spritesheet(akgl_SpriteSheet *ptr);
/**
* @brief Heap release character.
* @param ptr Heap object whose reference count is decremented.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_character(akgl_Character *ptr);
/**
* @brief Heap release string.
* @param ptr Heap object whose reference count is decremented.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_string(akgl_String *ptr);
#endif //_AKGL_HEAP_H_

6
include/akgl/iterator.h
View File

@@ -1,6 +1,12 @@
/**
* @file iterator.h
* @brief Declares the public iterator API.
*/
#ifndef _AKGL_ITERATOR_H_
#define _AKGL_ITERATOR_H_
/** @brief Selects operations and an optional layer for actor traversal. */
typedef struct {
uint32_t flags;
uint8_t layerid;

116
include/akgl/json_helpers.h
View File

@@ -1,20 +1,136 @@
/**
* @file json_helpers.h
* @brief Declares the public json helpers API.
*/
#ifndef _JSON_HELPERS_H_
#define _JSON_HELPERS_H_
#include <akerror.h>
#include "staticstring.h"
/**
* @brief Get json object value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_object_value(json_t *obj, char *key, json_t **dest);
/**
* @brief Get json boolean value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_boolean_value(json_t *obj, char *key, bool *dest);
/**
* @brief Get json integer value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_integer_value(json_t *obj, char *key, int *dest);
/**
* @brief Get json number value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_number_value(json_t *obj, char *key, float *dest);
/**
* @brief Get json double value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_double_value(json_t *obj, char *key, double *dest);
/**
* @brief Get json string value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_string_value(json_t *obj, char *key, akgl_String **dest);
/**
* @brief Get json array value.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_array_value(json_t *obj, char *key, json_t **dest);
/**
* @brief Get json array index object.
* @param array JSON array to read.
* @param index Zero-based element index.
* @param dest Output destination populated by the function.
* @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.
* @throws AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_array_index_object(json_t *array, int index, json_t **dest);
/**
* @brief Get json array index integer.
* @param array JSON array to read.
* @param index Zero-based element index.
* @param dest Output destination populated by the function.
* @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.
* @throws AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_array_index_integer(json_t *array, int index, int *dest);
/**
* @brief Get json array index string.
* @param array JSON array to read.
* @param index Zero-based element index.
* @param dest Output destination populated by the function.
* @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.
* @throws AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_array_index_string(json_t *array, int index, akgl_String **dest);
/**
* @brief Get json with default.
* @param e Error context to inspect and optionally consume.
* @param defval Fallback value copied when the supplied error is eligible.
* @param dest Output destination populated by the function.
* @param defsize Size in bytes of the fallback value.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_INDEX When the corresponding validation or operation fails.
* @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_get_json_with_default(akerr_ErrorContext *e, void *defval, void *dest, uint32_t defsize);
#endif // _JSON_HELPERS_H_

83
include/akgl/physics.h
View File

@@ -1,3 +1,8 @@
/**
* @file physics.h
* @brief Declares the public physics API.
*/
#ifndef _PHYSICS_H_
#define _PHYSICS_H_
@@ -7,6 +12,7 @@
#include <akgl/iterator.h>
#include <akgl/staticstring.h>
/** @brief Defines a pluggable physics backend and its environmental parameters. */
typedef struct akgl_PhysicsBackend {
akerr_ErrorContext AKERR_NOIGNORE *(*simulate)(struct akgl_PhysicsBackend *self, akgl_Iterator *opflags);
akerr_ErrorContext AKERR_NOIGNORE *(*gravity)(struct akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
@@ -23,19 +29,96 @@ typedef struct akgl_PhysicsBackend {
SDL_Time timer_gravity;
} akgl_PhysicsBackend;
/**
* @brief Physics null gravity.
* @param self Backend or object instance to operate on.
* @param actor Actor to inspect or modify.
* @param dt Elapsed simulation time in seconds.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_null_gravity(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
* @brief Physics null collide.
* @param self Backend or object instance to operate on.
* @param a1 First actor supplied to collision handling.
* @param a2 Second actor supplied to collision handling.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_null_collide(akgl_PhysicsBackend *self, akgl_Actor *a1, akgl_Actor *a2);
/**
* @brief Physics null move.
* @param self Backend or object instance to operate on.
* @param actor Actor to inspect or modify.
* @param dt Elapsed simulation time in seconds.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_null_move(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
* @brief Physics init null.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_init_null(akgl_PhysicsBackend *self);
/**
* @brief Physics arcade gravity.
* @param self Backend or object instance to operate on.
* @param actor Actor to inspect or modify.
* @param dt Elapsed simulation time in seconds.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_arcade_gravity(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
* @brief Physics arcade collide.
* @param self Backend or object instance to operate on.
* @param a1 First actor supplied to collision handling.
* @param a2 Second actor supplied to collision handling.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_API When the corresponding validation or operation fails.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_arcade_collide(akgl_PhysicsBackend *self, akgl_Actor *a1, akgl_Actor *a2);
/**
* @brief Physics arcade move.
* @param self Backend or object instance to operate on.
* @param actor Actor to inspect or modify.
* @param dt Elapsed simulation time in seconds.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_arcade_move(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
* @brief Physics init arcade.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_init_arcade(akgl_PhysicsBackend *self);
/**
* @brief Physics factory.
* @param self Backend or object instance to operate on.
* @param type Expected JSON property type or backend type name.
* @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_physics_factory(akgl_PhysicsBackend *self, akgl_String *type);
/**
* @brief Physics simulate.
* @param self Backend or object instance to operate on.
* @param opflags Optional iterator operation flags; `NULL` selects defaults.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
* @throws AKGL_ERR_LOGICINTERRUPT When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_simulate(akgl_PhysicsBackend *self, akgl_Iterator *opflags);
#endif // _PHYSICS_H_

79
include/akgl/registry.h
View File

@@ -1,29 +1,108 @@
/**
* @file registry.h
* @brief Declares the public registry API.
*/
#ifndef _REGISTRY_H_
#define _REGISTRY_H_
#include <akgl/error.h>
#include <akgl/staticstring.h>
/** @brief Registry of actors keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR;
/** @brief Registry of sprites keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_SPRITE;
/** @brief Registry of spritesheets keyed by asset path. */
extern SDL_PropertiesID AKGL_REGISTRY_SPRITESHEET;
/** @brief Registry of characters keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_CHARACTER;
/** @brief Registry mapping actor-state names to bit values. */
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR_STATE_STRINGS;
/** @brief Registry of fonts keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_FONT;
/** @brief Registry of music assets keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_MUSIC;
/** @brief Registry of string configuration properties. */
extern SDL_PropertiesID AKGL_REGISTRY_PROPERTIES;
/**
* @brief Registry init.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init();
/**
* @brief Registry init music.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_music();
/**
* @brief Registry init font.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_font();
/**
* @brief Registry init actor.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor();
/**
* @brief Registry init sprite.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_sprite();
/**
* @brief Registry init spritesheet.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_spritesheet();
/**
* @brief Registry init character.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_character();
/**
* @brief Registry init properties.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_properties();
/**
* @brief Registry load properties.
* @param fname Path to the input or output file.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_load_properties(char *fname);
/**
* @brief Registry init actor state strings.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor_state_strings();
/**
* @brief Set property.
* @param name Registry key or human-readable object name.
* @param value Property value to store.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_set_property(char *name, char *value);
/**
* @brief Get property.
* @param name Registry key or human-readable object name.
* @param dest Output destination populated by the function.
* @param def Fallback string returned when the property is absent.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_property(char *name, akgl_String **dest, char *def);
#endif //_REGISTRY_H_

56
include/akgl/renderer.h
View File

@@ -1,3 +1,8 @@
/**
* @file renderer.h
* @brief Declares the public renderer API.
*/
#ifndef _RENDERER_H_
#define _RENDERER_H_
@@ -7,6 +12,7 @@
#include <akgl/iterator.h>
/** @brief Defines a pluggable renderer backend and drawing callbacks. */
typedef struct akgl_RenderBackend {
SDL_Renderer *sdl_renderer;
akerr_ErrorContext AKERR_NOIGNORE *(*shutdown)(struct akgl_RenderBackend *self);
@@ -17,13 +23,63 @@ typedef struct akgl_RenderBackend {
akerr_ErrorContext AKERR_NOIGNORE *(*draw_world)(struct akgl_RenderBackend *self, akgl_Iterator *opflags);
} akgl_RenderBackend;
/**
* @brief Render 2d shutdown.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_shutdown(akgl_RenderBackend *self);
/**
* @brief Render 2d frame start.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_frame_start(akgl_RenderBackend *self);
/**
* @brief Render 2d frame end.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_frame_end(akgl_RenderBackend *self);
/**
* @brief Render 2d draw texture.
* @param self Backend or object instance to operate on.
* @param texture SDL texture to draw.
* @param src Source value to copy or inspect.
* @param dest Output destination populated by the function.
* @param angle Clockwise rotation angle in degrees.
* @param center Optional rotation center.
* @param flip SDL texture flip mode.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_draw_texture(akgl_RenderBackend *self, SDL_Texture *texture, SDL_FRect *src, SDL_FRect *dest, double angle, SDL_FPoint *center, SDL_FlipMode flip);
/**
* @brief Render 2d draw mesh.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_API When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_draw_mesh(akgl_RenderBackend *self);
/**
* @brief Render 2d draw world.
* @param self Backend or object instance to operate on.
* @param opflags Optional iterator operation flags; `NULL` selects defaults.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_render_2d_draw_world(akgl_RenderBackend *self, akgl_Iterator *opflags);
/**
* @brief Render init2d.
* @param self Backend or object instance to operate on.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @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_render_init2d(akgl_RenderBackend *self);
#endif // _RENDERER_H_

42
include/akgl/sprite.h
View File

@@ -1,3 +1,8 @@
/**
* @file sprite.h
* @brief Declares the public sprite API.
*/
#ifndef _AKGL_SPRITE_H_
#define _AKGL_SPRITE_H_
@@ -14,6 +19,7 @@
#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;
@@ -22,6 +28,7 @@ typedef struct {
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
@@ -36,11 +43,46 @@ typedef struct {
} 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_

21
include/akgl/staticstring.h
View File

@@ -1,3 +1,8 @@
/**
* @file staticstring.h
* @brief Declares the public staticstring API.
*/
#ifndef _STRING_H_
#define _STRING_H_
@@ -7,12 +12,28 @@
#define AKGL_MAX_STRING_LENGTH PATH_MAX
/** @brief Provides a fixed-capacity, heap-managed string buffer. */
typedef struct
{
int refcount;
char data[AKGL_MAX_STRING_LENGTH];
} akgl_String;
/**
* @brief String initialize.
* @param obj Object to initialize, inspect, or modify.
* @param init Optional initial string contents; `NULL` clears the buffer.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_string_initialize(akgl_String *obj, char *init);
/**
* @brief String copy.
* @param src Source value to copy or inspect.
* @param dst Output destination populated by the function.
* @param count Maximum number of elements or bytes to process; zero selects the default.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_string_copy(akgl_String *src, akgl_String *dst, int count);
#endif //_STRING_H_

26
include/akgl/text.h
View File

@@ -1,9 +1,35 @@
/**
* @file text.h
* @brief Declares the public text API.
*/
#ifndef _TEXT_H_
#define _TEXT_H_
#include <SDL3_ttf/SDL_ttf.h>
/**
* @brief Text loadfont.
* @param name Registry key or human-readable object name.
* @param filepath Path to the requested file.
* @param size Requested font size.
* @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_text_loadfont(char *name, char *filepath, int size);
/**
* @brief Text rendertextat.
* @param font Font used to render the text.
* @param text UTF-8 text to render.
* @param color Text color.
* @param wraplength Maximum rendered line width; zero disables wrapping.
* @param x Horizontal destination coordinate.
* @param y Vertical destination coordinate.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_rendertextat(TTF_Font *font, char *text, SDL_Color color, int wraplength, int x, int y);
#endif // _TEXT_H_

125
include/akgl/tilemap.h
View File

@@ -1,3 +1,8 @@
/**
* @file tilemap.h
* @brief Declares the public tilemap API.
*/
#ifndef _TILEMAP_H_
#define _TILEMAP_H_
@@ -23,6 +28,7 @@
#define AKGL_TILEMAP_LAYER_TYPE_OBJECTS 2
#define AKGL_TILEMAP_LAYER_TYPE_IMAGE 3
/** @brief Stores tileset metadata, texture, and frame offsets. */
typedef struct {
float x;
float y;
@@ -37,6 +43,7 @@ typedef struct {
char name[AKGL_TILEMAP_MAX_OBJECT_NAME_SIZE];
} akgl_TilemapObject;
/** @brief Represents an object embedded in a tilemap layer. */
typedef struct {
short type;
float opacity;
@@ -51,6 +58,7 @@ typedef struct {
akgl_TilemapObject objects[AKGL_TILEMAP_MAX_OBJECTS_PER_LAYER];
} akgl_TilemapLayer;
/** @brief Stores tile, image, or object data for one map layer. */
typedef struct {
int columns;
int firstgid;
@@ -81,6 +89,7 @@ typedef struct {
int margin;
} akgl_Tileset;
/** @brief Represents a complete tilemap and its optional physics backend. */
typedef struct {
int tilewidth;
int tileheight;
@@ -105,8 +114,32 @@ typedef struct {
akgl_PhysicsBackend physics;
} akgl_Tilemap;
/**
* @brief Tilemap load.
* @param fname Path to the input or output file.
* @param dest Output destination populated by the function.
* @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_tilemap_load(char *fname, akgl_Tilemap *dest);
/**
* @brief Tilemap draw.
* @param dest Output destination populated by the function.
* @param viewport World-space rectangle visible to the renderer.
* @param layeridx Zero-based tilemap layer index.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_draw(akgl_Tilemap *dest, SDL_FRect *viewport, int layeridx);
/**
* @brief Tilemap draw tileset.
* @param dest Output destination populated by the function.
* @param tilesetidx Zero-based tileset index.
* @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_tilemap_draw_tileset(akgl_Tilemap *dest, int tilesetidx);
/*
@@ -114,16 +147,108 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_draw_tileset(akgl_Tilemap *dest,
* They are only exposed here for unit testing.
*/
/**
* @brief Get json tilemap property.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param type Expected JSON property type or backend type name.
* @param dest Output destination populated by the function.
* @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 AKERR_TYPE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_tilemap_property(json_t *obj, char *key, char *type, json_t **dest);
/**
* @brief Get json properties string.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_properties_string(json_t *obj, char *key, akgl_String **dest);
/**
* @brief Get json properties integer.
* @param obj Object to initialize, inspect, or modify.
* @param key JSON object key or property name to locate.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_json_properties_integer(json_t *obj, char *key, int *dest);
/**
* @brief Tilemap compute tileset offsets.
* @param dest Output destination populated by the function.
* @param tilesetidx Zero-based tileset index.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_* Propagates an error reported by a delegated operation.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_compute_tileset_offsets(akgl_Tilemap *dest, int tilesetidx);
/**
* @brief Tilemap load layer objects.
* @param dest Output destination populated by the function.
* @param root Base directory used to resolve the path.
* @param layerid Zero-based tilemap layer index.
* @param dirname Directory containing paths referenced by the document.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_load_layer_objects(akgl_Tilemap *dest, json_t *root, int layerid, akgl_String *dirname);
/**
* @brief Tilemap load layer tile.
* @param dest Output destination populated by the function.
* @param root Base directory used to resolve the path.
* @param layerid Zero-based tilemap layer index.
* @param dirname Directory containing paths referenced by the 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_tilemap_load_layer_tile(akgl_Tilemap *dest, json_t *root, int layerid, akgl_String *dirname);
/**
* @brief Tilemap load layers.
* @param dest Output destination populated by the function.
* @param root Base directory used to resolve the path.
* @param dirname Directory containing paths referenced by the 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_tilemap_load_layers(akgl_Tilemap *dest, json_t *root, akgl_String *dirname);
/**
* @brief Tilemap load tilesets each.
* @param tileset JSON tileset object to load.
* @param dest Output destination populated by the function.
* @param tsidx Zero-based destination tileset index.
* @param dirname Directory containing paths referenced by the document.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_load_tilesets_each(json_t *tileset, akgl_Tilemap *dest, int tsidx, akgl_String *dirname);
/**
* @brief Tilemap load tilesets.
* @param dest Output destination populated by the function.
* @param root Base directory used to resolve the path.
* @param dirname Directory containing paths referenced by the document.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_load_tilesets(akgl_Tilemap *dest, json_t *root, akgl_String *dirname);
/**
* @brief Tilemap release.
* @param dest Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_release(akgl_Tilemap *dest);
/**
* @brief Tilemap scale actor.
* @param map Tilemap to inspect, draw, or modify.
* @param actor Actor to inspect or modify.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_tilemap_scale_actor(akgl_Tilemap *map, akgl_Actor *actor);
#endif //_TILEMAP_H_

5
include/akgl/types.h
View File

@@ -1,3 +1,8 @@
/**
* @file types.h
* @brief Declares the public types API.
*/
#ifndef _AKGL_TYPES_H_
#define _AKGL_TYPES_H_

60
include/akgl/util.h
View File

@@ -1,15 +1,22 @@
/**
* @file util.h
* @brief Declares the public util API.
*/
#ifndef _UTIL_H_
#define _UTIL_H_
#include <akerror.h>
#include <akgl/staticstring.h>
/** @brief Represents a two-dimensional point. */
typedef struct point {
int x;
int y;
int z;
} point;
/** @brief Stores the corners of an axis-aligned rectangle. */
typedef struct RectanglePoints {
point topleft;
point topright;
@@ -19,14 +26,67 @@ typedef struct RectanglePoints {
#define AKGL_COLLIDE_RECTANGLES(r1x, r1y, r1w, r1h, r2x, r2y, r2w, r2h) ((r1x < (r2x + r2w)) || ((r1x + r1w) > r2x)
/**
* @brief Rectangle points.
* @param dest Output destination populated by the function.
* @param rect Rectangle whose corner points are calculated.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_rectangle_points(RectanglePoints *dest, SDL_FRect *rect);
/**
* @brief Collide point rectangle.
* @param p Point to test for containment.
* @param r Rectangle corner data used for collision testing.
* @param collide Output set to whether the tested geometry intersects.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_collide_point_rectangle(point *p, RectanglePoints *r, bool *collide);
/**
* @brief Collide rectangles.
* @param r1 First rectangle to compare.
* @param r2 Second rectangle to compare.
* @param collide Output set to whether the tested geometry intersects.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_collide_rectangles(SDL_FRect *r1, SDL_FRect *r2, bool *collide);
/**
* @brief Path relative.
* @param root Base directory used to resolve the path.
* @param path Path to resolve or transform.
* @param dst Output destination populated by the function.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_path_relative(char *root, char *path, akgl_String *dst);
// These are REALLY slow routines that are only useful in testing harnesses
/**
* @brief Compare sdl surfaces.
* @param s1 First SDL surface to compare.
* @param s2 Second SDL surface to compare.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
* @throws AKERR_VALUE When the corresponding validation or operation fails.
*/
akerr_ErrorContext AKERR_NOIGNORE *akgl_compare_sdl_surfaces(SDL_Surface *s1, SDL_Surface *s2);
/**
* @brief Render and compare.
* @param t1 First texture to render for comparison.
* @param t2 Second texture to render for comparison.
* @param x Horizontal destination coordinate.
* @param y Vertical destination coordinate.
* @param w Destination width.
* @param h Destination height.
* @param writeout Optional filename for the rendered diagnostic image.
* @return `NULL` on success, otherwise an error context owned by the caller.
* @throws AKERR_IO 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_render_and_compare(SDL_Texture *t1, SDL_Texture *t2, int x, int y, int w, int h, char *writeout);
#endif // _UTIL_H_