Andrew Kesterson
549b27d3eb
Add file, structure, global, and function documentation across all libakgl-owned headers and sources, including parameter contracts and likely AKERR/AKGL_ERR exceptions. Add a strict Doxyfile and build the generated API documentation in Gitea CI with warnings treated as failures. Co-authored-by: Codex (GPT-5) <noreply@openai.com>
93 lines
3.7 KiB
C
93 lines
3.7 KiB
C
/**
|
|
* @file util.h
|
|
* @brief Declares the public util API.
|
|
*/
|
|
|
|
#ifndef _UTIL_H_
|
|
#define _UTIL_H_
|
|
|
|
#include <akerror.h>
|
|
#include <akgl/staticstring.h>
|
|
|
|
/** @brief Represents a two-dimensional point. */
|
|
typedef struct point {
|
|
int x;
|
|
int y;
|
|
int z;
|
|
} point;
|
|
|
|
/** @brief Stores the corners of an axis-aligned rectangle. */
|
|
typedef struct RectanglePoints {
|
|
point topleft;
|
|
point topright;
|
|
point bottomleft;
|
|
point bottomright;
|
|
} RectanglePoints;
|
|
|
|
#define AKGL_COLLIDE_RECTANGLES(r1x, r1y, r1w, r1h, r2x, r2y, r2w, r2h) ((r1x < (r2x + r2w)) || ((r1x + r1w) > r2x)
|
|
|
|
/**
|
|
* @brief Rectangle points.
|
|
* @param dest Output destination populated by the function.
|
|
* @param rect Rectangle whose corner points are calculated.
|
|
* @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_rectangle_points(RectanglePoints *dest, SDL_FRect *rect);
|
|
/**
|
|
* @brief Collide point rectangle.
|
|
* @param p Point to test for containment.
|
|
* @param r Rectangle corner data used for collision testing.
|
|
* @param collide Output set to whether the tested geometry intersects.
|
|
* @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_collide_point_rectangle(point *p, RectanglePoints *r, bool *collide);
|
|
/**
|
|
* @brief Collide rectangles.
|
|
* @param r1 First rectangle to compare.
|
|
* @param r2 Second rectangle to compare.
|
|
* @param collide Output set to whether the tested geometry intersects.
|
|
* @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_collide_rectangles(SDL_FRect *r1, SDL_FRect *r2, bool *collide);
|
|
|
|
/**
|
|
* @brief Path relative.
|
|
* @param root Base directory used to resolve the path.
|
|
* @param path Path to resolve or transform.
|
|
* @param dst Output destination populated by the function.
|
|
* @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_path_relative(char *root, char *path, akgl_String *dst);
|
|
|
|
// These are REALLY slow routines that are only useful in testing harnesses
|
|
/**
|
|
* @brief Compare sdl surfaces.
|
|
* @param s1 First SDL surface to compare.
|
|
* @param s2 Second SDL surface to compare.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
|
|
* @throws AKERR_VALUE When the corresponding validation or operation fails.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_compare_sdl_surfaces(SDL_Surface *s1, SDL_Surface *s2);
|
|
/**
|
|
* @brief Render and compare.
|
|
* @param t1 First texture to render for comparison.
|
|
* @param t2 Second texture to render for comparison.
|
|
* @param x Horizontal destination coordinate.
|
|
* @param y Vertical destination coordinate.
|
|
* @param w Destination width.
|
|
* @param h Destination height.
|
|
* @param writeout Optional filename for the rendered diagnostic image.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_IO 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_render_and_compare(SDL_Texture *t1, SDL_Texture *t2, int x, int y, int w, int h, char *writeout);
|
|
|
|
#endif // _UTIL_H_
|