Andrew Kesterson
3a262bee54
Closes internal-consistency items 7 through 15. Nineteen non-static functions were in the ABI with no declaration anywhere, so no consumer could call them and any consumer could collide with them. The four gamepad_handle_* functions are the ones that mattered: controller.h declared akgl_controller_handle_button_down and three siblings that did not exist, so anything compiled against the header alone failed to link. The definitions carry the declared names now, which also closes Defects -> Known and still open item 10, and their documentation moved to the header. The rest are either declared under a "part of the internal API" block -- akgl_game_save_actors and akgl_game_load_versioncmp, which tests/game.c had to declare for itself, plus six tilemap loader helpers the untested-loader work wants to reach -- or static, which is what the four save iterators and load_objectnamemap should always have been. akgl_path_relative_from is deleted: declared nowhere, called from nowhere, never wrote its output, and leaked a pooled string on every call, so it closes Known and still open item 4 and item 40 by ceasing to exist. scripts/check_api_surface.sh keeps it closed. It reads the built library's dynamic symbol table and every public header with comments stripped, and fails on an exported akgl_* symbol that is declared nowhere. Stripping comments is the whole point -- four of these were mentioned in controller.h prose, which is how they went unnoticed. The pool-size ceilings are defined once, in heap.h, so the #ifndef override hook fires for the first time; actor.h, sprite.h and character.h were defining the same four unconditionally from headers heap.h includes above its own guard. tests/header_pool_override.c fails the compile if that regresses. Also here: (void) rather than () on the twelve no-argument entry points, AKERR_NOIGNORE only on declarations, static helpers with the akgl_ prefix dropped, and the six parameter-name mismatches. akgl_get_json_with_default had its two contexts swapped rather than merely misspelled -- the incoming one was `err` and its own was `e`, which is the name reserved for an incoming one. 24/24 pass, reindent --check clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
220 lines
11 KiB
C
220 lines
11 KiB
C
/**
|
|
* @file registry.h
|
|
* @brief The name-to-object lookup tables, and the string configuration store.
|
|
*
|
|
* Nothing in this library is passed around by pointer where a name will do. An
|
|
* actor names the character it instantiates, a character names the sprites it
|
|
* draws, a sprite names the sheet it cuts frames from -- all resolved at load
|
|
* time through these eight registries. That is what lets the whole asset graph
|
|
* be described in JSON files that reference each other by name.
|
|
*
|
|
* They are SDL property sets, not akgl types, so a caller can enumerate one with
|
|
* `SDL_EnumerateProperties` -- which is exactly what akgl_registry_iterate_actor
|
|
* and akgl_character_state_sprites_iterate are for.
|
|
*
|
|
* Every id starts at 0, which SDL treats as "no such property set": reads return
|
|
* the default and writes are silently dropped. So an uninitialized registry does
|
|
* not fail loudly, it fails quietly, and akgl_registry_init has to run first.
|
|
*
|
|
* @warning akgl_registry_init does *not* initialize
|
|
* #AKGL_REGISTRY_PROPERTIES -- akgl_registry_init_properties is a
|
|
* separate call, made by akgl_game_init but by nothing else. A program
|
|
* that builds its own startup path and skips it gets a silently
|
|
* no-op akgl_set_property and an akgl_get_property that always hands
|
|
* back the caller's default, which in turn means akgl_render_2d_init
|
|
* and akgl_physics_init_arcade quietly ignore their configuration.
|
|
* TODO.md, "Known and still open" item 3.
|
|
*/
|
|
|
|
#ifndef _AKGL_REGISTRY_H_
|
|
#define _AKGL_REGISTRY_H_
|
|
|
|
#include <SDL3/SDL.h>
|
|
#include <akgl/error.h>
|
|
#include <akgl/staticstring.h>
|
|
|
|
/** @brief Actor name -> `akgl_Actor *`. Written by akgl_actor_initialize, cleared when an actor's last reference goes. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR;
|
|
/** @brief Sprite name -> `akgl_Sprite *`. The `name` field from a sprite JSON. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_SPRITE;
|
|
/** @brief Resolved image path -> `akgl_SpriteSheet *`. Keyed by path so two sprites sharing an image share the texture. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_SPRITESHEET;
|
|
/** @brief Character name -> `akgl_Character *`. What akgl_actor_set_character resolves against. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_CHARACTER;
|
|
/** @brief Actor-state name -> its bit value, as a number. Lets character JSON say "AKGL_ACTOR_STATE_FACE_LEFT" instead of 2. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR_STATE_STRINGS;
|
|
/** @brief Font name -> `TTF_Font *`. Names are chosen by the caller of akgl_text_loadfont, not derived from the file. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_FONT;
|
|
/** @brief Music name -> audio handle. Created but not yet populated by anything in the library. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_MUSIC;
|
|
/** @brief Configuration key -> string value. Read through akgl_get_property; everything is a string, including numbers. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_PROPERTIES;
|
|
|
|
/**
|
|
* @brief Create the seven asset registries, in dependency order.
|
|
*
|
|
* Spritesheet, sprite, character, actor, actor-state-strings, font, music. Call
|
|
* it once at startup, before loading anything.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate any one of the property sets;
|
|
* the message names which registry failed. The registries created before
|
|
* the failure are left in place rather than torn down.
|
|
*
|
|
* @warning This does not create #AKGL_REGISTRY_PROPERTIES -- see the warning on
|
|
* this file.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init(void);
|
|
/**
|
|
* @brief Create the music registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set, so calling it
|
|
* twice leaks the first one along with everything registered in it.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_music(void);
|
|
/**
|
|
* @brief Create the font registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_font(void);
|
|
/**
|
|
* @brief Create the actor registry, destroying any previous one first.
|
|
*
|
|
* The one initializer here that cleans up after itself, which is what makes it
|
|
* safe to call between levels: it destroys the old property set before creating
|
|
* the replacement, so the actors from the previous map are unregistered in one
|
|
* step. Note that it destroys the *registry*, not the actors -- releasing those
|
|
* is akgl_heap_release_actor's job.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set. The old one
|
|
* has already been destroyed at that point, so the registry is left at 0.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor(void);
|
|
/**
|
|
* @brief Create the sprite registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_sprite(void);
|
|
/**
|
|
* @brief Create the spritesheet registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_spritesheet(void);
|
|
/**
|
|
* @brief Create the character registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_character(void);
|
|
/**
|
|
* @brief Create the configuration-property registry.
|
|
*
|
|
* Deliberately separate from akgl_registry_init, because configuration has to be
|
|
* in place before the subsystems that read it start up. akgl_game_init creates
|
|
* it; filling it in -- with akgl_registry_load_properties or akgl_set_property --
|
|
* is the caller's job, and has to happen before akgl_render_2d_init or
|
|
* akgl_physics_init_arcade run.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set, so every
|
|
* property set before a second call is lost.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_properties(void);
|
|
/**
|
|
* @brief Load a JSON configuration file into the property registry.
|
|
*
|
|
* Expects a document with a top-level `properties` object whose members are all
|
|
* strings; each becomes one entry. Numbers are configured as strings here and
|
|
* parsed by whoever reads them -- `akgl_game.screenwidth` is `"800"`, not `800`.
|
|
*
|
|
* @param fname Path to the JSON document. Required. Used verbatim.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p fname is `NULL`, or if the file cannot be
|
|
* opened or does not parse. The message carries jansson's line number
|
|
* and text.
|
|
* @throws AKERR_KEY If the document has no top-level `properties` member.
|
|
* @throws AKERR_TYPE If `properties` is not an object, or if one of its members
|
|
* is not a string.
|
|
* @throws AKGL_ERR_HEAP If the string pool is exhausted.
|
|
*
|
|
* @note Writes into #AKGL_REGISTRY_PROPERTIES, so akgl_registry_init_properties
|
|
* has to have run -- otherwise every entry is silently dropped and this
|
|
* still returns success.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_load_properties(char *fname);
|
|
/**
|
|
* @brief Create the actor-state-name registry and fill it from the name table.
|
|
*
|
|
* Walks `AKGL_ACTOR_STATE_STRING_NAMES` and maps entry `i` to the value `1 << i`,
|
|
* which is what lets a character JSON write `"AKGL_ACTOR_STATE_FACE_LEFT"` and
|
|
* have akgl_character_load_json turn it into a bit.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set. The
|
|
* individual name registrations are not checked.
|
|
*
|
|
* @note The name table it reads disagrees with actor.h in two places: bits 11
|
|
* and 12 are named `UNDEFINED_11`/`UNDEFINED_12` rather than `MOVING_IN`
|
|
* and `MOVING_OUT`, so those two states cannot be named from JSON at all.
|
|
* TODO.md items 24-26.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor_state_strings(void);
|
|
/**
|
|
* @brief Set one configuration property.
|
|
*
|
|
* @param name Property key. Required.
|
|
* @param value Property value. Required. SDL copies it, so the caller's buffer
|
|
* can go away afterwards.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p name or @p value is `NULL`.
|
|
*
|
|
* @note The write itself is unchecked. If #AKGL_REGISTRY_PROPERTIES is still 0 --
|
|
* akgl_registry_init_properties never having run -- this discards the
|
|
* value and returns success.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_set_property(char *name, char *value);
|
|
/**
|
|
* @brief Read one configuration property into a pooled string, with a fallback.
|
|
*
|
|
* Absence is not an error: an unset property yields @p def, which is how every
|
|
* caller in the library gets a working default without checking first.
|
|
*
|
|
* @param name Property key. Required.
|
|
* @param dest Receives the value. Required. If `*dest` is `NULL` a string is
|
|
* claimed from the pool for you, so initialize it to `NULL` on the
|
|
* first call; either way the caller releases it with
|
|
* akgl_heap_release_string. If `*dest` is non-`NULL` it is written
|
|
* in place.
|
|
* @param def Value to use when @p name is not set. Effectively required --
|
|
* a `NULL` here on an unset property is an AKERR_NULLPOINTER rather
|
|
* than an empty result.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p name or @p dest is `NULL`, or if the property
|
|
* is unset and @p def is `NULL`.
|
|
* @throws AKERR_OUTOFBOUNDS If the stored value is #AKGL_MAX_STRING_LENGTH bytes
|
|
* or longer, which will not fit an akgl_String with its terminator.
|
|
* @throws AKERR_VALUE If the value and the destination overlap in memory.
|
|
* @throws AKGL_ERR_HEAP If `*dest` was `NULL` and the string pool is exhausted.
|
|
*
|
|
* @note Only the value and its terminator are copied. The rest of @p dest keeps
|
|
* whatever the previous holder left there, so read the result as a C
|
|
* string rather than as #AKGL_MAX_STRING_LENGTH bytes.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_property(char *name, akgl_String **dest, char *def);
|
|
|
|
#endif //_AKGL_REGISTRY_H_
|