andrew/libakgl
1
0
Fork 0
Code Issues 66 Pull Requests 1 Actions 1 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

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_