libakgl/include/akgl/heap.h

/**
 * @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_