Andrew Kesterson
549b27d3eb
Add file, structure, global, and function documentation across all libakgl-owned headers and sources, including parameter contracts and likely AKERR/AKGL_ERR exceptions. Add a strict Doxyfile and build the generated API documentation in Gitea CI with warnings treated as failures. Co-authored-by: Codex (GPT-5) <noreply@openai.com>
131 lines
5.4 KiB
C
131 lines
5.4 KiB
C
/**
|
|
* @file heap.h
|
|
* @brief Declares the public heap API.
|
|
*/
|
|
|
|
#ifndef _AKGL_HEAP_H_
|
|
#define _AKGL_HEAP_H_
|
|
|
|
#include "sprite.h"
|
|
#include "actor.h"
|
|
#include "character.h"
|
|
#include "staticstring.h"
|
|
#include <akerror.h>
|
|
|
|
#ifndef AKGL_MAX_HEAP_ACTOR
|
|
#define AKGL_MAX_HEAP_ACTOR 64
|
|
#endif
|
|
#ifndef AKGL_MAX_HEAP_SPRITE
|
|
#define AKGL_MAX_HEAP_SPRITE (AKGL_MAX_HEAP_ACTOR * 16)
|
|
#endif
|
|
#ifndef AKGL_MAX_HEAP_SPRITESHEET
|
|
#define AKGL_MAX_HEAP_SPRITESHEET AKGL_MAX_HEAP_SPRITE
|
|
#endif
|
|
#ifndef AKGL_MAX_HEAP_CHARACTER
|
|
#define AKGL_MAX_HEAP_CHARACTER 256
|
|
#endif
|
|
#ifndef AKGL_MAX_HEAP_STRING
|
|
#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_
|