diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 2319f7a..689a88a 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -14,7 +14,7 @@ jobs: run: | sudo apt-get update -y sudo apt-get install -y \ - cmake gcc pkg-config \ + cmake doxygen gcc pkg-config \ libasound2-dev libfreetype-dev libharfbuzz-dev \ libpng-dev libtiff-dev libwebp-dev \ libudev-dev libx11-dev libxcursor-dev libxext-dev \ @@ -24,6 +24,8 @@ jobs: run: | cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build --parallel + - name: Build API documentation + run: doxygen Doxyfile - name: Test (JUnit) run: | export LD_LIBRARY_PATH="$PWD/build:$PWD/build/deps/SDL:$PWD/build/deps/SDL_image:$PWD/build/deps/SDL_mixer:$PWD/build/deps/SDL_ttf" diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..5abb326 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,18 @@ +PROJECT_NAME = libakgl +PROJECT_BRIEF = "Game development support library" +OUTPUT_DIRECTORY = build/docs + +INPUT = include/akgl src +FILE_PATTERNS = *.h *.c +RECURSIVE = YES +EXCLUDE_PATTERNS = */SDL_GameControllerDB.h + +EXTRACT_ALL = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_AS_ERROR = FAIL_ON_WARNINGS + +GENERATE_HTML = YES +GENERATE_LATEX = NO +QUIET = YES diff --git a/include/akgl/actor.h b/include/akgl/actor.h index a5d16e9..b3020cc 100644 --- a/include/akgl/actor.h +++ b/include/akgl/actor.h @@ -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_ diff --git a/include/akgl/assets.h b/include/akgl/assets.h index 0ce126e..c901045 100644 --- a/include/akgl/assets.h +++ b/include/akgl/assets.h @@ -1,8 +1,20 @@ +/** + * @file assets.h + * @brief Declares the public assets API. + */ + #ifndef _ASSETS_H_ #define _ASSETS_H_ #include +/** + * @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_ diff --git a/include/akgl/character.h b/include/akgl/character.h index cb0c3f7..7e4952d 100644 --- a/include/akgl/character.h +++ b/include/akgl/character.h @@ -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_ diff --git a/include/akgl/controller.h b/include/akgl/controller.h index 5431321..8b8fb99 100644 --- a/include/akgl/controller.h +++ b/include/akgl/controller.h @@ -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_ diff --git a/include/akgl/draw.h b/include/akgl/draw.h index bce641e..71d01f4 100644 --- a/include/akgl/draw.h +++ b/include/akgl/draw.h @@ -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_ diff --git a/include/akgl/error.h b/include/akgl/error.h index e9782a3..0a29976 100644 --- a/include/akgl/error.h +++ b/include/akgl/error.h @@ -1,3 +1,8 @@ +/** + * @file error.h + * @brief Declares the public error API. + */ + #ifndef _ERROR_H_ #define _ERROR_H_ diff --git a/include/akgl/game.h b/include/akgl/game.h index e67c65d..f47894f 100644 --- a/include/akgl/game.h +++ b/include/akgl/game.h @@ -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_ diff --git a/include/akgl/heap.h b/include/akgl/heap.h index 7b11e24..5858e79 100644 --- a/include/akgl/heap.h +++ b/include/akgl/heap.h @@ -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_ diff --git a/include/akgl/iterator.h b/include/akgl/iterator.h index 7df46ce..7824bb5 100644 --- a/include/akgl/iterator.h +++ b/include/akgl/iterator.h @@ -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; diff --git a/include/akgl/json_helpers.h b/include/akgl/json_helpers.h index 837c609..8b8f1e9 100644 --- a/include/akgl/json_helpers.h +++ b/include/akgl/json_helpers.h @@ -1,20 +1,136 @@ +/** + * @file json_helpers.h + * @brief Declares the public json helpers API. + */ + #ifndef _JSON_HELPERS_H_ #define _JSON_HELPERS_H_ #include #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_ diff --git a/include/akgl/physics.h b/include/akgl/physics.h index d23c9a6..d1787fb 100644 --- a/include/akgl/physics.h +++ b/include/akgl/physics.h @@ -1,3 +1,8 @@ +/** + * @file physics.h + * @brief Declares the public physics API. + */ + #ifndef _PHYSICS_H_ #define _PHYSICS_H_ @@ -7,6 +12,7 @@ #include #include +/** @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_ diff --git a/include/akgl/registry.h b/include/akgl/registry.h index d8e9203..7a6a490 100644 --- a/include/akgl/registry.h +++ b/include/akgl/registry.h @@ -1,29 +1,108 @@ +/** + * @file registry.h + * @brief Declares the public registry API. + */ + #ifndef _REGISTRY_H_ #define _REGISTRY_H_ #include #include +/** @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_ diff --git a/include/akgl/renderer.h b/include/akgl/renderer.h index 30cea3b..6b3d2bc 100644 --- a/include/akgl/renderer.h +++ b/include/akgl/renderer.h @@ -1,3 +1,8 @@ +/** + * @file renderer.h + * @brief Declares the public renderer API. + */ + #ifndef _RENDERER_H_ #define _RENDERER_H_ @@ -7,6 +12,7 @@ #include +/** @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_ diff --git a/include/akgl/sprite.h b/include/akgl/sprite.h index 6309332..64c4975 100644 --- a/include/akgl/sprite.h +++ b/include/akgl/sprite.h @@ -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_ diff --git a/include/akgl/staticstring.h b/include/akgl/staticstring.h index 704a70c..e4efa6f 100644 --- a/include/akgl/staticstring.h +++ b/include/akgl/staticstring.h @@ -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_ diff --git a/include/akgl/text.h b/include/akgl/text.h index 5298797..4cdd4d6 100644 --- a/include/akgl/text.h +++ b/include/akgl/text.h @@ -1,9 +1,35 @@ +/** + * @file text.h + * @brief Declares the public text API. + */ + #ifndef _TEXT_H_ #define _TEXT_H_ #include +/** + * @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_ diff --git a/include/akgl/tilemap.h b/include/akgl/tilemap.h index 296207e..1bed423 100644 --- a/include/akgl/tilemap.h +++ b/include/akgl/tilemap.h @@ -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_ diff --git a/include/akgl/types.h b/include/akgl/types.h index 0187a9f..62cad49 100644 --- a/include/akgl/types.h +++ b/include/akgl/types.h @@ -1,3 +1,8 @@ +/** + * @file types.h + * @brief Declares the public types API. + */ + #ifndef _AKGL_TYPES_H_ #define _AKGL_TYPES_H_ diff --git a/include/akgl/util.h b/include/akgl/util.h index ed28f49..628e73e 100644 --- a/include/akgl/util.h +++ b/include/akgl/util.h @@ -1,15 +1,22 @@ +/** + * @file util.h + * @brief Declares the public util API. + */ + #ifndef _UTIL_H_ #define _UTIL_H_ #include #include +/** @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_ diff --git a/src/actor.c b/src/actor.c index 81d43d4..3e99ade 100644 --- a/src/actor.c +++ b/src/actor.c @@ -1,3 +1,8 @@ +/** + * @file actor.c + * @brief Implements the actor subsystem. + */ + #include #include #include @@ -168,6 +173,15 @@ akerr_ErrorContext *akgl_actor_update(akgl_Actor *obj) SUCCEED_RETURN(errctx); } +/** + * @brief Actor visible. + * @param obj Object to initialize, inspect, or modify. + * @param camera Camera rectangle used for visibility testing. + * @param visible Output set to whether the actor intersects the camera. + * @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. + */ static akerr_ErrorContext *actor_visible(akgl_Actor *obj, SDL_FRect *camera, bool *visible) { PREPARE_ERROR(errctx); diff --git a/src/actor_state_string_names.c b/src/actor_state_string_names.c index 7991289..7d34926 100644 --- a/src/actor_state_string_names.c +++ b/src/actor_state_string_names.c @@ -1,3 +1,8 @@ +/** + * @file actor_state_string_names.c + * @brief Implements the actor state string names subsystem. + */ + char *AKGL_ACTOR_STATE_STRING_NAMES[32] = { "AKGL_ACTOR_STATE_FACE_DOWN", "AKGL_ACTOR_STATE_FACE_LEFT", diff --git a/src/assets.c b/src/assets.c index 683d2c7..2b09bc9 100644 --- a/src/assets.c +++ b/src/assets.c @@ -1,3 +1,8 @@ +/** + * @file assets.c + * @brief Implements the assets subsystem. + */ + #include #include #include diff --git a/src/character.c b/src/character.c index df68432..0f0a159 100644 --- a/src/character.c +++ b/src/character.c @@ -1,3 +1,8 @@ +/** + * @file character.c + * @brief Implements the character subsystem. + */ + #include #include #include @@ -85,6 +90,14 @@ void akgl_character_state_sprites_iterate(void *userdata, SDL_PropertiesID regis } FINISH_NORETURN(errctx); } +/** + * @brief Character load json state int from strings. + * @param states JSON array of actor-state names. + * @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. + */ static akerr_ErrorContext *akgl_character_load_json_state_int_from_strings(json_t *states, int *dest) { int i = 0; @@ -109,6 +122,13 @@ static akerr_ErrorContext *akgl_character_load_json_state_int_from_strings(json_ SUCCEED_RETURN(errctx); } +/** + * @brief Character load json inner. + * @param json JSON object to parse. + * @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. + */ static akerr_ErrorContext *akgl_character_load_json_inner(json_t *json, akgl_Character *obj) { PREPARE_ERROR(errctx); diff --git a/src/controller.c b/src/controller.c index 2170dfd..a48446c 100644 --- a/src/controller.c +++ b/src/controller.c @@ -1,3 +1,8 @@ +/** + * @file controller.c + * @brief Implements the controller subsystem. + */ + #include #include #include @@ -106,6 +111,13 @@ _akgl_controller_handle_event_success: SUCCEED_RETURN(errctx); } +/** + * @brief Gamepad 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_NULLPOINTER When the corresponding validation or operation fails. + */ akerr_ErrorContext *gamepad_handle_button_down(void *appstate, SDL_Event *event) { akgl_Actor *player = NULL; @@ -157,6 +169,13 @@ akerr_ErrorContext *gamepad_handle_button_down(void *appstate, SDL_Event *event) SUCCEED_RETURN(errctx); } +/** + * @brief Gamepad 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_NULLPOINTER When the corresponding validation or operation fails. + */ akerr_ErrorContext *gamepad_handle_button_up(void *appstate, SDL_Event *event) { akgl_Actor *player = NULL; @@ -196,6 +215,13 @@ akerr_ErrorContext *gamepad_handle_button_up(void *appstate, SDL_Event *event) SUCCEED_RETURN(errctx); } +/** + * @brief Gamepad 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_NULLPOINTER When the corresponding validation or operation fails. + */ akerr_ErrorContext *gamepad_handle_added(void *appstate, SDL_Event *event) { SDL_JoystickID which; @@ -226,6 +252,13 @@ akerr_ErrorContext *gamepad_handle_added(void *appstate, SDL_Event *event) SUCCEED_RETURN(errctx); } +/** + * @brief Gamepad 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_NULLPOINTER When the corresponding validation or operation fails. + */ akerr_ErrorContext *gamepad_handle_removed(void *appstate, SDL_Event *event) { SDL_JoystickID which; diff --git a/src/draw.c b/src/draw.c index 9bb3a03..e7b9b01 100644 --- a/src/draw.c +++ b/src/draw.c @@ -1,3 +1,8 @@ +/** + * @file draw.c + * @brief Implements the draw subsystem. + */ + #include #include #include diff --git a/src/game.c b/src/game.c index e2d1dea..6f561c2 100644 --- a/src/game.c +++ b/src/game.c @@ -1,3 +1,8 @@ +/** + * @file game.c + * @brief Implements the game subsystem. + */ + #include #include #include @@ -165,6 +170,12 @@ void akgl_game_updateFPS() * entity name -> pointer map tables */ +/** + * @brief Serializes an actor name-to-pointer entry. + * @param userdata Open output stream supplied by the caller. + * @param props Actor registry being iterated. + * @param name Actor registry key to serialize. + */ void akgl_game_save_actorname_iterator(void *userdata, SDL_PropertiesID props, const char *name) { FILE *fp = (FILE *)userdata; @@ -180,6 +191,12 @@ void akgl_game_save_actorname_iterator(void *userdata, SDL_PropertiesID props, c } FINISH_NORETURN(e); } +/** + * @brief Game save spritename iterator. + * @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_game_save_spritename_iterator(void *userdata, SDL_PropertiesID props, const char *name) { FILE *fp = (FILE *)userdata; @@ -195,6 +212,12 @@ void akgl_game_save_spritename_iterator(void *userdata, SDL_PropertiesID props, } FINISH_NORETURN(e); } +/** + * @brief Game save spritesheetname iterator. + * @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_game_save_spritesheetname_iterator(void *userdata, SDL_PropertiesID props, const char *name) { FILE *fp = (FILE *)userdata; @@ -210,6 +233,12 @@ void akgl_game_save_spritesheetname_iterator(void *userdata, SDL_PropertiesID pr } FINISH_NORETURN(e); } +/** + * @brief Game save charactername iterator. + * @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_game_save_charactername_iterator(void *userdata, SDL_PropertiesID props, const char *name) { FILE *fp = (FILE *)userdata; @@ -225,6 +254,12 @@ void akgl_game_save_charactername_iterator(void *userdata, SDL_PropertiesID prop } FINISH_NORETURN(e); } +/** + * @brief Game save actors. + * @param fp Open save-game stream. + * @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_actors(FILE *fp) { PREPARE_ERROR(e); @@ -284,6 +319,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_game_save(char *fpath) SUCCEED_RETURN(e); // SUCCEED_NORETURN if in main(). } +/** + * @brief Game load objectnamemap. + * @param fp Open save-game stream. + * @param map Tilemap to inspect, draw, or modify. + * @param namelength Fixed serialized name-field length. + * @param ptrlength Serialized pointer-field length. + * @param registry SDL property registry being queried. + * @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_load_objectnamemap(FILE *fp, SDL_PropertiesID map, int namelength, int ptrlength, SDL_PropertiesID registry) { void *ptr = NULL; @@ -317,6 +362,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load_objectnamemap(FILE *fp, SDL_Pr SUCCEED_RETURN(e); } +/** + * @brief Game load versioncmp. + * @param versiontype Description of the version being compared. + * @param newversion Version read from the save data. + * @param curversion Version supported by the running library. + * @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. + * @throws AKERR_VALUE When the corresponding validation or operation fails. + */ akerr_ErrorContext AKERR_NOIGNORE *akgl_game_load_versioncmp(char *versiontype, char *newversion, char *curversion) { semver_t current_version = {}; diff --git a/src/heap.c b/src/heap.c index 68904e0..c61c83b 100644 --- a/src/heap.c +++ b/src/heap.c @@ -1,3 +1,8 @@ +/** + * @file heap.c + * @brief Implements the heap subsystem. + */ + #include #include diff --git a/src/json_helpers.c b/src/json_helpers.c index b36a5ea..2503857 100644 --- a/src/json_helpers.c +++ b/src/json_helpers.c @@ -1,3 +1,8 @@ +/** + * @file json_helpers.c + * @brief Implements the json helpers subsystem. + */ + #include #include #include diff --git a/src/physics.c b/src/physics.c index 83d86be..f461435 100644 --- a/src/physics.c +++ b/src/physics.c @@ -1,3 +1,8 @@ +/** + * @file physics.c + * @brief Implements the physics subsystem. + */ + #include #include #include diff --git a/src/registry.c b/src/registry.c index c39730d..ffc3681 100644 --- a/src/registry.c +++ b/src/registry.c @@ -1,3 +1,8 @@ +/** + * @file registry.c + * @brief Implements the registry subsystem. + */ + #include #include #include diff --git a/src/renderer.c b/src/renderer.c index 3c14382..8f70a45 100644 --- a/src/renderer.c +++ b/src/renderer.c @@ -1,3 +1,8 @@ +/** + * @file renderer.c + * @brief Implements the renderer subsystem. + */ + #include #include diff --git a/src/sprite.c b/src/sprite.c index 13cc821..ce3a949 100644 --- a/src/sprite.c +++ b/src/sprite.c @@ -1,3 +1,8 @@ +/** + * @file sprite.c + * @brief Implements the sprite subsystem. + */ + #include #include #include @@ -35,6 +40,14 @@ akerr_ErrorContext *akgl_sprite_sheet_coords_for_frame(akgl_Sprite *self, SDL_FR SUCCEED_RETURN(e); } +/** + * @brief Sprite load json spritesheet. + * @param json JSON object to parse. + * @param sheet Spritesheet used by the sprite. + * @param relative_path Base directory for relative asset references. + * @return `NULL` on success, otherwise an error context owned by the caller. + * @throws AKERR_* Propagates an error reported by a delegated operation. + */ static akerr_ErrorContext *akgl_sprite_load_json_spritesheet(json_t *json, akgl_SpriteSheet **sheet, char *relative_path) { PREPARE_ERROR(errctx); diff --git a/src/staticstring.c b/src/staticstring.c index a91f59f..002ae81 100644 --- a/src/staticstring.c +++ b/src/staticstring.c @@ -1,3 +1,8 @@ +/** + * @file staticstring.c + * @brief Implements the staticstring subsystem. + */ + #include #include #include diff --git a/src/text.c b/src/text.c index 996b212..8cf305e 100644 --- a/src/text.c +++ b/src/text.c @@ -1,3 +1,8 @@ +/** + * @file text.c + * @brief Implements the text subsystem. + */ + #include #include #include diff --git a/src/tilemap.c b/src/tilemap.c index e503dc3..8aa135f 100644 --- a/src/tilemap.c +++ b/src/tilemap.c @@ -1,3 +1,8 @@ +/** + * @file tilemap.c + * @brief Implements the tilemap subsystem. + */ + #include #include @@ -82,6 +87,14 @@ akerr_ErrorContext *akgl_get_json_properties_integer(json_t *obj, char *key, int SUCCEED_RETURN(errctx); } +/** + * @brief Get json properties number. + * @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 *akgl_get_json_properties_number(json_t *obj, char *key, float *dest) { PREPARE_ERROR(errctx); @@ -92,6 +105,14 @@ akerr_ErrorContext *akgl_get_json_properties_number(json_t *obj, char *key, floa SUCCEED_RETURN(errctx); } +/** + * @brief Get json properties float. + * @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 *akgl_get_json_properties_float(json_t *obj, char *key, float *dest) { PREPARE_ERROR(errctx); @@ -102,6 +123,14 @@ akerr_ErrorContext *akgl_get_json_properties_float(json_t *obj, char *key, float SUCCEED_RETURN(errctx); } +/** + * @brief Get json properties double. + * @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 *akgl_get_json_properties_double(json_t *obj, char *key, double *dest) { PREPARE_ERROR(errctx); @@ -232,6 +261,15 @@ akerr_ErrorContext *akgl_tilemap_load_tilesets(akgl_Tilemap *dest, json_t *root, SUCCEED_RETURN(errctx); } +/** + * @brief Tilemap load layer object actor. + * @param curobj Tilemap object being populated. + * @param layerdatavalue JSON object describing the layer entry. + * @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_KEY When the corresponding validation or operation fails. + */ akerr_ErrorContext *akgl_tilemap_load_layer_object_actor(akgl_TilemapObject *curobj, json_t *layerdatavalue, int layerid, akgl_String *dirname) { PREPARE_ERROR(errctx); @@ -353,6 +391,16 @@ akerr_ErrorContext *akgl_tilemap_load_layer_tile(akgl_Tilemap *dest, json_t *roo SUCCEED_RETURN(errctx); } +/** + * @brief Tilemap load layer image. + * @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 AKGL_ERR_SDL When the corresponding validation or operation fails. + */ akerr_ErrorContext *akgl_tilemap_load_layer_image(akgl_Tilemap *dest, json_t *root, int layerid, akgl_String *dirname) { PREPARE_ERROR(errctx); @@ -439,6 +487,13 @@ akerr_ErrorContext *akgl_tilemap_load_layers(akgl_Tilemap *dest, json_t *root, a SUCCEED_RETURN(errctx); } +/** + * @brief Tilemap load physics. + * @param dest Output destination populated by the function. + * @param root Base directory used to resolve the path. + * @return `NULL` on success, otherwise an error context owned by the caller. + * @throws AKERR_KEY When the corresponding validation or operation fails. + */ akerr_ErrorContext *akgl_tilemap_load_physics(akgl_Tilemap *dest, json_t *root) { PREPARE_ERROR(e); diff --git a/src/util.c b/src/util.c index 0f2fc32..ee7ad7e 100644 --- a/src/util.c +++ b/src/util.c @@ -1,3 +1,8 @@ +/** + * @file util.c + * @brief Implements the util subsystem. + */ + #include #include #include @@ -15,6 +20,15 @@ #include +/** + * @brief Path relative root. + * @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. + * @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails. + */ akerr_ErrorContext *akgl_path_relative_root(char *root, char *path, akgl_String *dst) { PREPARE_ERROR(e); @@ -80,6 +94,14 @@ akerr_ErrorContext *akgl_path_relative(char *root, char *path, akgl_String *dst) SUCCEED_RETURN(e); } +/** + * @brief Path relative from. + * @param path Path to resolve or transform. + * @param from Base path from which the result is made relative. + * @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 *akgl_path_relative_from(char *path, char *from, akgl_String **dst) { akgl_String *dirnamestr;