Mercurial > molko
changeset 539:7fb5a859bcb4
core: doxygenize state
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 05 Mar 2023 12:33:01 +0100 |
parents | 80242343d152 |
children | 876eee0eb0ad |
files | libmlk-core/mlk/core/state.c libmlk-core/mlk/core/state.h |
diffstat | 2 files changed, 162 insertions(+), 20 deletions(-) [+] |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/state.c Sun Mar 05 11:32:36 2023 +0100 +++ b/libmlk-core/mlk/core/state.c Sun Mar 05 12:33:01 2023 +0100 @@ -1,5 +1,5 @@ /* - * state.c -- abstract state + * state.c -- abstract game loop state * * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr> *
--- a/libmlk-core/mlk/core/state.h Sun Mar 05 11:32:36 2023 +0100 +++ b/libmlk-core/mlk/core/state.h Sun Mar 05 12:33:01 2023 +0100 @@ -1,5 +1,5 @@ /* - * state.h -- abstract state + * state.h -- abstract game loop state * * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr> * @@ -19,47 +19,189 @@ #ifndef MLK_CORE_STATE_H #define MLK_CORE_STATE_H +/** + * \file mlk/core/state.h + * \brief Abstract game loop state + */ + union mlk_event; +/** + * \struct mlk_state + * \brief State structure + * + * This structure contains only virtual functions that the user can fill and + * will be called by the main loop. + * + * All of the functions can be NULL but usually indicate an useless game. + */ struct mlk_state { + /** + * (read-write, borrowed, optional) + * + * Optional state data. + */ void *data; - void (*start)(struct mlk_state *); - void (*handle)(struct mlk_state *, const union mlk_event *); - void (*update)(struct mlk_state *, unsigned int); - void (*draw)(struct mlk_state *); - void (*suspend)(struct mlk_state *); - void (*resume)(struct mlk_state *); - void (*end)(struct mlk_state *); - void (*finish)(struct mlk_state *); + + /** + * (read-write, optional) + * + * Invoked when the state starts, which is called only one time. + * + * \param self this state + */ + void (*start)(struct mlk_state *self); + + /** + * (read-write, optional) + * + * Handle an event. + * + * \param self this state + * \param event the event + */ + void (*handle)(struct mlk_state *self, const union mlk_event *event); + + /** + * (read-write, optional) + * + * Update the state. + * + * \param self this state + * \param ticks frame ticks + */ + void (*update)(struct mlk_state *self, unsigned int ticks); + + /** + * (read-write, optional) + * + * Draw the state. + * + * \param self this state + */ + void (*draw)(struct mlk_state *self); + + /** + * (read-write, optional) + * + * Suspend this state. + * + * This function is called just before switching to a new state. + * + * \param self this state + */ + void (*suspend)(struct mlk_state *self); + + /** + * (read-write, optional) + * + * Resume this state. + * + * This function is called after the previous state has been left. + * + * \param self this state + */ + void (*resume)(struct mlk_state *self); + + /** + * (read-write, optional) + * + * Terminate the state. + * + * This function is called when the state is terminated. + * + * \param self this state + */ + void (*end)(struct mlk_state *self); + + /** + * (read-write, optional) + * + * Cleanup resources allocated by the state. + * + * \param self this state + */ + void (*finish)(struct mlk_state *self); }; #if defined(__cplusplus) extern "C" { #endif +/** + * Invoke ::mlk_state::start function if not NULL. + * + * \pre state != NULL + * \param state the state + */ void -mlk_state_start(struct mlk_state *); - -void -mlk_state_handle(struct mlk_state *, const union mlk_event *); +mlk_state_start(struct mlk_state *state); +/** + * Invoke ::mlk_state::handle function if not NULL. + * + * \pre state != NULL + * \pre event != NULL + * \param state the state + * \param event the event + */ void -mlk_state_update(struct mlk_state *, unsigned int); +mlk_state_handle(struct mlk_state *state, const union mlk_event *event); +/** + * Invoke ::mlk_state::update function if not NULL. + * + * \pre state != NULL + * \param state the state + * \param ticks frame ticks + */ void -mlk_state_draw(struct mlk_state *); +mlk_state_update(struct mlk_state *state, unsigned int ticks); +/** + * Invoke ::mlk_state::draw function if not NULL. + * + * \pre state != NULL + * \param state the state + */ void -mlk_state_suspend(struct mlk_state *); +mlk_state_draw(struct mlk_state *state); +/** + * Invoke ::mlk_state::suspend function if not NULL. + * + * \pre state != NULL + * \param state the state + */ void -mlk_state_resume(struct mlk_state *); +mlk_state_suspend(struct mlk_state *state); +/** + * Invoke ::mlk_state::resume function if not NULL. + * + * \pre state != NULL + * \param state the state + */ void -mlk_state_end(struct mlk_state *); +mlk_state_resume(struct mlk_state *state); +/** + * Invoke ::mlk_state::end function if not NULL + * + * \pre state != NULL + * \param state the state + */ void -mlk_state_finish(struct mlk_state *); +mlk_state_end(struct mlk_state *state); + +/** + * Invoke ::mlk_state::finish function if not NULL + * + * \pre state != NULL + * \param state the state + */ +void +mlk_state_finish(struct mlk_state *state); #if defined(__cplusplus) }