Mercurial > molko
changeset 399:77f843de956c
doc: update actions/drawables
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 18 Feb 2022 16:34:18 +0100 |
parents | 14ce7c4871e3 |
children | 4fb0ce06a43a |
files | doc/docs/dev/api/core/action.md doc/docs/dev/api/core/drawable.md |
diffstat | 2 files changed, 48 insertions(+), 38 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/docs/dev/api/core/action.md Sun Feb 27 10:08:51 2022 +0100 +++ b/doc/docs/dev/api/core/action.md Fri Feb 18 16:34:18 2022 +0100 @@ -18,15 +18,8 @@ Most more high level objects can handle actions to add flexibility (like in battles, maps, etc). -## Macros - -### ACTION\_STACK\_MAX - -Maximum number of action in a unique [action_stack](#action_stack). - -```c -#define ACTION_STACK_MAX 128 -``` +The `action_stack` structure does not take ownership of actions, they must be +valid on the user side. ## Structs @@ -41,7 +34,7 @@ |-------------------|--------|--------------------------------------------------| | [data](#data) | (+&?) | `void *` | | [handle](#handle) | (+?) | `void (*)(struct action *, const union event *)` | -| [update](#update) | (+?) | `int (*)(struct action *, unsigned int)` | +| [update](#update) | (+?) | `int (*)(struct action *, unsigned int)` | | [draw](#draw) | (+?) | `void (*)(struct action *)` | | [end](#end) | (+?) | `void (*)(struct action *)` | | [finish](#finish) | (+?) | `void (*)(struct action *)` | @@ -114,14 +107,19 @@ destroyed. User is responsible of deallocating them if they were allocated from the heap. -| Field | Type | -|---------------------|-------------------------------------| -| [actions](#actions) | `struct action *[ACTION_STACK_MAX]` | +| Field | Access | Type | +|-----------------------|--------|------------------------------------| +| [actions](#actions) | (+&) | `struct action **` | +| [actionsz](#actionsz) | (+) | `size_t` | #### actions Non-owning array of actions to manage. +#### actionsz + +Maximum capacity in [actions](#actions) field. + ## Functions ### action\_handle @@ -173,14 +171,13 @@ ### action\_stack\_init -Initalize the action stack `st`. +Initialize the stack `st` with the given `actions` array of capacity `actionsz`. +This function is optional when using designated initializers but you must make +sure to zero-initialize the array of actions if you do so. -!!! note - It is unnecessary if the object was zero'ed. - -``` +```c void -action_stack_init(struct action_stack *st) +action_stack_init(struct action_stack *st, struct action **actions, size_t actionsz) ``` ### action\_stack\_add @@ -238,3 +235,19 @@ void action_stack_finish(struct action_stack *st) ``` + +## Example + +Using an `action_stack` with a maximum of ten actions. + +```c +struct action actions[10]; +struct action_stack stack; + +action_stack_init(&stack, actions, 10); +action_stack_add(&stack, my_action()); + +/* + * Call action_stack_update and other functions in your main loop. + */ +```
--- a/doc/docs/dev/api/core/drawable.md Sun Feb 27 10:08:51 2022 +0100 +++ b/doc/docs/dev/api/core/drawable.md Fri Feb 18 16:34:18 2022 +0100 @@ -11,17 +11,10 @@ This module allows creating automatic objects that draw theirselves into the screen and vanish once complete. They could be considered as lightweight alternatives to [actions](action.md), however in contrast to them, drawables do -have a position. - -## Macros - -### DRAWABLE\_STACK\_MAX +have a position and don't handle events. -Maximum number of drawable in a unique [drawable_stack](#drawable_stack). - -```c -#define DRAWABLE_STACK_MAX 128 -``` +Please refer to the [actions](action.md) documentation because most of the API +is identical verbatim. ## Structs @@ -93,14 +86,19 @@ You can add, clear, update and draw them. -| Field | Access | Type | -|---------------------|--------|-----------------------------------------| -| [objects](#objects) | (+&?) | `struct drawable *[DRAWABLE_STACK_MAX]` | +| Field | Access | Type | +|-----------------------|--------|-----------------------------------------| +| [objects](#objects) | (+&?) | `struct drawable **` | +| [objectsz](#objectsz) | (+) | `size_t` | #### objects Non-owning array of drawables to manage. +#### objectsz + +Maximum capacity in [objects](#objects) field. + ## Functions ### drawable\_update @@ -142,14 +140,13 @@ ### drawable\_stack\_init -Initalize the drawable stack `st`. +Initialize the stack `st` with the given `drawables` array of capacity +`drawablesz`. This function is optional when using designated initializers but +you must make sure to zero-initialize the array of drawables if you do so. -!!! note - It is unnecessary if the object was zero'ed. - -``` +```c void -drawable_stack_init(struct drawable_stack *st) +drawable_stack_init(struct drawable_stack *st, struct drawable **drawables, size_t drawablesz) ``` ### drawable\_stack\_add