Andrew Kesterson
f0858b0d38
The Doxygen comments were generated from the declarations, so 217 @throws lines across 21 headers read "When the corresponding validation or operation fails" and told a caller nothing beyond the status name. The @param lines were the same shape: every output was "Output destination populated by the function", every instance "Object to initialize, inspect, or modify". Rewritten against the implementations, following the pattern libakstdlib already uses: - @throws names the condition. akgl_sprite_load_json separated AKERR_KEY (absent) from AKERR_TYPE (present, wrong type) from AKERR_OUTOFBOUNDS (filename too long, or array indexed past its end), and gained AKGL_ERR_SDL and AKGL_ERR_HEAP, which it raises and never declared. - Parameters say whether they are required, what a NULL means, and what is written on a failure path. Where an argument is not checked, the doc says so: akgl_heap_next_actor's dest is a crash on NULL, not an error, and akgl_render_2d_frame_start dereferences self before testing it. - The conventions move up to the file blocks so the per-function docs stay short. json_helpers.h states once that absence is an error here and that json_t * results are borrowed; heap.h explains the pool model and the acquire asymmetry; physics.h carries the thrust/environmental/velocity table. - Struct fields, enum values, macros and exported globals are documented, including the dead ones - sprite_w/sprite_h, movetimer, p_scale and timer_gravity are read by nothing, and say so. Also fixes ten comments in error.h and audio.h that opened with /** rather than /**<, so Doxygen attached them to the following entity and rendered the text as part of the macro's value. Verified against the generated HTML. Comments only - no declaration changed. Doxygen builds clean under WARN_AS_ERROR, scripts/reindent.sh --check passes, 19/19 suites pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
64 lines
3.9 KiB
C
64 lines
3.9 KiB
C
/**
|
|
* @file iterator.h
|
|
* @brief The work order handed to a registry sweep.
|
|
*
|
|
* There is no iterator object with a `next()` on it. Traversal is SDL's --
|
|
* `SDL_EnumerateProperties` over a registry -- and this struct is the `userdata`
|
|
* carried into each callback, telling it *which* entries to touch and *what* to
|
|
* do to each one. akgl_registry_iterate_actor and
|
|
* akgl_registry_iterate_character are the callbacks that read it;
|
|
* akgl_game_update, akgl_physics_simulate, and akgl_render_2d_draw_world are the
|
|
* entry points that take one.
|
|
*
|
|
* The operations are independent bits, not an enum: a single sweep can update,
|
|
* scale, and render, and they run in that fixed order regardless of how the bits
|
|
* were set. Passing `NULL` where an `akgl_Iterator *` is expected is not an
|
|
* error at the top-level entry points -- each substitutes its own default set --
|
|
* but it *is* an error once inside a callback.
|
|
*/
|
|
|
|
#ifndef _AKGL_ITERATOR_H_
|
|
#define _AKGL_ITERATOR_H_
|
|
|
|
/** @brief Selects operations and an optional layer for actor traversal. */
|
|
typedef struct {
|
|
uint32_t flags; /**< Bitwise OR of the `AKGL_ITERATOR_OP_*` values below. */
|
|
uint8_t layerid; /**< Layer to restrict the sweep to. Read only when #AKGL_ITERATOR_OP_LAYERMASK is set. */
|
|
} akgl_Iterator;
|
|
|
|
#define AKGL_ITERATOR_OP_UPDATE 1 // 1 Call the actor's updatefunc
|
|
#define AKGL_ITERATOR_OP_RENDER 1 << 1 // 2 Call the actor's renderfunc
|
|
#define AKGL_ITERATOR_OP_RELEASE 1 << 2 // 4 Release the object back to its heap layer
|
|
#define AKGL_ITERATOR_OP_LAYERMASK 1 << 3 // 8 Skip anything whose layer != layerid
|
|
#define AKGL_ITERATOR_OP_TILEMAPSCALE 1 << 4 // 16 Scale actors to the tilemap; otherwise force scale 1.0
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_5 1 << 5 // 32
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_6 1 << 6 // 64
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_7 1 << 7 // 128
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_8 1 << 8 // 256
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_9 1 << 9 // 512
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_10 1 << 10 // 1024
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_11 1 << 11 // 2048
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_12 1 << 12 // 4096
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_13 1 << 13 // 8192
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_14 1 << 14 // 16384
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_15 1 << 15 // 32768
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_16 1 << 16 // 65536
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_17 1 << 17 // 131072
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_18 1 << 18 // 262144
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_19 1 << 19 // 524288
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_20 1 << 20 // 1048576
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_21 1 << 21 // 2097152
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_22 1 << 22 // 4194304
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_23 1 << 23 // 8388608
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_24 1 << 24 // 16777216
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_25 1 << 25 // 33554432
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_26 1 << 26 // 67108864
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_27 1 << 27 // 134217728
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_28 1 << 28 // 268435456
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_29 1 << 29 // 536870912
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_30 1 << 30 // 1073741824
|
|
#define AKGL_ITERATOR_OP_UNDEFINED_31 1 << 31 // 2147483648
|
|
|
|
|
|
#endif // _AKGL_ITERATOR_H_
|