/**
 * @file sprite.h
 * @brief Declares the public sprite API.
 */

#ifndef _AKGL_SPRITE_H_
#define _AKGL_SPRITE_H_

#include <SDL3/SDL_properties.h>
#include <SDL3/SDL.h>
#include <akerror.h>


#define AKGL_SPRITE_MAX_FRAMES                 16
#define AKGL_SPRITE_MAX_NAME_LENGTH            128
#define AKGL_SPRITE_MAX_REGISTRY_SIZE          1024
#define AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH  512

#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;
    char name[AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH];
    uint16_t sprite_w;
    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
    uint32_t frames; // how many frames are in this animation
    uint32_t width;
    uint32_t height;
    uint32_t speed; // how many milliseconds a given sprite frame should be visible before cycling
    bool loop; // when this sprite is done playing, it should immediately start again
    bool loopReverse; // when this sprite is done playing, it should go in reverse order through its frames
    char name[AKGL_SPRITE_MAX_NAME_LENGTH];
    akgl_SpriteSheet *sheet;
} 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_