SDL 3.0
SDL_test_common.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * Common functions of SDL test framework.
24 *
25 * This code is a part of the SDL test library, not the main SDL library.
26 */
27
28/* Ported from original test/common.h file. */
29
30#ifndef SDL_test_common_h_
31#define SDL_test_common_h_
32
33#include <SDL3/SDL.h>
34
35#ifdef SDL_PLATFORM_PSP
36#define DEFAULT_WINDOW_WIDTH 480
37#define DEFAULT_WINDOW_HEIGHT 272
38#elif defined(SDL_PLATFORM_VITA)
39#define DEFAULT_WINDOW_WIDTH 960
40#define DEFAULT_WINDOW_HEIGHT 544
41#else
42#define DEFAULT_WINDOW_WIDTH 640
43#define DEFAULT_WINDOW_HEIGHT 480
44#endif
45
47#define VERBOSE_VIDEO 0x00000001
48#define VERBOSE_MODES 0x00000002
49#define VERBOSE_RENDER 0x00000004
50#define VERBOSE_EVENT 0x00000008
51#define VERBOSE_AUDIO 0x00000010
52#define VERBOSE_MOTION 0x00000020
53
54/* !< Function pointer parsing one argument at argv[index], returning the number of parsed arguments,
55 * or a negative value when the argument is invalid */
56typedef int (SDLCALL *SDLTest_ParseArgumentsFp)(void *data, char **argv, int index);
57
58/* !< Finalize the argument parser. */
59typedef void (SDLCALL *SDLTest_FinalizeArgumentParserFp)(void *arg);
60
62{
63 /* !< Parse an argument. */
65 /* !< Finalize this argument parser. Called once before parsing the first argument. */
67 /* !< Null-terminated array of arguments. Printed when running with --help. */
68 const char **usage;
69 /* !< User data, passed to all callbacks. */
70 void *data;
71 /* !< Next argument parser. */
74
75typedef struct
76{
77 /* SDL init flags */
78 char **argv;
81
82 /* Video info */
83 const char *videodriver;
86 const char *window_title;
87 const char *window_icon;
104 float scale;
105 int depth;
112 const char *gpudriver;
113
114 /* Renderer info */
115 const char *renderdriver;
120
121 /* Audio info */
122 const char *audiodriver;
127
128 /* GL settings */
150
151 /* Mouse info */
154
155 /* Options info */
159
162
163#include <SDL3/SDL_begin_code.h>
164/* Set up for C function definitions, even when using C++ */
165#ifdef __cplusplus
166extern "C" {
167#endif
168
169/* Function prototypes */
170
171/**
172 * Parse command line parameters and create common state.
173 *
174 * \param argv Array of command line parameters
175 * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
176 *
177 * \returns a newly allocated common state object.
178 */
180
181/**
182 * Free the common state object.
183 *
184 * You should call SDL_Quit() before calling this function.
185 *
186 * \param state The common state object to destroy
187 */
189
190/**
191 * Process one common argument.
192 *
193 * \param state The common state describing the test window to create.
194 * \param index The index of the argument to process in argv[].
195 *
196 * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
197 */
198int SDLCALL SDLTest_CommonArg(SDLTest_CommonState *state, int index);
199
200
201/**
202 * Logs command line usage info.
203 *
204 * This logs the appropriate command line options for the subsystems in use
205 * plus other common options, and then any application-specific options.
206 * This uses the SDL_Log() function and splits up output to be friendly to
207 * 80-character-wide terminals.
208 *
209 * \param state The common state describing the test window for the app.
210 * \param argv0 argv[0], as passed to main/SDL_main.
211 * \param options an array of strings for application specific options. The last element of the array should be NULL.
212 */
213void SDLCALL SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options);
214
215/**
216 * Open test window.
217 *
218 * \param state The common state describing the test window to create.
219 *
220 * \returns true if initialization succeeded, false otherwise
221 */
223
224/**
225 * Easy argument handling when test app doesn't need any custom args.
226 *
227 * \param state The common state describing the test window to create.
228 * \param argc argc, as supplied to SDL_main
229 * \param argv argv, as supplied to SDL_main
230 *
231 * \returns false if app should quit, true otherwise.
232 */
233bool SDLCALL SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv);
234
235/**
236 * Print the details of an event.
237 *
238 * This is automatically called by SDLTest_CommonEvent() as needed.
239 *
240 * \param event The event to print.
241 */
242void SDLCALL SDLTest_PrintEvent(const SDL_Event *event);
243
244/**
245 * Common event handler for test windows if you use a standard SDL_main.
246 *
247 * \param state The common state used to create test window.
248 * \param event The event to handle.
249 * \param done Flag indicating we are done.
250 */
251void SDLCALL SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done);
252
253/**
254 * Common event handler for test windows if you use SDL_AppEvent.
255 *
256 * This does _not_ free anything in `event`.
257 *
258 * \param state The common state used to create test window.
259 * \param event The event to handle.
260 * \returns Value suitable for returning from SDL_AppEvent().
261 */
263
264/**
265 * Close test window.
266 *
267 * \param state The common state used to create test window.
268 *
269 */
271
272/**
273 * Draws various window information (position, size, etc.) to the renderer.
274 *
275 * \param renderer The renderer to draw to.
276 * \param window The window whose information should be displayed.
277 * \param usedHeight Returns the height used, so the caller can draw more below.
278 *
279 */
280void SDLCALL SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight);
281
282/* Ends C function definitions when using C++ */
283#ifdef __cplusplus
284}
285#endif
286#include <SDL3/SDL_close_code.h>
287
288#endif /* SDL_test_common_h_ */
Uint32 SDL_AudioDeviceID
Definition SDL_audio.h:374
SDL_AudioFormat
Definition SDL_audio.h:222
Uint32 SDL_InitFlags
Definition SDL_init.h:78
SDL_AppResult
Definition SDL_init.h:110
SDL_RendererLogicalPresentation
Definition SDL_render.h:106
struct SDL_Renderer SDL_Renderer
Definition SDL_render.h:119
uint32_t Uint32
Definition SDL_stdinc.h:435
void SDLTest_PrintEvent(const SDL_Event *event)
bool SDLTest_CommonInit(SDLTest_CommonState *state)
void SDLTest_CommonQuit(SDLTest_CommonState *state)
Uint32 SDLTest_VerboseFlags
bool SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv)
void SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done)
int SDLTest_CommonArg(SDLTest_CommonState *state, int index)
void SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight)
void(* SDLTest_FinalizeArgumentParserFp)(void *arg)
void SDLTest_CommonDestroyState(SDLTest_CommonState *state)
void SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options)
SDL_AppResult SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event)
int(* SDLTest_ParseArgumentsFp)(void *data, char **argv, int index)
SDLTest_CommonState * SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags)
Uint32 SDL_DisplayID
Definition SDL_video.h:75
struct SDL_Window SDL_Window
Definition SDL_video.h:173
Uint64 SDL_WindowFlags
Definition SDL_video.h:187
SDLTest_FinalizeArgumentParserFp finalize
SDLTest_ParseArgumentsFp parse_arguments
struct SDLTest_ArgumentParser * next
SDLTest_ArgumentParser video_argparser
SDLTest_ArgumentParser common_argparser
SDL_Texture ** targets
SDLTest_ArgumentParser audio_argparser
const char * window_title
SDLTest_VerboseFlags verbose
SDL_DisplayID displayID
const char * videodriver
SDL_AudioDeviceID audio_id
const char * window_icon
SDL_AudioFormat audio_format
SDL_RendererLogicalPresentation logical_presentation
const char * renderdriver
SDL_WindowFlags window_flags
SDL_Renderer ** renderers
SDLTest_ArgumentParser * argparser
SDL_DisplayMode fullscreen_mode