Mercurial > molko

comparison libmlk-core/core/state.h @ 243:71b3b7036de7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: lot of cleanups, - prefix libraries with libmlk, - move assets from source directories closes #2520, - prefix header guards closes #2519
author David Demelier <markand@malikania.fr>
date Sat, 28 Nov 2020 22:37:30 +0100
parents libcore/core/state.h@87f8ef73a160
children c4da052c0def
comparison
equal deleted inserted replaced
242:4c24604efcab 243:71b3b7036de7
1 /*
2 * state.h -- abstract state
3 *
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
5 *
6 * Permission to use, copy, modify, and/or distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
9 *
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 */
18
19 #ifndef MOLKO_CORE_STATE_H
20 #define MOLKO_CORE_STATE_H
21
22 /**
23 * \file state.h
24 * \brief Abstract state.
25 * \ingroup states
26 *
27 * The state module is a facility that allows changing game context with ease
28 * using a single \ref game_switch routine.
29 *
30 * The user creates any state required, set appropriate functions if needed and
31 * place them in the game using \ref game_switch. Then function \ref game_handle
32 * \ref game_update and finally \ref game_draw.
33 */
34
35 union event;
36
37 /**
38 * \brief Abstract state.
39 */
40 struct state {
41 /**
42 * (+&?) Optional user data.
43 */
44 void *data;
45
46 /**
47 * (+?) This function is called when the state is about to begin.
48 *
49 * \param state this state
50 */
51 void (*start)(struct state *state);
52
53 /**
54 * (+) This function is called for each event that happened.
55 *
56 * \param state this state
57 * \param ev the event
58 */
59 void (*handle)(struct state *state, const union event *ev);
60
61 /**
62 * (+) Update the state.
63 *
64 * This function is called to update the game, with the number of
65 * milliseconds since the last frame.
66 *
67 * \param state this state
68 * \param ev the event
69 */
70 void (*update)(struct state *state, unsigned int ticks);
71
72 /**
73 * (+) This function is supposed to draw the game.
74 *
75 * \param state this state
76 */
77 void (*draw)(struct state *state);
78
79 /**
80 * (+?) This function is called when the state is about to be switched
81 * away from.
82 *
83 * This function is not called in case `quick` is set to true when
84 * calling \ref game_switch function.
85 *
86 * \param state this state
87 */
88 void (*end)(struct state *state);
89
90 /**
91 * (+?) This function is called to close resources if necessary.
92 *
93 * \param state the state
94 */
95 void (*finish)(struct state *state);
96 };
97
98 /**
99 * Shortcut for state->start (if not NULL)
100 *
101 * \pre state != NULL
102 * \param state the state
103 */
104 void
105 state_start(struct state *state);
106
107 /**
108 * Shortcut for state->handle (if not NULL)
109 *
110 * \pre state != NULL
111 * \pre ev != NULL
112 * \param state the state
113 * \param ev the event
114 */
115 void
116 state_handle(struct state *state, const union event *ev);
117
118 /**
119 * Shortcut for state->update (if not NULL)
120 *
121 * \pre state != NULL
122 * \param state the state
123 * \param ticks elapsed milliseconds since last frame
124 */
125 void
126 state_update(struct state *state, unsigned int ticks);
127
128 /**
129 * Shortcut for state->draw (if not NULL)
130 *
131 * \pre state != NULL
132 * \param state the state
133 */
134 void
135 state_draw(struct state *state);
136
137 /**
138 * Shortcut for state->end (if not NULL)
139 *
140 * \pre state != NULL
141 * \param state the state
142 */
143 void
144 state_end(struct state *state);
145
146 /**
147 * Shortcut for state->finish (if not NULL)
148 *
149 * \pre state != NULL
150 * \param state the state
151 */
152 void
153 state_finish(struct state *state);
154
155 #endif /* !MOLKO_CORE_STATE_H */