libakgl/include/akgl/controller.h

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

#ifndef _CONTROLLER_H_
#define _CONTROLLER_H_

#include <SDL3/SDL.h>
#include <akerror.h>
#include "types.h"

#define AKGL_MAX_CONTROL_MAPS 8
#define AKGL_MAX_CONTROLS     32

/** @brief Maps one SDL input to pressed and released callbacks. */
typedef struct {
    uint32_t event_on;
    uint32_t event_off;
    uint8_t button;
    SDL_Keycode key;
    uint8_t axis;
    uint8_t axis_range_min;
    uint8_t axis_range_max;
    akerr_ErrorContext AKERR_NOIGNORE *(*handler_on)(akgl_Actor *obj, SDL_Event *event);
    akerr_ErrorContext AKERR_NOIGNORE *(*handler_off)(akgl_Actor *obj, SDL_Event *event);
} akgl_Control;

/** @brief Groups input bindings for one actor and its input devices. */
typedef struct {
    akgl_Actor *target;
    uint16_t nextMap;
    akgl_Control controls[AKGL_MAX_CONTROLS];
    SDL_KeyboardID kbid;
    SDL_JoystickID jsid;
    SDL_MouseID mouseid;
    SDL_PenID penid;
} akgl_ControlMap;

/** @brief Stores all process-wide actor input maps. */
extern akgl_ControlMap GAME_ControlMaps[AKGL_MAX_CONTROL_MAPS];

/**
 * @brief Controller list keyboards.
 * @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_controller_list_keyboards(void);

/**
 * @brief Controller handle event.
 * @param appstate Application state supplied by SDL.
 * @param event SDL input event to process.
 * @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_controller_handle_event(void *appstate, SDL_Event *event);

/**
 * @brief Controller handle button down.
 * @param appstate Application state supplied by SDL.
 * @param event SDL input event to process.
 * @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_controller_handle_button_down(void *appstate, SDL_Event *event);
/**
 * @brief Controller handle button up.
 * @param appstate Application state supplied by SDL.
 * @param event SDL input event to process.
 * @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_controller_handle_button_up(void *appstate, SDL_Event *event);
/**
 * @brief Controller handle added.
 * @param appstate Application state supplied by SDL.
 * @param event SDL input event to process.
 * @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_controller_handle_added(void *appstate, SDL_Event *event);
/**
 * @brief Controller handle removed.
 * @param appstate Application state supplied by SDL.
 * @param event SDL input event to process.
 * @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_controller_handle_removed(void *appstate, SDL_Event *event);

/**
 * @brief Controller pushmap.
 * @param controlmapid Index of the control map to update.
 * @param control Control binding to append to the selected map.
 * @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_controller_pushmap(int controlmapid, akgl_Control *control);

/**
 * @brief Controller default.
 * @param controlmapid Index of the control map to update.
 * @param actorname Registry name of the controlled actor.
 * @param kbid SDL keyboard identifier assigned to the map.
 * @param jsid SDL joystick or gamepad identifier assigned to the map.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
 * @throws AKGL_ERR_REGISTRY When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_controller_default(int controlmapid, char *actorname, int kbid, int jsid);

/**
 * @brief Controller open gamepads.
 * @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_controller_open_gamepads(void);
#endif // _CONTROLLER_H_