libakgl/include/akgl/renderer.h

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

#ifndef _RENDERER_H_
#define _RENDERER_H_

#include <SDL3/SDL.h>

#include <akerror.h>

#include <akgl/iterator.h>

/** @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);
    akerr_ErrorContext AKERR_NOIGNORE *(*frame_start)(struct akgl_RenderBackend *self);
    akerr_ErrorContext AKERR_NOIGNORE *(*frame_end)(struct akgl_RenderBackend *self);
    akerr_ErrorContext AKERR_NOIGNORE *(*draw_texture)(struct akgl_RenderBackend *self, SDL_Texture *texture, SDL_FRect *src, SDL_FRect *dest, double angle, SDL_FPoint *center, SDL_FlipMode flip);
    akerr_ErrorContext AKERR_NOIGNORE *(*draw_mesh)(struct akgl_RenderBackend *self);
    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_