libakgl/include/akgl/physics.h

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

#ifndef _PHYSICS_H_
#define _PHYSICS_H_

#include <SDL3/SDL.h>
#include <akerror.h>
#include <akgl/actor.h>
#include <akgl/iterator.h>
#include <akgl/staticstring.h>

/** @brief Defines a pluggable physics backend and its environmental parameters. */
typedef struct akgl_PhysicsBackend {
    akerr_ErrorContext AKERR_NOIGNORE *(*simulate)(struct akgl_PhysicsBackend *self, akgl_Iterator *opflags);
    akerr_ErrorContext AKERR_NOIGNORE *(*gravity)(struct akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
    akerr_ErrorContext AKERR_NOIGNORE *(*collide)(struct akgl_PhysicsBackend *self, akgl_Actor *a1, akgl_Actor *a2);
    akerr_ErrorContext AKERR_NOIGNORE *(*move)(struct akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);

    double drag_x;
    double drag_y;
    double drag_z;
    double gravity_x;
    double gravity_y;
    double gravity_z;
    SDL_Time gravity_time;
    SDL_Time timer_gravity;
} akgl_PhysicsBackend;

/**
 * @brief Physics null gravity.
 * @param self Backend or object instance to operate on.
 * @param actor Actor to inspect or modify.
 * @param dt Elapsed simulation time in seconds.
 * @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_physics_null_gravity(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
 * @brief Physics null collide.
 * @param self Backend or object instance to operate on.
 * @param a1 First actor supplied to collision handling.
 * @param a2 Second actor supplied to collision handling.
 * @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_physics_null_collide(akgl_PhysicsBackend *self, akgl_Actor *a1, akgl_Actor *a2);
/**
 * @brief Physics null move.
 * @param self Backend or object instance to operate on.
 * @param actor Actor to inspect or modify.
 * @param dt Elapsed simulation time in seconds.
 * @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_physics_null_move(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
 * @brief Physics init null.
 * @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_physics_init_null(akgl_PhysicsBackend *self);


/**
 * @brief Physics arcade gravity.
 * @param self Backend or object instance to operate on.
 * @param actor Actor to inspect or modify.
 * @param dt Elapsed simulation time in seconds.
 * @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_physics_arcade_gravity(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
 * @brief Physics arcade collide.
 * @param self Backend or object instance to operate on.
 * @param a1 First actor supplied to collision handling.
 * @param a2 Second actor supplied to collision handling.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_API When the corresponding validation or operation fails.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_arcade_collide(akgl_PhysicsBackend *self, akgl_Actor *a1, akgl_Actor *a2);
/**
 * @brief Physics arcade move.
 * @param self Backend or object instance to operate on.
 * @param actor Actor to inspect or modify.
 * @param dt Elapsed simulation time in seconds.
 * @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_physics_arcade_move(akgl_PhysicsBackend *self, akgl_Actor *actor, float32_t dt);
/**
 * @brief Physics init arcade.
 * @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_physics_init_arcade(akgl_PhysicsBackend *self);

/**
 * @brief Physics factory.
 * @param self Backend or object instance to operate on.
 * @param type Expected JSON property type or backend type name.
 * @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_physics_factory(akgl_PhysicsBackend *self, akgl_String *type);

/**
 * @brief Physics simulate.
 * @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.
 * @throws AKGL_ERR_LOGICINTERRUPT When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_physics_simulate(akgl_PhysicsBackend *self, akgl_Iterator *opflags);

#endif // _PHYSICS_H_