Mercurial > molko

annotate src/core/wait.h @ 70:53b217afe122

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: improve doxygen documentation
author David Demelier <markand@malikania.fr>
date Mon, 27 Jan 2020 14:13:49 +0100
parents 9435a53adab4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
66
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * wait.h -- wait action
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 #ifndef MOLKO_WAIT_H
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 #define MOLKO_WAIT_H
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 /**
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 * \file wait.h
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * \brief Wait action.
70
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
25 * \ingroup actions
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
26 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
27 * This module is meant to create a delayed action.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
28 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
29 * Combined with \ref script.h, you can create a sequence of actions with
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
30 * delays between each.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
31 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
32 * \code
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
33 * struct script script;
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
34 * struct action action;
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
35 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
36 * // Prepare the script.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
37 * script_init(&script);
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
38 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
39 * // Add some actions to script using script_append.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
40 * // ...
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
41 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
42 * // Wait one second delay before next action.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
43 * wait_action(&(struct wait) { .delay = 1000 }, &action);
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
44 * script_append(&script, &action);
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
45 *
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
46 * // Add more actions after this delay.
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
47 * // ...
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
48 * \endcode
66
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
50
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 #include <stdbool.h>
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
52
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 struct action;
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
54
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 /**
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 * \brief Wait action.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 struct wait {
70
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
59 unsigned int delay; /*!< (RW) Time to wait in milliseconds */
66
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 unsigned int elapsed; /*!< (RO) Elapsed time */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 };
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 /**
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 * Start the wait action.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 *
70
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 66
diff changeset
66 * This function is equivalent to `w->elapsed = 0`;
66
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 * \pre w != NULL
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 * \param w the wait object
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 void
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 wait_start(struct wait *w);
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
73
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 /**
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 * Update the wait object.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 * \pre w != NULL
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 * \param w the wait object
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 * \param ticks the number of milliseconds since last frame
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 * \return true if complete
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 bool
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 wait_update(struct wait *w, unsigned int ticks);
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
84
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 /**
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 * Create an action from the wait object.
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 *
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 * \pre w != NULL
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 * \pre a != NULL
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 * \param w the wait object to copy from
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 * \param a the action to fill
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 */
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 void
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 wait_action(const struct wait *w, struct action *a);
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
95
9435a53adab4 core: implement wait action, closes #2466
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 #endif /* !MOLKO_WAIT_H */