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
46typedef Uint32 SDLTest_VerboseFlags;
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
61typedef struct SDLTest_ArgumentParser
62{
63 /* !< Parse an argument. */
64 SDLTest_ParseArgumentsFp parse_arguments;
65 /* !< Finalize this argument parser. Called once before parsing the first argument. */
66 SDLTest_FinalizeArgumentParserFp finalize;
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. */
72 struct SDLTest_ArgumentParser *next;
73} SDLTest_ArgumentParser;
74
75typedef struct
76{
77 /* SDL init flags */
78 char **argv;
79 SDL_InitFlags flags;
80 SDLTest_VerboseFlags verbose;
81
82 /* Video info */
83 const char *videodriver;
84 int display_index;
85 SDL_DisplayID displayID;
86 const char *window_title;
87 const char *window_icon;
88 SDL_WindowFlags window_flags;
89 bool flash_on_focus_loss;
90 int window_x;
91 int window_y;
92 int window_w;
93 int window_h;
94 int window_minW;
95 int window_minH;
96 int window_maxW;
97 int window_maxH;
98 float window_min_aspect;
99 float window_max_aspect;
100 int logical_w;
101 int logical_h;
102 bool auto_scale_content;
103 SDL_RendererLogicalPresentation logical_presentation;
104 float scale;
105 int depth;
106 float refresh_rate;
107 bool fill_usable_bounds;
108 bool fullscreen_exclusive;
109 SDL_DisplayMode fullscreen_mode;
110 int num_windows;
111 SDL_Window **windows;
112 const char *gpudriver;
113
114 /* Renderer info */
115 const char *renderdriver;
116 int render_vsync;
117 bool skip_renderer;
118 SDL_Renderer **renderers;
119 SDL_Texture **targets;
120
121 /* Audio info */
122 const char *audiodriver;
123 SDL_AudioFormat audio_format;
124 int audio_channels;
125 int audio_freq;
126 SDL_AudioDeviceID audio_id;
127
128 /* GL settings */
129 int gl_red_size;
130 int gl_green_size;
131 int gl_blue_size;
132 int gl_alpha_size;
133 int gl_buffer_size;
134 int gl_depth_size;
135 int gl_stencil_size;
136 int gl_double_buffer;
137 int gl_accum_red_size;
138 int gl_accum_green_size;
139 int gl_accum_blue_size;
140 int gl_accum_alpha_size;
141 int gl_stereo;
142 int gl_release_behavior;
143 int gl_multisamplebuffers;
144 int gl_multisamplesamples;
145 int gl_retained_backing;
146 int gl_accelerated;
147 int gl_major_version;
148 int gl_minor_version;
149 int gl_debug;
150 int gl_profile_mask;
151
152 /* Mouse info */
153 SDL_Rect confine;
154 bool hide_cursor;
155
156 /* Options info */
157 SDLTest_ArgumentParser common_argparser;
158 SDLTest_ArgumentParser video_argparser;
159 SDLTest_ArgumentParser audio_argparser;
160
161 SDLTest_ArgumentParser *argparser;
162} SDLTest_CommonState;
163
164#include <SDL3/SDL_begin_code.h>
165/* Set up for C function definitions, even when using C++ */
166#ifdef __cplusplus
167extern "C" {
168#endif
169
170/* Function prototypes */
171
172/**
173 * Parse command line parameters and create common state.
174 *
175 * \param argv Array of command line parameters
176 * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
177 *
178 * \returns a newly allocated common state object.
179 */
180SDLTest_CommonState * SDLCALL SDLTest_CommonCreateState(char **argv, SDL_InitFlags flags);
181
182/**
183 * Free the common state object.
184 *
185 * You should call SDL_Quit() before calling this function.
186 *
187 * \param state The common state object to destroy
188 */
189void SDLCALL SDLTest_CommonDestroyState(SDLTest_CommonState *state);
190
191/**
192 * Process one common argument.
193 *
194 * \param state The common state describing the test window to create.
195 * \param index The index of the argument to process in argv[].
196 *
197 * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
198 */
199int SDLCALL SDLTest_CommonArg(SDLTest_CommonState *state, int index);
200
201
202/**
203 * Logs command line usage info.
204 *
205 * This logs the appropriate command line options for the subsystems in use
206 * plus other common options, and then any application-specific options.
207 * This uses the SDL_Log() function and splits up output to be friendly to
208 * 80-character-wide terminals.
209 *
210 * \param state The common state describing the test window for the app.
211 * \param argv0 argv[0], as passed to main/SDL_main.
212 * \param options an array of strings for application specific options. The last element of the array should be NULL.
213 */
214void SDLCALL SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options);
215
216/**
217 * Open test window.
218 *
219 * \param state The common state describing the test window to create.
220 *
221 * \returns true if initialization succeeded, false otherwise
222 */
223bool SDLCALL SDLTest_CommonInit(SDLTest_CommonState *state);
224
225/**
226 * Easy argument handling when test app doesn't need any custom args.
227 *
228 * \param state The common state describing the test window to create.
229 * \param argc argc, as supplied to SDL_main
230 * \param argv argv, as supplied to SDL_main
231 *
232 * \returns false if app should quit, true otherwise.
233 */
234bool SDLCALL SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, int argc, char **argv);
235
236/**
237 * Print the details of an event.
238 *
239 * This is automatically called by SDLTest_CommonEvent() as needed.
240 *
241 * \param event The event to print.
242 */
243void SDLCALL SDLTest_PrintEvent(const SDL_Event *event);
244
245/**
246 * Common event handler for test windows if you use a standard SDL_main.
247 *
248 * \param state The common state used to create test window.
249 * \param event The event to handle.
250 * \param done Flag indicating we are done.
251 */
252void SDLCALL SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done);
253
254/**
255 * Common event handler for test windows if you use SDL_AppEvent.
256 *
257 * This does _not_ free anything in `event`.
258 *
259 * \param state The common state used to create test window.
260 * \param event The event to handle.
261 * \returns Value suitable for returning from SDL_AppEvent().
262 */
263SDL_AppResult SDLCALL SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event);
264
265/**
266 * Close test window.
267 *
268 * \param state The common state used to create test window.
269 *
270 */
271void SDLCALL SDLTest_CommonQuit(SDLTest_CommonState *state);
272
273/**
274 * Draws various window information (position, size, etc.) to the renderer.
275 *
276 * \param renderer The renderer to draw to.
277 * \param window The window whose information should be displayed.
278 * \param usedHeight Returns the height used, so the caller can draw more below.
279 *
280 */
281void SDLCALL SDLTest_CommonDrawWindowInfo(SDL_Renderer *renderer, SDL_Window *window, float *usedHeight);
282
283/* Ends C function definitions when using C++ */
284#ifdef __cplusplus
285}
286#endif
287#include <SDL3/SDL_close_code.h>
288
289#endif /* SDL_test_common_h_ */
290