mse / ConfectionerEngine (public) (License: Confectioner Engine license) (since 2021-04-24) (hash sha1)
Farming RPG engine
Clone URLs: https://rocketgit.com/user/mse/ConfectionerEngine ssh://rocketgit@ssh.rocketgit.com/user/mse/ConfectionerEngine git://git.rocketgit.com/user/mse/ConfectionerEngine
master
List of commits:
Subject Hash Author Date (UTC)
Fix Windows build and update SDL d8f30e756bc4d5a63e5b7524db2b69ae5af4f88f mse 2021-09-29 23:31:25
Update gamecontrollerdb 3da6ad2629e0b28cad34b3ff7a89c0fe0d96a2fd mse 2021-09-29 23:02:39
Parse newline escape sequences in caption ff33cfb3e88098ae24a6afa1cc7ac9049b6e4c1f mse 2021-09-27 23:45:58
Fix loadOBJ(...) 0b307ff98c2aa8f79d62770b3e2aff6fb7d8670a mse 2021-09-25 05:18:15
Add uploadModelTransforms(...) 53530b8cabe72cfa6c71148bd484a1b5a17df565 mse 2021-09-23 14:33:47
Readability a5885db68a6134c7c3930b6cf10650f0b340088d mse 2021-09-13 15:56:30
Pad HUD health with 0 267304751e17901c276108d8899d096e2094cb2a mse 2021-09-13 11:02:57
Housekeeping 6ff79e3a21829e267e866a8472777e180d337ff4 mse 2021-09-13 07:33:00
Add CSL comments 7a818e8b57cb38c9bfef922e66bd6f735b4962e4 mse 2021-09-12 09:26:07
Add Confectioner Scripting Language (CSL) & change array separator to ; 8d980bfac5d649574f749b7c04a19af766f71091 mse 2021-09-11 12:31:58
Fix console /set bug 7c45e27e7f40472bea317b0316e4367135b49704 mse 2021-09-11 01:32:11
Scriptable lines@, ids@, bugfix 9f606fd2a793fd76a9d1b9e186434d231b973085 mse 2021-09-10 14:43:50
Add array scripting (@ operator, ARRLEN <array>) 3f098b3e0a04922c2c7a981b232efd8d08a8d9a0 mse 2021-09-10 14:02:39
Optimize script runtime a298b01c9b77192b7ed8aba3832a8ab51c9d389a mse 2021-09-09 06:57:49
Scriptable bg$, fg$, caption$ 0ad08aa3887118d2376f4fa7f8b7c66e0f164c73 mse 2021-09-06 11:04:38
Animation command: ANIM <loop|play> <bg|fg> <fps> <directory> 6066e2cae1dc29043902d46549f443c7b683fd88 mse 2021-09-06 06:42:13
Switch to C++17 489987b1b2749f37e0ac76594308635affbd24f2 mse 2021-09-05 10:51:02
Fix stats synchronization bug 3b6195c3321a6f10af43839cc00d24f301eddb3e mse 2021-09-05 04:45:58
Add top-level command: STRLEN, scriptable player name$ ec7a623cdc98b9832f35f0beb3e45179e6094436 mse 2021-09-05 03:17:47
Start work on animation system d2aafd6f46c719342054e3f256f972f4917f2231 mse 2021-09-05 02:41:28
Commit d8f30e756bc4d5a63e5b7524db2b69ae5af4f88f - Fix Windows build and update SDL
Author: mse
Author date (UTC): 2021-09-29 23:31
Committer name: mse
Committer date (UTC): 2021-09-29 23:31
Parent(s): 3da6ad2629e0b28cad34b3ff7a89c0fe0d96a2fd
Signer:
Signing key:
Signing status: N
Tree: 312166a2fcd0bae25670d7de41c27534e8374fd5
File Lines added Lines deleted
Makefile 1 1
confec.cpp 1 1
include/SDL2/SDL.h 97 14
include/SDL2/SDL_assert.h 76 51
include/SDL2/SDL_atomic.h 118 34
include/SDL2/SDL_audio.h 701 375
include/SDL2/SDL_bits.h 11 6
include/SDL2/SDL_blendmode.h 91 14
include/SDL2/SDL_clipboard.h 25 7
include/SDL2/SDL_config.h 18 7
include/SDL2/SDL_cpuinfo.h 296 71
include/SDL2/SDL_egl.h 1 1
include/SDL2/SDL_endian.h 93 40
include/SDL2/SDL_error.h 62 19
include/SDL2/SDL_events.h 350 79
include/SDL2/SDL_filesystem.h 73 64
include/SDL2/SDL_gamecontroller.h 460 131
include/SDL2/SDL_gesture.h 36 6
include/SDL2/SDL_haptic.h 282 209
include/SDL2/SDL_hints.h 1160 898
include/SDL2/SDL_joystick.h 452 130
include/SDL2/SDL_keyboard.h 140 63
include/SDL2/SDL_keycode.h 3 3
include/SDL2/SDL_loadso.h 36 8
include/SDL2/SDL_locale.h 32 32
include/SDL2/SDL_log.h 184 19
include/SDL2/SDL_main.h 22 16
include/SDL2/SDL_messagebox.h 68 23
include/SDL2/SDL_metal.h 21 34
include/SDL2/SDL_misc.h 19 15
include/SDL2/SDL_mouse.h 240 110
include/SDL2/SDL_mutex.h 251 67
include/SDL2/SDL_name.h 1 1
include/SDL2/SDL_opengl.h 1 1
include/SDL2/SDL_opengles.h 1 1
include/SDL2/SDL_opengles2.h 1 1
include/SDL2/SDL_pixels.h 168 34
include/SDL2/SDL_platform.h 37 2
include/SDL2/SDL_power.h 21 10
include/SDL2/SDL_quit.h 1 1
include/SDL2/SDL_rect.h 72 28
include/SDL2/SDL_render.h 958 491
include/SDL2/SDL_revision.h 2 2
include/SDL2/SDL_rwops.h 163 34
include/SDL2/SDL_scancode.h 1 1
include/SDL2/SDL_sensor.h 54 50
include/SDL2/SDL_shape.h 34 31
include/SDL2/SDL_stdinc.h 64 17
include/SDL2/SDL_surface.h 469 145
include/SDL2/SDL_system.h 251 101
include/SDL2/SDL_syswm.h 44 20
include/SDL2/SDL_test.h 1 1
include/SDL2/SDL_test_assert.h 2 2
include/SDL2/SDL_test_common.h 18 6
include/SDL2/SDL_test_compare.h 1 1
include/SDL2/SDL_test_crc32.h 1 1
include/SDL2/SDL_test_font.h 3 3
include/SDL2/SDL_test_fuzzer.h 28 26
include/SDL2/SDL_test_harness.h 3 3
include/SDL2/SDL_test_images.h 1 1
include/SDL2/SDL_test_log.h 1 1
include/SDL2/SDL_test_md5.h 1 1
include/SDL2/SDL_test_memory.h 1 1
include/SDL2/SDL_test_random.h 2 2
include/SDL2/SDL_thread.h 210 122
include/SDL2/SDL_timer.h 79 22
include/SDL2/SDL_touch.h 44 8
include/SDL2/SDL_types.h 1 1
include/SDL2/SDL_version.h 57 47
include/SDL2/SDL_video.h 1086 467
include/SDL2/SDL_vulkan.h 98 161
include/SDL2/begin_code.h 1 1
include/SDL2/close_code.h 1 1
File Makefile changed (mode: 100644) (index c7186de..ca1d7e8)
... ... PROGRAM_DRMFREE=cave-confec
3 3 INCLUDES=include/fworld.h include/civilian.h INCLUDES=include/fworld.h include/civilian.h
4 4
5 5 # SDL2 # SDL2
6 SDL2_VER=2.0.14
6 SDL2_VER=2.0.16
7 7 SDL2_DIR=SDL2-$(SDL2_VER) SDL2_DIR=SDL2-$(SDL2_VER)
8 8 SDL2_TAR=$(SDL2_DIR).tar.gz SDL2_TAR=$(SDL2_DIR).tar.gz
9 9 SDL2_WIN_TAR=SDL2-devel-$(SDL2_VER)-mingw.tar.gz SDL2_WIN_TAR=SDL2-devel-$(SDL2_VER)-mingw.tar.gz
File confec.cpp changed (mode: 100644) (index 660ba95..dce0851)
... ... int main( int argc, char* argv[] ){
1242 1242 if( ext == ".png" || ext == ".PNG" if( ext == ".png" || ext == ".PNG"
1243 1243 || ext == ".jpg" || ext == ".JPG" || ext == ".jpg" || ext == ".JPG"
1244 1244 || ext == ".jpeg" || ext == ".JPEG" ){ || ext == ".jpeg" || ext == ".JPEG" ){
1245 frame_files[entry.path().filename()] = true;
1245 frame_files[entry.path().filename().string()] = true;
1246 1246 } }
1247 1247 } }
1248 1248 } }
File include/SDL2/SDL.h changed (mode: 100644) (index e2656ca..222a8bd)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
93 93 /* @} */ /* @} */
94 94
95 95 /** /**
96 * This function initializes the subsystems specified by \c flags
96 * Initialize the SDL library.
97 *
98 * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
99 * two may be used interchangeably. Though for readability of your code
100 * SDL_InitSubSystem() might be preferred.
101 *
102 * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
103 * subsystems are initialized by default. Message boxes
104 * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
105 * video subsystem, in hopes of being useful in showing an error dialog when
106 * SDL_Init fails. You must specifically initialize other subsystems if you
107 * use them in your application.
108 *
109 * Logging (such as SDL_Log) works without initialization, too.
110 *
111 * `flags` may be any of the following OR'd together:
112 *
113 * - `SDL_INIT_TIMER`: timer subsystem
114 * - `SDL_INIT_AUDIO`: audio subsystem
115 * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
116 * subsystem
117 * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
118 * events subsystem
119 * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
120 * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
121 * initializes the joystick subsystem
122 * - `SDL_INIT_EVENTS`: events subsystem
123 * - `SDL_INIT_EVERYTHING`: all of the above subsystems
124 * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
125 *
126 * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
127 * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
128 * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
129 * this call will increase the ref-count and return.
130 *
131 * \param flags subsystem initialization flags
132 * \returns 0 on success or a negative error code on failure; call
133 * SDL_GetError() for more information.
134 *
135 * \sa SDL_InitSubSystem
136 * \sa SDL_Quit
137 * \sa SDL_SetMainReady
138 * \sa SDL_WasInit
97 139 */ */
98 140 extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags); extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
99 141
100 142 /** /**
101 * This function initializes specific SDL subsystems
143 * Compatibility function to initialize the SDL library.
144 *
145 * In SDL2, this function and SDL_Init() are interchangeable.
146 *
147 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
148 * \returns 0 on success or a negative error code on failure; call
149 * SDL_GetError() for more information.
102 150 * *
103 * Subsystem initialization is ref-counted, you must call
104 * SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
105 * shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
106 * If a subsystem is already loaded then this call will
107 * increase the ref-count and return.
151 * \sa SDL_Init
152 * \sa SDL_Quit
153 * \sa SDL_QuitSubSystem
108 154 */ */
109 155 extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags); extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
110 156
111 157 /** /**
112 * This function cleans up specific SDL subsystems
158 * Shut down specific SDL subsystems.
159 *
160 * If you start a subsystem using a call to that subsystem's init function
161 * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
162 * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
163 * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
164 * generally, you should not be using those functions directly anyhow; use
165 * SDL_Init() instead.
166 *
167 * You still need to call SDL_Quit() even if you close all open subsystems
168 * with SDL_QuitSubSystem().
169 *
170 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
171 *
172 * \sa SDL_InitSubSystem
173 * \sa SDL_Quit
113 174 */ */
114 175 extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags); extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
115 176
116 177 /** /**
117 * This function returns a mask of the specified subsystems which have
118 * previously been initialized.
178 * Get a mask of the specified subsystems which are currently initialized.
179 *
180 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
181 * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
182 * returns the initialization status of the specified subsystems.
119 183 * *
120 * If \c flags is 0, it returns a mask of all initialized subsystems.
184 * The return value does not include SDL_INIT_NOPARACHUTE.
185 *
186 * \sa SDL_Init
187 * \sa SDL_InitSubSystem
121 188 */ */
122 189 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags); extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
123 190
124 191 /** /**
125 * This function cleans up all initialized subsystems. You should
126 * call it upon all exit conditions.
192 * Clean up all initialized subsystems.
193 *
194 * You should call this function even if you have already shutdown each
195 * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
196 * function even in the case of errors in initialization.
197 *
198 * If you start a subsystem using a call to that subsystem's init function
199 * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
200 * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
201 * it down before calling SDL_Quit(). But generally, you should not be using
202 * those functions directly anyhow; use SDL_Init() instead.
203 *
204 * You can use this function with atexit() to ensure that it is run when your
205 * application is shutdown, but it is not wise to do this from a library or
206 * other dynamically loaded code.
207 *
208 * \sa SDL_Init
209 * \sa SDL_QuitSubSystem
127 210 */ */
128 211 extern DECLSPEC void SDLCALL SDL_Quit(void); extern DECLSPEC void SDLCALL SDL_Quit(void);
129 212
File include/SDL2/SDL_assert.h changed (mode: 100644) (index f8a368e..a627b17)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... assert can have unique static variables associated with it.
53 53 #define SDL_TriggerBreakpoint() __debugbreak() #define SDL_TriggerBreakpoint() __debugbreak()
54 54 #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) ) #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) )
55 55 #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
56 #elif ( defined(__APPLE__) && defined(__arm64__) ) /* this might work on other ARM targets, but this is a known quantity... */
56 #elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */
57 57 #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" ) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" )
58 #elif defined(__APPLE__) && defined(__arm__)
59 #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
58 60 #elif defined(__386__) && defined(__WATCOMC__) #elif defined(__386__) && defined(__WATCOMC__)
59 61 #define SDL_TriggerBreakpoint() { _asm { int 0x03 } } #define SDL_TriggerBreakpoint() { _asm { int 0x03 } }
60 62 #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__) #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__)
 
... ... extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
187 189 #define SDL_assert_always(condition) SDL_enabled_assert(condition) #define SDL_assert_always(condition) SDL_enabled_assert(condition)
188 190
189 191
192 /**
193 * A callback that fires when an SDL assertion fails.
194 *
195 * \param data a pointer to the SDL_AssertData structure corresponding to the
196 * current assertion
197 * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
198 * \returns an SDL_AssertState value indicating how to handle the failure.
199 */
190 200 typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
191 201 const SDL_AssertData* data, void* userdata); const SDL_AssertData* data, void* userdata);
192 202
193 203 /** /**
194 * \brief Set an application-defined assertion handler.
204 * Set an application-defined assertion handler.
195 205 * *
196 * This allows an app to show its own assertion UI and/or force the
197 * response to an assertion failure. If the app doesn't provide this, SDL
198 * will try to do the right thing, popping up a system-specific GUI dialog,
199 * and probably minimizing any fullscreen windows.
206 * This function allows an application to show its own assertion UI and/or
207 * force the response to an assertion failure. If the application doesn't
208 * provide this, SDL will try to do the right thing, popping up a
209 * system-specific GUI dialog, and probably minimizing any fullscreen windows.
200 210 * *
201 * This callback may fire from any thread, but it runs wrapped in a mutex, so
202 * it will only fire from one thread at a time.
211 * This callback may fire from any thread, but it runs wrapped in a mutex, so
212 * it will only fire from one thread at a time.
203 213 * *
204 * Setting the callback to NULL restores SDL's original internal handler.
214 * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
205 215 * *
206 * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
216 * \param handler the SDL_AssertionHandler function to call when an assertion
217 * fails or NULL for the default handler
218 * \param userdata a pointer that is passed to `handler`
207 219 * *
208 * Return SDL_AssertState value of how to handle the assertion failure.
209 *
210 * \param handler Callback function, called when an assertion fails.
211 * \param userdata A pointer passed to the callback as-is.
220 * \sa SDL_GetAssertionHandler
212 221 */ */
213 222 extern DECLSPEC void SDLCALL SDL_SetAssertionHandler( extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
214 223 SDL_AssertionHandler handler, SDL_AssertionHandler handler,
215 224 void *userdata); void *userdata);
216 225
217 226 /** /**
218 * \brief Get the default assertion handler.
227 * Get the default assertion handler.
228 *
229 * This returns the function pointer that is called by default when an
230 * assertion is triggered. This is an internal function provided by SDL, that
231 * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
232 * provide a different function.
219 233 * *
220 * This returns the function pointer that is called by default when an
221 * assertion is triggered. This is an internal function provided by SDL,
222 * that is used for assertions when SDL_SetAssertionHandler() hasn't been
223 * used to provide a different function.
234 * \returns the default SDL_AssertionHandler that is called when an assert
235 * triggers.
224 236 * *
225 * \return The default SDL_AssertionHandler that is called when an assert triggers.
237 * \since This function is available since SDL 2.0.2.
238 *
239 * \sa SDL_GetAssertionHandler
226 240 */ */
227 241 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void); extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
228 242
229 243 /** /**
230 * \brief Get the current assertion handler.
244 * Get the current assertion handler.
245 *
246 * This returns the function pointer that is called when an assertion is
247 * triggered. This is either the value last passed to
248 * SDL_SetAssertionHandler(), or if no application-specified function is set,
249 * is equivalent to calling SDL_GetDefaultAssertionHandler().
250 *
251 * The parameter `puserdata` is a pointer to a void*, which will store the
252 * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
253 * will always be NULL for the default handler. If you don't care about this
254 * data, it is safe to pass a NULL pointer to this function to ignore it.
231 255 * *
232 * This returns the function pointer that is called when an assertion is
233 * triggered. This is either the value last passed to
234 * SDL_SetAssertionHandler(), or if no application-specified function is
235 * set, is equivalent to calling SDL_GetDefaultAssertionHandler().
256 * \param puserdata pointer which is filled with the "userdata" pointer that
257 * was passed to SDL_SetAssertionHandler()
258 * \returns the SDL_AssertionHandler that is called when an assert triggers.
236 259 * *
237 * \param puserdata Pointer to a void*, which will store the "userdata"
238 * pointer that was passed to SDL_SetAssertionHandler().
239 * This value will always be NULL for the default handler.
240 * If you don't care about this data, it is safe to pass
241 * a NULL pointer to this function to ignore it.
242 * \return The SDL_AssertionHandler that is called when an assert triggers.
260 * \since This function is available since SDL 2.0.2.
261 *
262 * \sa SDL_SetAssertionHandler
243 263 */ */
244 264 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata); extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
245 265
246 266 /** /**
247 * \brief Get a list of all assertion failures.
267 * Get a list of all assertion failures.
268 *
269 * This function gets all assertions triggered since the last call to
270 * SDL_ResetAssertionReport(), or the start of the program.
248 271 * *
249 * Get all assertions triggered since last call to SDL_ResetAssertionReport(),
250 * or the start of the program.
272 * The proper way to examine this data looks something like this:
251 273 * *
252 * The proper way to examine this data looks something like this:
274 * ```c
275 * const SDL_AssertData *item = SDL_GetAssertionReport();
276 * while (item) {
277 * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
278 * item->condition, item->function, item->filename,
279 * item->linenum, item->trigger_count,
280 * item->always_ignore ? "yes" : "no");
281 * item = item->next;
282 * }
283 * ```
253 284 * *
254 * <code>
255 * const SDL_AssertData *item = SDL_GetAssertionReport();
256 * while (item) {
257 * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
258 * item->condition, item->function, item->filename,
259 * item->linenum, item->trigger_count,
260 * item->always_ignore ? "yes" : "no");
261 * item = item->next;
262 * }
263 * </code>
285 * \returns a list of all failed assertions or NULL if the list is empty. This
286 * memory should not be modified or freed by the application.
264 287 * *
265 * \return List of all assertions.
266 * \sa SDL_ResetAssertionReport
288 * \sa SDL_ResetAssertionReport
267 289 */ */
268 290 extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
269 291
270 292 /** /**
271 * \brief Reset the list of all assertion failures.
293 * Clear the list of all assertion failures.
272 294 * *
273 * Reset list of all assertions triggered.
295 * This function will clear the list of all assertions triggered up to that
296 * point. Immediately following this call, SDL_GetAssertionReport will return
297 * no items. In addition, any previously-triggered assertions will be reset to
298 * a trigger_count of zero, and their always_ignore state will be false.
274 299 * *
275 * \sa SDL_GetAssertionReport
300 * \sa SDL_GetAssertionReport
276 301 */ */
277 302 extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void); extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
278 303
File include/SDL2/SDL_atomic.h changed (mode: 100644) (index e99f1bc..5e1eae7)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
89 89 typedef int SDL_SpinLock; typedef int SDL_SpinLock;
90 90
91 91 /** /**
92 * \brief Try to lock a spin lock by setting it to a non-zero value.
92 * Try to lock a spin lock by setting it to a non-zero value.
93 93 * *
94 * \param lock Points to the lock.
94 * ***Please note that spinlocks are dangerous if you don't know what you're
95 * doing. Please be careful using any sort of spinlock!***
95 96 * *
96 * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
97 * \param lock a pointer to a lock variable
98 * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
99 * held.
100 *
101 * \sa SDL_AtomicLock
102 * \sa SDL_AtomicUnlock
97 103 */ */
98 104 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock); extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
99 105
100 106 /** /**
101 * \brief Lock a spin lock by setting it to a non-zero value.
107 * Lock a spin lock by setting it to a non-zero value.
108 *
109 * ***Please note that spinlocks are dangerous if you don't know what you're
110 * doing. Please be careful using any sort of spinlock!***
102 111 * *
103 * \param lock Points to the lock.
112 * \param lock a pointer to a lock variable
113 *
114 * \sa SDL_AtomicTryLock
115 * \sa SDL_AtomicUnlock
104 116 */ */
105 117 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock); extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
106 118
107 119 /** /**
108 * \brief Unlock a spin lock by setting it to 0. Always returns immediately
120 * Unlock a spin lock by setting it to 0.
121 *
122 * Always returns immediately.
123 *
124 * ***Please note that spinlocks are dangerous if you don't know what you're
125 * doing. Please be careful using any sort of spinlock!***
126 *
127 * \param lock a pointer to a lock variable
128 *
129 * \since This function is available since SDL 2.0.0.
109 130 * *
110 * \param lock Points to the lock.
131 * \sa SDL_AtomicLock
132 * \sa SDL_AtomicTryLock
111 133 */ */
112 134 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock); extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
113 135
 
... ... extern _inline void SDL_CompilerBarrier (void);
137 159 * Memory barriers are designed to prevent reads and writes from being * Memory barriers are designed to prevent reads and writes from being
138 160 * reordered by the compiler and being seen out of order on multi-core CPUs. * reordered by the compiler and being seen out of order on multi-core CPUs.
139 161 * *
140 * A typical pattern would be for thread A to write some data and a flag,
141 * and for thread B to read the flag and get the data. In this case you
142 * would insert a release barrier between writing the data and the flag,
162 * A typical pattern would be for thread A to write some data and a flag, and
163 * for thread B to read the flag and get the data. In this case you would
164 * insert a release barrier between writing the data and the flag,
143 165 * guaranteeing that the data write completes no later than the flag is * guaranteeing that the data write completes no later than the flag is
144 * written, and you would insert an acquire barrier between reading the
145 * flag and reading the data, to ensure that all the reads associated
146 * with the flag have completed.
166 * written, and you would insert an acquire barrier between reading the flag
167 * and reading the data, to ensure that all the reads associated with the flag
168 * have completed.
147 169 * *
148 * In this pattern you should always see a release barrier paired with
149 * an acquire barrier and you should gate the data reads/writes with a
150 * single flag variable.
170 * In this pattern you should always see a release barrier paired with an
171 * acquire barrier and you should gate the data reads/writes with a single
172 * flag variable.
151 173 * *
152 174 * For more information on these semantics, take a look at the blog post: * For more information on these semantics, take a look at the blog post:
153 175 * http://preshing.com/20120913/acquire-and-release-semantics * http://preshing.com/20120913/acquire-and-release-semantics
 
... ... typedef void (*SDL_KernelMemoryBarrierFunc)();
216 238 typedef struct { int value; } SDL_atomic_t; typedef struct { int value; } SDL_atomic_t;
217 239
218 240 /** /**
219 * \brief Set an atomic variable to a new value if it is currently an old value.
241 * Set an atomic variable to a new value if it is currently an old value.
220 242 * *
221 * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
243 * ***Note: If you don't know what this function is for, you shouldn't use
244 * it!***
222 245 * *
223 * \note If you don't know what this function is for, you shouldn't use it!
224 */
246 * \param a a pointer to an SDL_atomic_t variable to be modified
247 * \param oldval the old value
248 * \param newval the new value
249 * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
250 *
251 * \since This function is available since SDL 2.0.0.
252 *
253 * \sa SDL_AtomicCASPtr
254 * \sa SDL_AtomicGet
255 * \sa SDL_AtomicSet
256 */
225 257 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval); extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
226 258
227 259 /** /**
228 * \brief Set an atomic variable to a value.
260 * Set an atomic variable to a value.
261 *
262 * This function also acts as a full memory barrier.
263 *
264 * ***Note: If you don't know what this function is for, you shouldn't use
265 * it!***
266 *
267 * \param a a pointer to an SDL_atomic_t variable to be modified
268 * \param v the desired value
269 * \returns the previous value of the atomic variable.
229 270 * *
230 * \return The previous value of the atomic variable.
271 * \sa SDL_AtomicGet
231 272 */ */
232 273 extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v); extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
233 274
234 275 /** /**
235 * \brief Get the value of an atomic variable
276 * Get the value of an atomic variable.
277 *
278 * ***Note: If you don't know what this function is for, you shouldn't use
279 * it!***
280 *
281 * \param a a pointer to an SDL_atomic_t variable
282 * \returns the current value of an atomic variable.
283 *
284 * \sa SDL_AtomicSet
236 285 */ */
237 286 extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
238 287
239 288 /** /**
240 * \brief Add to an atomic variable.
289 * Add to an atomic variable.
290 *
291 * This function also acts as a full memory barrier.
241 292 * *
242 * \return The previous value of the atomic variable.
293 * ***Note: If you don't know what this function is for, you shouldn't use
294 * it!***
243 295 * *
244 * \note This same style can be used for any number operation
296 * \param a a pointer to an SDL_atomic_t variable to be modified
297 * \param v the desired value to add
298 * \returns the previous value of the atomic variable.
299 *
300 * \sa SDL_AtomicDecRef
301 * \sa SDL_AtomicIncRef
245 302 */ */
246 303 extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v); extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
247 304
 
... ... extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
263 320 #endif #endif
264 321
265 322 /** /**
266 * \brief Set a pointer to a new value if it is currently an old value.
323 * Set a pointer to a new value if it is currently an old value.
267 324 * *
268 * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
325 * ***Note: If you don't know what this function is for, you shouldn't use
326 * it!***
269 327 * *
270 * \note If you don't know what this function is for, you shouldn't use it!
271 */
328 * \param a a pointer to a pointer
329 * \param oldval the old pointer value
330 * \param newval the new pointer value
331 * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
332 *
333 * \since This function is available since SDL 2.0.0.
334 *
335 * \sa SDL_AtomicCAS
336 * \sa SDL_AtomicGetPtr
337 * \sa SDL_AtomicSetPtr
338 */
272 339 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval); extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
273 340
274 341 /** /**
275 * \brief Set a pointer to a value atomically.
342 * Set a pointer to a value atomically.
343 *
344 * ***Note: If you don't know what this function is for, you shouldn't use
345 * it!***
346 *
347 * \param a a pointer to a pointer
348 * \param v the desired pointer value
349 * \returns the previous value of the pointer.
276 350 * *
277 * \return The previous value of the pointer.
351 * \sa SDL_AtomicCASPtr
352 * \sa SDL_AtomicGetPtr
278 353 */ */
279 354 extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v); extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
280 355
281 356 /** /**
282 * \brief Get the value of a pointer atomically.
357 * Get the value of a pointer atomically.
358 *
359 * ***Note: If you don't know what this function is for, you shouldn't use
360 * it!***
361 *
362 * \param a a pointer to a pointer
363 * \returns the current value of a pointer.
364 *
365 * \sa SDL_AtomicCASPtr
366 * \sa SDL_AtomicSetPtr
283 367 */ */
284 368 extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a); extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
285 369
File include/SDL2/SDL_audio.h changed (mode: 100644) (index 4ba3491..0aa0017)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
19 19 3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
20 20 */ */
21 21
22 /* !!! FIXME: several functions in here need Doxygen comments. */
23
22 24 /** /**
23 25 * \file SDL_audio.h * \file SDL_audio.h
24 26 * *
 
... ... typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
212 214 * set both its (buf) field to a pointer that is aligned to 16 bytes, and its * set both its (buf) field to a pointer that is aligned to 16 bytes, and its
213 215 * (len) field to something that's a multiple of 16, if possible. * (len) field to something that's a multiple of 16, if possible.
214 216 */ */
215 #ifdef __GNUC__
217 #if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__)
216 218 /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
217 219 pad it out to 88 bytes to guarantee ABI compatibility between compilers. pad it out to 88 bytes to guarantee ABI compatibility between compilers.
220 This is not a concern on CHERI architectures, where pointers must be stored
221 at aligned locations otherwise they will become invalid, and thus structs
222 containing pointers cannot be packed without giving a warning or error.
218 223 vvv vvv
219 224 The next time we rev the ABI, make sure to size the ints and add padding. The next time we rev the ABI, make sure to size the ints and add padding.
220 225 */ */
 
... ... extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
265 270 /* @} */ /* @} */
266 271
267 272 /** /**
268 * This function returns the name of the current audio driver, or NULL
269 * if no driver has been initialized.
273 * Get the name of the current audio driver.
274 *
275 * The returned string points to internal static memory and thus never becomes
276 * invalid, even if you quit the audio subsystem and initialize a new driver
277 * (although such a case would return a different static string from another
278 * call to this function, of course). As such, you should not modify or free
279 * the returned string.
280 *
281 * \returns the name of the current audio driver or NULL if no driver has been
282 * initialized.
283 *
284 * \since This function is available since SDL 2.0.0.
285 *
286 * \sa SDL_AudioInit
270 287 */ */
271 288 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
272 289
273 290 /** /**
274 * This function opens the audio device with the desired parameters, and
275 * returns 0 if successful, placing the actual hardware parameters in the
276 * structure pointed to by \c obtained. If \c obtained is NULL, the audio
277 * data passed to the callback function will be guaranteed to be in the
278 * requested format, and will be automatically converted to the hardware
279 * audio format if necessary. This function returns -1 if it failed
280 * to open the audio device, or couldn't set up the audio thread.
281 *
282 * When filling in the desired audio spec structure,
283 * - \c desired->freq should be the desired audio frequency in samples-per-
284 * second.
285 * - \c desired->format should be the desired audio format.
286 * - \c desired->samples is the desired size of the audio buffer, in
287 * samples. This number should be a power of two, and may be adjusted by
288 * the audio driver to a value more suitable for the hardware. Good values
289 * seem to range between 512 and 8096 inclusive, depending on the
290 * application and CPU speed. Smaller values yield faster response time,
291 * but can lead to underflow if the application is doing heavy processing
292 * and cannot fill the audio buffer in time. A stereo sample consists of
293 * both right and left channels in LR ordering.
294 * Note that the number of samples is directly related to time by the
295 * following formula: \code ms = (samples*1000)/freq \endcode
296 * - \c desired->size is the size in bytes of the audio buffer, and is
297 * calculated by SDL_OpenAudio().
298 * - \c desired->silence is the value used to set the buffer to silence,
299 * and is calculated by SDL_OpenAudio().
300 * - \c desired->callback should be set to a function that will be called
301 * when the audio device is ready for more data. It is passed a pointer
302 * to the audio buffer, and the length in bytes of the audio buffer.
303 * This function usually runs in a separate thread, and so you should
304 * protect data structures that it accesses by calling SDL_LockAudio()
305 * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
306 * pointer here, and call SDL_QueueAudio() with some frequency, to queue
307 * more audio samples to be played (or for capture devices, call
308 * SDL_DequeueAudio() with some frequency, to obtain audio samples).
309 * - \c desired->userdata is passed as the first parameter to your callback
310 * function. If you passed a NULL callback, this value is ignored.
311 *
312 * The audio device starts out playing silence when it's opened, and should
313 * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
314 * for your audio callback function to be called. Since the audio driver
315 * may modify the requested size of the audio buffer, you should allocate
316 * any local mixing buffers after you open the audio device.
291 * This function is a legacy means of opening the audio device.
292 *
293 * This function remains for compatibility with SDL 1.2, but also because it's
294 * slightly easier to use than the new functions in SDL 2.0. The new, more
295 * powerful, and preferred way to do this is SDL_OpenAudioDevice().
296 *
297 * This function is roughly equivalent to:
298 *
299 * ```c++
300 * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
301 * ```
302 *
303 * With two notable exceptions:
304 *
305 * - If `obtained` is NULL, we use `desired` (and allow no changes), which
306 * means desired will be modified to have the correct values for silence,
307 * etc, and SDL will convert any differences between your app's specific
308 * request and the hardware behind the scenes.
309 * - The return value is always success or failure, and not a device ID, which
310 * means you can only have one device open at a time with this function.
311 *
312 * \param desired an SDL_AudioSpec structure representing the desired output
313 * format. Please refer to the SDL_OpenAudioDevice
314 * documentation for details on how to prepare this structure.
315 * \param obtained an SDL_AudioSpec structure filled in with the actual
316 * parameters, or NULL.
317 * \returns 0 if successful, placing the actual hardware parameters in the
318 * structure pointed to by `obtained`.
319 *
320 * If `obtained` is NULL, the audio data passed to the callback
321 * function will be guaranteed to be in the requested format, and
322 * will be automatically converted to the actual hardware audio
323 * format if necessary. If `obtained` is NULL, `desired` will have
324 * fields modified.
325 *
326 * This function returns a negative error code on failure to open the
327 * audio device or failure to set up the audio thread; call
328 * SDL_GetError() for more information.
329 *
330 * \sa SDL_CloseAudio
331 * \sa SDL_LockAudio
332 * \sa SDL_PauseAudio
333 * \sa SDL_UnlockAudio
317 334 */ */
318 335 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
319 336 SDL_AudioSpec * obtained); SDL_AudioSpec * obtained);
 
... ... extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
330 347 typedef Uint32 SDL_AudioDeviceID; typedef Uint32 SDL_AudioDeviceID;
331 348
332 349 /** /**
333 * Get the number of available devices exposed by the current driver.
334 * Only valid after a successfully initializing the audio subsystem.
335 * Returns -1 if an explicit list of devices can't be determined; this is
336 * not an error. For example, if SDL is set up to talk to a remote audio
337 * server, it can't list every one available on the Internet, but it will
338 * still allow a specific host to be specified to SDL_OpenAudioDevice().
350 * Get the number of built-in audio devices.
351 *
352 * This function is only valid after successfully initializing the audio
353 * subsystem.
354 *
355 * Note that audio capture support is not implemented as of SDL 2.0.4, so the
356 * `iscapture` parameter is for future expansion and should always be zero for
357 * now.
358 *
359 * This function will return -1 if an explicit list of devices can't be
360 * determined. Returning -1 is not an error. For example, if SDL is set up to
361 * talk to a remote audio server, it can't list every one available on the
362 * Internet, but it will still allow a specific host to be specified in
363 * SDL_OpenAudioDevice().
364 *
365 * In many common cases, when this function returns a value <= 0, it can still
366 * successfully open the default device (NULL for first argument of
367 * SDL_OpenAudioDevice()).
368 *
369 * This function may trigger a complete redetect of available hardware. It
370 * should not be called for each iteration of a loop, but rather once at the
371 * start of a loop:
372 *
373 * ```c++
374 * // Don't do this:
375 * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
339 376 * *
340 * In many common cases, when this function returns a value <= 0, it can still
341 * successfully open the default device (NULL for first argument of
342 * SDL_OpenAudioDevice()).
377 * // do this instead:
378 * const int count = SDL_GetNumAudioDevices(0);
379 * for (int i = 0; i < count; ++i) { do_something_here(); }
380 * ```
381 *
382 * \param iscapture zero to request playback devices, non-zero to request
383 * recording devices
384 * \returns the number of available devices exposed by the current driver or
385 * -1 if an explicit list of devices can't be determined. A return
386 * value of -1 does not necessarily mean an error condition.
387 *
388 * \since This function is available since SDL 2.0.0.
389 *
390 * \sa SDL_GetAudioDeviceName
391 * \sa SDL_OpenAudioDevice
343 392 */ */
344 393 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
345 394
346 395 /** /**
347 * Get the human-readable name of a specific audio device.
348 * Must be a value between 0 and (number of audio devices-1).
349 * Only valid after a successfully initializing the audio subsystem.
350 * The values returned by this function reflect the latest call to
351 * SDL_GetNumAudioDevices(); recall that function to redetect available
352 * hardware.
353 *
354 * The string returned by this function is UTF-8 encoded, read-only, and
355 * managed internally. You are not to free it. If you need to keep the
356 * string for any length of time, you should make your own copy of it, as it
357 * will be invalid next time any of several other SDL functions is called.
396 * Get the human-readable name of a specific audio device.
397 *
398 * This function is only valid after successfully initializing the audio
399 * subsystem. The values returned by this function reflect the latest call to
400 * SDL_GetNumAudioDevices(); re-call that function to redetect available
401 * hardware.
402 *
403 * The string returned by this function is UTF-8 encoded, read-only, and
404 * managed internally. You are not to free it. If you need to keep the string
405 * for any length of time, you should make your own copy of it, as it will be
406 * invalid next time any of several other SDL functions are called.
407 *
408 * \param index the index of the audio device; valid values range from 0 to
409 * SDL_GetNumAudioDevices() - 1
410 * \param iscapture non-zero to query the list of recording devices, zero to
411 * query the list of output devices.
412 * \returns the name of the audio device at the requested index, or NULL on
413 * error.
414 *
415 * \sa SDL_GetNumAudioDevices
358 416 */ */
359 417 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
360 418 int iscapture); int iscapture);
361 419
420 /**
421 * Get the preferred audio format of a specific audio device.
422 *
423 * This function is only valid after a successfully initializing the audio
424 * subsystem. The values returned by this function reflect the latest call to
425 * SDL_GetNumAudioDevices(); re-call that function to redetect available
426 * hardware.
427 *
428 * `spec` will be filled with the sample rate, sample format, and channel
429 * count. All other values in the structure are filled with 0. When the
430 * supported struct members are 0, SDL was unable to get the property from the
431 * backend.
432 *
433 * \param index the index of the audio device; valid values range from 0 to
434 * SDL_GetNumAudioDevices() - 1
435 * \param iscapture non-zero to query the list of recording devices, zero to
436 * query the list of output devices.
437 * \param spec The SDL_AudioSpec to be initialized by this function.
438 * \returns 0 on success, nonzero on error
439 *
440 * \sa SDL_GetNumAudioDevices
441 */
442 extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
443 int iscapture,
444 SDL_AudioSpec *spec);
445
362 446
363 447 /** /**
364 * Open a specific audio device. Passing in a device name of NULL requests
365 * the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
366 *
367 * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
368 * some drivers allow arbitrary and driver-specific strings, such as a
369 * hostname/IP address for a remote audio server, or a filename in the
370 * diskaudio driver.
371 *
372 * \return 0 on error, a valid device ID that is >= 2 on success.
373 *
374 * SDL_OpenAudio(), unlike this function, always acts on device ID 1.
448 * Open a specific audio device.
449 *
450 * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
451 * this function will never return a 1 so as not to conflict with the legacy
452 * function.
453 *
454 * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
455 * this function would fail if `iscapture` was not zero. Starting with SDL
456 * 2.0.5, recording is implemented and this value can be non-zero.
457 *
458 * Passing in a `device` name of NULL requests the most reasonable default
459 * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
460 * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
461 * some drivers allow arbitrary and driver-specific strings, such as a
462 * hostname/IP address for a remote audio server, or a filename in the
463 * diskaudio driver.
464 *
465 * When filling in the desired audio spec structure:
466 *
467 * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
468 * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
469 * - `desired->samples` is the desired size of the audio buffer, in _sample
470 * frames_ (with stereo output, two samples--left and right--would make a
471 * single sample frame). This number should be a power of two, and may be
472 * adjusted by the audio driver to a value more suitable for the hardware.
473 * Good values seem to range between 512 and 8096 inclusive, depending on
474 * the application and CPU speed. Smaller values reduce latency, but can
475 * lead to underflow if the application is doing heavy processing and cannot
476 * fill the audio buffer in time. Note that the number of sample frames is
477 * directly related to time by the following formula: `ms =
478 * (sampleframes*1000)/freq`
479 * - `desired->size` is the size in _bytes_ of the audio buffer, and is
480 * calculated by SDL_OpenAudioDevice(). You don't initialize this.
481 * - `desired->silence` is the value used to set the buffer to silence, and is
482 * calculated by SDL_OpenAudioDevice(). You don't initialize this.
483 * - `desired->callback` should be set to a function that will be called when
484 * the audio device is ready for more data. It is passed a pointer to the
485 * audio buffer, and the length in bytes of the audio buffer. This function
486 * usually runs in a separate thread, and so you should protect data
487 * structures that it accesses by calling SDL_LockAudioDevice() and
488 * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
489 * pointer here, and call SDL_QueueAudio() with some frequency, to queue
490 * more audio samples to be played (or for capture devices, call
491 * SDL_DequeueAudio() with some frequency, to obtain audio samples).
492 * - `desired->userdata` is passed as the first parameter to your callback
493 * function. If you passed a NULL callback, this value is ignored.
494 *
495 * `allowed_changes` can have the following flags OR'd together:
496 *
497 * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
498 * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
499 * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
500 * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
501 *
502 * These flags specify how SDL should behave when a device cannot offer a
503 * specific feature. If the application requests a feature that the hardware
504 * doesn't offer, SDL will always try to get the closest equivalent.
505 *
506 * For example, if you ask for float32 audio format, but the sound card only
507 * supports int16, SDL will set the hardware to int16. If you had set
508 * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
509 * structure. If that flag was *not* set, SDL will prepare to convert your
510 * callback's float32 audio to int16 before feeding it to the hardware and
511 * will keep the originally requested format in the `obtained` structure.
512 *
513 * If your application can only handle one specific data format, pass a zero
514 * for `allowed_changes` and let SDL transparently handle any differences.
515 *
516 * An opened audio device starts out paused, and should be enabled for playing
517 * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
518 * callback function to be called. Since the audio driver may modify the
519 * requested size of the audio buffer, you should allocate any local mixing
520 * buffers after you open the audio device.
521 *
522 * The audio callback runs in a separate thread in most cases; you can prevent
523 * race conditions between your callback and other threads without fully
524 * pausing playback with SDL_LockAudioDevice(). For more information about the
525 * callback, see SDL_AudioSpec.
526 *
527 * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
528 * driver-specific name as appropriate. NULL requests the most
529 * reasonable default device.
530 * \param iscapture non-zero to specify a device should be opened for
531 * recording, not playback
532 * \param desired an SDL_AudioSpec structure representing the desired output
533 * format; see SDL_OpenAudio() for more information
534 * \param obtained an SDL_AudioSpec structure filled in with the actual output
535 * format; see SDL_OpenAudio() for more information
536 * \param allowed_changes 0, or one or more flags OR'd together
537 * \returns a valid device ID that is > 0 on success or 0 on failure; call
538 * SDL_GetError() for more information.
539 *
540 * For compatibility with SDL 1.2, this will never return 1, since
541 * SDL reserves that ID for the legacy SDL_OpenAudio() function.
542 *
543 * \since This function is available since SDL 2.0.0.
544 *
545 * \sa SDL_CloseAudioDevice
546 * \sa SDL_GetAudioDeviceName
547 * \sa SDL_LockAudioDevice
548 * \sa SDL_OpenAudio
549 * \sa SDL_PauseAudioDevice
550 * \sa SDL_UnlockAudioDevice
375 551 */ */
376 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
377 *device,
378 int iscapture,
379 const
380 SDL_AudioSpec *
381 desired,
382 SDL_AudioSpec *
383 obtained,
384 int
385 allowed_changes);
552 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
553 const char *device,
554 int iscapture,
555 const SDL_AudioSpec *desired,
556 SDL_AudioSpec *obtained,
557 int allowed_changes);
386 558
387 559
388 560
 
... ... typedef enum
399 571 SDL_AUDIO_PAUSED SDL_AUDIO_PAUSED
400 572 } SDL_AudioStatus; } SDL_AudioStatus;
401 573 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
402
403 extern DECLSPEC SDL_AudioStatus SDLCALL
404 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
574 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
405 575 /* @} *//* Audio State */ /* @} *//* Audio State */
406 576
407 577 /** /**
 
... ... extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
420 590 /* @} *//* Pause audio functions */ /* @} *//* Pause audio functions */
421 591
422 592 /** /**
423 * \brief Load the audio data of a WAVE file into memory
424 *
425 * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
426 * to be valid pointers. The entire data portion of the file is then loaded
427 * into memory and decoded if necessary.
428 *
429 * If \c freesrc is non-zero, the data source gets automatically closed and
430 * freed before the function returns.
431 *
432 * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
433 * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
434 * µ-law (8 bits). Other formats are currently unsupported and cause an error.
435 *
436 * If this function succeeds, the pointer returned by it is equal to \c spec
437 * and the pointer to the audio data allocated by the function is written to
438 * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
439 * members \c freq, \c channels, and \c format are set to the values of the
440 * audio data in the buffer. The \c samples member is set to a sane default and
441 * all others are set to zero.
442 *
443 * It's necessary to use SDL_FreeWAV() to free the audio data returned in
444 * \c audio_buf when it is no longer used.
445 *
446 * Because of the underspecification of the Waveform format, there are many
447 * problematic files in the wild that cause issues with strict decoders. To
448 * provide compatibility with these files, this decoder is lenient in regards
449 * to the truncation of the file, the fact chunk, and the size of the RIFF
450 * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
451 * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
452 * loading process.
453 *
454 * Any file that is invalid (due to truncation, corruption, or wrong values in
455 * the headers), too big, or unsupported causes an error. Additionally, any
456 * critical I/O error from the data source will terminate the loading process
457 * with an error. The function returns NULL on error and in all cases (with the
458 * exception of \c src being NULL), an appropriate error message will be set.
459 *
460 * It is required that the data source supports seeking.
461 *
462 * Example:
463 * \code
464 * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
465 * \endcode
466 *
467 * \param src The data source with the WAVE data
468 * \param freesrc A integer value that makes the function close the data source if non-zero
469 * \param spec A pointer filled with the audio format of the audio data
470 * \param audio_buf A pointer filled with the audio data allocated by the function
471 * \param audio_len A pointer filled with the length of the audio data buffer in bytes
472 * \return NULL on error, or non-NULL on success.
593 * Load the audio data of a WAVE file into memory.
594 *
595 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
596 * be valid pointers. The entire data portion of the file is then loaded into
597 * memory and decoded if necessary.
598 *
599 * If `freesrc` is non-zero, the data source gets automatically closed and
600 * freed before the function returns.
601 *
602 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
603 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
604 * A-law and mu-law (8 bits). Other formats are currently unsupported and
605 * cause an error.
606 *
607 * If this function succeeds, the pointer returned by it is equal to `spec`
608 * and the pointer to the audio data allocated by the function is written to
609 * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
610 * members `freq`, `channels`, and `format` are set to the values of the audio
611 * data in the buffer. The `samples` member is set to a sane default and all
612 * others are set to zero.
613 *
614 * It's necessary to use SDL_FreeWAV() to free the audio data returned in
615 * `audio_buf` when it is no longer used.
616 *
617 * Because of the underspecification of the .WAV format, there are many
618 * problematic files in the wild that cause issues with strict decoders. To
619 * provide compatibility with these files, this decoder is lenient in regards
620 * to the truncation of the file, the fact chunk, and the size of the RIFF
621 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
622 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
623 * tune the behavior of the loading process.
624 *
625 * Any file that is invalid (due to truncation, corruption, or wrong values in
626 * the headers), too big, or unsupported causes an error. Additionally, any
627 * critical I/O error from the data source will terminate the loading process
628 * with an error. The function returns NULL on error and in all cases (with
629 * the exception of `src` being NULL), an appropriate error message will be
630 * set.
631 *
632 * It is required that the data source supports seeking.
633 *
634 * Example:
635 *
636 * ```c++
637 * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
638 * ```
639 *
640 * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
641 * messy way:
642 *
643 * ```c++
644 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
645 * ```
646 *
647 * \param src The data source for the WAVE data
648 * \param freesrc If non-zero, SDL will _always_ free the data source
649 * \param spec An SDL_AudioSpec that will be filled in with the wave file's
650 * format details
651 * \param audio_buf A pointer filled with the audio data, allocated by the
652 * function.
653 * \param audio_len A pointer filled with the length of the audio data buffer
654 * in bytes
655 * \returns This function, if successfully called, returns `spec`, which will
656 * be filled with the audio data format of the wave source data.
657 * `audio_buf` will be filled with a pointer to an allocated buffer
658 * containing the audio data, and `audio_len` is filled with the
659 * length of that audio buffer in bytes.
660 *
661 * This function returns NULL if the .WAV file cannot be opened, uses
662 * an unknown data format, or is corrupt; call SDL_GetError() for
663 * more information.
664 *
665 * When the application is done with the data returned in
666 * `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
667 *
668 * \sa SDL_FreeWAV
669 * \sa SDL_LoadWAV
473 670 */ */
474 671 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
475 672 int freesrc, int freesrc,
 
... ... extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
485 682 SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
486 683
487 684 /** /**
488 * This function frees data previously allocated with SDL_LoadWAV_RW()
685 * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
686 *
687 * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
688 * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
689 * this function with a NULL pointer.
690 *
691 * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
692 * SDL_LoadWAV_RW()
693 *
694 * \sa SDL_LoadWAV
695 * \sa SDL_LoadWAV_RW
489 696 */ */
490 697 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
491 698
492 699 /** /**
493 * This function takes a source format and rate and a destination format
494 * and rate, and initializes the \c cvt structure with information needed
495 * by SDL_ConvertAudio() to convert a buffer of audio data from one format
496 * to the other. An unsupported format causes an error and -1 will be returned.
497 *
498 * \return 0 if no conversion is needed, 1 if the audio filter is set up,
499 * or -1 on error.
700 * Initialize an SDL_AudioCVT structure for conversion.
701 *
702 * Before an SDL_AudioCVT structure can be used to convert audio data it must
703 * be initialized with source and destination information.
704 *
705 * This function will zero out every field of the SDL_AudioCVT, so it must be
706 * called before the application fills in the final buffer information.
707 *
708 * Once this function has returned successfully, and reported that a
709 * conversion is necessary, the application fills in the rest of the fields in
710 * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
711 * and then can call SDL_ConvertAudio() to complete the conversion.
712 *
713 * \param cvt an SDL_AudioCVT structure filled in with audio conversion
714 * information
715 * \param src_format the source format of the audio data; for more info see
716 * SDL_AudioFormat
717 * \param src_channels the number of channels in the source
718 * \param src_rate the frequency (sample-frames-per-second) of the source
719 * \param dst_format the destination format of the audio data; for more info
720 * see SDL_AudioFormat
721 * \param dst_channels the number of channels in the destination
722 * \param dst_rate the frequency (sample-frames-per-second) of the destination
723 * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
724 * or a negative error code on failure; call SDL_GetError() for more
725 * information.
726 *
727 * \sa SDL_ConvertAudio
500 728 */ */
501 729 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
502 730 SDL_AudioFormat src_format, SDL_AudioFormat src_format,
 
... ... extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
507 735 int dst_rate); int dst_rate);
508 736
509 737 /** /**
510 * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
511 * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
512 * audio data in the source format, this function will convert it in-place
513 * to the desired format.
514 *
515 * The data conversion may expand the size of the audio data, so the buffer
516 * \c cvt->buf should be allocated after the \c cvt structure is initialized by
517 * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
518 *
519 * \return 0 on success or -1 if \c cvt->buf is NULL.
738 * Convert audio data to a desired audio format.
739 *
740 * This function does the actual audio data conversion, after the application
741 * has called SDL_BuildAudioCVT() to prepare the conversion information and
742 * then filled in the buffer details.
743 *
744 * Once the application has initialized the `cvt` structure using
745 * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
746 * data in the source format, this function will convert the buffer, in-place,
747 * to the desired format.
748 *
749 * The data conversion may go through several passes; any given pass may
750 * possibly temporarily increase the size of the data. For example, SDL might
751 * expand 16-bit data to 32 bits before resampling to a lower frequency,
752 * shrinking the data size after having grown it briefly. Since the supplied
753 * buffer will be both the source and destination, converting as necessary
754 * in-place, the application must allocate a buffer that will fully contain
755 * the data during its largest conversion pass. After SDL_BuildAudioCVT()
756 * returns, the application should set the `cvt->len` field to the size, in
757 * bytes, of the source data, and allocate a buffer that is `cvt->len *
758 * cvt->len_mult` bytes long for the `buf` field.
759 *
760 * The source data should be copied into this buffer before the call to
761 * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
762 * converted audio, and `cvt->len_cvt` will be the size of the converted data,
763 * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
764 * this function returns.
765 *
766 * \param cvt an SDL_AudioCVT structure that was previously set up by
767 * SDL_BuildAudioCVT().
768 * \returns 0 if the conversion was completed successfully or a negative error
769 * code on failure; call SDL_GetError() for more information.
770 *
771 * \sa SDL_BuildAudioCVT
520 772 */ */
521 773 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
522 774
 
... ... struct _SDL_AudioStream;
532 784 typedef struct _SDL_AudioStream SDL_AudioStream; typedef struct _SDL_AudioStream SDL_AudioStream;
533 785
534 786 /** /**
535 * Create a new audio stream
536 *
537 * \param src_format The format of the source audio
538 * \param src_channels The number of channels of the source audio
539 * \param src_rate The sampling rate of the source audio
540 * \param dst_format The format of the desired audio output
541 * \param dst_channels The number of channels of the desired audio output
542 * \param dst_rate The sampling rate of the desired audio output
543 * \return 0 on success, or -1 on error.
544 *
545 * \sa SDL_AudioStreamPut
546 * \sa SDL_AudioStreamGet
547 * \sa SDL_AudioStreamAvailable
548 * \sa SDL_AudioStreamFlush
549 * \sa SDL_AudioStreamClear
550 * \sa SDL_FreeAudioStream
787 * Create a new audio stream.
788 *
789 * \param src_format The format of the source audio
790 * \param src_channels The number of channels of the source audio
791 * \param src_rate The sampling rate of the source audio
792 * \param dst_format The format of the desired audio output
793 * \param dst_channels The number of channels of the desired audio output
794 * \param dst_rate The sampling rate of the desired audio output
795 * \returns 0 on success, or -1 on error.
796 *
797 * \sa SDL_AudioStreamPut
798 * \sa SDL_AudioStreamGet
799 * \sa SDL_AudioStreamAvailable
800 * \sa SDL_AudioStreamFlush
801 * \sa SDL_AudioStreamClear
802 * \sa SDL_FreeAudioStream
551 803 */ */
552 804 extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
553 805 const Uint8 src_channels, const Uint8 src_channels,
 
... ... extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
557 809 const int dst_rate); const int dst_rate);
558 810
559 811 /** /**
560 * Add data to be converted/resampled to the stream
561 *
562 * \param stream The stream the audio data is being added to
563 * \param buf A pointer to the audio data to add
564 * \param len The number of bytes to write to the stream
565 * \return 0 on success, or -1 on error.
566 *
567 * \sa SDL_NewAudioStream
568 * \sa SDL_AudioStreamGet
569 * \sa SDL_AudioStreamAvailable
570 * \sa SDL_AudioStreamFlush
571 * \sa SDL_AudioStreamClear
572 * \sa SDL_FreeAudioStream
812 * Add data to be converted/resampled to the stream.
813 *
814 * \param stream The stream the audio data is being added to
815 * \param buf A pointer to the audio data to add
816 * \param len The number of bytes to write to the stream
817 * \returns 0 on success, or -1 on error.
818 *
819 * \sa SDL_NewAudioStream
820 * \sa SDL_AudioStreamGet
821 * \sa SDL_AudioStreamAvailable
822 * \sa SDL_AudioStreamFlush
823 * \sa SDL_AudioStreamClear
824 * \sa SDL_FreeAudioStream
573 825 */ */
574 826 extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
575 827
576 828 /** /**
577 * Get converted/resampled data from the stream
578 *
579 * \param stream The stream the audio is being requested from
580 * \param buf A buffer to fill with audio data
581 * \param len The maximum number of bytes to fill
582 * \return The number of bytes read from the stream, or -1 on error
583 *
584 * \sa SDL_NewAudioStream
585 * \sa SDL_AudioStreamPut
586 * \sa SDL_AudioStreamAvailable
587 * \sa SDL_AudioStreamFlush
588 * \sa SDL_AudioStreamClear
589 * \sa SDL_FreeAudioStream
829 * Get converted/resampled data from the stream
830 *
831 * \param stream The stream the audio is being requested from
832 * \param buf A buffer to fill with audio data
833 * \param len The maximum number of bytes to fill
834 * \returns the number of bytes read from the stream, or -1 on error
835 *
836 * \sa SDL_NewAudioStream
837 * \sa SDL_AudioStreamPut
838 * \sa SDL_AudioStreamAvailable
839 * \sa SDL_AudioStreamFlush
840 * \sa SDL_AudioStreamClear
841 * \sa SDL_FreeAudioStream
590 842 */ */
591 843 extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len); extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
592 844
593 845 /** /**
594 * Get the number of converted/resampled bytes available. The stream may be
595 * buffering data behind the scenes until it has enough to resample
596 * correctly, so this number might be lower than what you expect, or even
597 * be zero. Add more data or flush the stream if you need the data now.
598 *
599 * \sa SDL_NewAudioStream
600 * \sa SDL_AudioStreamPut
601 * \sa SDL_AudioStreamGet
602 * \sa SDL_AudioStreamFlush
603 * \sa SDL_AudioStreamClear
604 * \sa SDL_FreeAudioStream
846 * Get the number of converted/resampled bytes available.
847 *
848 * The stream may be buffering data behind the scenes until it has enough to
849 * resample correctly, so this number might be lower than what you expect, or
850 * even be zero. Add more data or flush the stream if you need the data now.
851 *
852 * \sa SDL_NewAudioStream
853 * \sa SDL_AudioStreamPut
854 * \sa SDL_AudioStreamGet
855 * \sa SDL_AudioStreamFlush
856 * \sa SDL_AudioStreamClear
857 * \sa SDL_FreeAudioStream
605 858 */ */
606 859 extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
607 860
608 861 /** /**
609 862 * Tell the stream that you're done sending data, and anything being buffered * Tell the stream that you're done sending data, and anything being buffered
610 * should be converted/resampled and made available immediately.
611 *
612 * It is legal to add more data to a stream after flushing, but there will
613 * be audio gaps in the output. Generally this is intended to signal the
614 * end of input, so the complete output becomes available.
615 *
616 * \sa SDL_NewAudioStream
617 * \sa SDL_AudioStreamPut
618 * \sa SDL_AudioStreamGet
619 * \sa SDL_AudioStreamAvailable
620 * \sa SDL_AudioStreamClear
621 * \sa SDL_FreeAudioStream
863 * should be converted/resampled and made available immediately.
864 *
865 * It is legal to add more data to a stream after flushing, but there will be
866 * audio gaps in the output. Generally this is intended to signal the end of
867 * input, so the complete output becomes available.
868 *
869 * \sa SDL_NewAudioStream
870 * \sa SDL_AudioStreamPut
871 * \sa SDL_AudioStreamGet
872 * \sa SDL_AudioStreamAvailable
873 * \sa SDL_AudioStreamClear
874 * \sa SDL_FreeAudioStream
622 875 */ */
623 876 extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
624 877
625 878 /** /**
626 * Clear any pending data in the stream without converting it
627 *
628 * \sa SDL_NewAudioStream
629 * \sa SDL_AudioStreamPut
630 * \sa SDL_AudioStreamGet
631 * \sa SDL_AudioStreamAvailable
632 * \sa SDL_AudioStreamFlush
633 * \sa SDL_FreeAudioStream
879 * Clear any pending data in the stream without converting it
880 *
881 * \sa SDL_NewAudioStream
882 * \sa SDL_AudioStreamPut
883 * \sa SDL_AudioStreamGet
884 * \sa SDL_AudioStreamAvailable
885 * \sa SDL_AudioStreamFlush
886 * \sa SDL_FreeAudioStream
634 887 */ */
635 888 extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
636 889
637 890 /** /**
638 891 * Free an audio stream * Free an audio stream
639 892 * *
640 * \sa SDL_NewAudioStream
641 * \sa SDL_AudioStreamPut
642 * \sa SDL_AudioStreamGet
643 * \sa SDL_AudioStreamAvailable
644 * \sa SDL_AudioStreamFlush
645 * \sa SDL_AudioStreamClear
893 * \sa SDL_NewAudioStream
894 * \sa SDL_AudioStreamPut
895 * \sa SDL_AudioStreamGet
896 * \sa SDL_AudioStreamAvailable
897 * \sa SDL_AudioStreamFlush
898 * \sa SDL_AudioStreamClear
646 899 */ */
647 900 extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
648 901
649 902 #define SDL_MIX_MAXVOLUME 128 #define SDL_MIX_MAXVOLUME 128
650 903 /** /**
651 * This takes two audio buffers of the playing audio format and mixes
652 * them, performing addition, volume adjustment, and overflow clipping.
653 * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
654 * for full audio volume. Note this does not change hardware volume.
655 * This is provided for convenience -- you can mix your own audio data.
904 * This function is a legacy means of mixing audio.
905 *
906 * This function is equivalent to calling
907 *
908 * ```c++
909 * SDL_MixAudioFormat(dst, src, format, len, volume);
910 * ```
911 *
912 * where `format` is the obtained format of the audio device from the legacy
913 * SDL_OpenAudio() function.
914 *
915 * \param dst the destination for the mixed audio
916 * \param src the source audio buffer to be mixed
917 * \param len the length of the audio buffer in bytes
918 * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
919 * for full audio volume
920 *
921 * \sa SDL_MixAudioFormat
656 922 */ */
657 923 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
658 924 Uint32 len, int volume); Uint32 len, int volume);
659 925
660 926 /** /**
661 * This works like SDL_MixAudio(), but you specify the audio format instead of
662 * using the format of audio device 1. Thus it can be used when no audio
663 * device is open at all.
927 * Mix audio data in a specified format.
928 *
929 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
930 * it into `dst`, performing addition, volume adjustment, and overflow
931 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
932 * `format` data.
933 *
934 * This is provided for convenience -- you can mix your own audio data.
935 *
936 * Do not use this function for mixing together more than two streams of
937 * sample data. The output from repeated application of this function may be
938 * distorted by clipping, because there is no accumulator with greater range
939 * than the input (not to mention this being an inefficient way of doing it).
940 *
941 * It is a common misconception that this function is required to write audio
942 * data to an output stream in an audio callback. While you can do that,
943 * SDL_MixAudioFormat() is really only needed when you're mixing a single
944 * audio stream with a volume adjustment.
945 *
946 * \param dst the destination for the mixed audio
947 * \param src the source audio buffer to be mixed
948 * \param format the SDL_AudioFormat structure representing the desired audio
949 * format
950 * \param len the length of the audio buffer in bytes
951 * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
952 * for full audio volume
664 953 */ */
665 954 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
666 955 const Uint8 * src, const Uint8 * src,
 
... ... extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
668 957 Uint32 len, int volume); Uint32 len, int volume);
669 958
670 959 /** /**
671 * Queue more audio on non-callback devices.
672 *
673 * (If you are looking to retrieve queued audio from a non-callback capture
674 * device, you want SDL_DequeueAudio() instead. This will return -1 to
675 * signify an error if you use it with capture devices.)
676 *
677 * SDL offers two ways to feed audio to the device: you can either supply a
678 * callback that SDL triggers with some frequency to obtain more audio
679 * (pull method), or you can supply no callback, and then SDL will expect
680 * you to supply data at regular intervals (push method) with this function.
681 *
682 * There are no limits on the amount of data you can queue, short of
683 * exhaustion of address space. Queued data will drain to the device as
684 * necessary without further intervention from you. If the device needs
685 * audio but there is not enough queued, it will play silence to make up
686 * the difference. This means you will have skips in your audio playback
687 * if you aren't routinely queueing sufficient data.
688 *
689 * This function copies the supplied data, so you are safe to free it when
690 * the function returns. This function is thread-safe, but queueing to the
691 * same device from two threads at once does not promise which buffer will
692 * be queued first.
693 *
694 * You may not queue audio on a device that is using an application-supplied
695 * callback; doing so returns an error. You have to use the audio callback
696 * or queue audio with this function, but not both.
697 *
698 * You should not call SDL_LockAudio() on the device before queueing; SDL
699 * handles locking internally for this function.
700 *
701 * \param dev The device ID to which we will queue audio.
702 * \param data The data to queue to the device for later playback.
703 * \param len The number of bytes (not samples!) to which (data) points.
704 * \return 0 on success, or -1 on error.
705 *
706 * \sa SDL_GetQueuedAudioSize
707 * \sa SDL_ClearQueuedAudio
960 * Queue more audio on non-callback devices.
961 *
962 * If you are looking to retrieve queued audio from a non-callback capture
963 * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
964 * -1 to signify an error if you use it with capture devices.
965 *
966 * SDL offers two ways to feed audio to the device: you can either supply a
967 * callback that SDL triggers with some frequency to obtain more audio (pull
968 * method), or you can supply no callback, and then SDL will expect you to
969 * supply data at regular intervals (push method) with this function.
970 *
971 * There are no limits on the amount of data you can queue, short of
972 * exhaustion of address space. Queued data will drain to the device as
973 * necessary without further intervention from you. If the device needs audio
974 * but there is not enough queued, it will play silence to make up the
975 * difference. This means you will have skips in your audio playback if you
976 * aren't routinely queueing sufficient data.
977 *
978 * This function copies the supplied data, so you are safe to free it when the
979 * function returns. This function is thread-safe, but queueing to the same
980 * device from two threads at once does not promise which buffer will be
981 * queued first.
982 *
983 * You may not queue audio on a device that is using an application-supplied
984 * callback; doing so returns an error. You have to use the audio callback or
985 * queue audio with this function, but not both.
986 *
987 * You should not call SDL_LockAudio() on the device before queueing; SDL
988 * handles locking internally for this function.
989 *
990 * Note that SDL2
991 * [https://discourse.libsdl.org/t/sdl2-support-for-planar-audio/31263/3 does
992 * not support planar audio]. You will need to resample from planar audio
993 * formats into a non-planar one (see SDL_AudioFormat) before queuing audio.
994 *
995 * \param dev the device ID to which we will queue audio
996 * \param data the data to queue to the device for later playback
997 * \param len the number of bytes (not samples!) to which `data` points
998 * \returns 0 on success or a negative error code on failure; call
999 * SDL_GetError() for more information.
1000 *
1001 * \since This function is available since SDL 2.0.4.
1002 *
1003 * \sa SDL_ClearQueuedAudio
1004 * \sa SDL_GetQueuedAudioSize
708 1005 */ */
709 1006 extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len); extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
710 1007
711 1008 /** /**
712 * Dequeue more audio on non-callback devices.
713 *
714 * (If you are looking to queue audio for output on a non-callback playback
715 * device, you want SDL_QueueAudio() instead. This will always return 0
716 * if you use it with playback devices.)
717 *
718 * SDL offers two ways to retrieve audio from a capture device: you can
719 * either supply a callback that SDL triggers with some frequency as the
720 * device records more audio data, (push method), or you can supply no
721 * callback, and then SDL will expect you to retrieve data at regular
722 * intervals (pull method) with this function.
723 *
724 * There are no limits on the amount of data you can queue, short of
725 * exhaustion of address space. Data from the device will keep queuing as
726 * necessary without further intervention from you. This means you will
727 * eventually run out of memory if you aren't routinely dequeueing data.
728 *
729 * Capture devices will not queue data when paused; if you are expecting
730 * to not need captured audio for some length of time, use
731 * SDL_PauseAudioDevice() to stop the capture device from queueing more
732 * data. This can be useful during, say, level loading times. When
733 * unpaused, capture devices will start queueing data from that point,
734 * having flushed any capturable data available while paused.
735 *
736 * This function is thread-safe, but dequeueing from the same device from
737 * two threads at once does not promise which thread will dequeued data
738 * first.
739 *
740 * You may not dequeue audio from a device that is using an
741 * application-supplied callback; doing so returns an error. You have to use
742 * the audio callback, or dequeue audio with this function, but not both.
743 *
744 * You should not call SDL_LockAudio() on the device before queueing; SDL
745 * handles locking internally for this function.
746 *
747 * \param dev The device ID from which we will dequeue audio.
748 * \param data A pointer into where audio data should be copied.
749 * \param len The number of bytes (not samples!) to which (data) points.
750 * \return number of bytes dequeued, which could be less than requested.
751 *
752 * \sa SDL_GetQueuedAudioSize
753 * \sa SDL_ClearQueuedAudio
1009 * Dequeue more audio on non-callback devices.
1010 *
1011 * If you are looking to queue audio for output on a non-callback playback
1012 * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
1013 * return 0 if you use it with playback devices.
1014 *
1015 * SDL offers two ways to retrieve audio from a capture device: you can either
1016 * supply a callback that SDL triggers with some frequency as the device
1017 * records more audio data, (push method), or you can supply no callback, and
1018 * then SDL will expect you to retrieve data at regular intervals (pull
1019 * method) with this function.
1020 *
1021 * There are no limits on the amount of data you can queue, short of
1022 * exhaustion of address space. Data from the device will keep queuing as
1023 * necessary without further intervention from you. This means you will
1024 * eventually run out of memory if you aren't routinely dequeueing data.
1025 *
1026 * Capture devices will not queue data when paused; if you are expecting to
1027 * not need captured audio for some length of time, use SDL_PauseAudioDevice()
1028 * to stop the capture device from queueing more data. This can be useful
1029 * during, say, level loading times. When unpaused, capture devices will start
1030 * queueing data from that point, having flushed any capturable data available
1031 * while paused.
1032 *
1033 * This function is thread-safe, but dequeueing from the same device from two
1034 * threads at once does not promise which thread will dequeue data first.
1035 *
1036 * You may not dequeue audio from a device that is using an
1037 * application-supplied callback; doing so returns an error. You have to use
1038 * the audio callback, or dequeue audio with this function, but not both.
1039 *
1040 * You should not call SDL_LockAudio() on the device before dequeueing; SDL
1041 * handles locking internally for this function.
1042 *
1043 * \param dev the device ID from which we will dequeue audio
1044 * \param data a pointer into where audio data should be copied
1045 * \param len the number of bytes (not samples!) to which (data) points
1046 * \returns the number of bytes dequeued, which could be less than requested;
1047 * call SDL_GetError() for more information.
1048 *
1049 * \since This function is available since SDL 2.0.5.
1050 *
1051 * \sa SDL_ClearQueuedAudio
1052 * \sa SDL_GetQueuedAudioSize
754 1053 */ */
755 1054 extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len); extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
756 1055
757 1056 /** /**
758 * Get the number of bytes of still-queued audio.
759 *
760 * For playback device:
1057 * Get the number of bytes of still-queued audio.
761 1058 * *
762 * This is the number of bytes that have been queued for playback with
763 * SDL_QueueAudio(), but have not yet been sent to the hardware. This
764 * number may shrink at any time, so this only informs of pending data.
1059 * For playback devices: this is the number of bytes that have been queued for
1060 * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
765 1061 * *
766 * Once we've sent it to the hardware, this function can not decide the
767 * exact byte boundary of what has been played. It's possible that we just
768 * gave the hardware several kilobytes right before you called this
769 * function, but it hasn't played any of it yet, or maybe half of it, etc.
1062 * Once we've sent it to the hardware, this function can not decide the exact
1063 * byte boundary of what has been played. It's possible that we just gave the
1064 * hardware several kilobytes right before you called this function, but it
1065 * hasn't played any of it yet, or maybe half of it, etc.
770 1066 * *
771 * For capture devices:
1067 * For capture devices, this is the number of bytes that have been captured by
1068 * the device and are waiting for you to dequeue. This number may grow at any
1069 * time, so this only informs of the lower-bound of available data.
772 1070 * *
773 * This is the number of bytes that have been captured by the device and
774 * are waiting for you to dequeue. This number may grow at any time, so
775 * this only informs of the lower-bound of available data.
1071 * You may not queue or dequeue audio on a device that is using an
1072 * application-supplied callback; calling this function on such a device
1073 * always returns 0. You have to use the audio callback or queue audio, but
1074 * not both.
776 1075 * *
777 * You may not queue audio on a device that is using an application-supplied
778 * callback; calling this function on such a device always returns 0.
779 * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
780 * the audio callback, but not both.
1076 * You should not call SDL_LockAudio() on the device before querying; SDL
1077 * handles locking internally for this function.
781 1078 * *
782 * You should not call SDL_LockAudio() on the device before querying; SDL
783 * handles locking internally for this function.
1079 * \param dev the device ID of which we will query queued audio size
1080 * \returns the number of bytes (not samples!) of queued audio.
784 1081 * *
785 * \param dev The device ID of which we will query queued audio size.
786 * \return Number of bytes (not samples!) of queued audio.
1082 * \since This function is available since SDL 2.0.4.
787 1083 * *
788 * \sa SDL_QueueAudio
789 * \sa SDL_ClearQueuedAudio
1084 * \sa SDL_ClearQueuedAudio
1085 * \sa SDL_QueueAudio
1086 * \sa SDL_DequeueAudio
790 1087 */ */
791 1088 extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
792 1089
793 1090 /** /**
794 * Drop any queued audio data. For playback devices, this is any queued data
795 * still waiting to be submitted to the hardware. For capture devices, this
796 * is any data that was queued by the device that hasn't yet been dequeued by
797 * the application.
1091 * Drop any queued audio data waiting to be sent to the hardware.
1092 *
1093 * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
1094 * output devices, the hardware will start playing silence if more audio isn't
1095 * queued. For capture devices, the hardware will start filling the empty
1096 * queue with new data if the capture device isn't paused.
798 1097 * *
799 * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
800 * playback devices, the hardware will start playing silence if more audio
801 * isn't queued. Unpaused capture devices will start filling the queue again
802 * as soon as they have more data available (which, depending on the state
803 * of the hardware and the thread, could be before this function call
804 * returns!).
1098 * This will not prevent playback of queued audio that's already been sent to
1099 * the hardware, as we can not undo that, so expect there to be some fraction
1100 * of a second of audio that might still be heard. This can be useful if you
1101 * want to, say, drop any pending music or any unprocessed microphone input
1102 * during a level change in your game.
805 1103 * *
806 * This will not prevent playback of queued audio that's already been sent
807 * to the hardware, as we can not undo that, so expect there to be some
808 * fraction of a second of audio that might still be heard. This can be
809 * useful if you want to, say, drop any pending music during a level change
810 * in your game.
1104 * You may not queue or dequeue audio on a device that is using an
1105 * application-supplied callback; calling this function on such a device
1106 * always returns 0. You have to use the audio callback or queue audio, but
1107 * not both.
811 1108 * *
812 * You may not queue audio on a device that is using an application-supplied
813 * callback; calling this function on such a device is always a no-op.
814 * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
815 * the audio callback, but not both.
1109 * You should not call SDL_LockAudio() on the device before clearing the
1110 * queue; SDL handles locking internally for this function.
816 1111 * *
817 * You should not call SDL_LockAudio() on the device before clearing the
818 * queue; SDL handles locking internally for this function.
1112 * This function always succeeds and thus returns void.
819 1113 * *
820 * This function always succeeds and thus returns void.
1114 * \param dev the device ID of which to clear the audio queue
821 1115 * *
822 * \param dev The device ID of which to clear the audio queue.
1116 * \since This function is available since SDL 2.0.4.
823 1117 * *
824 * \sa SDL_QueueAudio
825 * \sa SDL_GetQueuedAudioSize
1118 * \sa SDL_GetQueuedAudioSize
1119 * \sa SDL_QueueAudio
1120 * \sa SDL_DequeueAudio
826 1121 */ */
827 1122 extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev); extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
828 1123
 
... ... extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
843 1138 /* @} *//* Audio lock functions */ /* @} *//* Audio lock functions */
844 1139
845 1140 /** /**
846 * This function shuts down audio processing and closes the audio device.
1141 * This function is a legacy means of closing the audio device.
1142 *
1143 * This function is equivalent to calling
1144 *
1145 * ```c++
1146 * SDL_CloseAudioDevice(1);
1147 * ```
1148 *
1149 * and is only useful if you used the legacy SDL_OpenAudio() function.
1150 *
1151 * \sa SDL_OpenAudio
847 1152 */ */
848 1153 extern DECLSPEC void SDLCALL SDL_CloseAudio(void); extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
1154
1155 /**
1156 * Use this function to shut down audio processing and close the audio device.
1157 *
1158 * The application should close open audio devices once they are no longer
1159 * needed. Calling this function will wait until the device's audio callback
1160 * is not running, release the audio hardware and then clean up internal
1161 * state. No further audio will play from this device once this function
1162 * returns.
1163 *
1164 * This function may block briefly while pending audio data is played by the
1165 * hardware, so that applications don't drop the last buffer of data they
1166 * supplied.
1167 *
1168 * The device ID is invalid as soon as the device is closed, and is eligible
1169 * for reuse in a new SDL_OpenAudioDevice() call immediately.
1170 *
1171 * \param dev an audio device previously opened with SDL_OpenAudioDevice()
1172 *
1173 * \sa SDL_OpenAudioDevice
1174 */
849 1175 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
850 1176
851 1177 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
File include/SDL2/SDL_bits.h changed (mode: 100644) (index db150ed..553b687)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
45 45 * with 0. This operation can also be stated as "count leading zeroes" and * with 0. This operation can also be stated as "count leading zeroes" and
46 46 * "log base 2". * "log base 2".
47 47 * *
48 * \return Index of the most significant bit, or -1 if the value is 0.
48 * \return the index of the most significant bit, or -1 if the value is 0.
49 49 */ */
50 50 #if defined(__WATCOMC__) && defined(__386__) #if defined(__WATCOMC__) && defined(__386__)
51 extern _inline int _SDL_clz_watcom (Uint32);
52 #pragma aux _SDL_clz_watcom = \
51 extern _inline int _SDL_bsr_watcom (Uint32);
52 #pragma aux _SDL_bsr_watcom = \
53 53 "bsr eax, eax" \ "bsr eax, eax" \
54 "xor eax, 31" \
55 54 parm [eax] nomemory \ parm [eax] nomemory \
56 55 value [eax] \ value [eax] \
57 56 modify exact [eax] nomemory; modify exact [eax] nomemory;
 
... ... SDL_MostSignificantBitIndex32(Uint32 x)
72 71 if (x == 0) { if (x == 0) {
73 72 return -1; return -1;
74 73 } }
75 return 31 - _SDL_clz_watcom(x);
74 return _SDL_bsr_watcom(x);
75 #elif defined(_MSC_VER)
76 unsigned long index;
77 if (_BitScanReverse(&index, x)) {
78 return index;
79 }
80 return -1;
76 81 #else #else
77 82 /* Based off of Bit Twiddling Hacks by Sean Eron Anderson /* Based off of Bit Twiddling Hacks by Sean Eron Anderson
78 83 * <seander@cs.stanford.edu>, released in the public domain. * <seander@cs.stanford.edu>, released in the public domain.
File include/SDL2/SDL_blendmode.h changed (mode: 100644) (index 5e21a79..374f225)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
91 91 } SDL_BlendFactor; } SDL_BlendFactor;
92 92
93 93 /** /**
94 * \brief Create a custom blend mode, which may or may not be supported by a given renderer
95 *
96 * \param srcColorFactor source color factor
97 * \param dstColorFactor destination color factor
98 * \param colorOperation color operation
99 * \param srcAlphaFactor source alpha factor
100 * \param dstAlphaFactor destination alpha factor
101 * \param alphaOperation alpha operation
102 *
103 * The result of the blend mode operation will be:
104 * dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
105 * and
106 * dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
94 * Compose a custom blend mode for renderers.
95 *
96 * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
97 * the SDL_BlendMode returned by this function if the renderer supports it.
98 *
99 * A blend mode controls how the pixels from a drawing operation (source) get
100 * combined with the pixels from the render target (destination). First, the
101 * components of the source and destination pixels get multiplied with their
102 * blend factors. Then, the blend operation takes the two products and
103 * calculates the result that will get stored in the render target.
104 *
105 * Expressed in pseudocode, it would look like this:
106 *
107 * ```c
108 * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
109 * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
110 * ```
111 *
112 * Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
113 * dst)` can return one of the following:
114 *
115 * - `src + dst`
116 * - `src - dst`
117 * - `dst - src`
118 * - `min(src, dst)`
119 * - `max(src, dst)`
120 *
121 * The red, green, and blue components are always multiplied with the first,
122 * second, and third components of the SDL_BlendFactor, respectively. The
123 * fourth component is not used.
124 *
125 * The alpha component is always multiplied with the fourth component of the
126 * SDL_BlendFactor. The other components are not used in the alpha
127 * calculation.
128 *
129 * Support for these blend modes varies for each renderer. To check if a
130 * specific SDL_BlendMode is supported, create a renderer and pass it to
131 * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
132 * return with an error if the blend mode is not supported.
133 *
134 * This list describes the support of custom blend modes for each renderer in
135 * SDL 2.0.6. All renderers support the four blend modes listed in the
136 * SDL_BlendMode enumeration.
137 *
138 * - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
139 * - **direct3d11**: Supports all operations with all factors. However, some
140 * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
141 * `SDL_BLENDOPERATION_MAXIMUM`.
142 * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
143 * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL
144 * 2.0.6.
145 * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
146 * factors. Color and alpha factors need to be the same. OpenGL ES 1
147 * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
148 * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
149 * operations being different from each other. May support color and alpha
150 * factors being different from each other.
151 * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
152 * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
153 * operations with all factors.
154 * - **psp**: No custom blend mode support.
155 * - **software**: No custom blend mode support.
156 *
157 * Some renderers do not provide an alpha component for the default render
158 * target. The `SDL_BLENDFACTOR_DST_ALPHA` and
159 * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
160 * case.
161 *
162 * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
163 * blue components of the source pixels
164 * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
165 * blue components of the destination pixels
166 * \param colorOperation the SDL_BlendOperation used to combine the red,
167 * green, and blue components of the source and
168 * destination pixels
169 * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
170 * the source pixels
171 * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
172 * the destination pixels
173 * \param alphaOperation the SDL_BlendOperation used to combine the alpha
174 * component of the source and destination pixels
175 * \returns an SDL_BlendMode that represents the chosen factors and
176 * operations.
177 *
178 * \since This function is available in SDL 2.0.6.
179 *
180 * \sa SDL_SetRenderDrawBlendMode
181 * \sa SDL_GetRenderDrawBlendMode
182 * \sa SDL_SetTextureBlendMode
183 * \sa SDL_GetTextureBlendMode
107 184 */ */
108 185 extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor, extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
109 186 SDL_BlendFactor dstColorFactor, SDL_BlendFactor dstColorFactor,
File include/SDL2/SDL_clipboard.h changed (mode: 100644) (index dbf69fc..79e4dcc)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
39 39 /* Function prototypes */ /* Function prototypes */
40 40
41 41 /** /**
42 * \brief Put UTF-8 text into the clipboard
42 * Put UTF-8 text into the clipboard.
43 43 * *
44 * \sa SDL_GetClipboardText()
44 * \param text the text to store in the clipboard
45 * \returns 0 on success or a negative error code on failure; call
46 * SDL_GetError() for more information.
47 *
48 * \sa SDL_GetClipboardText
49 * \sa SDL_HasClipboardText
45 50 */ */
46 51 extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text); extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
47 52
48 53 /** /**
49 * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
54 * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
55 *
56 * This functions returns NULL if there was not enough memory left for a copy
57 * of the clipboard's content.
58 *
59 * \returns the clipboard text on success or NULL on failure; call
60 * SDL_GetError() for more information. Caller must call SDL_free()
61 * on the returned pointer when done with it.
50 62 * *
51 * \sa SDL_SetClipboardText()
63 * \sa SDL_HasClipboardText
64 * \sa SDL_SetClipboardText
52 65 */ */
53 66 extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void); extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
54 67
55 68 /** /**
56 * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
69 * Query whether the clipboard exists and contains a non-empty text string.
70 *
71 * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
72 *
73 * \since This function is available since SDL 2.0.0.
57 74 * *
58 * \sa SDL_GetClipboardText()
75 * \sa SDL_GetClipboardText
76 * \sa SDL_SetClipboardText
59 77 */ */
60 78 extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
61 79
File include/SDL2/SDL_config.h changed (mode: 100644) (index 18a3638..33436c4)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
28 28 /* This is a set of defines to configure the SDL features */ /* This is a set of defines to configure the SDL features */
29 29
30 30 #if !defined(_STDINT_H_) && (!defined(HAVE_STDINT_H) || !_HAVE_STDINT_H) #if !defined(_STDINT_H_) && (!defined(HAVE_STDINT_H) || !_HAVE_STDINT_H)
31 #if defined(__GNUC__) || defined(__DMC__) || defined(__WATCOMC__)
31 #if defined(__GNUC__) || defined(__DMC__) || defined(__WATCOMC__) || defined(__clang__)
32 32 #define HAVE_STDINT_H 1 #define HAVE_STDINT_H 1
33 33 #elif defined(_MSC_VER) #elif defined(_MSC_VER)
34 34 typedef signed __int8 int8_t; typedef signed __int8 int8_t;
 
... ... typedef unsigned int uintptr_t;
84 84 #define HAVE_XINPUT_H 1 #define HAVE_XINPUT_H 1
85 85 #define HAVE_MMDEVICEAPI_H 1 #define HAVE_MMDEVICEAPI_H 1
86 86 #define HAVE_AUDIOCLIENT_H 1 #define HAVE_AUDIOCLIENT_H 1
87 #define HAVE_SENSORSAPI_H
87 #define HAVE_SENSORSAPI_H 1
88 #if (defined(_M_IX86) || defined(_M_X64) || defined(_M_AMD64)) && (defined(_MSC_VER) && _MSC_VER >= 1600)
89 #define HAVE_IMMINTRIN_H 1
90 #elif defined(__has_include) && (defined(__i386__) || defined(__x86_64))
91 # if __has_include(<immintrin.h>)
92 # define HAVE_IMMINTRIN_H 1
93 # endif
94 #endif
88 95
89 96 /* This is disabled by default to avoid C runtime dependencies and manifest requirements */ /* This is disabled by default to avoid C runtime dependencies and manifest requirements */
90 97 #ifdef HAVE_LIBC #ifdef HAVE_LIBC
 
... ... typedef unsigned int uintptr_t;
119 126 #define HAVE_STRRCHR 1 #define HAVE_STRRCHR 1
120 127 #define HAVE_STRSTR 1 #define HAVE_STRSTR 1
121 128 /* #undef HAVE_STRTOK_R */ /* #undef HAVE_STRTOK_R */
122 #if defined(_MSC_VER)
123 #define HAVE_STRTOK_S 1
124 #endif
125 129 /* These functions have security warnings, so we won't use them */ /* These functions have security warnings, so we won't use them */
126 130 /* #undef HAVE__LTOA */ /* #undef HAVE__LTOA */
127 131 /* #undef HAVE__ULTOA */ /* #undef HAVE__ULTOA */
 
... ... typedef unsigned int uintptr_t;
136 140 #define HAVE__STRNICMP 1 #define HAVE__STRNICMP 1
137 141 #define HAVE__WCSICMP 1 #define HAVE__WCSICMP 1
138 142 #define HAVE__WCSNICMP 1 #define HAVE__WCSNICMP 1
143 #define HAVE__WCSDUP 1
139 144 #define HAVE_ACOS 1 #define HAVE_ACOS 1
140 145 #define HAVE_ACOSF 1 #define HAVE_ACOSF 1
141 146 #define HAVE_ASIN 1 #define HAVE_ASIN 1
 
... ... typedef unsigned int uintptr_t;
172 177 /* These functions were added with the VC++ 2013 C runtime library */ /* These functions were added with the VC++ 2013 C runtime library */
173 178 #if _MSC_VER >= 1800 #if _MSC_VER >= 1800
174 179 #define HAVE_STRTOLL 1 #define HAVE_STRTOLL 1
180 #define HAVE_STRTOULL 1
175 181 #define HAVE_VSSCANF 1 #define HAVE_VSSCANF 1
182 #define HAVE_LROUND 1
183 #define HAVE_LROUNDF 1
184 #define HAVE_ROUND 1
185 #define HAVE_ROUNDF 1
176 186 #define HAVE_SCALBN 1 #define HAVE_SCALBN 1
177 187 #define HAVE_SCALBNF 1 #define HAVE_SCALBNF 1
178 188 #define HAVE_TRUNC 1 #define HAVE_TRUNC 1
 
... ... typedef unsigned int uintptr_t;
192 202 #endif #endif
193 203
194 204 /* Check to see if we have Windows 10 build environment */ /* Check to see if we have Windows 10 build environment */
195 #if _MSC_VER >= 1911 /* Visual Studio 15.3 */
205 #if defined(_MSC_VER) && (_MSC_VER >= 1911) /* Visual Studio 15.3 */
196 206 #include <sdkddkver.h> #include <sdkddkver.h>
197 207 #if _WIN32_WINNT >= 0x0601 /* Windows 7 */ #if _WIN32_WINNT >= 0x0601 /* Windows 7 */
198 208 #define SDL_WINDOWS7_SDK #define SDL_WINDOWS7_SDK
 
... ... typedef unsigned int uintptr_t;
233 243 #define SDL_LOADSO_WINDOWS 1 #define SDL_LOADSO_WINDOWS 1
234 244
235 245 /* Enable various threading systems */ /* Enable various threading systems */
246 #define SDL_THREAD_GENERIC_COND_SUFFIX 1
236 247 #define SDL_THREAD_WINDOWS 1 #define SDL_THREAD_WINDOWS 1
237 248
238 249 /* Enable various timer systems */ /* Enable various timer systems */
File include/SDL2/SDL_cpuinfo.h changed (mode: 100644) (index df3123c..4401c37)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
34 34 /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
35 35 #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))
36 36 #ifdef __clang__ #ifdef __clang__
37 /* Many of the intrinsics SDL uses are not implemented by clang with Visual Studio */
38 #undef __MMX__
39 #undef __SSE__
40 #undef __SSE2__
41 #else
37 /* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
38 so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
39
40 #ifndef __PRFCHWINTRIN_H
41 #define __PRFCHWINTRIN_H
42
43 static __inline__ void __attribute__((__always_inline__, __nodebug__))
44 _m_prefetch(void *__P)
45 {
46 __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */);
47 }
48
49 #endif /* __PRFCHWINTRIN_H */
50 #endif /* __clang__ */
42 51 #include <intrin.h> #include <intrin.h>
43 52 #ifndef _WIN64 #ifndef _WIN64
44 53 #ifndef __MMX__ #ifndef __MMX__
 
54 63 #ifndef __SSE2__ #ifndef __SSE2__
55 64 #define __SSE2__ #define __SSE2__
56 65 #endif #endif
57 #endif /* __clang__ */
58 66 #elif defined(__MINGW64_VERSION_MAJOR) #elif defined(__MINGW64_VERSION_MAJOR)
59 67 #include <intrin.h> #include <intrin.h>
68 #if !defined(SDL_DISABLE_ARM_NEON_H) && defined(__ARM_NEON)
69 # include <arm_neon.h>
70 #endif
60 71 #else #else
61 72 /* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC_H to have it included. */ /* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC_H to have it included. */
62 73 #if defined(HAVE_ALTIVEC_H) && defined(__ALTIVEC__) && !defined(__APPLE_ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC_H) #if defined(HAVE_ALTIVEC_H) && defined(__ALTIVEC__) && !defined(__APPLE_ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC_H)
 
79 90 # endif # endif
80 91 # endif # endif
81 92 #endif #endif
93 #endif /* compiler version */
94
82 95 #if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H) #if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H)
83 96 #include <mm3dnow.h> #include <mm3dnow.h>
84 97 #endif #endif
 
98 111 #include <pmmintrin.h> #include <pmmintrin.h>
99 112 #endif #endif
100 113 #endif /* HAVE_IMMINTRIN_H */ #endif /* HAVE_IMMINTRIN_H */
101 #endif /* compiler version */
102 114
103 115 #include "begin_code.h" #include "begin_code.h"
104 116 /* Set up for C function definitions, even when using C++ */ /* Set up for C function definitions, even when using C++ */
 
... ... extern "C" {
114 126 #define SDL_CACHELINE_SIZE 128 #define SDL_CACHELINE_SIZE 128
115 127
116 128 /** /**
117 * This function returns the number of CPU cores available.
129 * Get the number of CPU cores available.
130 *
131 * \returns the total number of logical CPU cores. On CPUs that include
132 * technologies such as hyperthreading, the number of logical cores
133 * may be more than the number of physical cores.
134 *
135 * \since This function is available since SDL 2.0.0.
118 136 */ */
119 137 extern DECLSPEC int SDLCALL SDL_GetCPUCount(void); extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
120 138
121 139 /** /**
122 * This function returns the L1 cache line size of the CPU
140 * Determine the L1 cache line size of the CPU.
123 141 * *
124 * This is useful for determining multi-threaded structure padding
125 * or SIMD prefetch sizes.
142 * This is useful for determining multi-threaded structure padding or SIMD
143 * prefetch sizes.
144 *
145 * \returns the L1 cache line size of the CPU, in bytes.
146 *
147 * \since This function is available since SDL 2.0.0.
126 148 */ */
127 149 extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
128 150
129 151 /** /**
130 * This function returns true if the CPU has the RDTSC instruction.
152 * Determine whether the CPU has the RDTSC instruction.
153 *
154 * This always returns false on CPUs that aren't using Intel instruction sets.
155 *
156 * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
157 *
158 * \sa SDL_Has3DNow
159 * \sa SDL_HasAltiVec
160 * \sa SDL_HasAVX
161 * \sa SDL_HasAVX2
162 * \sa SDL_HasMMX
163 * \sa SDL_HasSSE
164 * \sa SDL_HasSSE2
165 * \sa SDL_HasSSE3
166 * \sa SDL_HasSSE41
167 * \sa SDL_HasSSE42
131 168 */ */
132 169 extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
133 170
134 171 /** /**
135 * This function returns true if the CPU has AltiVec features.
172 * Determine whether the CPU has AltiVec features.
173 *
174 * This always returns false on CPUs that aren't using PowerPC instruction
175 * sets.
176 *
177 * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
178 *
179 * \sa SDL_Has3DNow
180 * \sa SDL_HasAVX
181 * \sa SDL_HasAVX2
182 * \sa SDL_HasMMX
183 * \sa SDL_HasRDTSC
184 * \sa SDL_HasSSE
185 * \sa SDL_HasSSE2
186 * \sa SDL_HasSSE3
187 * \sa SDL_HasSSE41
188 * \sa SDL_HasSSE42
136 189 */ */
137 190 extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
138 191
139 192 /** /**
140 * This function returns true if the CPU has MMX features.
193 * Determine whether the CPU has MMX features.
194 *
195 * This always returns false on CPUs that aren't using Intel instruction sets.
196 *
197 * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
198 *
199 * \sa SDL_Has3DNow
200 * \sa SDL_HasAltiVec
201 * \sa SDL_HasAVX
202 * \sa SDL_HasAVX2
203 * \sa SDL_HasRDTSC
204 * \sa SDL_HasSSE
205 * \sa SDL_HasSSE2
206 * \sa SDL_HasSSE3
207 * \sa SDL_HasSSE41
208 * \sa SDL_HasSSE42
141 209 */ */
142 210 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
143 211
144 212 /** /**
145 * This function returns true if the CPU has 3DNow! features.
213 * Determine whether the CPU has 3DNow! features.
214 *
215 * This always returns false on CPUs that aren't using AMD instruction sets.
216 *
217 * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
218 *
219 * \sa SDL_HasAltiVec
220 * \sa SDL_HasAVX
221 * \sa SDL_HasAVX2
222 * \sa SDL_HasMMX
223 * \sa SDL_HasRDTSC
224 * \sa SDL_HasSSE
225 * \sa SDL_HasSSE2
226 * \sa SDL_HasSSE3
227 * \sa SDL_HasSSE41
228 * \sa SDL_HasSSE42
146 229 */ */
147 230 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void); extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
148 231
149 232 /** /**
150 * This function returns true if the CPU has SSE features.
233 * Determine whether the CPU has SSE features.
234 *
235 * This always returns false on CPUs that aren't using Intel instruction sets.
236 *
237 * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
238 *
239 * \sa SDL_Has3DNow
240 * \sa SDL_HasAltiVec
241 * \sa SDL_HasAVX
242 * \sa SDL_HasAVX2
243 * \sa SDL_HasMMX
244 * \sa SDL_HasRDTSC
245 * \sa SDL_HasSSE2
246 * \sa SDL_HasSSE3
247 * \sa SDL_HasSSE41
248 * \sa SDL_HasSSE42
151 249 */ */
152 250 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
153 251
154 252 /** /**
155 * This function returns true if the CPU has SSE2 features.
253 * Determine whether the CPU has SSE2 features.
254 *
255 * This always returns false on CPUs that aren't using Intel instruction sets.
256 *
257 * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
258 *
259 * \sa SDL_Has3DNow
260 * \sa SDL_HasAltiVec
261 * \sa SDL_HasAVX
262 * \sa SDL_HasAVX2
263 * \sa SDL_HasMMX
264 * \sa SDL_HasRDTSC
265 * \sa SDL_HasSSE
266 * \sa SDL_HasSSE3
267 * \sa SDL_HasSSE41
268 * \sa SDL_HasSSE42
156 269 */ */
157 270 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
158 271
159 272 /** /**
160 * This function returns true if the CPU has SSE3 features.
273 * Determine whether the CPU has SSE3 features.
274 *
275 * This always returns false on CPUs that aren't using Intel instruction sets.
276 *
277 * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
278 *
279 * \sa SDL_Has3DNow
280 * \sa SDL_HasAltiVec
281 * \sa SDL_HasAVX
282 * \sa SDL_HasAVX2
283 * \sa SDL_HasMMX
284 * \sa SDL_HasRDTSC
285 * \sa SDL_HasSSE
286 * \sa SDL_HasSSE2
287 * \sa SDL_HasSSE41
288 * \sa SDL_HasSSE42
161 289 */ */
162 290 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
163 291
164 292 /** /**
165 * This function returns true if the CPU has SSE4.1 features.
293 * Determine whether the CPU has SSE4.1 features.
294 *
295 * This always returns false on CPUs that aren't using Intel instruction sets.
296 *
297 * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
298 *
299 * \sa SDL_Has3DNow
300 * \sa SDL_HasAltiVec
301 * \sa SDL_HasAVX
302 * \sa SDL_HasAVX2
303 * \sa SDL_HasMMX
304 * \sa SDL_HasRDTSC
305 * \sa SDL_HasSSE
306 * \sa SDL_HasSSE2
307 * \sa SDL_HasSSE3
308 * \sa SDL_HasSSE42
166 309 */ */
167 310 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
168 311
169 312 /** /**
170 * This function returns true if the CPU has SSE4.2 features.
313 * Determine whether the CPU has SSE4.2 features.
314 *
315 * This always returns false on CPUs that aren't using Intel instruction sets.
316 *
317 * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
318 *
319 * \sa SDL_Has3DNow
320 * \sa SDL_HasAltiVec
321 * \sa SDL_HasAVX
322 * \sa SDL_HasAVX2
323 * \sa SDL_HasMMX
324 * \sa SDL_HasRDTSC
325 * \sa SDL_HasSSE
326 * \sa SDL_HasSSE2
327 * \sa SDL_HasSSE3
328 * \sa SDL_HasSSE41
171 329 */ */
172 330 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
173 331
174 332 /** /**
175 * This function returns true if the CPU has AVX features.
333 * Determine whether the CPU has AVX features.
334 *
335 * This always returns false on CPUs that aren't using Intel instruction sets.
336 *
337 * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
338 *
339 * \since This function is available since SDL 2.0.2.
340 *
341 * \sa SDL_Has3DNow
342 * \sa SDL_HasAltiVec
343 * \sa SDL_HasAVX2
344 * \sa SDL_HasMMX
345 * \sa SDL_HasRDTSC
346 * \sa SDL_HasSSE
347 * \sa SDL_HasSSE2
348 * \sa SDL_HasSSE3
349 * \sa SDL_HasSSE41
350 * \sa SDL_HasSSE42
176 351 */ */
177 352 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
178 353
179 354 /** /**
180 * This function returns true if the CPU has AVX2 features.
355 * Determine whether the CPU has AVX2 features.
356 *
357 * This always returns false on CPUs that aren't using Intel instruction sets.
358 *
359 * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
360 *
361 * \since This function is available since SDL 2.0.4.
362 *
363 * \sa SDL_Has3DNow
364 * \sa SDL_HasAltiVec
365 * \sa SDL_HasAVX
366 * \sa SDL_HasMMX
367 * \sa SDL_HasRDTSC
368 * \sa SDL_HasSSE
369 * \sa SDL_HasSSE2
370 * \sa SDL_HasSSE3
371 * \sa SDL_HasSSE41
372 * \sa SDL_HasSSE42
181 373 */ */
182 374 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
183 375
184 376 /** /**
185 * This function returns true if the CPU has AVX-512F (foundation) features.
377 * Determine whether the CPU has AVX-512F (foundation) features.
378 *
379 * This always returns false on CPUs that aren't using Intel instruction sets.
380 *
381 * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
382 *
383 * \sa SDL_HasAVX
186 384 */ */
187 385 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
188 386
189 387 /** /**
190 * This function returns true if the CPU has ARM SIMD (ARMv6) features.
388 * Determine whether the CPU has ARM SIMD (ARMv6) features.
389 *
390 * This is different from ARM NEON, which is a different instruction set.
391 *
392 * This always returns false on CPUs that aren't using ARM instruction sets.
393 *
394 * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
395 *
396 * \sa SDL_HasNEON
191 397 */ */
192 398 extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
193 399
194 400 /** /**
195 * This function returns true if the CPU has NEON (ARM SIMD) features.
401 * Determine whether the CPU has NEON (ARM SIMD) features.
402 *
403 * This always returns false on CPUs that aren't using ARM instruction sets.
404 *
405 * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
196 406 */ */
197 407 extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
198 408
199 409 /** /**
200 * This function returns the amount of RAM configured in the system, in MB.
410 * Get the amount of RAM configured in the system.
411 *
412 * \returns the amount of RAM configured in the system in MB.
413 *
414 * \since This function is available since SDL 2.0.1.
201 415 */ */
202 416 extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void); extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
203 417
204 418 /** /**
205 * \brief Report the alignment this system needs for SIMD allocations.
419 * Report the alignment this system needs for SIMD allocations.
206 420 * *
207 421 * This will return the minimum number of bytes to which a pointer must be * This will return the minimum number of bytes to which a pointer must be
208 * aligned to be compatible with SIMD instructions on the current machine.
209 * For example, if the machine supports SSE only, it will return 16, but if
210 * it supports AVX-512F, it'll return 64 (etc). This only reports values for
211 * instruction sets SDL knows about, so if your SDL build doesn't have
212 * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
213 * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
214 * Plan accordingly.
422 * aligned to be compatible with SIMD instructions on the current machine. For
423 * example, if the machine supports SSE only, it will return 16, but if it
424 * supports AVX-512F, it'll return 64 (etc). This only reports values for
425 * instruction sets SDL knows about, so if your SDL build doesn't have
426 * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
427 * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
428 * Plan accordingly.
429 *
430 * \returns the alignment in bytes needed for available, known SIMD
431 * instructions.
215 432 */ */
216 433 extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void); extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
217 434
218 435 /** /**
219 * \brief Allocate memory in a SIMD-friendly way.
436 * Allocate memory in a SIMD-friendly way.
220 437 * *
221 438 * This will allocate a block of memory that is suitable for use with SIMD * This will allocate a block of memory that is suitable for use with SIMD
222 * instructions. Specifically, it will be properly aligned and padded for
223 * the system's supported vector instructions.
439 * instructions. Specifically, it will be properly aligned and padded for the
440 * system's supported vector instructions.
224 441 * *
225 * The memory returned will be padded such that it is safe to read or write
226 * an incomplete vector at the end of the memory block. This can be useful
227 * so you don't have to drop back to a scalar fallback at the end of your
228 * SIMD processing loop to deal with the final elements without overflowing
229 * the allocated buffer.
442 * The memory returned will be padded such that it is safe to read or write an
443 * incomplete vector at the end of the memory block. This can be useful so you
444 * don't have to drop back to a scalar fallback at the end of your SIMD
445 * processing loop to deal with the final elements without overflowing the
446 * allocated buffer.
230 447 * *
231 * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
232 * or delete[], etc.
448 * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
449 * delete[], etc.
233 450 * *
234 * Note that SDL will only deal with SIMD instruction sets it is aware of;
235 * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
236 * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
237 * know that AVX-512 wants 64. To be clear: if you can't decide to use an
238 * instruction set with an SDL_Has*() function, don't use that instruction
239 * set with memory allocated through here.
451 * Note that SDL will only deal with SIMD instruction sets it is aware of; for
452 * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
453 * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
454 * 64. To be clear: if you can't decide to use an instruction set with an
455 * SDL_Has*() function, don't use that instruction set with memory allocated
456 * through here.
240 457 * *
241 458 * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
242 * out of memory.
459 * out of memory, but you are not allowed to dereference it (because you only
460 * own zero bytes of that buffer).
243 461 * *
244 * \param len The length, in bytes, of the block to allocated. The actual
245 * allocated block might be larger due to padding, etc.
246 * \return Pointer to newly-allocated block, NULL if out of memory.
462 * \param len The length, in bytes, of the block to allocate. The actual
463 * allocated block might be larger due to padding, etc.
464 * \returns a pointer to thenewly-allocated block, NULL if out of memory.
247 465 * *
248 466 * \sa SDL_SIMDAlignment * \sa SDL_SIMDAlignment
249 467 * \sa SDL_SIMDRealloc * \sa SDL_SIMDRealloc
 
... ... extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
252 470 extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len); extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
253 471
254 472 /** /**
255 * \brief Reallocate memory obtained from SDL_SIMDAlloc
473 * Reallocate memory obtained from SDL_SIMDAlloc
256 474 * *
257 475 * It is not valid to use this function on a pointer from anything but * It is not valid to use this function on a pointer from anything but
258 * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
259 * SDL_malloc, memalign, new[], etc.
260 *
261 * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
262 * accepts NULL, at which point this function is the same as
263 * calling SDL_realloc with a NULL pointer.
264 * \param len The length, in bytes, of the block to allocated. The actual
265 * allocated block might be larger due to padding, etc. Passing 0
266 * will return a non-NULL pointer, assuming the system isn't out of
267 * memory.
268 * \return Pointer to newly-reallocated block, NULL if out of memory.
476 * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
477 * SDL_malloc, memalign, new[], etc.
478 *
479 * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
480 * accepts NULL, at which point this function is the same as
481 * calling SDL_SIMDAlloc with a NULL pointer.
482 * \param len The length, in bytes, of the block to allocated. The actual
483 * allocated block might be larger due to padding, etc. Passing 0
484 * will return a non-NULL pointer, assuming the system isn't out of
485 * memory.
486 * \returns a pointer to the newly-reallocated block, NULL if out of memory.
269 487 * *
270 488 * \sa SDL_SIMDAlignment * \sa SDL_SIMDAlignment
271 489 * \sa SDL_SIMDAlloc * \sa SDL_SIMDAlloc
 
... ... extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
274 492 extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len); extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
275 493
276 494 /** /**
277 * \brief Deallocate memory obtained from SDL_SIMDAlloc
495 * Deallocate memory obtained from SDL_SIMDAlloc
278 496 * *
279 497 * It is not valid to use this function on a pointer from anything but * It is not valid to use this function on a pointer from anything but
280 * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
281 * SDL_malloc, memalign, new[], etc.
498 * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
499 * malloc, realloc, SDL_malloc, memalign, new[], etc.
282 500 * *
283 501 * However, SDL_SIMDFree(NULL) is a legal no-op. * However, SDL_SIMDFree(NULL) is a legal no-op.
284 502 * *
503 * The memory pointed to by `ptr` is no longer valid for access upon return,
504 * and may be returned to the system or reused by a future allocation. The
505 * pointer passed to this function is no longer safe to dereference once this
506 * function returns, and should be discarded.
507 *
508 * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
509 * deallocate. NULL is a legal no-op.
510 *
285 511 * \sa SDL_SIMDAlloc * \sa SDL_SIMDAlloc
286 512 * \sa SDL_SIMDRealloc * \sa SDL_SIMDRealloc
287 513 */ */
288 514 extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr); extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
289 515
290 /* vi: set ts=4 sw=4 expandtab: */
291 516 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
292 517 #ifdef __cplusplus #ifdef __cplusplus
293 518 } }
File include/SDL2/SDL_egl.h changed (mode: 100644) (index 531441e..223357e)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_endian.h changed (mode: 100644) (index 171c008..205b793)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
30 30
31 31 #include "SDL_stdinc.h" #include "SDL_stdinc.h"
32 32
33 #ifdef _MSC_VER
34 /* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
35 so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
36
37 #ifdef __clang__
38 #ifndef __PRFCHWINTRIN_H
39 #define __PRFCHWINTRIN_H
40
41 static __inline__ void __attribute__((__always_inline__, __nodebug__))
42 _m_prefetch(void *__P)
43 {
44 __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */);
45 }
46
47 #endif /* __PRFCHWINTRIN_H */
48 #endif /* __clang__ */
49
50 #include <intrin.h>
51 #endif
52
33 53 /** /**
34 54 * \name The two types of endianness * \name The two types of endianness
35 55 */ */
 
45 65 #elif defined(__OpenBSD__) #elif defined(__OpenBSD__)
46 66 #include <endian.h> #include <endian.h>
47 67 #define SDL_BYTEORDER BYTE_ORDER #define SDL_BYTEORDER BYTE_ORDER
68 #elif defined(__FreeBSD__) || defined(__NetBSD__)
69 #include <sys/endian.h>
70 #define SDL_BYTEORDER BYTE_ORDER
48 71 #else #else
49 72 #if defined(__hppa__) || \ #if defined(__hppa__) || \
50 73 defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \ defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \
 
... ... extern "C" {
68 91 /** /**
69 92 * \file SDL_endian.h * \file SDL_endian.h
70 93 */ */
71 #if defined(__GNUC__) && defined(__i386__) && \
72 !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
94 #if (defined(__clang__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 2))) || \
95 (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8)))
96 #define SDL_Swap16(x) __builtin_bswap16(x)
97 #elif defined(__GNUC__) && defined(__i386__) && \
98 !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
73 99 SDL_FORCE_INLINE Uint16 SDL_FORCE_INLINE Uint16
74 100 SDL_Swap16(Uint16 x) SDL_Swap16(Uint16 x)
75 101 { {
 
... ... SDL_Swap16(Uint16 x)
92 118 __asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x)); __asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x));
93 119 return (Uint16)result; return (Uint16)result;
94 120 } }
95 #elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
121 #elif defined(__GNUC__) && defined(__aarch64__)
122 SDL_FORCE_INLINE Uint16
123 SDL_Swap16(Uint16 x)
124 {
125 __asm__("rev16 %w1, %w0" : "=r"(x) : "r"(x));
126 return x;
127 }
128 #elif defined(__GNUC__) && (defined(__m68k__) && !defined(__mcoldfire__))
96 129 SDL_FORCE_INLINE Uint16 SDL_FORCE_INLINE Uint16
97 130 SDL_Swap16(Uint16 x) SDL_Swap16(Uint16 x)
98 131 { {
99 132 __asm__("rorw #8,%0": "=d"(x): "0"(x):"cc"); __asm__("rorw #8,%0": "=d"(x): "0"(x):"cc");
100 133 return x; return x;
101 134 } }
135 #elif defined(_MSC_VER)
136 #pragma intrinsic(_byteswap_ushort)
137 #define SDL_Swap16(x) _byteswap_ushort(x)
102 138 #elif defined(__WATCOMC__) && defined(__386__) #elif defined(__WATCOMC__) && defined(__386__)
103 139 extern _inline Uint16 SDL_Swap16(Uint16); extern _inline Uint16 SDL_Swap16(Uint16);
104 140 #pragma aux SDL_Swap16 = \ #pragma aux SDL_Swap16 = \
 
... ... SDL_Swap16(Uint16 x)
113 149 } }
114 150 #endif #endif
115 151
116 #if defined(__GNUC__) && defined(__i386__)
152 #if (defined(__clang__) && (__clang_major__ > 2 || (__clang_major__ == 2 && __clang_minor__ >= 6))) || \
153 (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
154 #define SDL_Swap32(x) __builtin_bswap32(x)
155 #elif defined(__GNUC__) && defined(__i386__) && \
156 !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
117 157 SDL_FORCE_INLINE Uint32 SDL_FORCE_INLINE Uint32
118 158 SDL_Swap32(Uint32 x) SDL_Swap32(Uint32 x)
119 159 { {
 
... ... SDL_Swap32(Uint32 x)
133 173 { {
134 174 Uint32 result; Uint32 result;
135 175
136 __asm__("rlwimi %0,%2,24,16,23": "=&r"(result):"0"(x >> 24), "r"(x));
137 __asm__("rlwimi %0,%2,8,8,15": "=&r"(result):"0"(result), "r"(x));
138 __asm__("rlwimi %0,%2,24,0,7": "=&r"(result):"0"(result), "r"(x));
176 __asm__("rlwimi %0,%2,24,16,23": "=&r"(result): "0" (x>>24), "r"(x));
177 __asm__("rlwimi %0,%2,8,8,15" : "=&r"(result): "0" (result), "r"(x));
178 __asm__("rlwimi %0,%2,24,0,7" : "=&r"(result): "0" (result), "r"(x));
139 179 return result; return result;
140 180 } }
141 #elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
181 #elif defined(__GNUC__) && defined(__aarch64__)
182 SDL_FORCE_INLINE Uint32
183 SDL_Swap32(Uint32 x)
184 {
185 __asm__("rev %w1, %w0": "=r"(x):"r"(x));
186 return x;
187 }
188 #elif defined(__GNUC__) && (defined(__m68k__) && !defined(__mcoldfire__))
142 189 SDL_FORCE_INLINE Uint32 SDL_FORCE_INLINE Uint32
143 190 SDL_Swap32(Uint32 x) SDL_Swap32(Uint32 x)
144 191 { {
 
... ... SDL_Swap32(Uint32 x)
147 194 } }
148 195 #elif defined(__WATCOMC__) && defined(__386__) #elif defined(__WATCOMC__) && defined(__386__)
149 196 extern _inline Uint32 SDL_Swap32(Uint32); extern _inline Uint32 SDL_Swap32(Uint32);
150 #ifndef __SW_3 /* 486+ */
151 197 #pragma aux SDL_Swap32 = \ #pragma aux SDL_Swap32 = \
152 198 "bswap eax" \ "bswap eax" \
153 199 parm [eax] \ parm [eax] \
154 200 modify [eax]; modify [eax];
155 #else /* 386-only */
156 #pragma aux SDL_Swap32 = \
157 "xchg al, ah" \
158 "ror eax, 16" \
159 "xchg al, ah" \
160 parm [eax] \
161 modify [eax];
162 #endif
201 #elif defined(_MSC_VER)
202 #pragma intrinsic(_byteswap_ulong)
203 #define SDL_Swap32(x) _byteswap_ulong(x)
163 204 #else #else
164 205 SDL_FORCE_INLINE Uint32 SDL_FORCE_INLINE Uint32
165 206 SDL_Swap32(Uint32 x) SDL_Swap32(Uint32 x)
 
... ... SDL_Swap32(Uint32 x)
169 210 } }
170 211 #endif #endif
171 212
172 #if defined(__GNUC__) && defined(__i386__)
213 #if (defined(__clang__) && (__clang_major__ > 2 || (__clang_major__ == 2 && __clang_minor__ >= 6))) || \
214 (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
215 #define SDL_Swap64(x) __builtin_bswap64(x)
216 #elif defined(__GNUC__) && defined(__i386__) && \
217 !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
173 218 SDL_FORCE_INLINE Uint64 SDL_FORCE_INLINE Uint64
174 219 SDL_Swap64(Uint64 x) SDL_Swap64(Uint64 x)
175 220 { {
176 union
177 {
178 struct
179 {
221 union {
222 struct {
180 223 Uint32 a, b; Uint32 a, b;
181 224 } s; } s;
182 225 Uint64 u; Uint64 u;
183 226 } v; } v;
184 227 v.u = x; v.u = x;
185 __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1": "=r"(v.s.a), "=r"(v.s.b):"0"(v.s.a),
186 "1"(v.s.
187 b));
228 __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1"
229 : "=r"(v.s.a), "=r"(v.s.b)
230 : "0" (v.s.a), "1"(v.s.b));
188 231 return v.u; return v.u;
189 232 } }
190 233 #elif defined(__GNUC__) && defined(__x86_64__) #elif defined(__GNUC__) && defined(__x86_64__)
 
... ... SDL_Swap64(Uint64 x)
194 237 __asm__("bswapq %0": "=r"(x):"0"(x)); __asm__("bswapq %0": "=r"(x):"0"(x));
195 238 return x; return x;
196 239 } }
240 #elif defined(__WATCOMC__) && defined(__386__)
241 extern _inline Uint64 SDL_Swap64(Uint64);
242 #pragma aux SDL_Swap64 = \
243 "bswap eax" \
244 "bswap edx" \
245 "xchg eax,edx" \
246 parm [eax edx] \
247 modify [eax edx];
248 #elif defined(_MSC_VER)
249 #pragma intrinsic(_byteswap_uint64)
250 #define SDL_Swap64(x) _byteswap_uint64(x)
197 251 #else #else
198 252 SDL_FORCE_INLINE Uint64 SDL_FORCE_INLINE Uint64
199 253 SDL_Swap64(Uint64 x) SDL_Swap64(Uint64 x)
 
... ... SDL_Swap64(Uint64 x)
215 269 SDL_FORCE_INLINE float SDL_FORCE_INLINE float
216 270 SDL_SwapFloat(float x) SDL_SwapFloat(float x)
217 271 { {
218 union
219 {
272 union {
220 273 float f; float f;
221 274 Uint32 ui32; Uint32 ui32;
222 275 } swapper; } swapper;
 
... ... SDL_SwapFloat(float x)
232 285 */ */
233 286 /* @{ */ /* @{ */
234 287 #if SDL_BYTEORDER == SDL_LIL_ENDIAN #if SDL_BYTEORDER == SDL_LIL_ENDIAN
235 #define SDL_SwapLE16(X) (X)
236 #define SDL_SwapLE32(X) (X)
237 #define SDL_SwapLE64(X) (X)
288 #define SDL_SwapLE16(X) (X)
289 #define SDL_SwapLE32(X) (X)
290 #define SDL_SwapLE64(X) (X)
238 291 #define SDL_SwapFloatLE(X) (X) #define SDL_SwapFloatLE(X) (X)
239 #define SDL_SwapBE16(X) SDL_Swap16(X)
240 #define SDL_SwapBE32(X) SDL_Swap32(X)
241 #define SDL_SwapBE64(X) SDL_Swap64(X)
292 #define SDL_SwapBE16(X) SDL_Swap16(X)
293 #define SDL_SwapBE32(X) SDL_Swap32(X)
294 #define SDL_SwapBE64(X) SDL_Swap64(X)
242 295 #define SDL_SwapFloatBE(X) SDL_SwapFloat(X) #define SDL_SwapFloatBE(X) SDL_SwapFloat(X)
243 296 #else #else
244 #define SDL_SwapLE16(X) SDL_Swap16(X)
245 #define SDL_SwapLE32(X) SDL_Swap32(X)
246 #define SDL_SwapLE64(X) SDL_Swap64(X)
297 #define SDL_SwapLE16(X) SDL_Swap16(X)
298 #define SDL_SwapLE32(X) SDL_Swap32(X)
299 #define SDL_SwapLE64(X) SDL_Swap64(X)
247 300 #define SDL_SwapFloatLE(X) SDL_SwapFloat(X) #define SDL_SwapFloatLE(X) SDL_SwapFloat(X)
248 #define SDL_SwapBE16(X) (X)
249 #define SDL_SwapBE32(X) (X)
250 #define SDL_SwapBE64(X) (X)
301 #define SDL_SwapBE16(X) (X)
302 #define SDL_SwapBE32(X) (X)
303 #define SDL_SwapBE64(X) (X)
251 304 #define SDL_SwapFloatBE(X) (X) #define SDL_SwapFloatBE(X) (X)
252 305 #endif #endif
253 306 /* @} *//* Swap to native */ /* @} *//* Swap to native */
File include/SDL2/SDL_error.h changed (mode: 100644) (index 962d62f..f61a200)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
40 40
41 41
42 42 /** /**
43 * \brief Set the error message for the current thread
43 * Set the SDL error message for the current thread.
44 44 * *
45 * \return -1, there is no error handling for this function
45 * Calling this function will replace any previous error message that was set.
46 *
47 * This function always returns -1, since SDL frequently uses -1 to signify an
48 * failing result, leading to this idiom:
49 *
50 * ```c
51 * if (error_code) {
52 * return SDL_SetError("This operation has failed: %d", error_code);
53 * }
54 * ```
55 *
56 * \param fmt a printf()-style message format string
57 * \param ... additional parameters matching % tokens in the `fmt` string, if
58 * any
59 * \returns always -1.
60 *
61 * \sa SDL_ClearError
62 * \sa SDL_GetError
46 63 */ */
47 64 extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
48 65
49 66 /** /**
50 * \brief Get the last error message that was set
67 * Retrieve a message about the last error that occurred on the current
68 * thread.
69 *
70 * It is possible for multiple errors to occur before calling SDL_GetError().
71 * Only the last error is returned.
72 *
73 * The message is only applicable when an SDL function has signaled an error.
74 * You must check the return values of SDL function calls to determine when to
75 * appropriately call SDL_GetError(). You should _not_ use the results of
76 * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
77 * an error string even when reporting success.
51 78 * *
52 * SDL API functions may set error messages and then succeed, so you should
53 * only use the error value if a function fails.
54 *
55 * This returns a pointer to a static buffer for convenience and should not
56 * be called by multiple threads simultaneously.
79 * SDL will _not_ clear the error string for successful API calls. You _must_
80 * check return values for failure cases before you can assume the error
81 * string applies.
57 82 * *
58 * \return a pointer to the last error message that was set
83 * Error strings are set per-thread, so an error set in a different thread
84 * will not interfere with the current thread's operation.
85 *
86 * The returned string is internally allocated and must not be freed by the
87 * application.
88 *
89 * \returns a message with information about the specific error that occurred,
90 * or an empty string if there hasn't been an error message set since
91 * the last call to SDL_ClearError(). The message is only applicable
92 * when an SDL function has signaled an error. You must check the
93 * return values of SDL function calls to determine when to
94 * appropriately call SDL_GetError().
95 *
96 * \sa SDL_ClearError
97 * \sa SDL_SetError
59 98 */ */
60 99 extern DECLSPEC const char *SDLCALL SDL_GetError(void); extern DECLSPEC const char *SDLCALL SDL_GetError(void);
61 100
62 101 /** /**
63 * \brief Get the last error message that was set for the current thread
102 * Get the last error message that was set for the current thread.
64 103 * *
65 * SDL API functions may set error messages and then succeed, so you should
66 * only use the error value if a function fails.
67 *
68 * \param errstr A buffer to fill with the last error message that was set
69 * for the current thread
70 * \param maxlen The size of the buffer pointed to by the errstr parameter
104 * This allows the caller to copy the error string into a provided buffer, but
105 * otherwise operates exactly the same as SDL_GetError().
71 106 * *
72 * \return errstr
107 * \param errstr A buffer to fill with the last error message that was set for
108 * the current thread
109 * \param maxlen The size of the buffer pointed to by the errstr parameter
110 * \returns the pointer passed in as the `errstr` parameter.
111 *
112 * \sa SDL_GetError
73 113 */ */
74 114 extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen); extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
75 115
76 116 /** /**
77 * \brief Clear the error message for the current thread
117 * Clear any previous error message for this thread.
118 *
119 * \sa SDL_GetError
120 * \sa SDL_SetError
78 121 */ */
79 122 extern DECLSPEC void SDLCALL SDL_ClearError(void); extern DECLSPEC void SDLCALL SDL_ClearError(void);
80 123
File include/SDL2/SDL_events.h changed (mode: 100644) (index ae560c0..c3037b2)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
50 50 #define SDL_PRESSED 1 #define SDL_PRESSED 1
51 51
52 52 /** /**
53 * \brief The types of events that can be delivered.
53 * The types of events that can be delivered.
54 54 */ */
55 55 typedef enum typedef enum
56 56 { {
 
... ... typedef union SDL_Event
620 620 SDL_DollarGestureEvent dgesture; /**< Gesture event data */ SDL_DollarGestureEvent dgesture; /**< Gesture event data */
621 621 SDL_DropEvent drop; /**< Drag and drop event data */ SDL_DropEvent drop; /**< Drag and drop event data */
622 622
623 /* This is necessary for ABI compatibility between Visual C++ and GCC
624 Visual C++ will respect the push pack pragma and use 52 bytes for
625 this structure, and GCC will use the alignment of the largest datatype
626 within the union, which is 8 bytes.
623 /* This is necessary for ABI compatibility between Visual C++ and GCC.
624 Visual C++ will respect the push pack pragma and use 52 bytes (size of
625 SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
626 architectures) for this union, and GCC will use the alignment of the
627 largest datatype within the union, which is 8 bytes on 64-bit
628 architectures.
627 629
628 630 So... we'll add padding to force the size to be 56 bytes for both. So... we'll add padding to force the size to be 56 bytes for both.
631
632 On architectures where pointers are 16 bytes, this needs rounding up to
633 the next multiple of 16, 64, and on architectures where pointers are
634 even larger the size of SDL_UserEvent will dominate as being 3 pointers.
629 635 */ */
630 Uint8 padding[56];
636 Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
631 637 } SDL_Event; } SDL_Event;
632 638
633 639 /* Make sure we haven't broken binary compatibility */ /* Make sure we haven't broken binary compatibility */
634 SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
640 SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
635 641
636 642
637 643 /* Function prototypes */ /* Function prototypes */
638 644
639 645 /** /**
640 * Pumps the event loop, gathering events from the input devices.
646 * Pump the event loop, gathering events from the input devices.
647 *
648 * This function updates the event queue and internal input device state.
649 *
650 * **WARNING**: This should only be run in the thread that initialized the
651 * video subsystem, and for extra safety, you should consider only doing those
652 * things on the main thread in any case.
641 653 * *
642 * This function updates the event queue and internal input device state.
654 * SDL_PumpEvents() gathers all the pending input information from devices and
655 * places it in the event queue. Without calls to SDL_PumpEvents() no events
656 * would ever be placed on the queue. Often the need for calls to
657 * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
658 * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
659 * polling or waiting for events (e.g. you are filtering them), then you must
660 * call SDL_PumpEvents() to force an event queue update.
643 661 * *
644 * This should only be run in the thread that sets the video mode.
662 * \sa SDL_PollEvent
663 * \sa SDL_WaitEvent
645 664 */ */
646 665 extern DECLSPEC void SDLCALL SDL_PumpEvents(void); extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
647 666
 
... ... typedef enum
654 673 } SDL_eventaction; } SDL_eventaction;
655 674
656 675 /** /**
657 * Checks the event queue for messages and optionally returns them.
676 * Check the event queue for messages and optionally return them.
658 677 * *
659 * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
660 * the back of the event queue.
678 * `action` may be any of the following:
661 679 * *
662 * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
663 * of the event queue, within the specified minimum and maximum type,
664 * will be returned and will not be removed from the queue.
680 * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
681 * event queue.
682 * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
683 * within the specified minimum and maximum type, will be returned to the
684 * caller and will _not_ be removed from the queue.
685 * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
686 * within the specified minimum and maximum type, will be returned to the
687 * caller and will be removed from the queue.
665 688 * *
666 * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
667 * of the event queue, within the specified minimum and maximum type,
668 * will be returned and will be removed from the queue.
689 * You may have to call SDL_PumpEvents() before calling this function.
690 * Otherwise, the events may not be ready to be filtered when you call
691 * SDL_PeepEvents().
669 692 * *
670 * \return The number of events actually stored, or -1 if there was an error.
693 * This function is thread-safe.
671 694 * *
672 * This function is thread-safe.
695 * \param events destination buffer for the retrieved events
696 * \param numevents if action is SDL_ADDEVENT, the number of events to add
697 * back to the event queue; if action is SDL_PEEKEVENT or
698 * SDL_GETEVENT, the maximum number of events to retrieve
699 * \param action action to take; see [[#action|Remarks]] for details
700 * \param minType minimum value of the event type to be considered;
701 * SDL_FIRSTEVENT is a safe choice
702 * \param maxType maximum value of the event type to be considered;
703 * SDL_LASTEVENT is a safe choice
704 * \returns the number of events actually stored or a negative error code on
705 * failure; call SDL_GetError() for more information.
706 *
707 * \sa SDL_PollEvent
708 * \sa SDL_PumpEvents
709 * \sa SDL_PushEvent
673 710 */ */
674 711 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
675 712 SDL_eventaction action, SDL_eventaction action,
 
... ... extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
677 714 /* @} */ /* @} */
678 715
679 716 /** /**
680 * Checks to see if certain event types are in the event queue.
717 * Check for the existence of a certain event type in the event queue.
718 *
719 * If you need to check for a range of event types, use SDL_HasEvents()
720 * instead.
721 *
722 * \param type the type of event to be queried; see SDL_EventType for details
723 * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
724 * events matching `type` are not present.
725 *
726 * \sa SDL_HasEvents
681 727 */ */
682 728 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
729
730
731 /**
732 * Check for the existence of certain event types in the event queue.
733 *
734 * If you need to check for a single event type, use SDL_HasEvent() instead.
735 *
736 * \param minType the low end of event type to be queried, inclusive; see
737 * SDL_EventType for details
738 * \param maxType the high end of event type to be queried, inclusive; see
739 * SDL_EventType for details
740 * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
741 * present, or SDL_FALSE if not.
742 *
743 * \sa SDL_HasEvents
744 */
683 745 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
684 746
685 747 /** /**
686 * This function clears events from the event queue
687 * This function only affects currently queued events. If you want to make
688 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
689 * on the main thread immediately before the flush call.
748 * Clear events of a specific type from the event queue.
749 *
750 * This will unconditionally remove any events from the queue that match
751 * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
752 * instead.
753 *
754 * It's also normal to just ignore events you don't care about in your event
755 * loop without calling this function.
756 *
757 * This function only affects currently queued events. If you want to make
758 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
759 * on the main thread immediately before the flush call.
760 *
761 * \param type the type of event to be cleared; see SDL_EventType for details
762 *
763 * \sa SDL_FlushEvents
690 764 */ */
691 765 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
766
767 /**
768 * Clear events of a range of types from the event queue.
769 *
770 * This will unconditionally remove any events from the queue that are in the
771 * range of `minType` to `maxType`, inclusive. If you need to remove a single
772 * event type, use SDL_FlushEvent() instead.
773 *
774 * It's also normal to just ignore events you don't care about in your event
775 * loop without calling this function.
776 *
777 * This function only affects currently queued events. If you want to make
778 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
779 * on the main thread immediately before the flush call.
780 *
781 * \param minType the low end of event type to be cleared, inclusive; see
782 * SDL_EventType for details
783 * \param maxType the high end of event type to be cleared, inclusive; see
784 * SDL_EventType for details
785 *
786 * \sa SDL_FlushEvent
787 */
692 788 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType); extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
693 789
694 790 /** /**
695 * \brief Polls for currently pending events.
791 * Poll for currently pending events.
792 *
793 * If `event` is not NULL, the next event is removed from the queue and stored
794 * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
795 * this event, immediately stored in the SDL Event structure -- not an event
796 * to follow.
797 *
798 * If `event` is NULL, it simply returns 1 if there is an event in the queue,
799 * but will not remove it from the queue.
696 800 * *
697 * \return 1 if there are any pending events, or 0 if there are none available.
801 * As this function implicitly calls SDL_PumpEvents(), you can only call this
802 * function in the thread that set the video mode.
698 803 * *
699 * \param event If not NULL, the next event is removed from the queue and
700 * stored in that area.
804 * SDL_PollEvent() is the favored way of receiving system events since it can
805 * be done from the main loop and does not suspend the main loop while waiting
806 * on an event to be posted.
807 *
808 * The common practice is to fully process the event queue once every frame,
809 * usually as a first step before updating the game's state:
810 *
811 * ```c
812 * while (game_is_still_running) {
813 * SDL_Event event;
814 * while (SDL_PollEvent(&event)) { // poll until all events are handled!
815 * // decide what to do with this event.
816 * }
817 *
818 * // update game state, draw the current frame
819 * }
820 * ```
821 *
822 * \param event the SDL_Event structure to be filled with the next event from
823 * the queue, or NULL
824 * \returns 1 if there is a pending event or 0 if there are none available.
825 *
826 * \sa SDL_GetEventFilter
827 * \sa SDL_PeepEvents
828 * \sa SDL_PushEvent
829 * \sa SDL_SetEventFilter
830 * \sa SDL_WaitEvent
831 * \sa SDL_WaitEventTimeout
701 832 */ */
702 833 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
703 834
704 835 /** /**
705 * \brief Waits indefinitely for the next available event.
836 * Wait indefinitely for the next available event.
706 837 * *
707 * \return 1, or 0 if there was an error while waiting for events.
838 * If `event` is not NULL, the next event is removed from the queue and stored
839 * in the SDL_Event structure pointed to by `event`.
708 840 * *
709 * \param event If not NULL, the next event is removed from the queue and
710 * stored in that area.
841 * As this function implicitly calls SDL_PumpEvents(), you can only call this
842 * function in the thread that initialized the video subsystem.
843 *
844 * \param event the SDL_Event structure to be filled in with the next event
845 * from the queue, or NULL
846 * \returns 1 on success or 0 if there was an error while waiting for events;
847 * call SDL_GetError() for more information.
848 *
849 * \sa SDL_PollEvent
850 * \sa SDL_PumpEvents
851 * \sa SDL_WaitEventTimeout
711 852 */ */
712 853 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
713 854
714 855 /** /**
715 * \brief Waits until the specified timeout (in milliseconds) for the next
716 * available event.
856 * Wait until the specified timeout (in milliseconds) for the next available
857 * event.
858 *
859 * If `event` is not NULL, the next event is removed from the queue and stored
860 * in the SDL_Event structure pointed to by `event`.
861 *
862 * As this function implicitly calls SDL_PumpEvents(), you can only call this
863 * function in the thread that initialized the video subsystem.
717 864 * *
718 * \return 1, or 0 if there was an error while waiting for events.
865 * \param event the SDL_Event structure to be filled in with the next event
866 * from the queue, or NULL
867 * \param timeout the maximum number of milliseconds to wait for the next
868 * available event
869 * \returns 1 on success or 0 if there was an error while waiting for events;
870 * call SDL_GetError() for more information. This also returns 0 if
871 * the timeout elapsed without an event arriving.
719 872 * *
720 * \param event If not NULL, the next event is removed from the queue and
721 * stored in that area.
722 * \param timeout The timeout (in milliseconds) to wait for next event.
873 * \sa SDL_PollEvent
874 * \sa SDL_PumpEvents
875 * \sa SDL_WaitEvent
723 876 */ */
724 877 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
725 878 int timeout); int timeout);
726 879
727 880 /** /**
728 * \brief Add an event to the event queue.
881 * Add an event to the event queue.
729 882 * *
730 * \return 1 on success, 0 if the event was filtered, or -1 if the event queue
731 * was full or there was some other error.
883 * The event queue can actually be used as a two way communication channel.
884 * Not only can events be read from the queue, but the user can also push
885 * their own events onto it. `event` is a pointer to the event structure you
886 * wish to push onto the queue. The event is copied into the queue, and the
887 * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
888 *
889 * Note: Pushing device input events onto the queue doesn't modify the state
890 * of the device within SDL.
891 *
892 * This function is thread-safe, and can be called from other threads safely.
893 *
894 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
895 * the event filter but events added with SDL_PeepEvents() do not.
896 *
897 * For pushing application-specific events, please use SDL_RegisterEvents() to
898 * get an event type that does not conflict with other code that also wants
899 * its own custom event types.
900 *
901 * \param event the SDL_Event to be added to the queue
902 * \returns 1 on success, 0 if the event was filtered, or a negative error
903 * code on failure; call SDL_GetError() for more information. A
904 * common reason for error is the event queue being full.
905 *
906 * \sa SDL_PeepEvents
907 * \sa SDL_PollEvent
908 * \sa SDL_RegisterEvents
732 909 */ */
733 910 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event); extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
734 911
912 /**
913 * A function pointer used for callbacks that watch the event queue.
914 *
915 * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
916 * or SDL_AddEventWatch, etc
917 * \param event the event that triggered the callback
918 * \returns 1 to permit event to be added to the queue, and 0 to disallow
919 * it. When used with SDL_AddEventWatch, the return value is ignored.
920 *
921 * \sa SDL_SetEventFilter
922 * \sa SDL_AddEventWatch
923 */
735 924 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
736 925
737 926 /** /**
738 * Sets up a filter to process all events before they change internal state and
739 * are posted to the internal event queue.
927 * Set up a filter to process all events before they change internal state and
928 * are posted to the internal event queue.
740 929 * *
741 * The filter is prototyped as:
742 * \code
743 * int SDL_EventFilter(void *userdata, SDL_Event * event);
744 * \endcode
930 * If the filter function returns 1 when called, then the event will be added
931 * to the internal queue. If it returns 0, then the event will be dropped from
932 * the queue, but the internal state will still be updated. This allows
933 * selective filtering of dynamically arriving events.
745 934 * *
746 * If the filter returns 1, then the event will be added to the internal queue.
747 * If it returns 0, then the event will be dropped from the queue, but the
748 * internal state will still be updated. This allows selective filtering of
749 * dynamically arriving events.
935 * **WARNING**: Be very careful of what you do in the event filter function,
936 * as it may run in a different thread!
750 937 * *
751 * \warning Be very careful of what you do in the event filter function, as
752 * it may run in a different thread!
938 * On platforms that support it, if the quit event is generated by an
939 * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
940 * application at the next event poll.
753 941 * *
754 * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
755 * event filter is only called when the window manager desires to close the
756 * application window. If the event filter returns 1, then the window will
757 * be closed, otherwise the window will remain open if possible.
942 * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
943 * event filter is only called when the window manager desires to close the
944 * application window. If the event filter returns 1, then the window will be
945 * closed, otherwise the window will remain open if possible.
758 946 * *
759 * If the quit event is generated by an interrupt signal, it will bypass the
760 * internal queue and be delivered to the application at the next event poll.
947 * Note: Disabled events never make it to the event filter function; see
948 * SDL_EventState().
949 *
950 * Note: If you just want to inspect events without filtering, you should use
951 * SDL_AddEventWatch() instead.
952 *
953 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
954 * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
955 * not.
956 *
957 * \param filter An SDL_EventFilter function to call when an event happens
958 * \param userdata a pointer that is passed to `filter`
959 *
960 * \sa SDL_AddEventWatch
961 * \sa SDL_EventState
962 * \sa SDL_GetEventFilter
963 * \sa SDL_PeepEvents
964 * \sa SDL_PushEvent
761 965 */ */
762 966 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
763 967 void *userdata); void *userdata);
764 968
765 969 /** /**
766 * Return the current event filter - can be used to "chain" filters.
767 * If there is no event filter set, this function returns SDL_FALSE.
970 * Query the current event filter.
971 *
972 * This function can be used to "chain" filters, by saving the existing filter
973 * before replacing it with a function that will call that saved filter.
974 *
975 * \param filter the current callback function will be stored here
976 * \param userdata the pointer that is passed to the current event filter will
977 * be stored here
978 * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
979 *
980 * \sa SDL_SetEventFilter
768 981 */ */
769 982 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
770 983 void **userdata); void **userdata);
771 984
772 985 /** /**
773 * Add a function which is called when an event is added to the queue.
986 * Add a callback to be triggered when an event is added to the event queue.
987 *
988 * `filter` will be called when an event happens, and its return value is
989 * ignored.
990 *
991 * **WARNING**: Be very careful of what you do in the event filter function,
992 * as it may run in a different thread!
993 *
994 * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
995 * the internal queue and be delivered to the watch callback immediately, and
996 * arrive at the next event poll.
997 *
998 * Note: the callback is called for events posted by the user through
999 * SDL_PushEvent(), but not for disabled events, nor for events by a filter
1000 * callback set with SDL_SetEventFilter(), nor for events posted by the user
1001 * through SDL_PeepEvents().
1002 *
1003 * \param filter an SDL_EventFilter function to call when an event happens.
1004 * \param userdata a pointer that is passed to `filter`
1005 *
1006 * \sa SDL_DelEventWatch
1007 * \sa SDL_SetEventFilter
774 1008 */ */
775 1009 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
776 1010 void *userdata); void *userdata);
777 1011
778 1012 /** /**
779 * Remove an event watch function added with SDL_AddEventWatch()
1013 * Remove an event watch callback added with SDL_AddEventWatch().
1014 *
1015 * This function takes the same input as SDL_AddEventWatch() to identify and
1016 * delete the corresponding callback.
1017 *
1018 * \param filter the function originally passed to SDL_AddEventWatch()
1019 * \param userdata the pointer originally passed to SDL_AddEventWatch()
1020 *
1021 * \sa SDL_AddEventWatch
780 1022 */ */
781 1023 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
782 1024 void *userdata); void *userdata);
783 1025
784 1026 /** /**
785 * Run the filter function on the current event queue, removing any
786 * events for which the filter returns 0.
1027 * Run a specific filter function on the current event queue, removing any
1028 * events for which the filter returns 0.
1029 *
1030 * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
1031 * this function does not change the filter permanently, it only uses the
1032 * supplied filter until this function returns.
1033 *
1034 * \param filter the SDL_EventFilter function to call when an event happens
1035 * \param userdata a pointer that is passed to `filter`
1036 *
1037 * \sa SDL_GetEventFilter
1038 * \sa SDL_SetEventFilter
787 1039 */ */
788 1040 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
789 1041 void *userdata); void *userdata);
 
... ... extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
795 1047 #define SDL_ENABLE 1 #define SDL_ENABLE 1
796 1048
797 1049 /** /**
798 * This function allows you to set the state of processing certain events.
799 * - If \c state is set to ::SDL_IGNORE, that event will be automatically
800 * dropped from the event queue and will not be filtered.
801 * - If \c state is set to ::SDL_ENABLE, that event will be processed
802 * normally.
803 * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
804 * current processing state of the specified event.
1050 * Set the state of processing events by type.
1051 *
1052 * `state` may be any of the following:
1053 *
1054 * - `SDL_QUERY`: returns the current processing state of the specified event
1055 * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
1056 * from the event queue and will not be filtered
1057 * - `SDL_ENABLE`: the event will be processed normally
1058 *
1059 * \param type the type of event; see SDL_EventType for details
1060 * \param state how to process the event
1061 * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
1062 * of the event before this function makes any changes to it.
1063 *
1064 * \sa SDL_GetEventState
805 1065 */ */
806 1066 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
807 1067 /* @} */ /* @} */
808 1068 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY) #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
809 1069
810 1070 /** /**
811 * This function allocates a set of user-defined events, and returns
812 * the beginning event number for that set of events.
1071 * Allocate a set of user-defined events, and return the beginning event
1072 * number for that set of events.
1073 *
1074 * Calling this function with `numevents` <= 0 is an error and will return
1075 * (Uint32)-1.
1076 *
1077 * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
1078 * 0xFFFFFFFF), but is clearer to write.
1079 *
1080 * \param numevents the number of events to be allocated
1081 * \returns the beginning event number, or (Uint32)-1 if there are not enough
1082 * user-defined events left.
1083 *
1084 * \since This function is available since SDL 2.0.0.
813 1085 * *
814 * If there aren't enough user-defined events left, this function
815 * returns (Uint32)-1
1086 * \sa SDL_PushEvent
816 1087 */ */
817 1088 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
818 1089
File include/SDL2/SDL_filesystem.h changed (mode: 100644) (index 68042b6..9dbd28f)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
38 38 #endif #endif
39 39
40 40 /** /**
41 * \brief Get the path where the application resides.
41 * Get the directory where the application was run from.
42 42 * *
43 * Get the "base path". This is the directory where the application was run
44 * from, which is probably the installation directory, and may or may not
45 * be the process's current working directory.
43 * This is not necessarily a fast call, so you should call this once near
44 * startup and save the string if you need it.
46 45 * *
47 * This returns an absolute path in UTF-8 encoding, and is guaranteed to
48 * end with a path separator ('\\' on Windows, '/' most other places).
46 * **Mac OS X and iOS Specific Functionality**: If the application is in a
47 * ".app" bundle, this function returns the Resource directory (e.g.
48 * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
49 * a property to the Info.plist file. Adding a string key with the name
50 * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
51 * behaviour.
49 52 * *
50 * The pointer returned by this function is owned by you. Please call
51 * SDL_free() on the pointer when you are done with it, or it will be a
52 * memory leak. This is not necessarily a fast call, though, so you should
53 * call this once near startup and save the string if you need it.
53 * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
54 * application in /Applications/SDLApp/MyApp.app):
54 55 * *
55 * Some platforms can't determine the application's path, and on other
56 * platforms, this might be meaningless. In such cases, this function will
57 * return NULL.
56 * - `resource`: bundle resource directory (the default). For example:
57 * `/Applications/SDLApp/MyApp.app/Contents/Resources`
58 * - `bundle`: the Bundle directory. Fpr example:
59 * `/Applications/SDLApp/MyApp.app/`
60 * - `parent`: the containing directory of the bundle. For example:
61 * `/Applications/SDLApp/`
58 62 * *
59 * \return String of base dir in UTF-8 encoding, or NULL on error.
63 * The returned path is guaranteed to end with a path separator ('\' on
64 * Windows, '/' on most other platforms).
65 *
66 * The pointer returned is owned by the caller. Please call SDL_free() on the
67 * pointer when done with it.
68 *
69 * \returns an absolute path in UTF-8 encoding to the application data
70 * directory. NULL will be returned on error or when the platform
71 * doesn't implement this functionality, call SDL_GetError() for more
72 * information.
73 *
74 * \since This function is available since SDL 2.0.1.
60 75 * *
61 76 * \sa SDL_GetPrefPath * \sa SDL_GetPrefPath
62 77 */ */
63 78 extern DECLSPEC char *SDLCALL SDL_GetBasePath(void); extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
64 79
65 80 /** /**
66 * \brief Get the user-and-app-specific path where files can be written.
81 * Get the user-and-app-specific path where files can be written.
67 82 * *
68 83 * Get the "pref dir". This is meant to be where users can write personal * Get the "pref dir". This is meant to be where users can write personal
69 * files (preferences and save games, etc) that are specific to your
70 * application. This directory is unique per user, per application.
84 * files (preferences and save games, etc) that are specific to your
85 * application. This directory is unique per user, per application.
71 86 * *
72 * This function will decide the appropriate location in the native filesystem,
73 * create the directory if necessary, and return a string of the absolute
74 * path to the directory in UTF-8 encoding.
87 * This function will decide the appropriate location in the native
88 * filesystem, create the directory if necessary, and return a string of the
89 * absolute path to the directory in UTF-8 encoding.
75 90 * *
76 91 * On Windows, the string might look like: * On Windows, the string might look like:
77 * "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
78 92 * *
79 * On Linux, the string might look like:
80 * "/home/bob/.local/share/My Program Name/"
93 * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
94 *
95 * On Linux, the string might look like"
96 *
97 * `/home/bob/.local/share/My Program Name/`
81 98 * *
82 99 * On Mac OS X, the string might look like: * On Mac OS X, the string might look like:
83 * "/Users/bob/Library/Application Support/My Program Name/"
84 *
85 * (etc.)
86 *
87 * You specify the name of your organization (if it's not a real organization,
88 * your name or an Internet domain you own might do) and the name of your
89 * application. These should be untranslated proper names.
90 *
91 * Both the org and app strings may become part of a directory name, so
92 * please follow these rules:
93 *
94 * - Try to use the same org string (including case-sensitivity) for
95 * all your applications that use this function.
96 * - Always use a unique app string for each one, and make sure it never
97 * changes for an app once you've decided on it.
98 * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
99 * - ...only use letters, numbers, and spaces. Avoid punctuation like
100 * "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
101 *
102 * This returns an absolute path in UTF-8 encoding, and is guaranteed to
103 * end with a path separator ('\\' on Windows, '/' most other places).
104 *
105 * The pointer returned by this function is owned by you. Please call
106 * SDL_free() on the pointer when you are done with it, or it will be a
107 * memory leak. This is not necessarily a fast call, though, so you should
108 * call this once near startup and save the string if you need it.
109 *
110 * You should assume the path returned by this function is the only safe
111 * place to write files (and that SDL_GetBasePath(), while it might be
112 * writable, or even the parent of the returned path, aren't where you
113 * should be writing things).
114 *
115 * Some platforms can't determine the pref path, and on other
116 * platforms, this might be meaningless. In such cases, this function will
117 * return NULL.
118 *
119 * \param org The name of your organization.
120 * \param app The name of your application.
121 * \return UTF-8 string of user dir in platform-dependent notation. NULL
122 * if there's a problem (creating directory failed, etc).
100 *
101 * `/Users/bob/Library/Application Support/My Program Name/`
102 *
103 * You should assume the path returned by this function is the only safe place
104 * to write files (and that SDL_GetBasePath(), while it might be writable, or
105 * even the parent of the returned path, isn't where you should be writing
106 * things).
107 *
108 * Both the org and app strings may become part of a directory name, so please
109 * follow these rules:
110 *
111 * - Try to use the same org string (_including case-sensitivity_) for all
112 * your applications that use this function.
113 * - Always use a unique app string for each one, and make sure it never
114 * changes for an app once you've decided on it.
115 * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
116 * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
117 * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
118 *
119 * The returned path is guaranteed to end with a path separator ('\' on
120 * Windows, '/' on most other platforms).
121 *
122 * The pointer returned is owned by the caller. Please call SDL_free() on the
123 * pointer when done with it.
124 *
125 * \param org the name of your organization
126 * \param app the name of your application
127 * \returns a UTF-8 string of the user directory in platform-dependent
128 * notation. NULL if there's a problem (creating directory failed,
129 * etc.).
130 *
131 * \since This function is available since SDL 2.0.1.
123 132 * *
124 133 * \sa SDL_GetBasePath * \sa SDL_GetBasePath
125 134 */ */
File include/SDL2/SDL_gamecontroller.h changed (mode: 100644) (index e42433c..cf1bd48)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
67 67 SDL_CONTROLLER_TYPE_PS4, SDL_CONTROLLER_TYPE_PS4,
68 68 SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO, SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO,
69 69 SDL_CONTROLLER_TYPE_VIRTUAL, SDL_CONTROLLER_TYPE_VIRTUAL,
70 SDL_CONTROLLER_TYPE_PS5
70 SDL_CONTROLLER_TYPE_PS5,
71 SDL_CONTROLLER_TYPE_AMAZON_LUNA,
72 SDL_CONTROLLER_TYPE_GOOGLE_STADIA
71 73 } SDL_GameControllerType; } SDL_GameControllerType;
72 74
73 75 typedef enum typedef enum
 
... ... typedef struct SDL_GameControllerButtonBind
99 101
100 102 /** /**
101 103 * To count the number of game controllers in the system for the following: * To count the number of game controllers in the system for the following:
104 *
105 * ```c
102 106 * int nJoysticks = SDL_NumJoysticks(); * int nJoysticks = SDL_NumJoysticks();
103 107 * int nGameControllers = 0; * int nGameControllers = 0;
104 108 * for (int i = 0; i < nJoysticks; i++) { * for (int i = 0; i < nJoysticks; i++) {
 
... ... typedef struct SDL_GameControllerButtonBind
106 110 * nGameControllers++; * nGameControllers++;
107 111 * } * }
108 112 * } * }
113 * ```
109 114 * *
110 115 * Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is: * Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
111 116 * guid,name,mappings * guid,name,mappings
 
... ... typedef struct SDL_GameControllerButtonBind
119 124 * Buttons can be used as a controller axis and vice versa. * Buttons can be used as a controller axis and vice versa.
120 125 * *
121 126 * This string shows an example of a valid mapping for a controller * This string shows an example of a valid mapping for a controller
122 * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
123 127 * *
128 * ```c
129 * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
130 * ```
124 131 */ */
125 132
126 133 /** /**
127 * Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
128 * A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
134 * Load a set of Game Controller mappings from a seekable SDL data stream.
135 *
136 * You can call this function several times, if needed, to load different
137 * database files.
138 *
139 * If a new mapping is loaded for an already known controller GUID, the later
140 * version will overwrite the one currently loaded.
141 *
142 * Mappings not belonging to the current platform or with no platform field
143 * specified will be ignored (i.e. mappings for Linux will be ignored in
144 * Windows, etc).
145 *
146 * This function will load the text database entirely in memory before
147 * processing it, so take this into consideration if you are in a memory
148 * constrained environment.
149 *
150 * \param rw the data stream for the mappings to be added
151 * \param freerw non-zero to close the stream after being read
152 * \returns the number of mappings added or -1 on error; call SDL_GetError()
153 * for more information.
154 *
155 * \since This function is available since SDL 2.0.2.
129 156 * *
130 * If \c freerw is non-zero, the stream will be closed after being read.
131 *
132 * \return number of mappings added, -1 on error
157 * \sa SDL_GameControllerAddMapping
158 * \sa SDL_GameControllerAddMappingsFromFile
159 * \sa SDL_GameControllerMappingForGUID
133 160 */ */
134 161 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw); extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
135 162
 
... ... extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
141 168 #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1) #define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
142 169
143 170 /** /**
144 * Add or update an existing mapping configuration
171 * Add support for controllers that SDL is unaware of or to cause an existing
172 * controller to have a different binding.
145 173 * *
146 * \return 1 if mapping is added, 0 if updated, -1 on error
174 * The mapping string has the format "GUID,name,mapping", where GUID is the
175 * string value from SDL_JoystickGetGUIDString(), name is the human readable
176 * string for the device and mappings are controller mappings to joystick
177 * ones. Under Windows there is a reserved GUID of "xinput" that covers all
178 * XInput devices. The mapping format for joystick is: {| |bX |a joystick
179 * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
180 * |} Buttons can be used as a controller axes and vice versa.
181 *
182 * This string shows an example of a valid mapping for a controller:
183 *
184 * ```c
185 * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
186 * ```
187 *
188 * \param mappingString the mapping string
189 * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
190 * -1 on error; call SDL_GetError() for more information.
191 *
192 * \sa SDL_GameControllerMapping
193 * \sa SDL_GameControllerMappingForGUID
147 194 */ */
148 195 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString); extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
149 196
150 197 /** /**
151 * Get the number of mappings installed
198 * Get the number of mappings installed.
152 199 * *
153 * \return the number of mappings
200 * \returns the number of mappings.
154 201 */ */
155 202 extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void); extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
156 203
157 204 /** /**
158 * Get the mapping at a particular index.
205 * Get the mapping at a particular index.
159 206 * *
160 * \return the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.
207 * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
208 * the index is out of range.
161 209 */ */
162 210 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index); extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
163 211
164 212 /** /**
165 * Get a mapping string for a GUID
213 * Get the game controller mapping string for a given GUID.
166 214 * *
167 * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
215 * The returned string must be freed with SDL_free().
216 *
217 * \param guid a structure containing the GUID for which a mapping is desired
218 * \returns a mapping string or NULL on error; call SDL_GetError() for more
219 * information.
220 *
221 * \sa SDL_JoystickGetDeviceGUID
222 * \sa SDL_JoystickGetGUID
168 223 */ */
169 224 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid); extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
170 225
171 226 /** /**
172 * Get a mapping string for an open GameController
227 * Get the current mapping of a Game Controller.
228 *
229 * The returned string must be freed with SDL_free().
173 230 * *
174 * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
231 * Details about mappings are discussed with SDL_GameControllerAddMapping().
232 *
233 * \param gamecontroller the game controller you want to get the current
234 * mapping for
235 * \returns a string that has the controller's mapping or NULL if no mapping
236 * is available; call SDL_GetError() for more information.
237 *
238 * \since This function is available since SDL 2.0.0.
239 *
240 * \sa SDL_GameControllerAddMapping
241 * \sa SDL_GameControllerMappingForGUID
175 242 */ */
176 243 extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller); extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
177 244
178 245 /** /**
179 * Is the joystick on this index supported by the game controller interface?
246 * Check if the given joystick is supported by the game controller interface.
247 *
248 * `joystick_index` is the same as the `device_index` passed to
249 * SDL_JoystickOpen().
250 *
251 * \param joystick_index the device_index of a device, up to
252 * SDL_NumJoysticks()
253 * \returns SDL_TRUE if the given joystick is supported by the game controller
254 * interface, SDL_FALSE if it isn't or it's an invalid index.
255 *
256 * \since This function is available since SDL 2.0.0.
257 *
258 * \sa SDL_GameControllerNameForIndex
259 * \sa SDL_GameControllerOpen
180 260 */ */
181 261 extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
182 262
183 263 /** /**
184 * Get the implementation dependent name of a game controller.
185 * This can be called before any controllers are opened.
186 * If no name can be found, this function returns NULL.
264 * Get the implementation dependent name for the game controller.
265 *
266 * This function can be called before any controllers are opened.
267 *
268 * `joystick_index` is the same as the `device_index` passed to
269 * SDL_JoystickOpen().
270 *
271 * \param joystick_index the device_index of a device, from zero to
272 * SDL_NumJoysticks()-1
273 * \returns the implementation-dependent name for the game controller, or NULL
274 * if there is no name or the index is invalid.
275 *
276 * \since This function is available since SDL 2.0.0.
277 *
278 * \sa SDL_GameControllerName
279 * \sa SDL_GameControllerOpen
280 * \sa SDL_IsGameController
187 281 */ */
188 282 extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index); extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
189 283
190 284 /** /**
191 * Get the type of a game controller.
192 * This can be called before any controllers are opened.
285 * Get the type of a game controller.
286 *
287 * This can be called before any controllers are opened.
288 *
289 * \param joystick_index the device_index of a device, from zero to
290 * SDL_NumJoysticks()-1
291 * \returns the controller type.
193 292 */ */
194 293 extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index); extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
195 294
196 295 /** /**
197 * Get the mapping of a game controller.
198 * This can be called before any controllers are opened.
296 * Get the mapping of a game controller.
297 *
298 * This can be called before any controllers are opened.
199 299 * *
200 * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
300 * \param joystick_index the device_index of a device, from zero to
301 * SDL_NumJoysticks()-1
302 * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
303 * no mapping is available.
201 304 */ */
202 305 extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index); extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
203 306
204 307 /** /**
205 * Open a game controller for use.
206 * The index passed as an argument refers to the N'th game controller on the system.
207 * This index is not the value which will identify this controller in future
208 * controller events. The joystick's instance id (::SDL_JoystickID) will be
209 * used there instead.
308 * Open a game controller for use.
309 *
310 * `joystick_index` is the same as the `device_index` passed to
311 * SDL_JoystickOpen().
312 *
313 * The index passed as an argument refers to the N'th game controller on the
314 * system. This index is not the value which will identify this controller in
315 * future controller events. The joystick's instance id (SDL_JoystickID) will
316 * be used there instead.
210 317 * *
211 * \return A controller identifier, or NULL if an error occurred.
318 * \param joystick_index the device_index of a device, up to
319 * SDL_NumJoysticks()
320 * \returns a gamecontroller identifier or NULL if an error occurred; call
321 * SDL_GetError() for more information.
322 *
323 * \since This function is available since SDL 2.0.0.
324 *
325 * \sa SDL_GameControllerClose
326 * \sa SDL_GameControllerNameForIndex
327 * \sa SDL_IsGameController
212 328 */ */
213 329 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index); extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
214 330
215 331 /** /**
216 * Return the SDL_GameController associated with an instance id.
332 * Get the SDL_GameController associated with an instance id.
333 *
334 * \param joyid the instance id to get the SDL_GameController for
335 * \returns an SDL_GameController on success or NULL on failure; call
336 * SDL_GetError() for more information.
337 *
338 * \since This function is available since SDL 2.0.4.
217 339 */ */
218 340 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid); extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
219 341
220 342 /** /**
221 * Return the SDL_GameController associated with a player index.
343 * Get the SDL_GameController associated with a player index.
344 *
345 * Please note that the player index is _not_ the device index, nor is it the
346 * instance id!
347 *
348 * \param player_index the player index, which is not the device index or the
349 * instance id!
350 * \returns the SDL_GameController associated with a player index.
351 *
352 * \sa SDL_GameControllerGetPlayerIndex
353 * \sa SDL_GameControllerSetPlayerIndex
222 354 */ */
223 355 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index); extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
224 356
225 357 /** /**
226 * Return the name for this currently opened controller
358 * Get the implementation-dependent name for an opened game controller.
359 *
360 * This is the same name as returned by SDL_GameControllerNameForIndex(), but
361 * it takes a controller identifier instead of the (unstable) device index.
362 *
363 * \param gamecontroller a game controller identifier previously returned by
364 * SDL_GameControllerOpen()
365 * \returns the implementation dependent name for the game controller, or NULL
366 * if there is no name or the identifier passed is invalid.
367 *
368 * \since This function is available since SDL 2.0.0.
369 *
370 * \sa SDL_GameControllerNameForIndex
371 * \sa SDL_GameControllerOpen
227 372 */ */
228 373 extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller); extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
229 374
230 375 /** /**
231 * Return the type of this currently opened controller
376 * Get the type of this currently opened controller
377 *
378 * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
379 * it takes a controller identifier instead of the (unstable) device index.
380 *
381 * \param gamecontroller the game controller object to query.
382 * \returns the controller type.
232 383 */ */
233 384 extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller); extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
234 385
235 386 /** /**
236 * Get the player index of an opened game controller, or -1 if it's not available
387 * Get the player index of an opened game controller.
237 388 * *
238 * For XInput controllers this returns the XInput user index.
389 * For XInput controllers this returns the XInput user index.
390 *
391 * \param gamecontroller the game controller object to query.
392 * \returns the player index for controller, or -1 if it's not available.
239 393 */ */
240 394 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller); extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
241 395
242 396 /** /**
243 * Set the player index of an opened game controller
397 * Set the player index of an opened game controller.
398 *
399 * \param gamecontroller the game controller object to adjust.
400 * \param player_index Player index to assign to this controller.
244 401 */ */
245 402 extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index); extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
246 403
247 404 /** /**
248 * Get the USB vendor ID of an opened controller, if available.
249 * If the vendor ID isn't available this function returns 0.
405 * Get the USB vendor ID of an opened controller, if available.
406 *
407 * If the vendor ID isn't available this function returns 0.
408 *
409 * \param gamecontroller the game controller object to query.
410 * \return the USB vendor ID, or zero if unavailable.
250 411 */ */
251 412 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller); extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
252 413
253 414 /** /**
254 * Get the USB product ID of an opened controller, if available.
255 * If the product ID isn't available this function returns 0.
415 * Get the USB product ID of an opened controller, if available.
416 *
417 * If the product ID isn't available this function returns 0.
418 *
419 * \param gamecontroller the game controller object to query.
420 * \return the USB product ID, or zero if unavailable.
256 421 */ */
257 422 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller); extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
258 423
259 424 /** /**
260 * Get the product version of an opened controller, if available.
261 * If the product version isn't available this function returns 0.
425 * Get the product version of an opened controller, if available.
426 *
427 * If the product version isn't available this function returns 0.
428 *
429 * \param gamecontroller the game controller object to query.
430 * \return the USB product version, or zero if unavailable.
262 431 */ */
263 432 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller); extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
264 433
265 434 /** /**
266 * Get the serial number of an opened controller, if available.
267 *
268 * Returns the serial number of the controller, or NULL if it is not available.
435 * Get the serial number of an opened controller, if available.
436 *
437 * Returns the serial number of the controller, or NULL if it is not
438 * available.
439 *
440 * \param gamecontroller the game controller object to query.
441 * \return the serial number, or NULL if unavailable.
269 442 */ */
270 443 extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller); extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
271 444
272 445 /** /**
273 * Returns SDL_TRUE if the controller has been opened and currently connected,
274 * or SDL_FALSE if it has not.
446 * Check if a controller has been opened and is currently connected.
447 *
448 * \param gamecontroller a game controller identifier previously returned by
449 * SDL_GameControllerOpen()
450 * \returns SDL_TRUE if the controller has been opened and is currently
451 * connected, or SDL_FALSE if not.
452 *
453 * \sa SDL_GameControllerClose
454 * \sa SDL_GameControllerOpen
275 455 */ */
276 456 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
277 457
278 458 /** /**
279 * Get the underlying joystick object used by a controller
459 * Get the Joystick ID from a Game Controller.
460 *
461 * This function will give you a SDL_Joystick object, which allows you to use
462 * the SDL_Joystick functions with a SDL_GameController object. This would be
463 * useful for getting a joystick's position at any given time, even if it
464 * hasn't moved (moving it would produce an event, which would have the axis'
465 * value).
466 *
467 * The pointer returned is owned by the SDL_GameController. You should not
468 * call SDL_JoystickClose() on it, for example, since doing so will likely
469 * cause SDL to crash.
470 *
471 * \param gamecontroller the game controller object that you want to get a
472 * joystick from
473 * \returns a SDL_Joystick object; call SDL_GetError() for more information.
280 474 */ */
281 475 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller); extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
282 476
283 477 /** /**
284 * Enable/disable controller event polling.
478 * Query or change current state of Game Controller events.
479 *
480 * If controller events are disabled, you must call SDL_GameControllerUpdate()
481 * yourself and check the state of the controller when you want controller
482 * information.
285 483 * *
286 * If controller events are disabled, you must call SDL_GameControllerUpdate()
287 * yourself and check the state of the controller when you want controller
288 * information.
484 * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
485 * and 1 will have any effect. Other numbers will just be returned.
289 486 * *
290 * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
487 * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
488 * \returns the same value passed to the function, with exception to -1
489 * (SDL_QUERY), which will return the current state.
490 *
491 * \since This function is available since SDL 2.0.0.
492 *
493 * \sa SDL_JoystickEventState
291 494 */ */
292 495 extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state); extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
293 496
294 497 /** /**
295 * Update the current state of the open game controllers.
498 * Manually pump game controller updates if not using the loop.
296 499 * *
297 * This is called automatically by the event loop if any game controller
298 * events are enabled.
500 * This function is called automatically by the event loop if events are
501 * enabled. Under such circumstances, it will not be necessary to call this
502 * function.
299 503 */ */
300 504 extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
301 505
 
... ... typedef enum
322 526 } SDL_GameControllerAxis; } SDL_GameControllerAxis;
323 527
324 528 /** /**
325 * turn this string into a axis mapping
529 * Convert a string into SDL_GameControllerAxis enum.
530 *
531 * This function is called internally to translate SDL_GameController mapping
532 * strings for the underlying joystick device into the consistent
533 * SDL_GameController mapping. You do not normally need to call this function
534 * unless you are parsing SDL_GameController mappings in your own code.
535 *
536 * Note specially that "righttrigger" and "lefttrigger" map to
537 * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
538 * respectively.
539 *
540 * \param str string representing a SDL_GameController axis
541 * \returns the SDL_GameControllerAxis enum corresponding to the input string,
542 * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
543 *
544 * \sa SDL_GameControllerGetStringForAxis
326 545 */ */
327 extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
546 extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
328 547
329 548 /** /**
330 * turn this axis enum into a string mapping
549 * Convert from an SDL_GameControllerAxis enum to a string.
550 *
551 * The caller should not SDL_free() the returned string.
552 *
553 * \param axis an enum value for a given SDL_GameControllerAxis
554 * \returns a string for the given axis, or NULL if an invalid axis is
555 * specified. The string returned is of the format used by
556 * SDL_GameController mapping strings.
557 *
558 * \sa SDL_GameControllerGetAxisFromString
331 559 */ */
332 560 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis); extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
333 561
334 562 /** /**
335 * Get the SDL joystick layer binding for this controller button mapping
563 * Get the SDL joystick layer binding for a controller axis mapping.
564 *
565 * \param gamecontroller a game controller
566 * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
567 * \returns a SDL_GameControllerButtonBind describing the bind. On failure
568 * (like the given Controller axis doesn't exist on the device), its
569 * `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
570 *
571 * \since This function is available since SDL 2.0.0.
572 *
573 * \sa SDL_GameControllerGetBindForButton
336 574 */ */
337 575 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
338 576 SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
339 577 SDL_GameControllerAxis axis); SDL_GameControllerAxis axis);
340 578
341 579 /** /**
342 * Return whether a game controller has a given axis
580 * Query whether a game controller has a given axis.
581 *
582 * This merely reports whether the controller's mapping defined this axis, as
583 * that is all the information SDL has about the physical device.
584 *
585 * \param gamecontroller a game controller
586 * \param axis an axis enum value (an SDL_GameControllerAxis value)
587 * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
343 588 */ */
344 589 extern DECLSPEC SDL_bool SDLCALL extern DECLSPEC SDL_bool SDLCALL
345 590 SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
346 591
347 592 /** /**
348 * Get the current state of an axis control on a game controller.
593 * Get the current state of an axis control on a game controller.
349 594 * *
350 * The state is a value ranging from -32768 to 32767 (except for the triggers,
351 * which range from 0 to 32767).
595 * The axis indices start at index 0.
352 596 * *
353 * The axis indices start at index 0.
597 * The state is a value ranging from -32768 to 32767. Triggers, however, range
598 * from 0 to 32767 (they never return a negative value).
599 *
600 * \param gamecontroller a game controller
601 * \param axis an axis index (one of the SDL_GameControllerAxis values)
602 * \returns axis state (including 0) on success or 0 (also) on failure; call
603 * SDL_GetError() for more information.
604 *
605 * \since This function is available since SDL 2.0.0.
606 *
607 * \sa SDL_GameControllerGetButton
354 608 */ */
355 609 extern DECLSPEC Sint16 SDLCALL extern DECLSPEC Sint16 SDLCALL
356 610 SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis); SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
 
... ... typedef enum
376 630 SDL_CONTROLLER_BUTTON_DPAD_DOWN, SDL_CONTROLLER_BUTTON_DPAD_DOWN,
377 631 SDL_CONTROLLER_BUTTON_DPAD_LEFT, SDL_CONTROLLER_BUTTON_DPAD_LEFT,
378 632 SDL_CONTROLLER_BUTTON_DPAD_RIGHT, SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
379 SDL_CONTROLLER_BUTTON_MISC1, /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button */
633 SDL_CONTROLLER_BUTTON_MISC1, /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button */
380 634 SDL_CONTROLLER_BUTTON_PADDLE1, /* Xbox Elite paddle P1 */ SDL_CONTROLLER_BUTTON_PADDLE1, /* Xbox Elite paddle P1 */
381 635 SDL_CONTROLLER_BUTTON_PADDLE2, /* Xbox Elite paddle P3 */ SDL_CONTROLLER_BUTTON_PADDLE2, /* Xbox Elite paddle P3 */
382 636 SDL_CONTROLLER_BUTTON_PADDLE3, /* Xbox Elite paddle P2 */ SDL_CONTROLLER_BUTTON_PADDLE3, /* Xbox Elite paddle P2 */
 
... ... typedef enum
386 640 } SDL_GameControllerButton; } SDL_GameControllerButton;
387 641
388 642 /** /**
389 * turn this string into a button mapping
643 * Convert a string into an SDL_GameControllerButton enum.
644 *
645 * This function is called internally to translate SDL_GameController mapping
646 * strings for the underlying joystick device into the consistent
647 * SDL_GameController mapping. You do not normally need to call this function
648 * unless you are parsing SDL_GameController mappings in your own code.
649 *
650 * \param str string representing a SDL_GameController axis
651 * \returns the SDL_GameControllerButton enum corresponding to the input
652 * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
390 653 */ */
391 extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
654 extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
392 655
393 656 /** /**
394 * turn this button enum into a string mapping
657 * Convert from an SDL_GameControllerButton enum to a string.
658 *
659 * The caller should not SDL_free() the returned string.
660 *
661 * \param button an enum value for a given SDL_GameControllerButton
662 * \returns a string for the given button, or NULL if an invalid axis is
663 * specified. The string returned is of the format used by
664 * SDL_GameController mapping strings.
665 *
666 * \since This function is available since SDL 2.0.0.
667 *
668 * \sa SDL_GameControllerGetButtonFromString
395 669 */ */
396 670 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button); extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
397 671
398 672 /** /**
399 * Get the SDL joystick layer binding for this controller button mapping
673 * Get the SDL joystick layer binding for a controller button mapping.
674 *
675 * \param gamecontroller a game controller
676 * \param button an button enum value (an SDL_GameControllerButton value)
677 * \returns a SDL_GameControllerButtonBind describing the bind. On failure
678 * (like the given Controller button doesn't exist on the device),
679 * its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
680 *
681 * \since This function is available since SDL 2.0.0.
682 *
683 * \sa SDL_GameControllerGetBindForAxis
400 684 */ */
401 685 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
402 686 SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
403 687 SDL_GameControllerButton button); SDL_GameControllerButton button);
404 688
405 689 /** /**
406 * Return whether a game controller has a given button
690 * Query whether a game controller has a given button.
691 *
692 * This merely reports whether the controller's mapping defined this button,
693 * as that is all the information SDL has about the physical device.
694 *
695 * \param gamecontroller a game controller
696 * \param button a button enum value (an SDL_GameControllerButton value)
697 * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
407 698 */ */
408 699 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller, extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
409 700 SDL_GameControllerButton button); SDL_GameControllerButton button);
410 701
411 702 /** /**
412 * Get the current state of a button on a game controller.
703 * Get the current state of a button on a game controller.
704 *
705 * \param gamecontroller a game controller
706 * \param button a button index (one of the SDL_GameControllerButton values)
707 * \returns 1 for pressed state or 0 for not pressed state or error; call
708 * SDL_GetError() for more information.
709 *
710 * \since This function is available since SDL 2.0.0.
413 711 * *
414 * The button indices start at index 0.
712 * \sa SDL_GameControllerGetAxis
415 713 */ */
416 714 extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller, extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
417 715 SDL_GameControllerButton button); SDL_GameControllerButton button);
418 716
419 717 /** /**
420 * Get the number of touchpads on a game controller.
718 * Get the number of touchpads on a game controller.
421 719 */ */
422 720 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller); extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
423 721
424 722 /** /**
425 * Get the number of supported simultaneous fingers on a touchpad on a game controller.
723 * Get the number of supported simultaneous fingers on a touchpad on a game
724 * controller.
426 725 */ */
427 726 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad); extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
428 727
429 728 /** /**
430 * Get the current state of a finger on a touchpad on a game controller.
729 * Get the current state of a finger on a touchpad on a game controller.
431 730 */ */
432 731 extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
433 732
434 733 /** /**
435 * Return whether a game controller has a particular sensor.
734 * Return whether a game controller has a particular sensor.
436 735 * *
437 * \param gamecontroller The controller to query
438 * \param type The type of sensor to query
439 *
440 * \return SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
736 * \param gamecontroller The controller to query
737 * \param type The type of sensor to query
738 * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
441 739 */ */
442 740 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
443 741
444 742 /** /**
445 * Set whether data reporting for a game controller sensor is enabled
446 *
447 * \param gamecontroller The controller to update
448 * \param type The type of sensor to enable/disable
449 * \param enabled Whether data reporting should be enabled
743 * Set whether data reporting for a game controller sensor is enabled.
450 744 * *
451 * \return 0 or -1 if an error occurred.
745 * \param gamecontroller The controller to update
746 * \param type The type of sensor to enable/disable
747 * \param enabled Whether data reporting should be enabled
748 * \returns 0 or -1 if an error occurred.
452 749 */ */
453 750 extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled); extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
454 751
455 752 /** /**
456 * Query whether sensor data reporting is enabled for a game controller
457 *
458 * \param gamecontroller The controller to query
459 * \param type The type of sensor to query
753 * Query whether sensor data reporting is enabled for a game controller.
460 754 * *
461 * \return SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
755 * \param gamecontroller The controller to query
756 * \param type The type of sensor to query
757 * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
462 758 */ */
463 759 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
464 760
465 761 /** /**
466 * Get the current state of a game controller sensor.
762 * Get the data rate (number of events per second) of a game controller
763 * sensor.
467 764 * *
468 * The number of values and interpretation of the data is sensor dependent.
469 * See SDL_sensor.h for the details for each type of sensor.
765 * \param gamecontroller The controller to query
766 * \param type The type of sensor to query
767 * \return the data rate, or 0.0f if the data rate is not available.
768 */
769 extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameController *gamecontroller, SDL_SensorType type);
770
771 /**
772 * Get the current state of a game controller sensor.
470 773 * *
471 * \param gamecontroller The controller to query
472 * \param type The type of sensor to query
473 * \param data A pointer filled with the current sensor state
474 * \param num_values The number of values to write to data
774 * The number of values and interpretation of the data is sensor dependent.
775 * See SDL_sensor.h for the details for each type of sensor.
475 776 * *
476 * \return 0 or -1 if an error occurred.
777 * \param gamecontroller The controller to query
778 * \param type The type of sensor to query
779 * \param data A pointer filled with the current sensor state
780 * \param num_values The number of values to write to data
781 * \return 0 or -1 if an error occurred.
477 782 */ */
478 783 extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values); extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
479 784
480 785 /** /**
481 * Start a rumble effect
482 * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
786 * Start a rumble effect on a game controller.
483 787 * *
484 * \param gamecontroller The controller to vibrate
485 * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
486 * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
487 * \param duration_ms The duration of the rumble effect, in milliseconds
788 * Each call to this function cancels any previous rumble effect, and calling
789 * it with 0 intensity stops any rumbling.
488 790 * *
489 * \return 0, or -1 if rumble isn't supported on this controller
791 * \param gamecontroller The controller to vibrate
792 * \param low_frequency_rumble The intensity of the low frequency (left)
793 * rumble motor, from 0 to 0xFFFF
794 * \param high_frequency_rumble The intensity of the high frequency (right)
795 * rumble motor, from 0 to 0xFFFF
796 * \param duration_ms The duration of the rumble effect, in milliseconds
797 * \returns 0, or -1 if rumble isn't supported on this controller
490 798 */ */
491 799 extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
492 800
493 801 /** /**
494 * Start a rumble effect in the game controller's triggers
495 * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
802 * Start a rumble effect in the game controller's triggers.
803 *
804 * Each call to this function cancels any previous trigger rumble effect, and
805 * calling it with 0 intensity stops any rumbling.
496 806 * *
497 * \param gamecontroller The controller to vibrate
498 * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
499 * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
500 * \param duration_ms The duration of the rumble effect, in milliseconds
807 * Note that this is rumbling of the _triggers_ and not the game controller as
808 * a whole. The first controller to offer this feature was the PlayStation 5's
809 * DualShock 5.
501 810 * *
502 * \return 0, or -1 if rumble isn't supported on this controller
811 * \param gamecontroller The controller to vibrate
812 * \param left_rumble The intensity of the left trigger rumble motor, from 0
813 * to 0xFFFF
814 * \param right_rumble The intensity of the right trigger rumble motor, from 0
815 * to 0xFFFF
816 * \param duration_ms The duration of the rumble effect, in milliseconds
817 * \returns 0, or -1 if trigger rumble isn't supported on this controller
503 818 */ */
504 819 extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
505 820
506 821 /** /**
507 * Return whether a controller has an LED
822 * Query whether a game controller has an LED.
508 823 * *
509 * \param gamecontroller The controller to query
510 *
511 * \return SDL_TRUE, or SDL_FALSE if this controller does not have a modifiable LED
824 * \param gamecontroller The controller to query
825 * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
826 * modifiable LED
512 827 */ */
513 828 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller); extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
514 829
515 830 /** /**
516 * Update a controller's LED color.
517 *
518 * \param gamecontroller The controller to update
519 * \param red The intensity of the red LED
520 * \param green The intensity of the green LED
521 * \param blue The intensity of the blue LED
831 * Update a game controller's LED color.
522 832 * *
523 * \return 0, or -1 if this controller does not have a modifiable LED
833 * \param gamecontroller The controller to update
834 * \param red The intensity of the red LED
835 * \param green The intensity of the green LED
836 * \param blue The intensity of the blue LED
837 * \returns 0, or -1 if this controller does not have a modifiable LED
524 838 */ */
525 839 extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue); extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
526 840
527 841 /** /**
528 * Close a controller previously opened with SDL_GameControllerOpen().
842 * Send a controller specific effect packet
843 *
844 * \param gamecontroller The controller to affect
845 * \param data The data to send to the controller
846 * \param size The size of the data to send to the controller
847 * \returns 0, or -1 if this controller or driver doesn't support effect
848 * packets
529 849 */ */
530 extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
850 extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);
531 851
852 /**
853 * Close a game controller previously opened with SDL_GameControllerOpen().
854 *
855 * \param gamecontroller a game controller identifier previously returned by
856 * SDL_GameControllerOpen()
857 *
858 * \sa SDL_GameControllerOpen
859 */
860 extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
532 861
533 862 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
534 863 #ifdef __cplusplus #ifdef __cplusplus
File include/SDL2/SDL_gesture.h changed (mode: 100644) (index 81ed431..530b3d5)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef Sint64 SDL_GestureID;
46 46 /* Function prototypes */ /* Function prototypes */
47 47
48 48 /** /**
49 * \brief Begin Recording a gesture on the specified touch, or all touches (-1)
49 * Begin recording a gesture on a specified touch device or all touch devices.
50 50 * *
51 * If the parameter `touchId` is -1 (i.e., all devices), this function will
52 * always return 1, regardless of whether there actually are any devices.
51 53 * *
54 * \param touchId the touch device id, or -1 for all touch devices
55 * \returns 1 on success or 0 if the specified device could not be found.
56 *
57 * \since This function is available since SDL 2.0.0.
58 *
59 * \sa SDL_GetTouchDevice
52 60 */ */
53 61 extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId); extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
54 62
55 63
56 64 /** /**
57 * \brief Save all currently loaded Dollar Gesture templates
65 * Save all currently loaded Dollar Gesture templates.
66 *
67 * \param dst a SDL_RWops to save to
68 * \returns the number of saved templates on success or 0 on failure; call
69 * SDL_GetError() for more information.
58 70 * *
71 * \since This function is available since SDL 2.0.0.
59 72 * *
73 * \sa SDL_LoadDollarTemplates
74 * \sa SDL_SaveDollarTemplate
60 75 */ */
61 76 extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst); extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
62 77
63 78 /** /**
64 * \brief Save a currently loaded Dollar Gesture template
79 * Save a currently loaded Dollar Gesture template.
65 80 * *
81 * \param gestureId a gesture id
82 * \param dst a SDL_RWops to save to
83 * \returns 1 on success or 0 on failure; call SDL_GetError() for more
84 * information.
66 85 * *
86 * \since This function is available since SDL 2.0.0.
87 *
88 * \sa SDL_LoadDollarTemplates
89 * \sa SDL_SaveAllDollarTemplates
67 90 */ */
68 91 extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst); extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
69 92
70 93
71 94 /** /**
72 * \brief Load Dollar Gesture templates from a file
95 * Load Dollar Gesture templates from a file.
96 *
97 * \param touchId a touch id
98 * \param src a SDL_RWops to load from
99 * \returns the number of loaded templates on success or a negative error code
100 * (or 0) on failure; call SDL_GetError() for more information.
73 101 * *
102 * \since This function is available since SDL 2.0.0.
74 103 * *
104 * \sa SDL_SaveAllDollarTemplates
105 * \sa SDL_SaveDollarTemplate
75 106 */ */
76 107 extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src); extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
77 108
78
79 109 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
80 110 #ifdef __cplusplus #ifdef __cplusplus
81 111 } }
File include/SDL2/SDL_haptic.h changed (mode: 100644) (index c27da11..bb53ed3)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef union SDL_HapticEffect
821 821
822 822 /* Function prototypes */ /* Function prototypes */
823 823 /** /**
824 * \brief Count the number of haptic devices attached to the system.
824 * Count the number of haptic devices attached to the system.
825 825 * *
826 * \return Number of haptic devices detected on the system.
826 * \returns the number of haptic devices detected on the system or a negative
827 * error code on failure; call SDL_GetError() for more information.
828 *
829 * \since This function is available since SDL 2.0.0.
830 *
831 * \sa SDL_HapticName
827 832 */ */
828 833 extern DECLSPEC int SDLCALL SDL_NumHaptics(void); extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
829 834
830 835 /** /**
831 * \brief Get the implementation dependent name of a haptic device.
836 * Get the implementation dependent name of a haptic device.
837 *
838 * This can be called before any joysticks are opened. If no name can be
839 * found, this function returns NULL.
832 840 * *
833 * This can be called before any joysticks are opened.
834 * If no name can be found, this function returns NULL.
841 * \param device_index index of the device to query.
842 * \returns the name of the device or NULL on failure; call SDL_GetError() for
843 * more information.
835 844 * *
836 * \param device_index Index of the device to get its name.
837 * \return Name of the device or NULL on error.
845 * \since This function is available since SDL 2.0.0.
838 846 * *
839 * \sa SDL_NumHaptics
847 * \sa SDL_NumHaptics
840 848 */ */
841 849 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
842 850
843 851 /** /**
844 * \brief Opens a haptic device for use.
852 * Open a haptic device for use.
845 853 * *
846 * The index passed as an argument refers to the N'th haptic device on this
847 * system.
854 * The index passed as an argument refers to the N'th haptic device on this
855 * system.
848 856 * *
849 * When opening a haptic device, its gain will be set to maximum and
850 * autocenter will be disabled. To modify these values use
851 * SDL_HapticSetGain() and SDL_HapticSetAutocenter().
857 * When opening a haptic device, its gain will be set to maximum and
858 * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
859 * and SDL_HapticSetAutocenter().
852 860 * *
853 * \param device_index Index of the device to open.
854 * \return Device identifier or NULL on error.
861 * \param device_index index of the device to open
862 * \returns the device identifier or NULL on failure; call SDL_GetError() for
863 * more information.
855 864 * *
856 * \sa SDL_HapticIndex
857 * \sa SDL_HapticOpenFromMouse
858 * \sa SDL_HapticOpenFromJoystick
859 * \sa SDL_HapticClose
860 * \sa SDL_HapticSetGain
861 * \sa SDL_HapticSetAutocenter
862 * \sa SDL_HapticPause
863 * \sa SDL_HapticStopAll
865 * \since This function is available since SDL 2.0.0.
866 *
867 * \sa SDL_HapticClose
868 * \sa SDL_HapticIndex
869 * \sa SDL_HapticOpenFromJoystick
870 * \sa SDL_HapticOpenFromMouse
871 * \sa SDL_HapticPause
872 * \sa SDL_HapticSetAutocenter
873 * \sa SDL_HapticSetGain
874 * \sa SDL_HapticStopAll
864 875 */ */
865 876 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index); extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
866 877
867 878 /** /**
868 * \brief Checks if the haptic device at index has been opened.
879 * Check if the haptic device at the designated index has been opened.
869 880 * *
870 * \param device_index Index to check to see if it has been opened.
871 * \return 1 if it has been opened or 0 if it hasn't.
881 * \param device_index the index of the device to query
882 * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
883 * SDL_GetError() for more information.
872 884 * *
873 * \sa SDL_HapticOpen
874 * \sa SDL_HapticIndex
885 * \since This function is available since SDL 2.0.0.
886 *
887 * \sa SDL_HapticIndex
888 * \sa SDL_HapticOpen
875 889 */ */
876 890 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index); extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
877 891
878 892 /** /**
879 * \brief Gets the index of a haptic device.
893 * Get the index of a haptic device.
880 894 * *
881 * \param haptic Haptic device to get the index of.
882 * \return The index of the haptic device or -1 on error.
895 * \param haptic the SDL_Haptic device to query
896 * \returns the index of the specified haptic device or a negative error code
897 * on failure; call SDL_GetError() for more information.
883 898 * *
884 * \sa SDL_HapticOpen
885 * \sa SDL_HapticOpened
899 * \since This function is available since SDL 2.0.0.
900 *
901 * \sa SDL_HapticOpen
902 * \sa SDL_HapticOpened
886 903 */ */
887 904 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
888 905
889 906 /** /**
890 * \brief Gets whether or not the current mouse has haptic capabilities.
907 * Query whether or not the current mouse has haptic capabilities.
908 *
909 * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
891 910 * *
892 * \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
911 * \since This function is available since SDL 2.0.0.
893 912 * *
894 * \sa SDL_HapticOpenFromMouse
913 * \sa SDL_HapticOpenFromMouse
895 914 */ */
896 915 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void); extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
897 916
898 917 /** /**
899 * \brief Tries to open a haptic device from the current mouse.
918 * Try to open a haptic device from the current mouse.
900 919 * *
901 * \return The haptic device identifier or NULL on error.
920 * \returns the haptic device identifier or NULL on failure; call
921 * SDL_GetError() for more information.
902 922 * *
903 * \sa SDL_MouseIsHaptic
904 * \sa SDL_HapticOpen
923 * \since This function is available since SDL 2.0.0.
924 *
925 * \sa SDL_HapticOpen
926 * \sa SDL_MouseIsHaptic
905 927 */ */
906 928 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void); extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
907 929
908 930 /** /**
909 * \brief Checks to see if a joystick has haptic features.
931 * Query if a joystick has haptic features.
910 932 * *
911 * \param joystick Joystick to test for haptic capabilities.
912 * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
913 * or -1 if an error occurred.
933 * \param joystick the SDL_Joystick to test for haptic capabilities
934 * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
935 * negative error code on failure; call SDL_GetError() for more
936 * information.
914 937 * *
915 * \sa SDL_HapticOpenFromJoystick
938 * \since This function is available since SDL 2.0.0.
939 *
940 * \sa SDL_HapticOpenFromJoystick
916 941 */ */
917 942 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick); extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
918 943
919 944 /** /**
920 * \brief Opens a haptic device for use from a joystick device.
945 * Open a haptic device for use from a joystick device.
921 946 * *
922 * You must still close the haptic device separately. It will not be closed
923 * with the joystick.
947 * You must still close the haptic device separately. It will not be closed
948 * with the joystick.
924 949 * *
925 * When opening from a joystick you should first close the haptic device before
926 * closing the joystick device. If not, on some implementations the haptic
927 * device will also get unallocated and you'll be unable to use force feedback
928 * on that device.
950 * When opened from a joystick you should first close the haptic device before
951 * closing the joystick device. If not, on some implementations the haptic
952 * device will also get unallocated and you'll be unable to use force feedback
953 * on that device.
929 954 * *
930 * \param joystick Joystick to create a haptic device from.
931 * \return A valid haptic device identifier on success or NULL on error.
955 * \param joystick the SDL_Joystick to create a haptic device from
956 * \returns a valid haptic device identifier on success or NULL on failure;
957 * call SDL_GetError() for more information.
932 958 * *
933 * \sa SDL_HapticOpen
934 * \sa SDL_HapticClose
959 * \since This function is available since SDL 2.0.0.
960 *
961 * \sa SDL_HapticClose
962 * \sa SDL_HapticOpen
963 * \sa SDL_JoystickIsHaptic
935 964 */ */
936 965 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
937 966 joystick); joystick);
938 967
939 968 /** /**
940 * \brief Closes a haptic device previously opened with SDL_HapticOpen().
969 * Close a haptic device previously opened with SDL_HapticOpen().
941 970 * *
942 * \param haptic Haptic device to close.
971 * \param haptic the SDL_Haptic device to close
972 *
973 * \sa SDL_HapticOpen
943 974 */ */
944 975 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic); extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
945 976
946 977 /** /**
947 * \brief Returns the number of effects a haptic device can store.
978 * Get the number of effects a haptic device can store.
979 *
980 * On some platforms this isn't fully supported, and therefore is an
981 * approximation. Always check to see if your created effect was actually
982 * created and do not rely solely on SDL_HapticNumEffects().
948 983 * *
949 * On some platforms this isn't fully supported, and therefore is an
950 * approximation. Always check to see if your created effect was actually
951 * created and do not rely solely on SDL_HapticNumEffects().
984 * \param haptic the SDL_Haptic device to query
985 * \returns the number of effects the haptic device can store or a negative
986 * error code on failure; call SDL_GetError() for more information.
952 987 * *
953 * \param haptic The haptic device to query effect max.
954 * \return The number of effects the haptic device can store or
955 * -1 on error.
988 * \since This function is available since SDL 2.0.0.
956 989 * *
957 * \sa SDL_HapticNumEffectsPlaying
958 * \sa SDL_HapticQuery
990 * \sa SDL_HapticNumEffectsPlaying
991 * \sa SDL_HapticQuery
959 992 */ */
960 993 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
961 994
962 995 /** /**
963 * \brief Returns the number of effects a haptic device can play at the same
964 * time.
996 * Get the number of effects a haptic device can play at the same time.
965 997 * *
966 * This is not supported on all platforms, but will always return a value.
967 * Added here for the sake of completeness.
998 * This is not supported on all platforms, but will always return a value.
968 999 * *
969 * \param haptic The haptic device to query maximum playing effects.
970 * \return The number of effects the haptic device can play at the same time
971 * or -1 on error.
1000 * \param haptic the SDL_Haptic device to query maximum playing effects
1001 * \returns the number of effects the haptic device can play at the same time
1002 * or a negative error code on failure; call SDL_GetError() for more
1003 * information.
972 1004 * *
973 * \sa SDL_HapticNumEffects
974 * \sa SDL_HapticQuery
1005 * \since This function is available since SDL 2.0.0.
1006 *
1007 * \sa SDL_HapticNumEffects
1008 * \sa SDL_HapticQuery
975 1009 */ */
976 1010 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
977 1011
978 1012 /** /**
979 * \brief Gets the haptic device's supported features in bitwise manner.
1013 * Get the haptic device's supported features in bitwise manner.
980 1014 * *
981 * Example:
982 * \code
983 * if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
984 * printf("We have constant haptic effect!\n");
985 * }
986 * \endcode
1015 * \param haptic the SDL_Haptic device to query
1016 * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
1017 * on failure; call SDL_GetError() for more information.
987 1018 * *
988 * \param haptic The haptic device to query.
989 * \return Haptic features in bitwise manner (OR'd).
1019 * \since This function is available since SDL 2.0.0.
990 1020 * *
991 * \sa SDL_HapticNumEffects
992 * \sa SDL_HapticEffectSupported
1021 * \sa SDL_HapticEffectSupported
1022 * \sa SDL_HapticNumEffects
993 1023 */ */
994 1024 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic); extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
995 1025
996 1026
997 1027 /** /**
998 * \brief Gets the number of haptic axes the device has.
1028 * Get the number of haptic axes the device has.
999 1029 * *
1000 * \sa SDL_HapticDirection
1030 * The number of haptic axes might be useful if working with the
1031 * SDL_HapticDirection effect.
1032 *
1033 * \param haptic the SDL_Haptic device to query
1034 * \returns the number of axes on success or a negative error code on failure;
1035 * call SDL_GetError() for more information.
1001 1036 */ */
1002 1037 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
1003 1038
1004 1039 /** /**
1005 * \brief Checks to see if effect is supported by haptic.
1040 * Check to see if an effect is supported by a haptic device.
1041 *
1042 * \param haptic the SDL_Haptic device to query
1043 * \param effect the desired effect to query
1044 * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
1045 * negative error code on failure; call SDL_GetError() for more
1046 * information.
1006 1047 * *
1007 * \param haptic Haptic device to check on.
1008 * \param effect Effect to check to see if it is supported.
1009 * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
1048 * \since This function is available since SDL 2.0.0.
1010 1049 * *
1011 * \sa SDL_HapticQuery
1012 * \sa SDL_HapticNewEffect
1050 * \sa SDL_HapticNewEffect
1051 * \sa SDL_HapticQuery
1013 1052 */ */
1014 1053 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
1015 1054 SDL_HapticEffect * SDL_HapticEffect *
1016 1055 effect); effect);
1017 1056
1018 1057 /** /**
1019 * \brief Creates a new haptic effect on the device.
1058 * Create a new haptic effect on a specified device.
1020 1059 * *
1021 * \param haptic Haptic device to create the effect on.
1022 * \param effect Properties of the effect to create.
1023 * \return The identifier of the effect on success or -1 on error.
1060 * \param haptic an SDL_Haptic device to create the effect on
1061 * \param effect an SDL_HapticEffect structure containing the properties of
1062 * the effect to create
1063 * \returns the ID of the effect on success or a negative error code on
1064 * failure; call SDL_GetError() for more information.
1024 1065 * *
1025 * \sa SDL_HapticUpdateEffect
1026 * \sa SDL_HapticRunEffect
1027 * \sa SDL_HapticDestroyEffect
1066 * \sa SDL_HapticDestroyEffect
1067 * \sa SDL_HapticRunEffect
1068 * \sa SDL_HapticUpdateEffect
1028 1069 */ */
1029 1070 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
1030 1071 SDL_HapticEffect * effect); SDL_HapticEffect * effect);
1031 1072
1032 1073 /** /**
1033 * \brief Updates the properties of an effect.
1074 * Update the properties of an effect.
1075 *
1076 * Can be used dynamically, although behavior when dynamically changing
1077 * direction may be strange. Specifically the effect may re-upload itself and
1078 * start playing from the start. You also cannot change the type either when
1079 * running SDL_HapticUpdateEffect().
1034 1080 * *
1035 * Can be used dynamically, although behavior when dynamically changing
1036 * direction may be strange. Specifically the effect may reupload itself
1037 * and start playing from the start. You cannot change the type either when
1038 * running SDL_HapticUpdateEffect().
1081 * \param haptic the SDL_Haptic device that has the effect
1082 * \param effect the identifier of the effect to update
1083 * \param data an SDL_HapticEffect structure containing the new effect
1084 * properties to use
1085 * \returns 0 on success or a negative error code on failure; call
1086 * SDL_GetError() for more information.
1039 1087 * *
1040 * \param haptic Haptic device that has the effect.
1041 * \param effect Identifier of the effect to update.
1042 * \param data New effect properties to use.
1043 * \return 0 on success or -1 on error.
1088 * \since This function is available since SDL 2.0.0.
1044 1089 * *
1045 * \sa SDL_HapticNewEffect
1046 * \sa SDL_HapticRunEffect
1047 * \sa SDL_HapticDestroyEffect
1090 * \sa SDL_HapticDestroyEffect
1091 * \sa SDL_HapticNewEffect
1092 * \sa SDL_HapticRunEffect
1048 1093 */ */
1049 1094 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
1050 1095 int effect, int effect,
1051 1096 SDL_HapticEffect * data); SDL_HapticEffect * data);
1052 1097
1053 1098 /** /**
1054 * \brief Runs the haptic effect on its associated haptic device.
1099 * Run the haptic effect on its associated haptic device.
1055 1100 * *
1056 * If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
1057 * repeating the envelope (attack and fade) every time. If you only want the
1058 * effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
1059 * parameter.
1101 * To repeat the effect over and over indefinitely, set `iterations` to
1102 * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
1103 * one instance of the effect last indefinitely (so the effect does not fade),
1104 * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
1105 * instead.
1060 1106 * *
1061 * \param haptic Haptic device to run the effect on.
1062 * \param effect Identifier of the haptic effect to run.
1063 * \param iterations Number of iterations to run the effect. Use
1064 * ::SDL_HAPTIC_INFINITY for infinity.
1065 * \return 0 on success or -1 on error.
1107 * \param haptic the SDL_Haptic device to run the effect on
1108 * \param effect the ID of the haptic effect to run
1109 * \param iterations the number of iterations to run the effect; use
1110 * `SDL_HAPTIC_INFINITY` to repeat forever
1111 * \returns 0 on success or a negative error code on failure; call
1112 * SDL_GetError() for more information.
1066 1113 * *
1067 * \sa SDL_HapticStopEffect
1068 * \sa SDL_HapticDestroyEffect
1069 * \sa SDL_HapticGetEffectStatus
1114 * \since This function is available since SDL 2.0.0.
1115 *
1116 * \sa SDL_HapticDestroyEffect
1117 * \sa SDL_HapticGetEffectStatus
1118 * \sa SDL_HapticStopEffect
1070 1119 */ */
1071 1120 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
1072 1121 int effect, int effect,
1073 1122 Uint32 iterations); Uint32 iterations);
1074 1123
1075 1124 /** /**
1076 * \brief Stops the haptic effect on its associated haptic device.
1125 * Stop the haptic effect on its associated haptic device.
1077 1126 * *
1078 * \param haptic Haptic device to stop the effect on.
1079 * \param effect Identifier of the effect to stop.
1080 * \return 0 on success or -1 on error.
1127 * *
1081 1128 * *
1082 * \sa SDL_HapticRunEffect
1083 * \sa SDL_HapticDestroyEffect
1129 * \param haptic the SDL_Haptic device to stop the effect on
1130 * \param effect the ID of the haptic effect to stop
1131 * \returns 0 on success or a negative error code on failure; call
1132 * SDL_GetError() for more information.
1133 *
1134 * \since This function is available since SDL 2.0.0.
1135 *
1136 * \sa SDL_HapticDestroyEffect
1137 * \sa SDL_HapticRunEffect
1084 1138 */ */
1085 1139 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
1086 1140 int effect); int effect);
1087 1141
1088 1142 /** /**
1089 * \brief Destroys a haptic effect on the device.
1143 * Destroy a haptic effect on the device.
1090 1144 * *
1091 * This will stop the effect if it's running. Effects are automatically
1092 * destroyed when the device is closed.
1145 * This will stop the effect if it's running. Effects are automatically
1146 * destroyed when the device is closed.
1093 1147 * *
1094 * \param haptic Device to destroy the effect on.
1095 * \param effect Identifier of the effect to destroy.
1148 * \param haptic the SDL_Haptic device to destroy the effect on
1149 * \param effect the ID of the haptic effect to destroy
1096 1150 * *
1097 * \sa SDL_HapticNewEffect
1151 * \since This function is available since SDL 2.0.0.
1152 *
1153 * \sa SDL_HapticNewEffect
1098 1154 */ */
1099 1155 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
1100 1156 int effect); int effect);
1101 1157
1102 1158 /** /**
1103 * \brief Gets the status of the current effect on the haptic device.
1159 * Get the status of the current effect on the specified haptic device.
1160 *
1161 * Device must support the SDL_HAPTIC_STATUS feature.
1104 1162 * *
1105 * Device must support the ::SDL_HAPTIC_STATUS feature.
1163 * \param haptic the SDL_Haptic device to query for the effect status on
1164 * \param effect the ID of the haptic effect to query its status
1165 * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
1166 * code on failure; call SDL_GetError() for more information.
1106 1167 * *
1107 * \param haptic Haptic device to query the effect status on.
1108 * \param effect Identifier of the effect to query its status.
1109 * \return 0 if it isn't playing, 1 if it is playing or -1 on error.
1168 * \since This function is available since SDL 2.0.0.
1110 1169 * *
1111 * \sa SDL_HapticRunEffect
1112 * \sa SDL_HapticStopEffect
1170 * \sa SDL_HapticRunEffect
1171 * \sa SDL_HapticStopEffect
1113 1172 */ */
1114 1173 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
1115 1174 int effect); int effect);
1116 1175
1117 1176 /** /**
1118 * \brief Sets the global gain of the device.
1177 * Set the global gain of the specified haptic device.
1119 1178 * *
1120 * Device must support the ::SDL_HAPTIC_GAIN feature.
1179 * Device must support the SDL_HAPTIC_GAIN feature.
1121 1180 * *
1122 * The user may specify the maximum gain by setting the environment variable
1123 * SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to
1124 * SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
1125 * maximum.
1181 * The user may specify the maximum gain by setting the environment variable
1182 * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
1183 * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
1184 * maximum.
1126 1185 * *
1127 * \param haptic Haptic device to set the gain on.
1128 * \param gain Value to set the gain to, should be between 0 and 100.
1129 * \return 0 on success or -1 on error.
1186 * \param haptic the SDL_Haptic device to set the gain on
1187 * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
1188 * \returns 0 on success or a negative error code on failure; call
1189 * SDL_GetError() for more information.
1130 1190 * *
1131 * \sa SDL_HapticQuery
1191 * \since This function is available since SDL 2.0.0.
1192 *
1193 * \sa SDL_HapticQuery
1132 1194 */ */
1133 1195 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain); extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
1134 1196
1135 1197 /** /**
1136 * \brief Sets the global autocenter of the device.
1198 * Set the global autocenter of the device.
1137 1199 * *
1138 * Autocenter should be between 0 and 100. Setting it to 0 will disable
1139 * autocentering.
1200 * Autocenter should be between 0 and 100. Setting it to 0 will disable
1201 * autocentering.
1140 1202 * *
1141 * Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
1203 * Device must support the SDL_HAPTIC_AUTOCENTER feature.
1142 1204 * *
1143 * \param haptic Haptic device to set autocentering on.
1144 * \param autocenter Value to set autocenter to, 0 disables autocentering.
1145 * \return 0 on success or -1 on error.
1205 * \param haptic the SDL_Haptic device to set autocentering on
1206 * \param autocenter value to set autocenter to (0-100)
1207 * \returns 0 on success or a negative error code on failure; call
1208 * SDL_GetError() for more information.
1146 1209 * *
1147 * \sa SDL_HapticQuery
1210 * \sa SDL_HapticQuery
1148 1211 */ */
1149 1212 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
1150 1213 int autocenter); int autocenter);
1151 1214
1152 1215 /** /**
1153 * \brief Pauses a haptic device.
1216 * Pause a haptic device.
1154 1217 * *
1155 * Device must support the ::SDL_HAPTIC_PAUSE feature. Call
1156 * SDL_HapticUnpause() to resume playback.
1218 * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
1219 * SDL_HapticUnpause() to resume playback.
1157 1220 * *
1158 * Do not modify the effects nor add new ones while the device is paused.
1159 * That can cause all sorts of weird errors.
1221 * Do not modify the effects nor add new ones while the device is paused. That
1222 * can cause all sorts of weird errors.
1160 1223 * *
1161 * \param haptic Haptic device to pause.
1162 * \return 0 on success or -1 on error.
1224 * \param haptic the SDL_Haptic device to pause
1225 * \returns 0 on success or a negative error code on failure; call
1226 * SDL_GetError() for more information.
1163 1227 * *
1164 * \sa SDL_HapticUnpause
1228 * \sa SDL_HapticUnpause
1165 1229 */ */
1166 1230 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
1167 1231
1168 1232 /** /**
1169 * \brief Unpauses a haptic device.
1233 * Unpause a haptic device.
1170 1234 * *
1171 * Call to unpause after SDL_HapticPause().
1235 * Call to unpause after SDL_HapticPause().
1172 1236 * *
1173 * \param haptic Haptic device to unpause.
1174 * \return 0 on success or -1 on error.
1237 * \param haptic the SDL_Haptic device to unpause
1238 * \returns 0 on success or a negative error code on failure; call
1239 * SDL_GetError() for more information.
1175 1240 * *
1176 * \sa SDL_HapticPause
1241 * \sa SDL_HapticPause
1177 1242 */ */
1178 1243 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
1179 1244
1180 1245 /** /**
1181 * \brief Stops all the currently playing effects on a haptic device.
1246 * Stop all the currently playing effects on a haptic device.
1182 1247 * *
1183 * \param haptic Haptic device to stop.
1184 * \return 0 on success or -1 on error.
1248 * \param haptic the SDL_Haptic device to stop
1249 * \returns 0 on success or a negative error code on failure; call
1250 * SDL_GetError() for more information.
1185 1251 */ */
1186 1252 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
1187 1253
1188 1254 /** /**
1189 * \brief Checks to see if rumble is supported on a haptic device.
1255 * Check whether rumble is supported on a haptic device.
1190 1256 * *
1191 * \param haptic Haptic device to check to see if it supports rumble.
1192 * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
1257 * \param haptic haptic device to check for rumble support
1258 * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
1259 * negative error code on failure; call SDL_GetError() for more
1260 * information.
1193 1261 * *
1194 * \sa SDL_HapticRumbleInit
1195 * \sa SDL_HapticRumblePlay
1196 * \sa SDL_HapticRumbleStop
1262 * \sa SDL_HapticRumbleInit
1263 * \sa SDL_HapticRumblePlay
1264 * \sa SDL_HapticRumbleStop
1197 1265 */ */
1198 1266 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
1199 1267
1200 1268 /** /**
1201 * \brief Initializes the haptic device for simple rumble playback.
1269 * Initialize a haptic device for simple rumble playback.
1202 1270 * *
1203 * \param haptic Haptic device to initialize for simple rumble playback.
1204 * \return 0 on success or -1 on error.
1271 * \param haptic the haptic device to initialize for simple rumble playback
1272 * \returns 0 on success or a negative error code on failure; call
1273 * SDL_GetError() for more information.
1205 1274 * *
1206 * \sa SDL_HapticOpen
1207 * \sa SDL_HapticRumbleSupported
1208 * \sa SDL_HapticRumblePlay
1209 * \sa SDL_HapticRumbleStop
1275 * \since This function is available since SDL 2.0.0.
1276 *
1277 * \sa SDL_HapticOpen
1278 * \sa SDL_HapticRumblePlay
1279 * \sa SDL_HapticRumbleStop
1280 * \sa SDL_HapticRumbleSupported
1210 1281 */ */
1211 1282 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
1212 1283
1213 1284 /** /**
1214 * \brief Runs simple rumble on a haptic device
1285 * Run a simple rumble effect on a haptic device.
1215 1286 * *
1216 * \param haptic Haptic device to play rumble effect on.
1217 * \param strength Strength of the rumble to play as a 0-1 float value.
1218 * \param length Length of the rumble to play in milliseconds.
1219 * \return 0 on success or -1 on error.
1287 * \param haptic the haptic device to play the rumble effect on
1288 * \param strength strength of the rumble to play as a 0-1 float value
1289 * \param length length of the rumble to play in milliseconds
1290 * \returns 0 on success or a negative error code on failure; call
1291 * SDL_GetError() for more information.
1220 1292 * *
1221 * \sa SDL_HapticRumbleSupported
1222 * \sa SDL_HapticRumbleInit
1223 * \sa SDL_HapticRumbleStop
1293 * \sa SDL_HapticRumbleInit
1294 * \sa SDL_HapticRumbleStop
1295 * \sa SDL_HapticRumbleSupported
1224 1296 */ */
1225 1297 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length ); extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
1226 1298
1227 1299 /** /**
1228 * \brief Stops the simple rumble on a haptic device.
1300 * Stop the simple rumble on a haptic device.
1229 1301 * *
1230 * \param haptic Haptic to stop the rumble on.
1231 * \return 0 on success or -1 on error.
1302 * \param haptic the haptic device to stop the rumble effect on
1303 * \returns 0 on success or a negative error code on failure; call
1304 * SDL_GetError() for more information.
1232 1305 * *
1233 * \sa SDL_HapticRumbleSupported
1234 * \sa SDL_HapticRumbleInit
1235 * \sa SDL_HapticRumblePlay
1306 * \sa SDL_HapticRumbleInit
1307 * \sa SDL_HapticRumblePlay
1308 * \sa SDL_HapticRumbleSupported
1236 1309 */ */
1237 1310 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic); extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
1238 1311
File include/SDL2/SDL_hints.h changed (mode: 100644) (index 50a5a08..c3ae80d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
48 48 #endif #endif
49 49
50 50 /** /**
51 * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
52 *
53 * SDL can try to accelerate the SDL screen surface by using streaming
54 * textures with a 3D rendering engine. This variable controls whether and
55 * how this is done.
51 * \brief A variable controlling whether the Android / iOS built-in
52 * accelerometer should be listed as a joystick device.
56 53 * *
57 54 * This variable can be set to the following values: * This variable can be set to the following values:
58 * "0" - Disable 3D acceleration
59 * "1" - Enable 3D acceleration, using the default renderer.
60 * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.)
61 *
62 * By default SDL tries to make a best guess for each platform whether
63 * to use acceleration or not.
55 * "0" - The accelerometer is not listed as a joystick
56 * "1" - The accelerometer is available as a 3 axis joystick (the default).
64 57 */ */
65 #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
58 #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
66 59
67 60 /** /**
68 * \brief A variable specifying which render driver to use.
69 *
70 * If the application doesn't pick a specific renderer to use, this variable
71 * specifies the name of the preferred renderer. If the preferred renderer
72 * can't be initialized, the normal default renderer is used.
61 * \brief Specify the behavior of Alt+Tab while the keyboard is grabbed.
73 62 * *
74 * This variable is case insensitive and can be set to the following values:
75 * "direct3d"
76 * "opengl"
77 * "opengles2"
78 * "opengles"
79 * "metal"
80 * "software"
63 * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed
64 * and your window is full-screen. This prevents the user from getting stuck in
65 * your application if you've enabled keyboard grab.
81 66 * *
82 * The default varies by platform, but it's the first one in the list that
83 * is available on the current platform.
84 */
85 #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER"
67 * The variable can be set to the following values:
68 * "0" - SDL will not handle Alt+Tab. Your application is responsible
69 for handling Alt+Tab while the keyboard is grabbed.
70 * "1" - SDL will minimize your window when Alt+Tab is pressed (default)
71 */
72 #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
86 73
87 74 /** /**
88 * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available.
75 * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
76 * This is a debugging aid for developers and not expected to be used by end users. The default is "1"
89 77 * *
90 78 * This variable can be set to the following values: * This variable can be set to the following values:
91 * "0" - Disable shaders
92 * "1" - Enable shaders
93 *
94 * By default shaders are used if OpenGL supports them.
79 * "0" - don't allow topmost
80 * "1" - allow topmost
95 81 */ */
96 #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS"
82 #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
97 83
98 84 /** /**
99 * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations.
85 * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc.
100 86 * *
101 * This variable can be set to the following values:
102 * "0" - Thread-safety is not enabled (faster)
103 * "1" - Thread-safety is enabled
87 * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
104 88 * *
105 * By default the Direct3D device is created with thread-safety disabled.
89 * If both hints were set then SDL_RWFromFile() will look into expansion files
90 * after a given relative path was not found in the internal storage and assets.
91 *
92 * By default this hint is not set and the APK expansion files are not searched.
106 93 */ */
107 #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
108
94 #define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
95
109 96 /** /**
110 * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer.
97 * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
111 98 * *
112 * This variable does not have any effect on the Direct3D 9 based renderer.
99 * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
113 100 * *
114 * This variable can be set to the following values:
115 * "0" - Disable Debug Layer use
116 * "1" - Enable Debug Layer use
101 * If both hints were set then SDL_RWFromFile() will look into expansion files
102 * after a given relative path was not found in the internal storage and assets.
117 103 * *
118 * By default, SDL does not use Direct3D Debug Layer.
104 * By default this hint is not set and the APK expansion files are not searched.
119 105 */ */
120 #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG"
106 #define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
121 107
122 108 /** /**
123 * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize.
109 * \brief A variable to control whether the event loop will block itself when the app is paused.
124 110 * *
125 * This variable can be set to the following values:
126 * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen
127 * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
111 * The variable can be set to the following values:
112 * "0" - Non blocking.
113 * "1" - Blocking. (default)
128 114 * *
129 * By default letterbox is used
115 * The value should be set before SDL is initialized.
130 116 */ */
131 #define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE"
117 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
132 118
133 119 /** /**
134 * \brief A variable controlling the scaling quality
120 * \brief A variable to control whether SDL will pause audio in background
121 * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
135 122 * *
136 * This variable can be set to the following values:
137 * "0" or "nearest" - Nearest pixel sampling
138 * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D)
139 * "2" or "best" - Currently this is the same as "linear"
123 * The variable can be set to the following values:
124 * "0" - Non paused.
125 * "1" - Paused. (default)
140 126 * *
141 * By default nearest pixel sampling is used
127 * The value should be set before SDL is initialized.
142 128 */ */
143 #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY"
129 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
144 130
145 131 /** /**
146 * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
132 * \brief A variable to control whether we trap the Android back button to handle it manually.
133 * This is necessary for the right mouse button to work on some Android devices, or
134 * to be able to trap the back button for use in your code reliably. If set to true,
135 * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of
136 * SDL_SCANCODE_AC_BACK.
147 137 * *
148 * This variable can be set to the following values:
149 * "0" - Disable vsync
150 * "1" - Enable vsync
138 * The variable can be set to the following values:
139 * "0" - Back button will be handled as usual for system. (default)
140 * "1" - Back button will be trapped, allowing you to handle the key press
141 * manually. (This will also let right mouse click work on systems
142 * where the right mouse button functions as back.)
151 143 * *
152 * By default SDL does not sync screen surface updates with vertical refresh.
144 * The value of this hint is used at runtime, so it can be changed at any time.
153 145 */ */
154 #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC"
146 #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
155 147
156 148 /** /**
157 * \brief A variable controlling whether the screensaver is enabled.
149 * \brief A variable controlling whether controllers used with the Apple TV
150 * generate UI events.
151 *
152 * When UI events are generated by controller input, the app will be
153 * backgrounded when the Apple TV remote's menu button is pressed, and when the
154 * pause or B buttons on gamepads are pressed.
155 *
156 * More information about properly making use of controllers for the Apple TV
157 * can be found here:
158 * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
158 159 * *
159 160 * This variable can be set to the following values: * This variable can be set to the following values:
160 * "0" - Disable screensaver
161 * "1" - Enable screensaver
161 * "0" - Controller input does not generate UI events (the default).
162 * "1" - Controller input generates UI events.
163 */
164 #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
165
166 /**
167 * \brief A variable controlling whether the Apple TV remote's joystick axes
168 * will automatically match the rotation of the remote.
162 169 * *
163 * By default SDL will disable the screensaver.
170 * This variable can be set to the following values:
171 * "0" - Remote orientation does not affect joystick axes (the default).
172 * "1" - Joystick axes are based on the orientation of the remote.
164 173 */ */
165 #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER"
174 #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
166 175
167 176 /** /**
168 * \brief A variable controlling whether the graphics context is externally managed.
177 * \brief A variable controlling the audio category on iOS and Mac OS X
169 178 * *
170 * This variable can be set to the following values:
171 * "0" - SDL will manage graphics contexts that are attached to windows.
172 * "1" - Disable graphics context management on windows.
179 * This variable can be set to the following values:
173 180 * *
174 * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the
175 * context will be automatically saved and restored when pausing the application. Additionally, some
176 * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this
177 * behavior, which is desireable when the application manages the graphics context, such as
178 * an externally managed OpenGL context or attaching a Vulkan surface to the window.
181 * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
182 * "playback" - Use the AVAudioSessionCategoryPlayback category
183 *
184 * For more information, see Apple's documentation:
185 * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
179 186 */ */
180 #define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT"
187 #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY"
181 188
182 189 /** /**
183 * \brief A variable controlling whether the X11 VidMode extension should be used.
190 * \brief Specify an application name for an audio device.
184 191 * *
185 * This variable can be set to the following values:
186 * "0" - Disable XVidMode
187 * "1" - Enable XVidMode
192 * Some audio backends (such as PulseAudio) allow you to describe your audio
193 * stream. Among other things, this description might show up in a system
194 * control panel that lets the user adjust the volume on specific audio
195 * streams instead of using one giant master volume slider.
188 196 * *
189 * By default SDL will use XVidMode if it is available.
197 * This hints lets you transmit that information to the OS. The contents of
198 * this hint are used while opening an audio device. You should use a string
199 * that describes your program ("My Game 2: The Revenge")
200 *
201 * Setting this to "" or leaving it unset will have SDL use a reasonable
202 * default: probably the application's name or "SDL Application" if SDL
203 * doesn't have any better information.
204 *
205 * On targets where this is not supported, this hint does nothing.
190 206 */ */
191 #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE"
207 #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
192 208
193 209 /** /**
194 * \brief A variable controlling whether the X11 Xinerama extension should be used.
210 * \brief Specify an application name for an audio device.
195 211 * *
196 * This variable can be set to the following values:
197 * "0" - Disable Xinerama
198 * "1" - Enable Xinerama
212 * Some audio backends (such as PulseAudio) allow you to describe your audio
213 * stream. Among other things, this description might show up in a system
214 * control panel that lets the user adjust the volume on specific audio
215 * streams instead of using one giant master volume slider.
199 216 * *
200 * By default SDL will use Xinerama if it is available.
217 * This hints lets you transmit that information to the OS. The contents of
218 * this hint are used while opening an audio device. You should use a string
219 * that describes your what your program is playing ("audio stream" is
220 * probably sufficient in many cases, but this could be useful for something
221 * like "team chat" if you have a headset playing VoIP audio separately).
222 *
223 * Setting this to "" or leaving it unset will have SDL use a reasonable
224 * default: "audio stream" or something similar.
225 *
226 * On targets where this is not supported, this hint does nothing.
201 227 */ */
202 #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA"
228 #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
203 229
204 230 /** /**
205 * \brief A variable controlling whether the X11 XRandR extension should be used.
231 * \brief Specify an application role for an audio device.
206 232 * *
207 * This variable can be set to the following values:
208 * "0" - Disable XRandR
209 * "1" - Enable XRandR
233 * Some audio backends (such as Pipewire) allow you to describe the role of
234 * your audio stream. Among other things, this description might show up in
235 * a system control panel or software for displaying and manipulating media
236 * playback/capture graphs.
210 237 * *
211 * By default SDL will not use XRandR because of window manager issues.
238 * This hints lets you transmit that information to the OS. The contents of
239 * this hint are used while opening an audio device. You should use a string
240 * that describes your what your program is playing (Game, Music, Movie,
241 * etc...).
242 *
243 * Setting this to "" or leaving it unset will have SDL use a reasonable
244 * default: "Game" or something similar.
245 *
246 * On targets where this is not supported, this hint does nothing.
212 247 */ */
213 #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR"
248 #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE"
214 249
215 250 /** /**
216 * \brief A variable forcing the visual ID chosen for new X11 windows
251 * \brief A variable controlling speed/quality tradeoff of audio resampling.
252 *
253 * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
254 * to handle audio resampling. There are different resampling modes available
255 * that produce different levels of quality, using more CPU.
217 256 * *
257 * If this hint isn't specified to a valid setting, or libsamplerate isn't
258 * available, SDL will use the default, internal resampling algorithm.
259 *
260 * Note that this is currently only applicable to resampling audio that is
261 * being written to a device for playback or audio being read from a device
262 * for capture. SDL_AudioCVT always uses the default resampler (although this
263 * might change for SDL 2.1).
264 *
265 * This hint is currently only checked at audio subsystem initialization.
266 *
267 * This variable can be set to the following values:
268 *
269 * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast)
270 * "1" or "fast" - Use fast, slightly higher quality resampling, if available
271 * "2" or "medium" - Use medium quality resampling, if available
272 * "3" or "best" - Use high quality resampling, if available
218 273 */ */
219 #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID"
274 #define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE"
220 275
221 276 /** /**
222 * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
277 * \brief A variable controlling whether SDL updates joystick state when getting input events
223 278 * *
224 279 * This variable can be set to the following values: * This variable can be set to the following values:
225 * "0" - Disable _NET_WM_PING
226 * "1" - Enable _NET_WM_PING
227 280 * *
228 * By default SDL will use _NET_WM_PING, but for applications that know they
229 * will not always be able to respond to ping requests in a timely manner they can
230 * turn it off to avoid the window manager thinking the app is hung.
231 * The hint is checked in CreateWindow.
281 * "0" - You'll call SDL_JoystickUpdate() manually
282 * "1" - SDL will automatically call SDL_JoystickUpdate() (default)
283 *
284 * This hint can be toggled on and off at runtime.
232 285 */ */
233 #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING"
286 #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS"
234 287
235 288 /** /**
236 * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
237 *
238 * This variable can be set to the following values:
239 * "0" - Disable _NET_WM_BYPASS_COMPOSITOR
240 * "1" - Enable _NET_WM_BYPASS_COMPOSITOR
241 *
242 * By default SDL will use _NET_WM_BYPASS_COMPOSITOR
243 *
289 * \brief A variable controlling whether SDL updates sensor state when getting input events
290 *
291 * This variable can be set to the following values:
292 *
293 * "0" - You'll call SDL_SensorUpdate() manually
294 * "1" - SDL will automatically call SDL_SensorUpdate() (default)
295 *
296 * This hint can be toggled on and off at runtime.
244 297 */ */
245 #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
298 #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS"
246 299
247 300 /** /**
248 * \brief A variable controlling whether X11 should use GLX or EGL by default
301 * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs.
249 302 * *
250 * This variable can be set to the following values:
251 * "0" - Use GLX
252 * "1" - Use EGL
303 * The bitmap header version 4 is required for proper alpha channel support and
304 * SDL will use it when required. Should this not be desired, this hint can
305 * force the use of the 40 byte header version which is supported everywhere.
253 306 * *
254 * By default SDL will use GLX when both are present.
307 * The variable can be set to the following values:
308 * "0" - Surfaces with a colorkey or an alpha channel are saved to a
309 * 32-bit BMP file with an alpha mask. SDL will use the bitmap
310 * header version 4 and set the alpha mask accordingly.
311 * "1" - Surfaces with a colorkey or an alpha channel are saved to a
312 * 32-bit BMP file without an alpha mask. The alpha channel data
313 * will be in the file, but applications are going to ignore it.
314 *
315 * The default value is "0".
255 316 */ */
256 #define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL"
317 #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
257 318
258 319 /** /**
259 * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
320 * \brief Override for SDL_GetDisplayUsableBounds()
260 321 * *
261 * This variable can be set to the following values:
262 * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
263 * "1" - The window frame is interactive when the cursor is hidden
322 * If set, this hint will override the expected results for
323 * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
324 * to do this, but this allows an embedded system to request that some of the
325 * screen be reserved for other uses when paired with a well-behaved
326 * application.
264 327 * *
265 * By default SDL will allow interaction with the window frame when the cursor is hidden
328 * The contents of this hint must be 4 comma-separated integers, the first
329 * is the bounds x, then y, width and height, in that order.
266 330 */ */
267 #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
331 #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
268 332
269 333 /** /**
270 * \brief A variable to specify custom icon resource id from RC file on Windows platform
334 * \brief Disable giving back control to the browser automatically
335 * when running with asyncify
336 *
337 * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations
338 * such as refreshing the screen or polling events.
339 *
340 * This hint only applies to the emscripten platform
341 *
342 * The variable can be set to the following values:
343 * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes)
344 * "1" - Enable emscripten_sleep calls (the default)
271 345 */ */
272 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON"
273 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
346 #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY"
274 347
275 348 /** /**
276 * \brief A variable controlling whether the windows message loop is processed by SDL
349 * \brief override the binding element for keyboard inputs for Emscripten builds
277 350 * *
278 * This variable can be set to the following values:
279 * "0" - The window message loop is not run
280 * "1" - The window message loop is processed in SDL_PumpEvents()
351 * This hint only applies to the emscripten platform
281 352 * *
282 * By default SDL will process the windows message loop
353 * The variable can be one of
354 * "#window" - The javascript window object (this is the default)
355 * "#document" - The javascript document object
356 * "#screen" - the javascript window.screen object
357 * "#canvas" - the WebGL canvas element
358 * any other string without a leading # sign applies to the element on the page with that ID.
283 359 */ */
284 #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP"
360 #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
285 361
286 362 /** /**
287 * \brief A variable controlling whether grabbing input grabs the keyboard
363 * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
288 364 * *
289 * This variable can be set to the following values:
290 * "0" - Grab will affect only the mouse
291 * "1" - Grab will affect mouse and keyboard
365 * The variable can be set to the following values:
366 * "0" - Do not scan for Steam Controllers
367 * "1" - Scan for Steam Controllers (the default)
292 368 * *
293 * By default SDL will not grab the keyboard so system shortcuts still work.
369 * The default value is "1". This hint must be set before initializing the joystick subsystem.
294 370 */ */
295 #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
371 #define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
296 372
297 373 /** /**
298 * \brief A variable setting the double click time, in milliseconds.
374 * \brief A variable controlling whether SDL logs all events pushed onto its internal queue.
375 *
376 * This variable can be set to the following values:
377 *
378 * "0" - Don't log any events (default)
379 * "1" - Log all events except mouse and finger motion, which are pretty spammy.
380 * "2" - Log all events.
381 *
382 * This is generally meant to be used to debug SDL itself, but can be useful
383 * for application developers that need better visibility into what is going
384 * on in the event queue. Logged events are sent through SDL_Log(), which
385 * means by default they appear on stdout on most platforms or maybe
386 * OutputDebugString() on Windows, and can be funneled by the app with
387 * SDL_LogSetOutputFunction(), etc.
388 *
389 * This hint can be toggled on and off at runtime, if you only need to log
390 * events for a small subset of program execution.
299 391 */ */
300 #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME"
392 #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING"
301 393
302 394 /** /**
303 * \brief A variable setting the double click radius, in pixels.
395 * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
396 *
397 * SDL can try to accelerate the SDL screen surface by using streaming
398 * textures with a 3D rendering engine. This variable controls whether and
399 * how this is done.
400 *
401 * This variable can be set to the following values:
402 * "0" - Disable 3D acceleration
403 * "1" - Enable 3D acceleration, using the default renderer.
404 * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.)
405 *
406 * By default SDL tries to make a best guess for each platform whether
407 * to use acceleration or not.
304 408 */ */
305 #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS"
409 #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
306 410
307 411 /** /**
308 * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
412 * \brief A variable that lets you manually hint extra gamecontroller db entries.
413 *
414 * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
415 *
416 * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
417 * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
309 418 */ */
310 #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE"
419 #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
311 420
312 421 /** /**
313 * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
422 * \brief A variable that lets you provide a file with extra gamecontroller db entries.
423 *
424 * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
425 *
426 * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
427 * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
314 428 */ */
315 #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE"
429 #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
316 430
317 431 /** /**
318 * \brief A variable controlling whether relative mouse motion is affected by renderer scaling
432 * \brief A variable that overrides the automatic controller type detection
319 433 * *
320 * This variable can be set to the following values:
321 * "0" - Relative motion is unaffected by DPI or renderer's logical size
322 * "1" - Relative motion is scaled according to DPI scaling and logical size
434 * The variable should be comma separated entries, in the form: VID/PID=type
323 435 * *
324 * By default relative mouse deltas are affected by DPI and renderer scaling
436 * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
437 *
438 * The type should be one of:
439 * Xbox360
440 * XboxOne
441 * PS3
442 * PS4
443 * PS5
444 * SwitchPro
445 *
446 * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
325 447 */ */
326 #define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING"
448 #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE"
327 449
328 450 /** /**
329 * \brief A variable controlling whether relative mouse mode is implemented using mouse warping
451 * \brief A variable containing a list of devices to skip when scanning for game controllers.
330 452 * *
331 * This variable can be set to the following values:
332 * "0" - Relative mouse mode uses raw input
333 * "1" - Relative mouse mode uses mouse warping
453 * The format of the string is a comma separated list of USB VID/PID pairs
454 * in hexadecimal form, e.g.
334 455 * *
335 * By default SDL will use raw input for relative mouse mode
456 * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
457 *
458 * The variable can also take the form of @file, in which case the named
459 * file will be loaded and interpreted as the value of the variable.
336 460 */ */
337 #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP"
461 #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
338 462
339 463 /** /**
340 * \brief Allow mouse click events when clicking to focus an SDL window
464 * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
341 465 * *
342 * This variable can be set to the following values:
343 * "0" - Ignore mouse clicks that activate a window
344 * "1" - Generate events for mouse clicks that activate a window
466 * The format of the string is a comma separated list of USB VID/PID pairs
467 * in hexadecimal form, e.g.
345 468 * *
346 * By default SDL will ignore mouse clicks that activate a window
469 * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
470 *
471 * The variable can also take the form of @file, in which case the named
472 * file will be loaded and interpreted as the value of the variable.
347 473 */ */
348 #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH"
474 #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
349 475
350 476 /** /**
351 * \brief A variable controlling whether touch events should generate synthetic mouse events
477 * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout.
478 *
479 * For example, on Nintendo Switch controllers, normally you'd get:
352 480 * *
353 * This variable can be set to the following values:
354 * "0" - Touch events will not generate mouse events
355 * "1" - Touch events will generate mouse events
481 * (Y)
482 * (X) (B)
483 * (A)
356 484 * *
357 * By default SDL will generate mouse events for touch events
485 * but if this hint is set, you'll get:
486 *
487 * (X)
488 * (Y) (A)
489 * (B)
490 *
491 * The variable can be set to the following values:
492 * "0" - Report the face buttons by position, as though they were on an Xbox controller.
493 * "1" - Report the face buttons by label instead of position
494 *
495 * The default value is "1". This hint may be set at any time.
358 496 */ */
359 #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS"
497 #define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS"
360 498
361 499 /** /**
362 * \brief A variable controlling whether mouse events should generate synthetic touch events
500 * \brief A variable controlling whether grabbing input grabs the keyboard
363 501 * *
364 502 * This variable can be set to the following values: * This variable can be set to the following values:
365 * "0" - Mouse events will not generate touch events (default for desktop platforms)
366 * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS)
367 */
368
369 #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS"
370
371 /**
372 * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false.
373 * \warning Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're
374 * seeing if "true" causes more problems than it solves in modern times.
503 * "0" - Grab will affect only the mouse
504 * "1" - Grab will affect mouse and keyboard
375 505 * *
506 * By default SDL will not grab the keyboard so system shortcuts still work.
376 507 */ */
377 #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
508 #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
378 509
379 510 /** /**
380 511 * \brief A variable controlling whether the idle timer is disabled on iOS. * \brief A variable controlling whether the idle timer is disabled on iOS.
 
... ... extern "C" {
394 525 #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
395 526
396 527 /** /**
397 * \brief A variable controlling which orientations are allowed on iOS/Android.
398 *
399 * In some circumstances it is necessary to be able to explicitly control
400 * which UI orientations are allowed.
528 * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
401 529 * *
402 * This variable is a space delimited list of the following values:
403 * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
530 * The variable can be set to the following values:
531 * "0" - SDL_TEXTEDITING events are sent, and it is the application's
532 * responsibility to render the text from these events and
533 * differentiate it somehow from committed text. (default)
534 * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent,
535 * and text that is being composed will be rendered in its own UI.
404 536 */ */
405 #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
406
407 /**
408 * \brief A variable controlling whether controllers used with the Apple TV
409 * generate UI events.
410 *
411 * When UI events are generated by controller input, the app will be
412 * backgrounded when the Apple TV remote's menu button is pressed, and when the
413 * pause or B buttons on gamepads are pressed.
414 *
415 * More information about properly making use of controllers for the Apple TV
416 * can be found here:
417 * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
418 *
419 * This variable can be set to the following values:
420 * "0" - Controller input does not generate UI events (the default).
421 * "1" - Controller input generates UI events.
422 */
423 #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
424
425 /**
426 * \brief A variable controlling whether the Apple TV remote's joystick axes
427 * will automatically match the rotation of the remote.
428 *
429 * This variable can be set to the following values:
430 * "0" - Remote orientation does not affect joystick axes (the default).
431 * "1" - Joystick axes are based on the orientation of the remote.
432 */
433 #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
537 #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
434 538
435 539 /** /**
436 540 * \brief A variable controlling whether the home indicator bar on iPhone X * \brief A variable controlling whether the home indicator bar on iPhone X
 
... ... extern "C" {
443 547 */ */
444 548 #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR"
445 549
446 /**
447 * \brief A variable controlling whether the Android / iOS built-in
448 * accelerometer should be listed as a joystick device.
449 *
450 * This variable can be set to the following values:
451 * "0" - The accelerometer is not listed as a joystick
452 * "1" - The accelerometer is available as a 3 axis joystick (the default).
453 */
454 #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
455
456 /**
457 * \brief A variable controlling whether the Android / tvOS remotes
458 * should be listed as joystick devices, instead of sending keyboard events.
459 *
460 * This variable can be set to the following values:
461 * "0" - Remotes send enter/escape/arrow key events
462 * "1" - Remotes are available as 2 axis, 2 button joysticks (the default).
463 */
464 #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
465
466 /**
467 * \brief A variable that lets you disable the detection and use of Xinput gamepad devices
468 *
469 * The variable can be set to the following values:
470 * "0" - Disable XInput detection (only uses direct input)
471 * "1" - Enable XInput detection (the default)
472 */
473 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
474
475 /**
476 * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices.
477 *
478 * This hint is for backwards compatibility only and will be removed in SDL 2.1
479 *
480 * The default value is "0". This hint must be set before SDL_Init()
481 */
482 #define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING"
483
484 /**
485 * \brief A variable that overrides the automatic controller type detection
486 *
487 * The variable should be comma separated entries, in the form: VID/PID=type
488 *
489 * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
490 *
491 * The type should be one of:
492 * Xbox360
493 * XboxOne
494 * PS3
495 * PS4
496 * PS5
497 * SwitchPro
498 *
499 * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
500 */
501 #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE"
502
503 /**
504 * \brief A variable that lets you manually hint extra gamecontroller db entries.
505 *
506 * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
507 *
508 * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
509 * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
510 */
511 #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
512
513 /**
514 * \brief A variable that lets you provide a file with extra gamecontroller db entries.
515 *
516 * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
517 *
518 * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
519 * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
520 */
521 #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
522
523 /**
524 * \brief A variable containing a list of devices to skip when scanning for game controllers.
525 *
526 * The format of the string is a comma separated list of USB VID/PID pairs
527 * in hexadecimal form, e.g.
528 *
529 * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
530 *
531 * The variable can also take the form of @file, in which case the named
532 * file will be loaded and interpreted as the value of the variable.
533 */
534 #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
535
536 /**
537 * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
538 *
539 * The format of the string is a comma separated list of USB VID/PID pairs
540 * in hexadecimal form, e.g.
541 *
542 * 0xAAAA/0xBBBB,0xCCCC/0xDDDD
543 *
544 * The variable can also take the form of @file, in which case the named
545 * file will be loaded and interpreted as the value of the variable.
546 */
547 #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
548
549 /**
550 * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout.
551 *
552 * For example, on Nintendo Switch controllers, normally you'd get:
553 *
554 * (Y)
555 * (X) (B)
556 * (A)
557 *
558 * but if this hint is set, you'll get:
559 *
560 * (X)
561 * (Y) (A)
562 * (B)
563 *
564 * The variable can be set to the following values:
565 * "0" - Report the face buttons by position, as though they were on an Xbox controller.
566 * "1" - Report the face buttons by label instead of position
567 *
568 * The default value is "1". This hint may be set at any time.
569 */
570 #define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS"
571
572 550 /** /**
573 551 * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
574 552 * *
 
... ... extern "C" {
594 572 #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI"
595 573
596 574 /** /**
597 * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
575 * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used.
598 576 * *
599 577 * This variable can be set to the following values: * This variable can be set to the following values:
600 578 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
 
... ... extern "C" {
602 580 * *
603 581 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
604 582 */ */
605 #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4"
583 #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE"
584
585 /**
586 * \brief A variable controlling whether Switch Joy-Cons should be treated the same as Switch Pro Controllers when using the HIDAPI driver.
587 *
588 * This variable can be set to the following values:
589 * "0" - basic Joy-Con support with no analog input (the default)
590 * "1" - Joy-Cons treated as half full Pro Controllers with analog inputs and sensors
591 *
592 * This does not combine Joy-Cons into a single controller. That's up to the user.
593 */
594 #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS"
595
596 /**
597 * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used.
598 *
599 * This variable can be set to the following values:
600 * "0" - HIDAPI driver is not used
601 * "1" - HIDAPI driver is used
602 *
603 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
604 */
605 #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA"
606 606
607 607 /** /**
608 * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used.
608 * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
609 609 * *
610 610 * This variable can be set to the following values: * This variable can be set to the following values:
611 611 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
 
... ... extern "C" {
613 613 * *
614 614 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
615 615 */ */
616 #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5"
616 #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4"
617 617
618 618 /** /**
619 619 * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver. * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver.
 
... ... extern "C" {
627 627 * *
628 628 * Once extended reports are enabled, they can not be disabled without * Once extended reports are enabled, they can not be disabled without
629 629 * power cycling the controller. * power cycling the controller.
630 *
631 * For compatibility with applications written for versions of SDL prior
632 * to the introduction of PS5 controller support, this value will also
633 * control the state of extended reports on PS5 controllers when the
634 * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set.
630 635 */ */
631 636 #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE"
632 637
633 638 /** /**
634 * \brief A variable controlling whether the HIDAPI driver for Steam Controllers should be used.
639 * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used.
635 640 * *
636 641 * This variable can be set to the following values: * This variable can be set to the following values:
637 642 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
 
... ... extern "C" {
639 644 * *
640 645 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
641 646 */ */
642 #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM"
647 #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5"
643 648
644 649 /** /**
645 * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used.
650 * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller.
651 *
652 * This variable can be set to the following values:
653 * "0" - player LEDs are not enabled
654 * "1" - player LEDs are enabled (the default)
655 */
656 #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED"
657
658 /**
659 * \brief A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver.
660 *
661 * This variable can be set to the following values:
662 * "0" - extended reports are not enabled (the default)
663 * "1" - extended reports
664 *
665 * Extended input reports allow rumble on Bluetooth PS5 controllers, but
666 * break DirectInput handling for applications that don't use SDL.
667 *
668 * Once extended reports are enabled, they can not be disabled without
669 * power cycling the controller.
670 *
671 * For compatibility with applications written for versions of SDL prior
672 * to the introduction of PS5 controller support, this value defaults to
673 * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE.
674 */
675 #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE"
676
677 /**
678 * \brief A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used.
646 679 * *
647 680 * This variable can be set to the following values: * This variable can be set to the following values:
648 681 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
 
... ... extern "C" {
650 683 * *
651 684 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
652 685 */ */
653 #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH"
686 #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA"
654 687
655 688 /** /**
656 * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used.
689 * \brief A variable controlling whether the HIDAPI driver for Steam Controllers should be used.
657 690 * *
658 691 * This variable can be set to the following values: * This variable can be set to the following values:
659 692 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
660 693 * "1" - HIDAPI driver is used * "1" - HIDAPI driver is used
661 694 * *
662 * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI
695 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
663 696 */ */
664 #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX"
665
666 /**
667 * \brief A variable controlling whether the HIDAPI driver for XBox controllers on Windows should pull correlated
668 * data from XInput.
669 *
670 * This variable can be set to the following values:
671 * "0" - HIDAPI Xbox driver will only use HIDAPI data
672 * "1" - HIDAPI Xbox driver will also pull data from XInput, providing better trigger axes, guide button
673 * presses, and rumble support
674 *
675 * The default is "1". This hint applies to any joysticks opened after setting the hint.
676 */
677 #define SDL_HINT_JOYSTICK_HIDAPI_CORRELATE_XINPUT "SDL_JOYSTICK_HIDAPI_CORRELATE_XINPUT"
697 #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM"
678 698
679 699 /** /**
680 * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used.
700 * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used.
681 701 * *
682 702 * This variable can be set to the following values: * This variable can be set to the following values:
683 703 * "0" - HIDAPI driver is not used * "0" - HIDAPI driver is not used
 
... ... extern "C" {
685 705 * *
686 706 * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
687 707 */ */
688 #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE"
708 #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH"
689 709
690 710 /** /**
691 * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
711 * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch controller is opened
692 712 * *
693 * The variable can be set to the following values:
694 * "0" - Do not scan for Steam Controllers
695 * "1" - Scan for Steam Controllers (the default)
713 * This variable can be set to the following values:
714 * "0" - home button LED is left off
715 * "1" - home button LED is turned on (the default)
716 */
717 #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED"
718
719 /**
720 * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used.
696 721 * *
697 * The default value is "1". This hint must be set before initializing the joystick subsystem.
722 * This variable can be set to the following values:
723 * "0" - HIDAPI driver is not used
724 * "1" - HIDAPI driver is used
725 *
726 * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI
698 727 */ */
699 #define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
728 #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX"
700 729
701 730 /** /**
702 731 * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices.
 
... ... extern "C" {
708 737 */ */
709 738 #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT"
710 739
740 /**
741 * \brief A variable controlling whether the RAWINPUT driver should pull correlated data from XInput.
742 *
743 * This variable can be set to the following values:
744 * "0" - RAWINPUT driver will only use data from raw input APIs
745 * "1" - RAWINPUT driver will also pull data from XInput, providing
746 * better trigger axes, guide button presses, and rumble support
747 * for Xbox controllers
748 *
749 * The default is "1". This hint applies to any joysticks opened after setting the hint.
750 */
751 #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT"
752
711 753 /** /**
712 754 * \brief A variable controlling whether a separate thread should be used * \brief A variable controlling whether a separate thread should be used
713 755 * for handling joystick detection and raw input messages on Windows * for handling joystick detection and raw input messages on Windows
 
... ... extern "C" {
719 761 */ */
720 762 #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD"
721 763
764 /**
765 * \brief Determines whether SDL enforces that DRM master is required in order
766 * to initialize the KMSDRM video backend.
767 *
768 * The DRM subsystem has a concept of a "DRM master" which is a DRM client that
769 * has the ability to set planes, set cursor, etc. When SDL is DRM master, it
770 * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL
771 * is still able to process input and query attributes of attached displays,
772 * but it cannot change display state or draw to the screen directly.
773 *
774 * In some cases, it can be useful to have the KMSDRM backend even if it cannot
775 * be used for rendering. An app may want to use SDL for input processing while
776 * using another rendering API (such as an MMAL overlay on Raspberry Pi) or
777 * using its own code to render to DRM overlays that SDL doesn't support.
778 *
779 * This hint must be set before initializing the video subsystem.
780 *
781 * This variable can be set to the following values:
782 * "0" - SDL will allow usage of the KMSDRM backend without DRM master
783 * "1" - SDL Will require DRM master to use the KMSDRM backend (default)
784 */
785 #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER"
786
722 787 /** /**
723 788 * \brief A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values. * \brief A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values.
724 789 * *
 
... ... extern "C" {
729 794 #define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES" #define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES"
730 795
731 796 /** /**
732 * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
733 * This is a debugging aid for developers and not expected to be used by end users. The default is "1"
797 * \brief When set don't force the SDL app to become a foreground process
798 *
799 * This hint only applies to Mac OS X.
800 *
801 */
802 #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP"
803
804 /**
805 * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac
734 806 * *
735 * This variable can be set to the following values:
736 * "0" - don't allow topmost
737 * "1" - allow topmost
807 * If present, holding ctrl while left clicking will generate a right click
808 * event when on Mac.
738 809 */ */
739 #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
810 #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK"
740 811
741 812 /** /**
742 * \brief A variable that controls the timer resolution, in milliseconds.
743 *
744 * The higher resolution the timer, the more frequently the CPU services
745 * timer interrupts, and the more precise delays are, but this takes up
746 * power and CPU time. This hint is only used on Windows 7 and earlier.
747 *
748 * See this blog post for more information:
749 * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
750 *
751 * If this variable is set to "0", the system timer resolution is not set.
752 *
753 * The default value is "1". This hint may be set at any time.
813 * \brief A variable setting the double click radius, in pixels.
754 814 */ */
755 #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
756
815 #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS"
757 816
758 817 /** /**
759 * \brief A variable describing the content orientation on QtWayland-based platforms.
760 *
761 * On QtWayland platforms, windows are rotated client-side to allow for custom
762 * transitions. In order to correctly position overlays (e.g. volume bar) and
763 * gestures (e.g. events view, close/minimize gestures), the system needs to
764 * know in which orientation the application is currently drawing its contents.
765 *
766 * This does not cause the window to be rotated or resized, the application
767 * needs to take care of drawing the content in the right orientation (the
768 * framebuffer is always in portrait mode).
769 *
770 * This variable can be one of the following values:
771 * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape"
818 * \brief A variable setting the double click time, in milliseconds.
772 819 */ */
773 #define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION"
820 #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME"
774 821
775 822 /** /**
776 * \brief Flags to set on QtWayland windows to integrate with the native window manager.
823 * \brief Allow mouse click events when clicking to focus an SDL window
777 824 * *
778 * On QtWayland platforms, this hint controls the flags to set on the windows.
779 * For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures.
825 * This variable can be set to the following values:
826 * "0" - Ignore mouse clicks that activate a window
827 * "1" - Generate events for mouse clicks that activate a window
780 828 * *
781 * This variable is a space-separated list of the following values (empty = no flags):
782 * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager"
829 * By default SDL will ignore mouse clicks that activate a window
783 830 */ */
784 #define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS"
831 #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH"
785 832
786 833 /** /**
787 * \brief A string specifying SDL's threads stack size in bytes or "0" for the backend's default size
788 *
789 * Use this hint in case you need to set SDL's threads stack size to other than the default.
790 * This is specially useful if you build SDL against a non glibc libc library (such as musl) which
791 * provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses).
792 * Support for this hint is currently available only in the pthread, Windows, and PSP backend.
793 *
794 * Instead of this hint, in 2.0.9 and later, you can use
795 * SDL_CreateThreadWithStackSize(). This hint only works with the classic
796 * SDL_CreateThread().
797 */
798 #define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE"
834 * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
835 */
836 #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE"
799 837
800 838 /** /**
801 * \brief A string specifying additional information to use with SDL_SetThreadPriority.
802 *
803 * By default SDL_SetThreadPriority will make appropriate system changes in order to
804 * apply a thread priority. For example on systems using pthreads the scheduler policy
805 * is changed automatically to a policy that works well with a given priority.
806 * Code which has specific requirements can override SDL's default behavior with this hint.
807 *
808 * pthread hint values are "current", "other", "fifo" and "rr".
809 * Currently no other platform hint values are defined but may be in the future.
810 *
811 * \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro
812 * configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME
813 * after calling SDL_SetThreadPriority().
814 */
815 #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY"
839 * \brief A variable controlling whether relative mouse mode is implemented using mouse warping
840 *
841 * This variable can be set to the following values:
842 * "0" - Relative mouse mode uses raw input
843 * "1" - Relative mouse mode uses mouse warping
844 *
845 * By default SDL will use raw input for relative mouse mode
846 */
847 #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP"
816 848
817 849 /** /**
818 * \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime.
850 * \brief A variable controlling whether relative mouse motion is affected by renderer scaling
819 851 * *
820 * On some platforms, like Linux, a realtime priority thread may be subject to restrictions
821 * that require special handling by the application. This hint exists to let SDL know that
822 * the app is prepared to handle said restrictions.
823 *
824 * On Linux, SDL will apply the following configuration to any thread that becomes realtime:
825 * * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy,
826 * * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit.
827 * * Exceeding this limit will result in the kernel sending SIGKILL to the app,
828 * * Refer to the man pages for more information.
829 *
830 852 * This variable can be set to the following values: * This variable can be set to the following values:
831 * "0" - default platform specific behaviour
832 * "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy
853 * "0" - Relative motion is unaffected by DPI or renderer's logical size
854 * "1" - Relative motion is scaled according to DPI scaling and logical size
855 *
856 * By default relative mouse deltas are affected by DPI and renderer scaling
833 857 */ */
834 #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL"
858 #define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING"
835 859
836 860 /** /**
837 * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS)
861 * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
838 862 */ */
839 #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
863 #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE"
840 864
841 865 /** /**
842 * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac
866 * \brief A variable controlling whether mouse events should generate synthetic touch events
843 867 * *
844 * If present, holding ctrl while left clicking will generate a right click
845 * event when on Mac.
868 * This variable can be set to the following values:
869 * "0" - Mouse events will not generate touch events (default for desktop platforms)
870 * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS)
846 871 */ */
847 #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK"
848
849 /**
850 * \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
851 *
852 * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It
853 * can use two different sets of binaries, those compiled by the user from source
854 * or those provided by the Chrome browser. In the later case, these binaries require
855 * that SDL loads a DLL providing the shader compiler.
856 *
857 * This variable can be set to the following values:
858 * "d3dcompiler_46.dll" - default, best for Vista or later.
859 * "d3dcompiler_43.dll" - for XP support.
860 * "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries.
861 *
862 */
863 #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER"
872 #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS"
864 873
865 874 /** /**
866 * \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
867 *
868 * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
869 * SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly
870 * created SDL_Window:
871 *
872 * 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is
873 * needed for example when sharing an OpenGL context across multiple windows.
874 *
875 * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for
876 * OpenGL rendering.
877 *
878 * This variable can be set to the following values:
879 * The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should
880 * share a pixel format with.
881 */
882 #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT"
875 * \brief Tell SDL not to catch the SIGINT or SIGTERM signals.
876 *
877 * This hint only applies to Unix-like platforms, and should set before
878 * any calls to SDL_Init()
879 *
880 * The variable can be set to the following values:
881 * "0" - SDL will install a SIGINT and SIGTERM handler, and when it
882 * catches a signal, convert it into an SDL_QUIT event.
883 * "1" - SDL will not install a signal handler at all.
884 */
885 #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS"
883 886
884 887 /** /**
885 * \brief A URL to a WinRT app's privacy policy
888 * \brief A variable controlling what driver to use for OpenGL ES contexts.
886 889 * *
887 * All network-enabled WinRT apps must make a privacy policy available to its
888 * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be
889 * be available in the Windows Settings charm, as accessed from within the app.
890 * SDL provides code to add a URL-based link there, which can point to the app's
891 * privacy policy.
890 * On some platforms, currently Windows and X11, OpenGL drivers may support
891 * creating contexts with an OpenGL ES profile. By default SDL uses these
892 * profiles, when available, otherwise it attempts to load an OpenGL ES
893 * library, e.g. that provided by the ANGLE project. This variable controls
894 * whether SDL follows this default behaviour or will always load an
895 * OpenGL ES library.
892 896 * *
893 * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL
894 * before calling any SDL_Init() functions. The contents of the hint should
895 * be a valid URL. For example, "http://www.example.com".
897 * Circumstances where this is useful include
898 * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE,
899 * or emulator, e.g. those from ARM, Imagination or Qualcomm.
900 * - Resolving OpenGL ES function addresses at link time by linking with
901 * the OpenGL ES library instead of querying them at run time with
902 * SDL_GL_GetProcAddress().
896 903 * *
897 * The default value is "", which will prevent SDL from adding a privacy policy
898 * link to the Settings charm. This hint should only be set during app init.
904 * Caution: for an application to work with the default behaviour across
905 * different OpenGL drivers it must query the OpenGL ES function
906 * addresses at run time using SDL_GL_GetProcAddress().
899 907 * *
900 * The label text of an app's "Privacy Policy" link may be customized via another
901 * hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
908 * This variable is ignored on most platforms because OpenGL ES is native
909 * or not supported.
910 *
911 * This variable can be set to the following values:
912 * "0" - Use ES profile of OpenGL, if available. (Default when not set.)
913 * "1" - Load OpenGL ES library using the default library names.
902 914 * *
903 * Please note that on Windows Phone, Microsoft does not provide standard UI
904 * for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL
905 * will not get used on that platform. Network-enabled phone apps should display
906 * their privacy policy through some other, in-app means.
907 915 */ */
908 #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL"
916 #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER"
909 917
910 /** \brief Label text for a WinRT app's privacy policy link
911 *
912 * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT,
913 * Microsoft mandates that this policy be available via the Windows Settings charm.
914 * SDL provides code to add a link there, with its label text being set via the
915 * optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
918 /**
919 * \brief A variable controlling which orientations are allowed on iOS/Android.
916 920 * *
917 * Please note that a privacy policy's contents are not set via this hint. A separate
918 * hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the
919 * policy.
921 * In some circumstances it is necessary to be able to explicitly control
922 * which UI orientations are allowed.
920 923 * *
921 * The contents of this hint should be encoded as a UTF8 string.
924 * This variable is a space delimited list of the following values:
925 * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
926 */
927 #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
928
929 /**
930 * \brief Override for SDL_GetPreferredLocales()
922 931 * *
923 * The default value is "Privacy Policy". This hint should only be set during app
924 * initialization, preferably before any calls to SDL_Init().
932 * If set, this will be favored over anything the OS might report for the
933 * user's preferred locales. Changing this hint at runtime will not generate
934 * a SDL_LOCALECHANGED event (but if you can change the hint, you can push
935 * your own event, if you want).
925 936 * *
926 * For additional information on linking to a privacy policy, see the documentation for
927 * SDL_HINT_WINRT_PRIVACY_POLICY_URL.
937 * The format of this hint is a comma-separated list of language and locale,
938 * combined with an underscore, as is a common format: "en_GB". Locale is
939 * optional: "en". So you might have a list like this: "en_GB,jp,es_PT"
928 940 */ */
929 #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
941 #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES"
930 942
931 /** \brief Allows back-button-press events on Windows Phone to be marked as handled
943 /**
944 * \brief A variable describing the content orientation on QtWayland-based platforms.
932 945 * *
933 * Windows Phone devices typically feature a Back button. When pressed,
934 * the OS will emit back-button-press events, which apps are expected to
935 * handle in an appropriate manner. If apps do not explicitly mark these
936 * events as 'Handled', then the OS will invoke its default behavior for
937 * unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to
938 * terminate the app (and attempt to switch to the previous app, or to the
939 * device's home screen).
946 * On QtWayland platforms, windows are rotated client-side to allow for custom
947 * transitions. In order to correctly position overlays (e.g. volume bar) and
948 * gestures (e.g. events view, close/minimize gestures), the system needs to
949 * know in which orientation the application is currently drawing its contents.
940 950 * *
941 * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL
942 * to mark back-button-press events as Handled, if and when one is sent to
943 * the app.
951 * This does not cause the window to be rotated or resized, the application
952 * needs to take care of drawing the content in the right orientation (the
953 * framebuffer is always in portrait mode).
944 954 * *
945 * Internally, Windows Phone sends back button events as parameters to
946 * special back-button-press callback functions. Apps that need to respond
947 * to back-button-press events are expected to register one or more
948 * callback functions for such, shortly after being launched (during the
949 * app's initialization phase). After the back button is pressed, the OS
950 * will invoke these callbacks. If the app's callback(s) do not explicitly
951 * mark the event as handled by the time they return, or if the app never
952 * registers one of these callback, the OS will consider the event
953 * un-handled, and it will apply its default back button behavior (terminate
954 * the app).
955 * This variable can be one of the following values:
956 * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape"
957 */
958 #define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION"
959
960 /**
961 * \brief Flags to set on QtWayland windows to integrate with the native window manager.
955 962 * *
956 * SDL registers its own back-button-press callback with the Windows Phone
957 * OS. This callback will emit a pair of SDL key-press events (SDL_KEYDOWN
958 * and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which
959 * it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON.
960 * If the hint's value is set to "1", the back button event's Handled
961 * property will get set to 'true'. If the hint's value is set to something
962 * else, or if it is unset, SDL will leave the event's Handled property
963 * alone. (By default, the OS sets this property to 'false', to note.)
963 * On QtWayland platforms, this hint controls the flags to set on the windows.
964 * For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures.
964 965 * *
965 * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a
966 * back button is pressed, or can set it in direct-response to a back button
967 * being pressed.
966 * This variable is a space-separated list of the following values (empty = no flags):
967 * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager"
968 */
969 #define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS"
970
971 /**
972 * \brief A variable controlling whether the 2D render API is compatible or efficient.
968 973 * *
969 * In order to get notified when a back button is pressed, SDL apps should
970 * register a callback function with SDL_AddEventWatch(), and have it listen
971 * for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK.
972 * (Alternatively, SDL_KEYUP events can be listened-for. Listening for
973 * either event type is suitable.) Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON
974 * set by such a callback, will be applied to the OS' current
975 * back-button-press event.
974 * This variable can be set to the following values:
976 975 * *
977 * More details on back button behavior in Windows Phone apps can be found
978 * at the following page, on Microsoft's developer site:
979 * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx
976 * "0" - Don't use batching to make rendering more efficient.
977 * "1" - Use batching, but might cause problems if app makes its own direct OpenGL calls.
978 *
979 * Up to SDL 2.0.9, the render API would draw immediately when requested. Now
980 * it batches up draw requests and sends them all to the GPU only when forced
981 * to (during SDL_RenderPresent, when changing render targets, by updating a
982 * texture that the batch needs, etc). This is significantly more efficient,
983 * but it can cause problems for apps that expect to render on top of the
984 * render API's output. As such, SDL will disable batching if a specific
985 * render backend is requested (since this might indicate that the app is
986 * planning to use the underlying graphics API directly). This hint can
987 * be used to explicitly request batching in this instance. It is a contract
988 * that you will either never use the underlying graphics API directly, or
989 * if you do, you will call SDL_RenderFlush() before you do so any current
990 * batch goes to the GPU before your work begins. Not following this contract
991 * will result in undefined behavior.
980 992 */ */
981 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
993 #define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING"
982 994
983 995 /** /**
984 * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X.
996 * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer.
985 997 * *
986 * This hint only applies to Mac OS X.
998 * This variable does not have any effect on the Direct3D 9 based renderer.
987 999 * *
988 * The variable can be set to the following values:
989 * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and
990 * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen"
991 * button on their titlebars).
992 * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and
993 * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen"
994 * button on their titlebars).
1000 * This variable can be set to the following values:
1001 * "0" - Disable Debug Layer use
1002 * "1" - Enable Debug Layer use
995 1003 * *
996 * The default value is "1". Spaces are disabled regardless of this hint if
997 * the OS isn't at least Mac OS X Lion (10.7). This hint must be set before
998 * any windows are created.
1004 * By default, SDL does not use Direct3D Debug Layer.
999 1005 */ */
1000 #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES"
1001
1002 /**
1003 * \brief When set don't force the SDL app to become a foreground process
1004 *
1005 * This hint only applies to Mac OS X.
1006 *
1007 */
1008 #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP"
1006 #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG"
1009 1007
1010 1008 /** /**
1011 * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc.
1012 *
1013 * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
1009 * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations.
1014 1010 * *
1015 * If both hints were set then SDL_RWFromFile() will look into expansion files
1016 * after a given relative path was not found in the internal storage and assets.
1011 * This variable can be set to the following values:
1012 * "0" - Thread-safety is not enabled (faster)
1013 * "1" - Thread-safety is enabled
1017 1014 * *
1018 * By default this hint is not set and the APK expansion files are not searched.
1015 * By default the Direct3D device is created with thread-safety disabled.
1019 1016 */ */
1020 #define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
1021
1017 #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
1018
1022 1019 /** /**
1023 * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
1020 * \brief A variable specifying which render driver to use.
1024 1021 * *
1025 * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
1022 * If the application doesn't pick a specific renderer to use, this variable
1023 * specifies the name of the preferred renderer. If the preferred renderer
1024 * can't be initialized, the normal default renderer is used.
1026 1025 * *
1027 * If both hints were set then SDL_RWFromFile() will look into expansion files
1028 * after a given relative path was not found in the internal storage and assets.
1026 * This variable is case insensitive and can be set to the following values:
1027 * "direct3d"
1028 * "opengl"
1029 * "opengles2"
1030 * "opengles"
1031 * "metal"
1032 * "software"
1029 1033 * *
1030 * By default this hint is not set and the APK expansion files are not searched.
1034 * The default varies by platform, but it's the first one in the list that
1035 * is available on the current platform.
1031 1036 */ */
1032 #define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
1037 #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER"
1033 1038
1034 1039 /** /**
1035 * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
1040 * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize.
1036 1041 * *
1037 * The variable can be set to the following values:
1038 * "0" - SDL_TEXTEDITING events are sent, and it is the application's
1039 * responsibility to render the text from these events and
1040 * differentiate it somehow from committed text. (default)
1041 * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent,
1042 * and text that is being composed will be rendered in its own UI.
1042 * This variable can be set to the following values:
1043 * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen
1044 * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
1045 *
1046 * By default letterbox is used
1043 1047 */ */
1044 #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
1048 #define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE"
1045 1049
1046 1050 /** /**
1047 * \brief A variable to control whether we trap the Android back button to handle it manually.
1048 * This is necessary for the right mouse button to work on some Android devices, or
1049 * to be able to trap the back button for use in your code reliably. If set to true,
1050 * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of
1051 * SDL_SCANCODE_AC_BACK.
1051 * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available.
1052 1052 * *
1053 * The variable can be set to the following values:
1054 * "0" - Back button will be handled as usual for system. (default)
1055 * "1" - Back button will be trapped, allowing you to handle the key press
1056 * manually. (This will also let right mouse click work on systems
1057 * where the right mouse button functions as back.)
1053 * This variable can be set to the following values:
1054 * "0" - Disable shaders
1055 * "1" - Enable shaders
1058 1056 * *
1059 * The value of this hint is used at runtime, so it can be changed at any time.
1057 * By default shaders are used if OpenGL supports them.
1060 1058 */ */
1061 #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
1059 #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS"
1062 1060
1063 1061 /** /**
1064 * \brief A variable to control whether the event loop will block itself when the app is paused.
1062 * \brief A variable controlling the scaling quality
1065 1063 * *
1066 * The variable can be set to the following values:
1067 * "0" - Non blocking.
1068 * "1" - Blocking. (default)
1064 * This variable can be set to the following values:
1065 * "0" or "nearest" - Nearest pixel sampling
1066 * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D)
1067 * "2" or "best" - Currently this is the same as "linear"
1069 1068 * *
1070 * The value should be set before SDL is initialized.
1069 * By default nearest pixel sampling is used
1071 1070 */ */
1072 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
1071 #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY"
1073 1072
1074 1073 /** /**
1075 * \brief A variable to control whether SDL will pause audio in background
1076 * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
1074 * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
1077 1075 * *
1078 * The variable can be set to the following values:
1079 * "0" - Non paused.
1080 * "1" - Paused. (default)
1076 * This variable can be set to the following values:
1077 * "0" - Disable vsync
1078 * "1" - Enable vsync
1081 1079 * *
1082 * The value should be set before SDL is initialized.
1080 * By default SDL does not sync screen surface updates with vertical refresh.
1083 1081 */ */
1084 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
1082 #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC"
1085 1083
1086 1084 /** /**
1087 1085 * \brief A variable to control whether the return key on the soft keyboard * \brief A variable to control whether the return key on the soft keyboard
 
... ... extern "C" {
1096 1094 #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME"
1097 1095
1098 1096 /** /**
1099 * \brief override the binding element for keyboard inputs for Emscripten builds
1100 *
1101 * This hint only applies to the emscripten platform
1097 * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI
1102 1098 * *
1103 * The variable can be one of
1104 * "#window" - The javascript window object (this is the default)
1105 * "#document" - The javascript document object
1106 * "#screen" - the javascript window.screen object
1107 * "#canvas" - the WebGL canvas element
1108 * any other string without a leading # sign applies to the element on the page with that ID.
1099 * Also known as Z-order. The variable can take a negative or positive value.
1100 * The default is 10000.
1109 1101 */ */
1110 #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
1102 #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER"
1111 1103
1112 1104 /** /**
1113 * \brief Disable giving back control to the browser automatically
1114 * when running with asyncify
1115 *
1116 * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations
1117 * such as refreshing the screen or polling events.
1118 *
1119 * This hint only applies to the emscripten platform
1105 * \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime.
1120 1106 * *
1121 * The variable can be set to the following values:
1122 * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes)
1123 * "1" - Enable emscripten_sleep calls (the default)
1107 * On some platforms, like Linux, a realtime priority thread may be subject to restrictions
1108 * that require special handling by the application. This hint exists to let SDL know that
1109 * the app is prepared to handle said restrictions.
1110 *
1111 * On Linux, SDL will apply the following configuration to any thread that becomes realtime:
1112 * * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy,
1113 * * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit.
1114 * * Exceeding this limit will result in the kernel sending SIGKILL to the app,
1115 * * Refer to the man pages for more information.
1116 *
1117 * This variable can be set to the following values:
1118 * "0" - default platform specific behaviour
1119 * "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy
1124 1120 */ */
1125 #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY"
1121 #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL"
1126 1122
1127 1123 /** /**
1128 * \brief Tell SDL not to catch the SIGINT or SIGTERM signals.
1129 *
1130 * This hint only applies to Unix-like platforms, and should set before
1131 * any calls to SDL_Init()
1132 *
1133 * The variable can be set to the following values:
1134 * "0" - SDL will install a SIGINT and SIGTERM handler, and when it
1135 * catches a signal, convert it into an SDL_QUIT event.
1136 * "1" - SDL will not install a signal handler at all.
1137 */
1138 #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS"
1124 * \brief A string specifying additional information to use with SDL_SetThreadPriority.
1125 *
1126 * By default SDL_SetThreadPriority will make appropriate system changes in order to
1127 * apply a thread priority. For example on systems using pthreads the scheduler policy
1128 * is changed automatically to a policy that works well with a given priority.
1129 * Code which has specific requirements can override SDL's default behavior with this hint.
1130 *
1131 * pthread hint values are "current", "other", "fifo" and "rr".
1132 * Currently no other platform hint values are defined but may be in the future.
1133 *
1134 * \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro
1135 * configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME
1136 * after calling SDL_SetThreadPriority().
1137 */
1138 #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY"
1139 1139
1140 1140 /** /**
1141 * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows.
1142 *
1143 * The variable can be set to the following values:
1144 * "0" - SDL will generate a window-close event when it sees Alt+F4.
1145 * "1" - SDL will only do normal key handling for Alt+F4.
1146 */
1147 #define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4"
1141 * \brief A string specifying SDL's threads stack size in bytes or "0" for the backend's default size
1142 *
1143 * Use this hint in case you need to set SDL's threads stack size to other than the default.
1144 * This is specially useful if you build SDL against a non glibc libc library (such as musl) which
1145 * provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses).
1146 * Support for this hint is currently available only in the pthread, Windows, and PSP backend.
1147 *
1148 * Instead of this hint, in 2.0.9 and later, you can use
1149 * SDL_CreateThreadWithStackSize(). This hint only works with the classic
1150 * SDL_CreateThread().
1151 */
1152 #define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE"
1148 1153
1149 1154 /** /**
1150 * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs.
1155 * \brief A variable that controls the timer resolution, in milliseconds.
1151 1156 * *
1152 * The bitmap header version 4 is required for proper alpha channel support and
1153 * SDL will use it when required. Should this not be desired, this hint can
1154 * force the use of the 40 byte header version which is supported everywhere.
1157 * The higher resolution the timer, the more frequently the CPU services
1158 * timer interrupts, and the more precise delays are, but this takes up
1159 * power and CPU time. This hint is only used on Windows.
1155 1160 * *
1156 * The variable can be set to the following values:
1157 * "0" - Surfaces with a colorkey or an alpha channel are saved to a
1158 * 32-bit BMP file with an alpha mask. SDL will use the bitmap
1159 * header version 4 and set the alpha mask accordingly.
1160 * "1" - Surfaces with a colorkey or an alpha channel are saved to a
1161 * 32-bit BMP file without an alpha mask. The alpha channel data
1162 * will be in the file, but applications are going to ignore it.
1161 * See this blog post for more information:
1162 * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
1163 1163 * *
1164 * The default value is "0".
1164 * If this variable is set to "0", the system timer resolution is not set.
1165 *
1166 * The default value is "1". This hint may be set at any time.
1165 1167 */ */
1166 #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
1168 #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
1167 1169
1168 1170 /** /**
1169 * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception.
1170 * The 0x406D1388 Exception is a trick used to inform Visual Studio of a
1171 * thread's name, but it tends to cause problems with other debuggers,
1172 * and the .NET runtime. Note that SDL 2.0.6 and later will still use
1173 * the (safer) SetThreadDescription API, introduced in the Windows 10
1174 * Creators Update, if available.
1171 * \brief A variable controlling whether touch events should generate synthetic mouse events
1172 *
1173 * This variable can be set to the following values:
1174 * "0" - Touch events will not generate mouse events
1175 * "1" - Touch events will generate mouse events
1176 *
1177 * By default SDL will generate mouse events for touch events
1178 */
1179 #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS"
1180
1181 /**
1182 * \brief A variable controlling whether the Android / tvOS remotes
1183 * should be listed as joystick devices, instead of sending keyboard events.
1175 1184 * *
1176 * The variable can be set to the following values:
1177 * "0" - SDL will raise the 0x406D1388 Exception to name threads.
1178 * This is the default behavior of SDL <= 2.0.4.
1179 * "1" - SDL will not raise this exception, and threads will be unnamed. (default)
1180 * This is necessary with .NET languages or debuggers that aren't Visual Studio.
1185 * This variable can be set to the following values:
1186 * "0" - Remotes send enter/escape/arrow key events
1187 * "1" - Remotes are available as 2 axis, 2 button joysticks (the default).
1181 1188 */ */
1182 #define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING"
1189 #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
1183 1190
1184 1191 /** /**
1185 * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI
1192 * \brief A variable controlling whether the screensaver is enabled.
1186 1193 * *
1187 * Also known as Z-order. The variable can take a negative or positive value.
1188 * The default is 10000.
1194 * This variable can be set to the following values:
1195 * "0" - Disable screensaver
1196 * "1" - Enable screensaver
1197 *
1198 * By default SDL will disable the screensaver.
1189 1199 */ */
1190 #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER"
1200 #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER"
1191 1201
1192 1202 /** /**
1193 1203 * \brief Tell the video driver that we only want a double buffer. * \brief Tell the video driver that we only want a double buffer.
 
... ... extern "C" {
1202 1212 * *
1203 1213 * Since it's driver-specific, it's only supported where possible and * Since it's driver-specific, it's only supported where possible and
1204 1214 * implemented. Currently supported the following drivers: * implemented. Currently supported the following drivers:
1215 *
1205 1216 * - KMSDRM (kmsdrm) * - KMSDRM (kmsdrm)
1206 1217 * - Raspberry Pi (raspberrypi) * - Raspberry Pi (raspberrypi)
1207 1218 */ */
1208 1219 #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER"
1209 1220
1210 1221 /** /**
1211 * \brief A variable controlling what driver to use for OpenGL ES contexts.
1212 *
1213 * On some platforms, currently Windows and X11, OpenGL drivers may support
1214 * creating contexts with an OpenGL ES profile. By default SDL uses these
1215 * profiles, when available, otherwise it attempts to load an OpenGL ES
1216 * library, e.g. that provided by the ANGLE project. This variable controls
1217 * whether SDL follows this default behaviour or will always load an
1218 * OpenGL ES library.
1222 * \brief A variable controlling whether the graphics context is externally managed.
1219 1223 * *
1220 * Circumstances where this is useful include
1221 * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE,
1222 * or emulator, e.g. those from ARM, Imagination or Qualcomm.
1223 * - Resolving OpenGL ES function addresses at link time by linking with
1224 * the OpenGL ES library instead of querying them at run time with
1225 * SDL_GL_GetProcAddress().
1224 * This variable can be set to the following values:
1225 * "0" - SDL will manage graphics contexts that are attached to windows.
1226 * "1" - Disable graphics context management on windows.
1226 1227 * *
1227 * Caution: for an application to work with the default behaviour across
1228 * different OpenGL drivers it must query the OpenGL ES function
1229 * addresses at run time using SDL_GL_GetProcAddress().
1228 * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the
1229 * context will be automatically saved and restored when pausing the application. Additionally, some
1230 * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this
1231 * behavior, which is desireable when the application manages the graphics context, such as
1232 * an externally managed OpenGL context or attaching a Vulkan surface to the window.
1233 */
1234 #define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT"
1235
1236 /**
1237 * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS)
1238 */
1239 #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
1240
1241 /**
1242 * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X.
1230 1243 * *
1231 * This variable is ignored on most platforms because OpenGL ES is native
1232 * or not supported.
1244 * This hint only applies to Mac OS X.
1233 1245 * *
1234 * This variable can be set to the following values:
1235 * "0" - Use ES profile of OpenGL, if available. (Default when not set.)
1236 * "1" - Load OpenGL ES library using the default library names.
1246 * The variable can be set to the following values:
1247 * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and
1248 * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen"
1249 * button on their titlebars).
1250 * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and
1251 * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen"
1252 * button on their titlebars).
1237 1253 * *
1254 * The default value is "1". Spaces are disabled regardless of this hint if
1255 * the OS isn't at least Mac OS X Lion (10.7). This hint must be set before
1256 * any windows are created.
1238 1257 */ */
1239 #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER"
1258 #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES"
1240 1259
1241 1260 /** /**
1242 * \brief A variable controlling speed/quality tradeoff of audio resampling.
1243 *
1244 * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
1245 * to handle audio resampling. There are different resampling modes available
1246 * that produce different levels of quality, using more CPU.
1261 * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false.
1262 * \warning Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're
1263 * seeing if "true" causes more problems than it solves in modern times.
1247 1264 * *
1248 * If this hint isn't specified to a valid setting, or libsamplerate isn't
1249 * available, SDL will use the default, internal resampling algorithm.
1265 */
1266 #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
1267
1268 /**
1269 * \brief A variable controlling whether the libdecor Wayland backend is allowed to be used.
1250 1270 * *
1251 * Note that this is currently only applicable to resampling audio that is
1252 * being written to a device for playback or audio being read from a device
1253 * for capture. SDL_AudioCVT always uses the default resampler (although this
1254 * might change for SDL 2.1).
1271 * This variable can be set to the following values:
1272 * "0" - libdecor use is disabled.
1273 * "1" - libdecor use is enabled (default).
1255 1274 * *
1256 * This hint is currently only checked at audio subsystem initialization.
1275 * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable.
1276 */
1277 #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR"
1278
1279 /**
1280 * \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
1281 *
1282 * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
1283 * SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly
1284 * created SDL_Window:
1285 *
1286 * 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is
1287 * needed for example when sharing an OpenGL context across multiple windows.
1288 *
1289 * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for
1290 * OpenGL rendering.
1291 *
1292 * This variable can be set to the following values:
1293 * The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should
1294 * share a pixel format with.
1295 */
1296 #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT"
1297
1298 /**
1299 * \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
1300 *
1301 * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It
1302 * can use two different sets of binaries, those compiled by the user from source
1303 * or those provided by the Chrome browser. In the later case, these binaries require
1304 * that SDL loads a DLL providing the shader compiler.
1305 *
1306 * This variable can be set to the following values:
1307 * "d3dcompiler_46.dll" - default, best for Vista or later.
1308 * "d3dcompiler_43.dll" - for XP support.
1309 * "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries.
1310 *
1311 */
1312 #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER"
1313
1314 /**
1315 * \brief A variable controlling whether X11 should use GLX or EGL by default
1257 1316 * *
1258 * This variable can be set to the following values:
1317 * This variable can be set to the following values:
1318 * "0" - Use GLX
1319 * "1" - Use EGL
1259 1320 * *
1260 * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast)
1261 * "1" or "fast" - Use fast, slightly higher quality resampling, if available
1262 * "2" or "medium" - Use medium quality resampling, if available
1263 * "3" or "best" - Use high quality resampling, if available
1321 * By default SDL will use GLX when both are present.
1264 1322 */ */
1265 #define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE"
1323 #define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL"
1266 1324
1267 1325 /** /**
1268 * \brief A variable controlling the audio category on iOS and Mac OS X
1326 * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
1327 *
1328 * This variable can be set to the following values:
1329 * "0" - Disable _NET_WM_BYPASS_COMPOSITOR
1330 * "1" - Enable _NET_WM_BYPASS_COMPOSITOR
1331 *
1332 * By default SDL will use _NET_WM_BYPASS_COMPOSITOR
1333 *
1334 */
1335 #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
1336
1337 /**
1338 * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
1269 1339 * *
1270 1340 * This variable can be set to the following values: * This variable can be set to the following values:
1341 * "0" - Disable _NET_WM_PING
1342 * "1" - Enable _NET_WM_PING
1271 1343 * *
1272 * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
1273 * "playback" - Use the AVAudioSessionCategoryPlayback category
1344 * By default SDL will use _NET_WM_PING, but for applications that know they
1345 * will not always be able to respond to ping requests in a timely manner they can
1346 * turn it off to avoid the window manager thinking the app is hung.
1347 * The hint is checked in CreateWindow.
1348 */
1349 #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING"
1350
1351 /**
1352 * \brief A variable forcing the visual ID chosen for new X11 windows
1274 1353 * *
1275 * For more information, see Apple's documentation:
1276 * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
1277 1354 */ */
1278 #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY"
1355 #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID"
1279 1356
1280 1357 /** /**
1281 * \brief A variable controlling whether the 2D render API is compatible or efficient.
1358 * \brief A variable controlling whether the X11 Xinerama extension should be used.
1282 1359 * *
1283 1360 * This variable can be set to the following values: * This variable can be set to the following values:
1361 * "0" - Disable Xinerama
1362 * "1" - Enable Xinerama
1284 1363 * *
1285 * "0" - Don't use batching to make rendering more efficient.
1286 * "1" - Use batching, but might cause problems if app makes its own direct OpenGL calls.
1287 *
1288 * Up to SDL 2.0.9, the render API would draw immediately when requested. Now
1289 * it batches up draw requests and sends them all to the GPU only when forced
1290 * to (during SDL_RenderPresent, when changing render targets, by updating a
1291 * texture that the batch needs, etc). This is significantly more efficient,
1292 * but it can cause problems for apps that expect to render on top of the
1293 * render API's output. As such, SDL will disable batching if a specific
1294 * render backend is requested (since this might indicate that the app is
1295 * planning to use the underlying graphics API directly). This hint can
1296 * be used to explicitly request batching in this instance. It is a contract
1297 * that you will either never use the underlying graphics API directly, or
1298 * if you do, you will call SDL_RenderFlush() before you do so any current
1299 * batch goes to the GPU before your work begins. Not following this contract
1300 * will result in undefined behavior.
1364 * By default SDL will use Xinerama if it is available.
1301 1365 */ */
1302 #define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING"
1303
1366 #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA"
1304 1367
1305 1368 /** /**
1306 * \brief A variable controlling whether SDL updates joystick state when getting input events
1369 * \brief A variable controlling whether the X11 XRandR extension should be used.
1307 1370 * *
1308 1371 * This variable can be set to the following values: * This variable can be set to the following values:
1372 * "0" - Disable XRandR
1373 * "1" - Enable XRandR
1309 1374 * *
1310 * "0" - You'll call SDL_JoystickUpdate() manually
1311 * "1" - SDL will automatically call SDL_JoystickUpdate() (default)
1312 *
1313 * This hint can be toggled on and off at runtime.
1375 * By default SDL will not use XRandR because of window manager issues.
1314 1376 */ */
1315 #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS"
1316
1377 #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR"
1317 1378
1318 1379 /** /**
1319 * \brief A variable controlling whether SDL updates sensor state when getting input events
1380 * \brief A variable controlling whether the X11 VidMode extension should be used.
1320 1381 * *
1321 1382 * This variable can be set to the following values: * This variable can be set to the following values:
1383 * "0" - Disable XVidMode
1384 * "1" - Enable XVidMode
1322 1385 * *
1323 * "0" - You'll call SDL_SensorUpdate() manually
1324 * "1" - SDL will automatically call SDL_SensorUpdate() (default)
1325 *
1326 * This hint can be toggled on and off at runtime.
1386 * By default SDL will use XVidMode if it is available.
1327 1387 */ */
1328 #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS"
1329
1388 #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE"
1330 1389
1331 1390 /** /**
1332 * \brief A variable controlling whether SDL logs all events pushed onto its internal queue.
1391 * \brief Controls how the fact chunk affects the loading of a WAVE file.
1333 1392 * *
1334 * This variable can be set to the following values:
1393 * The fact chunk stores information about the number of samples of a WAVE
1394 * file. The Standards Update from Microsoft notes that this value can be used
1395 * to 'determine the length of the data in seconds'. This is especially useful
1396 * for compressed formats (for which this is a mandatory chunk) if they produce
1397 * multiple sample frames per block and truncating the block is not allowed.
1398 * The fact chunk can exactly specify how many sample frames there should be
1399 * in this case.
1335 1400 * *
1336 * "0" - Don't log any events (default)
1337 * "1" - Log all events except mouse and finger motion, which are pretty spammy.
1338 * "2" - Log all events.
1401 * Unfortunately, most application seem to ignore the fact chunk and so SDL
1402 * ignores it by default as well.
1339 1403 * *
1340 * This is generally meant to be used to debug SDL itself, but can be useful
1341 * for application developers that need better visibility into what is going
1342 * on in the event queue. Logged events are sent through SDL_Log(), which
1343 * means by default they appear on stdout on most platforms or maybe
1344 * OutputDebugString() on Windows, and can be funneled by the app with
1345 * SDL_LogSetOutputFunction(), etc.
1404 * This variable can be set to the following values:
1346 1405 * *
1347 * This hint can be toggled on and off at runtime, if you only need to log
1348 * events for a small subset of program execution.
1406 * "truncate" - Use the number of samples to truncate the wave data if
1407 * the fact chunk is present and valid
1408 * "strict" - Like "truncate", but raise an error if the fact chunk
1409 * is invalid, not present for non-PCM formats, or if the
1410 * data chunk doesn't have that many samples
1411 * "ignorezero" - Like "truncate", but ignore fact chunk if the number of
1412 * samples is zero
1413 * "ignore" - Ignore fact chunk entirely (default)
1349 1414 */ */
1350 #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING"
1351
1352
1415 #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK"
1353 1416
1354 1417 /** /**
1355 1418 * \brief Controls how the size of the RIFF chunk affects the loading of a WAVE file. * \brief Controls how the size of the RIFF chunk affects the loading of a WAVE file.
 
... ... extern "C" {
1389 1452 #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION"
1390 1453
1391 1454 /** /**
1392 * \brief Controls how the fact chunk affects the loading of a WAVE file.
1455 * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception.
1456 * The 0x406D1388 Exception is a trick used to inform Visual Studio of a
1457 * thread's name, but it tends to cause problems with other debuggers,
1458 * and the .NET runtime. Note that SDL 2.0.6 and later will still use
1459 * the (safer) SetThreadDescription API, introduced in the Windows 10
1460 * Creators Update, if available.
1393 1461 * *
1394 * The fact chunk stores information about the number of samples of a WAVE
1395 * file. The Standards Update from Microsoft notes that this value can be used
1396 * to 'determine the length of the data in seconds'. This is especially useful
1397 * for compressed formats (for which this is a mandatory chunk) if they produce
1398 * multiple sample frames per block and truncating the block is not allowed.
1399 * The fact chunk can exactly specify how many sample frames there should be
1400 * in this case.
1462 * The variable can be set to the following values:
1463 * "0" - SDL will raise the 0x406D1388 Exception to name threads.
1464 * This is the default behavior of SDL <= 2.0.4.
1465 * "1" - SDL will not raise this exception, and threads will be unnamed. (default)
1466 * This is necessary with .NET languages or debuggers that aren't Visual Studio.
1467 */
1468 #define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING"
1469
1470 /**
1471 * \brief A variable controlling whether the windows message loop is processed by SDL
1401 1472 * *
1402 * Unfortunately, most application seem to ignore the fact chunk and so SDL
1403 * ignores it by default as well.
1473 * This variable can be set to the following values:
1474 * "0" - The window message loop is not run
1475 * "1" - The window message loop is processed in SDL_PumpEvents()
1476 *
1477 * By default SDL will process the windows message loop
1478 */
1479 #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP"
1480
1481 /**
1482 * \brief Force SDL to use Critical Sections for mutexes on Windows.
1483 * On Windows 7 and newer, Slim Reader/Writer Locks are available.
1484 * They offer better performance, allocate no kernel ressources and
1485 * use less memory. SDL will fall back to Critical Sections on older
1486 * OS versions or if forced to by this hint.
1487 * This also affects Condition Variables. When SRW mutexes are used,
1488 * SDL will use Windows Condition Variables as well. Else, a generic
1489 * SDL_cond implementation will be used that works with all mutexes.
1404 1490 * *
1405 1491 * This variable can be set to the following values: * This variable can be set to the following values:
1492 * "0" - Use SRW Locks when available. If not, fall back to Critical Sections. (default)
1493 * "1" - Force the use of Critical Sections in all cases.
1406 1494 * *
1407 * "truncate" - Use the number of samples to truncate the wave data if
1408 * the fact chunk is present and valid
1409 * "strict" - Like "truncate", but raise an error if the fact chunk
1410 * is invalid, not present for non-PCM formats, or if the
1411 * data chunk doesn't have that many samples
1412 * "ignorezero" - Like "truncate", but ignore fact chunk if the number of
1413 * samples is zero
1414 * "ignore" - Ignore fact chunk entirely (default)
1415 1495 */ */
1416 #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK"
1496 #define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS"
1417 1497
1418 1498 /** /**
1419 * \brief Override for SDL_GetDisplayUsableBounds()
1499 * \brief Force SDL to use Kernel Semaphores on Windows.
1500 * Kernel Semaphores are inter-process and require a context
1501 * switch on every interaction. On Windows 8 and newer, the
1502 * WaitOnAddress API is available. Using that and atomics to
1503 * implement semaphores increases performance.
1504 * SDL will fall back to Kernel Objects on older OS versions
1505 * or if forced to by this hint.
1420 1506 * *
1421 * If set, this hint will override the expected results for
1422 * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
1423 * to do this, but this allows an embedded system to request that some of the
1424 * screen be reserved for other uses when paired with a well-behaved
1425 * application.
1507 * This variable can be set to the following values:
1508 * "0" - Use Atomics and WaitOnAddress API when available. If not, fall back to Kernel Objects. (default)
1509 * "1" - Force the use of Kernel Objects in all cases.
1426 1510 * *
1427 * The contents of this hint must be 4 comma-separated integers, the first
1428 * is the bounds x, then y, width and height, in that order.
1429 1511 */ */
1430 #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
1512 #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL"
1431 1513
1432 1514 /** /**
1433 * \brief Specify an application name for an audio device.
1515 * \brief A variable to specify custom icon resource id from RC file on Windows platform
1516 */
1517 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON"
1518 #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
1519
1520 /**
1521 * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows.
1434 1522 * *
1435 * Some audio backends (such as PulseAudio) allow you to describe your audio
1436 * stream. Among other things, this description might show up in a system
1437 * control panel that lets the user adjust the volume on specific audio
1438 * streams instead of using one giant master volume slider.
1523 * The variable can be set to the following values:
1524 * "0" - SDL will generate a window-close event when it sees Alt+F4.
1525 * "1" - SDL will only do normal key handling for Alt+F4.
1526 */
1527 #define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4"
1528
1529 /**
1530 * \brief Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9.
1531 * Direct3D 9Ex contains changes to state management that can eliminate device
1532 * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require
1533 * some changes to your application to cope with the new behavior, so this
1534 * is disabled by default.
1439 1535 * *
1440 * This hints lets you transmit that information to the OS. The contents of
1441 * this hint are used while opening an audio device. You should use a string
1442 * that describes your program ("My Game 2: The Revenge")
1536 * This hint must be set before initializing the video subsystem.
1443 1537 * *
1444 * Setting this to "" or leaving it unset will have SDL use a reasonable
1445 * default: probably the application's name or "SDL Application" if SDL
1446 * doesn't have any better information.
1538 * For more information on Direct3D 9Ex, see:
1539 * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex
1540 * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements
1541 *
1542 * This variable can be set to the following values:
1543 * "0" - Use the original Direct3D 9 API (default)
1544 * "1" - Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable)
1447 1545 * *
1448 * On targets where this is not supported, this hint does nothing.
1449 1546 */ */
1450 #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
1547 #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX"
1451 1548
1452 1549 /** /**
1453 * \brief Specify an application name for an audio device.
1550 * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
1454 1551 * *
1455 * Some audio backends (such as PulseAudio) allow you to describe your audio
1456 * stream. Among other things, this description might show up in a system
1457 * control panel that lets the user adjust the volume on specific audio
1458 * streams instead of using one giant master volume slider.
1552 * This variable can be set to the following values:
1553 * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
1554 * "1" - The window frame is interactive when the cursor is hidden
1459 1555 * *
1460 * This hints lets you transmit that information to the OS. The contents of
1461 * this hint are used while opening an audio device. You should use a string
1462 * that describes your what your program is playing ("audio stream" is
1463 * probably sufficient in many cases, but this could be useful for something
1464 * like "team chat" if you have a headset playing VoIP audio separately).
1556 * By default SDL will allow interaction with the window frame when the cursor is hidden
1557 */
1558 #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
1559
1560 /** \brief Allows back-button-press events on Windows Phone to be marked as handled
1465 1561 * *
1466 * Setting this to "" or leaving it unset will have SDL use a reasonable
1467 * default: "audio stream" or something similar.
1562 * Windows Phone devices typically feature a Back button. When pressed,
1563 * the OS will emit back-button-press events, which apps are expected to
1564 * handle in an appropriate manner. If apps do not explicitly mark these
1565 * events as 'Handled', then the OS will invoke its default behavior for
1566 * unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to
1567 * terminate the app (and attempt to switch to the previous app, or to the
1568 * device's home screen).
1468 1569 * *
1469 * On targets where this is not supported, this hint does nothing.
1570 * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL
1571 * to mark back-button-press events as Handled, if and when one is sent to
1572 * the app.
1573 *
1574 * Internally, Windows Phone sends back button events as parameters to
1575 * special back-button-press callback functions. Apps that need to respond
1576 * to back-button-press events are expected to register one or more
1577 * callback functions for such, shortly after being launched (during the
1578 * app's initialization phase). After the back button is pressed, the OS
1579 * will invoke these callbacks. If the app's callback(s) do not explicitly
1580 * mark the event as handled by the time they return, or if the app never
1581 * registers one of these callback, the OS will consider the event
1582 * un-handled, and it will apply its default back button behavior (terminate
1583 * the app).
1584 *
1585 * SDL registers its own back-button-press callback with the Windows Phone
1586 * OS. This callback will emit a pair of SDL key-press events (SDL_KEYDOWN
1587 * and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which
1588 * it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON.
1589 * If the hint's value is set to "1", the back button event's Handled
1590 * property will get set to 'true'. If the hint's value is set to something
1591 * else, or if it is unset, SDL will leave the event's Handled property
1592 * alone. (By default, the OS sets this property to 'false', to note.)
1593 *
1594 * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a
1595 * back button is pressed, or can set it in direct-response to a back button
1596 * being pressed.
1597 *
1598 * In order to get notified when a back button is pressed, SDL apps should
1599 * register a callback function with SDL_AddEventWatch(), and have it listen
1600 * for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK.
1601 * (Alternatively, SDL_KEYUP events can be listened-for. Listening for
1602 * either event type is suitable.) Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON
1603 * set by such a callback, will be applied to the OS' current
1604 * back-button-press event.
1605 *
1606 * More details on back button behavior in Windows Phone apps can be found
1607 * at the following page, on Microsoft's developer site:
1608 * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx
1470 1609 */ */
1471 #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
1610 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
1472 1611
1612 /** \brief Label text for a WinRT app's privacy policy link
1613 *
1614 * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT,
1615 * Microsoft mandates that this policy be available via the Windows Settings charm.
1616 * SDL provides code to add a link there, with its label text being set via the
1617 * optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
1618 *
1619 * Please note that a privacy policy's contents are not set via this hint. A separate
1620 * hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the
1621 * policy.
1622 *
1623 * The contents of this hint should be encoded as a UTF8 string.
1624 *
1625 * The default value is "Privacy Policy". This hint should only be set during app
1626 * initialization, preferably before any calls to SDL_Init().
1627 *
1628 * For additional information on linking to a privacy policy, see the documentation for
1629 * SDL_HINT_WINRT_PRIVACY_POLICY_URL.
1630 */
1631 #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
1473 1632
1474 1633 /** /**
1475 * \brief Override for SDL_GetPreferredLocales()
1634 * \brief A URL to a WinRT app's privacy policy
1476 1635 * *
1477 * If set, this will be favored over anything the OS might report for the
1478 * user's preferred locales. Changing this hint at runtime will not generate
1479 * a SDL_LOCALECHANGED event (but if you can change the hint, you can push
1480 * your own event, if you want).
1636 * All network-enabled WinRT apps must make a privacy policy available to its
1637 * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be
1638 * be available in the Windows Settings charm, as accessed from within the app.
1639 * SDL provides code to add a URL-based link there, which can point to the app's
1640 * privacy policy.
1481 1641 * *
1482 * The format of this hint is a comma-separated list of language and locale,
1483 * combined with an underscore, as is a common format: "en_GB". Locale is
1484 * optional: "en". So you might have a list like this: "en_GB,jp,es_PT"
1642 * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL
1643 * before calling any SDL_Init() functions. The contents of the hint should
1644 * be a valid URL. For example, "http://www.example.com".
1645 *
1646 * The default value is "", which will prevent SDL from adding a privacy policy
1647 * link to the Settings charm. This hint should only be set during app init.
1648 *
1649 * The label text of an app's "Privacy Policy" link may be customized via another
1650 * hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
1651 *
1652 * Please note that on Windows Phone, Microsoft does not provide standard UI
1653 * for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL
1654 * will not get used on that platform. Network-enabled phone apps should display
1655 * their privacy policy through some other, in-app means.
1485 1656 */ */
1486 #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES"
1657 #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL"
1658
1659 /**
1660 * \brief Mark X11 windows as override-redirect.
1661 *
1662 * If set, this _might_ increase framerate at the expense of the desktop
1663 * not working as expected. Override-redirect windows aren't noticed by the
1664 * window manager at all.
1665 *
1666 * You should probably only use this for fullscreen windows, and you probably
1667 * shouldn't even use it for that. But it's here if you want to try!
1668 */
1669 #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT"
1670
1671 /**
1672 * \brief A variable that lets you disable the detection and use of Xinput gamepad devices
1673 *
1674 * The variable can be set to the following values:
1675 * "0" - Disable XInput detection (only uses direct input)
1676 * "1" - Enable XInput detection (the default)
1677 */
1678 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
1679
1680 /**
1681 * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices.
1682 *
1683 * This hint is for backwards compatibility only and will be removed in SDL 2.1
1684 *
1685 * The default value is "0". This hint must be set before SDL_Init()
1686 */
1687 #define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING"
1688
1689 /**
1690 * \brief A variable that causes SDL to not ignore audio "monitors"
1691 *
1692 * This is currently only used for PulseAudio and ignored elsewhere.
1693 *
1694 * By default, SDL ignores audio devices that aren't associated with physical
1695 * hardware. Changing this hint to "1" will expose anything SDL sees that
1696 * appears to be an audio source or sink. This will add "devices" to the list
1697 * that the user probably doesn't want or need, but it can be useful in
1698 * scenarios where you want to hook up SDL to some sort of virtual device,
1699 * etc.
1700 *
1701 * The default value is "0". This hint must be set before SDL_Init().
1702 *
1703 * This hint is available since SDL 2.0.16. Before then, virtual devices are
1704 * always ignored.
1705 */
1706 #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS"
1487 1707
1488 1708
1489 1709 /** /**
 
... ... typedef enum
1498 1718
1499 1719
1500 1720 /** /**
1501 * \brief Set a hint with a specific priority
1721 * Set a hint with a specific priority.
1722 *
1723 * The priority controls the behavior when setting a hint that already has a
1724 * value. Hints will replace existing hints of their priority and lower.
1725 * Environment variables are considered to have override priority.
1502 1726 * *
1503 * The priority controls the behavior when setting a hint that already
1504 * has a value. Hints will replace existing hints of their priority and
1505 * lower. Environment variables are considered to have override priority.
1727 * \param name the hint to set
1728 * \param value the value of the hint variable
1729 * \param priority the SDL_HintPriority level for the hint
1730 * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
1506 1731 * *
1507 * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
1732 * \sa SDL_GetHint
1733 * \sa SDL_SetHint
1508 1734 */ */
1509 1735 extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
1510 1736 const char *value, const char *value,
1511 1737 SDL_HintPriority priority); SDL_HintPriority priority);
1512 1738
1513 1739 /** /**
1514 * \brief Set a hint with normal priority
1740 * Set a hint with normal priority.
1741 *
1742 * Hints will not be set if there is an existing override hint or environment
1743 * variable that takes precedence. You can use SDL_SetHintWithPriority() to
1744 * set the hint with override priority instead.
1745 *
1746 * \param name the hint to set
1747 * \param value the value of the hint variable
1748 * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
1515 1749 * *
1516 * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
1750 * \sa SDL_GetHint
1751 * \sa SDL_SetHintWithPriority
1517 1752 */ */
1518 1753 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
1519 1754 const char *value); const char *value);
1520 1755
1521 1756 /** /**
1522 * \brief Get a hint
1757 * Get the value of a hint.
1523 1758 * *
1524 * \return The string value of a hint variable.
1759 * \param name the hint to query
1760 * \returns the string value of a hint or NULL if the hint isn't set.
1761 *
1762 * \sa SDL_SetHint
1763 * \sa SDL_SetHintWithPriority
1525 1764 */ */
1526 1765 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
1527 1766
1528 1767 /** /**
1529 * \brief Get a hint
1768 * Get the boolean value of a hint variable.
1769 *
1770 * \param name the name of the hint to get the boolean value from
1771 * \param default_value the value to return if the hint does not exist
1772 * \returns the boolean value of a hint or the provided default value if the
1773 * hint does not exist.
1530 1774 * *
1531 * \return The boolean value of a hint variable.
1775 * \since This function is available since SDL 2.0.5.
1776 *
1777 * \sa SDL_GetHint
1778 * \sa SDL_SetHint
1532 1779 */ */
1533 1780 extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value);
1534 1781
1535 1782 /** /**
1536 * \brief type definition of the hint callback function.
1783 * Type definition of the hint callback function.
1784 *
1785 * \param userdata what was passed as `userdata` to SDL_AddHintCallback()
1786 * \param name what was passed as `name` to SDL_AddHintCallback()
1787 * \param oldValue the previous hint value
1788 * \param newValue the new value hint is to be set to
1537 1789 */ */
1538 1790 typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
1539 1791
1540 1792 /** /**
1541 * \brief Add a function to watch a particular hint
1793 * Add a function to watch a particular hint.
1542 1794 * *
1543 * \param name The hint to watch
1544 * \param callback The function to call when the hint value changes
1545 * \param userdata A pointer to pass to the callback function
1795 * \param name the hint to watch
1796 * \param callback An SDL_HintCallback function that will be called when the
1797 * hint value changes
1798 * \param userdata a pointer to pass to the callback function
1799 *
1800 * \since This function is available since SDL 2.0.0.
1801 *
1802 * \sa SDL_DelHintCallback
1546 1803 */ */
1547 1804 extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
1548 1805 SDL_HintCallback callback, SDL_HintCallback callback,
1549 1806 void *userdata); void *userdata);
1550 1807
1551 1808 /** /**
1552 * \brief Remove a function watching a particular hint
1809 * Remove a function watching a particular hint.
1810 *
1811 * \param name the hint being watched
1812 * \param callback An SDL_HintCallback function that will be called when the
1813 * hint value changes
1814 * \param userdata a pointer being passed to the callback function
1815 *
1816 * \since This function is available since SDL 2.0.0.
1553 1817 * *
1554 * \param name The hint being watched
1555 * \param callback The function being called when the hint value changes
1556 * \param userdata A pointer being passed to the callback function
1818 * \sa SDL_AddHintCallback
1557 1819 */ */
1558 1820 extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
1559 1821 SDL_HintCallback callback, SDL_HintCallback callback,
1560 1822 void *userdata); void *userdata);
1561 1823
1562 1824 /** /**
1563 * \brief Clear all hints
1825 * Clear all hints.
1564 1826 * *
1565 * This function is called during SDL_Quit() to free stored hints.
1827 * This function is automatically called during SDL_Quit().
1566 1828 */ */
1567 1829 extern DECLSPEC void SDLCALL SDL_ClearHints(void); extern DECLSPEC void SDLCALL SDL_ClearHints(void);
1568 1830
File include/SDL2/SDL_joystick.h changed (mode: 100644) (index 0bbeafe..8be4b73)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
30 30 * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
31 31 * then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in. * then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
32 32 * *
33 * The term "player_index" is the number assigned to a player on a specific
34 * controller. For XInput controllers this returns the XInput user index.
35 * Many joysticks will not be able to supply this information.
36 *
33 37 * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
34 38 * the device (a X360 wired controller for example). This identifier is platform dependent. * the device (a X360 wired controller for example). This identifier is platform dependent.
35 *
36 *
37 39 */ */
38 40
39 41 #ifndef SDL_joystick_h_ #ifndef SDL_joystick_h_
 
... ... typedef enum
124 126 * and game controller events will not be delivered. * and game controller events will not be delivered.
125 127 */ */
126 128 extern DECLSPEC void SDLCALL SDL_LockJoysticks(void); extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
129
130
131 /**
132 * Unlocking for multi-threaded access to the joystick API
133 *
134 * If you are using the joystick API or handling events from multiple threads
135 * you should use these locking functions to protect access to the joysticks.
136 *
137 * In particular, you are guaranteed that the joystick list won't change, so
138 * the API functions that take a joystick index will be valid, and joystick
139 * and game controller events will not be delivered.
140 */
127 141 extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void); extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
128 142
129 143 /** /**
130 * Count the number of joysticks attached to the system right now
144 * Count the number of joysticks attached to the system.
145 *
146 * \returns the number of attached joysticks on success or a negative error
147 * code on failure; call SDL_GetError() for more information.
148 *
149 * \sa SDL_JoystickName
150 * \sa SDL_JoystickOpen
131 151 */ */
132 152 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
133 153
134 154 /** /**
135 * Get the implementation dependent name of a joystick.
136 * This can be called before any joysticks are opened.
137 * If no name can be found, this function returns NULL.
155 * Get the implementation dependent name of a joystick.
156 *
157 * This can be called before any joysticks are opened.
158 *
159 * \param device_index the index of the joystick to query (the N'th joystick
160 * on the system)
161 * \returns the name of the selected joystick. If no name can be found, this
162 * function returns NULL; call SDL_GetError() for more information.
163 *
164 * \sa SDL_JoystickName
165 * \sa SDL_JoystickOpen
138 166 */ */
139 167 extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
140 168
141 169 /** /**
142 * Get the player index of a joystick, or -1 if it's not available
143 * This can be called before any joysticks are opened.
170 * Get the player index of a joystick, or -1 if it's not available This can be
171 * called before any joysticks are opened.
144 172 */ */
145 173 extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index); extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
146 174
147 175 /** /**
148 * Return the GUID for the joystick at this index
149 * This can be called before any joysticks are opened.
176 * Get the implementation-dependent GUID for the joystick at a given device
177 * index.
178 *
179 * This function can be called before any joysticks are opened.
180 *
181 * \param device_index the index of the joystick to query (the N'th joystick
182 * on the system
183 * \returns the GUID of the selected joystick. If called on an invalid index,
184 * this function returns a zero GUID
185 *
186 * \sa SDL_JoystickGetGUID
187 * \sa SDL_JoystickGetGUIDString
150 188 */ */
151 189 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index); extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
152 190
153 191 /** /**
154 * Get the USB vendor ID of a joystick, if available.
155 * This can be called before any joysticks are opened.
156 * If the vendor ID isn't available this function returns 0.
192 * Get the USB vendor ID of a joystick, if available.
193 *
194 * This can be called before any joysticks are opened. If the vendor ID isn't
195 * available this function returns 0.
196 *
197 * \param device_index the index of the joystick to query (the N'th joystick
198 * on the system
199 * \returns the USB vendor ID of the selected joystick. If called on an
200 * invalid index, this function returns zero
157 201 */ */
158 202 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
159 203
160 204 /** /**
161 * Get the USB product ID of a joystick, if available.
162 * This can be called before any joysticks are opened.
163 * If the product ID isn't available this function returns 0.
205 * Get the USB product ID of a joystick, if available.
206 *
207 * This can be called before any joysticks are opened. If the product ID isn't
208 * available this function returns 0.
209 *
210 * \param device_index the index of the joystick to query (the N'th joystick
211 * on the system
212 * \returns the USB product ID of the selected joystick. If called on an
213 * invalid index, this function returns zero
164 214 */ */
165 215 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
166 216
167 217 /** /**
168 * Get the product version of a joystick, if available.
169 * This can be called before any joysticks are opened.
170 * If the product version isn't available this function returns 0.
218 * Get the product version of a joystick, if available.
219 *
220 * This can be called before any joysticks are opened. If the product version
221 * isn't available this function returns 0.
222 *
223 * \param device_index the index of the joystick to query (the N'th joystick
224 * on the system
225 * \returns the product version of the selected joystick. If called on an
226 * invalid index, this function returns zero
171 227 */ */
172 228 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
173 229
174 230 /** /**
175 * Get the type of a joystick, if available.
176 * This can be called before any joysticks are opened.
231 * Get the type of a joystick, if available.
232 *
233 * This can be called before any joysticks are opened.
234 *
235 * \param device_index the index of the joystick to query (the N'th joystick
236 * on the system
237 * \returns the SDL_JoystickType of the selected joystick. If called on an
238 * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
177 239 */ */
178 240 extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index); extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
179 241
180 242 /** /**
181 * Get the instance ID of a joystick.
182 * This can be called before any joysticks are opened.
183 * If the index is out of range, this function will return -1.
243 * Get the instance ID of a joystick.
244 *
245 * This can be called before any joysticks are opened. If the index is out of
246 * range, this function will return -1.
247 *
248 * \param device_index the index of the joystick to query (the N'th joystick
249 * on the system
250 * \returns the instance id of the selected joystick. If called on an invalid
251 * index, this function returns zero
184 252 */ */
185 253 extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index); extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
186 254
187 255 /** /**
188 * Open a joystick for use.
189 * The index passed as an argument refers to the N'th joystick on the system.
190 * This index is not the value which will identify this joystick in future
191 * joystick events. The joystick's instance id (::SDL_JoystickID) will be used
192 * there instead.
256 * Open a joystick for use.
257 *
258 * The `device_index` argument refers to the N'th joystick presently
259 * recognized by SDL on the system. It is **NOT** the same as the instance ID
260 * used to identify the joystick in future events. See
261 * SDL_JoystickInstanceID() for more details about instance IDs.
262 *
263 * The joystick subsystem must be initialized before a joystick can be opened
264 * for use.
265 *
266 * \param device_index the index of the joystick to query
267 * \returns a joystick identifier or NULL if an error occurred; call
268 * SDL_GetError() for more information.
193 269 * *
194 * \return A joystick identifier, or NULL if an error occurred.
270 * \sa SDL_JoystickClose
271 * \sa SDL_JoystickInstanceID
195 272 */ */
196 273 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
197 274
198 275 /** /**
199 * Return the SDL_Joystick associated with an instance id.
276 * Get the SDL_Joystick associated with an instance id.
277 *
278 * \param instance_id the instance id to get the SDL_Joystick for
279 * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
280 * for more information.
281 *
282 * \since This function is available since SDL 2.0.4.
200 283 */ */
201 284 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id); extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
202 285
203 286 /** /**
204 * Return the SDL_Joystick associated with a player index.
287 * Get the SDL_Joystick associated with a player index.
288 *
289 * \param player_index the player index to get the SDL_Joystick for
290 * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
291 * for more information.
205 292 */ */
206 293 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index); extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
207 294
208 295 /** /**
209 * Attaches a new virtual joystick.
210 * Returns the joystick's device index, or -1 if an error occurred.
296 * Attach a new virtual joystick.
297 *
298 * \returns the joystick's device index, or -1 if an error occurred.
211 299 */ */
212 300 extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type, extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
213 301 int naxes, int naxes,
 
... ... extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
215 303 int nhats); int nhats);
216 304
217 305 /** /**
218 * Detaches a virtual joystick
219 * Returns 0 on success, or -1 if an error occurred.
306 * Detach a virtual joystick.
307 *
308 * \param device_index a value previously returned from
309 * SDL_JoystickAttachVirtual()
310 * \returns 0 on success, or -1 if an error occurred.
220 311 */ */
221 312 extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index); extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
222 313
223 314 /** /**
224 * Indicates whether or not a virtual-joystick is at a given device index.
315 * Query whether or not the joystick at a given device index is virtual.
316 *
317 * \param device_index a joystick device index.
318 * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
225 319 */ */
226 320 extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index); extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
227 321
228 322 /** /**
229 * Set values on an opened, virtual-joystick's controls.
230 * Please note that values set here will not be applied until the next
231 * call to SDL_JoystickUpdate, which can either be called directly,
232 * or can be called indirectly through various other SDL APIS,
233 * including, but not limited to the following: SDL_PollEvent,
234 * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
235 *
236 * Returns 0 on success, -1 on error.
323 * Set values on an opened, virtual-joystick's axis.
324 *
325 * Please note that values set here will not be applied until the next call to
326 * SDL_JoystickUpdate, which can either be called directly, or can be called
327 * indirectly through various other SDL APIs, including, but not limited to
328 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
329 * SDL_WaitEvent.
330 *
331 * \param joystick the virtual joystick on which to set state.
332 * \param axis the specific axis on the virtual joystick to set.
333 * \param value the new value for the specified axis.
334 * \returns 0 on success, -1 on error.
237 335 */ */
238 336 extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
337
338 /**
339 * Set values on an opened, virtual-joystick's button.
340 *
341 * Please note that values set here will not be applied until the next call to
342 * SDL_JoystickUpdate, which can either be called directly, or can be called
343 * indirectly through various other SDL APIs, including, but not limited to
344 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
345 * SDL_WaitEvent.
346 *
347 * \param joystick the virtual joystick on which to set state.
348 * \param button the specific button on the virtual joystick to set.
349 * \param value the new value for the specified button.
350 * \returns 0 on success, -1 on error.
351 */
239 352 extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
353
354 /**
355 * Set values on an opened, virtual-joystick's hat.
356 *
357 * Please note that values set here will not be applied until the next call to
358 * SDL_JoystickUpdate, which can either be called directly, or can be called
359 * indirectly through various other SDL APIs, including, but not limited to
360 * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
361 * SDL_WaitEvent.
362 *
363 * \param joystick the virtual joystick on which to set state.
364 * \param hat the specific hat on the virtual joystick to set.
365 * \param value the new value for the specified hat.
366 * \returns 0 on success, -1 on error.
367 */
240 368 extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
241 369
242 370 /** /**
243 * Return the name for this currently opened joystick.
244 * If no name can be found, this function returns NULL.
371 * Get the implementation dependent name of a joystick.
372 *
373 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
374 * \returns the name of the selected joystick. If no name can be found, this
375 * function returns NULL; call SDL_GetError() for more information.
376 *
377 * \since This function is available since SDL 2.0.0.
378 *
379 * \sa SDL_JoystickNameForIndex
380 * \sa SDL_JoystickOpen
245 381 */ */
246 382 extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick); extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
247 383
248 384 /** /**
249 * Get the player index of an opened joystick, or -1 if it's not available
385 * Get the player index of an opened joystick.
250 386 * *
251 * For XInput controllers this returns the XInput user index.
387 * For XInput controllers this returns the XInput user index. Many joysticks
388 * will not be able to supply this information.
389 *
390 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
391 * \returns the player index, or -1 if it's not available.
252 392 */ */
253 393 extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick); extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
254 394
255 395 /** /**
256 * Set the player index of an opened joystick
396 * Set the player index of an opened joystick.
397 *
398 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
399 * \param player_index the player index to set.
257 400 */ */
258 401 extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index); extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
259 402
260 403 /** /**
261 * Return the GUID for this opened joystick
404 * Get the implementation-dependent GUID for the joystick.
405 *
406 * This function requires an open joystick.
407 *
408 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
409 * \returns the GUID of the given joystick. If called on an invalid index,
410 * this function returns a zero GUID; call SDL_GetError() for more
411 * information.
412 *
413 * \sa SDL_JoystickGetDeviceGUID
414 * \sa SDL_JoystickGetGUIDString
262 415 */ */
263 416 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick); extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
264 417
265 418 /** /**
266 * Get the USB vendor ID of an opened joystick, if available.
267 * If the vendor ID isn't available this function returns 0.
419 * Get the USB vendor ID of an opened joystick, if available.
420 *
421 * If the vendor ID isn't available this function returns 0.
422 *
423 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
424 * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
268 425 */ */
269 426 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
270 427
271 428 /** /**
272 * Get the USB product ID of an opened joystick, if available.
273 * If the product ID isn't available this function returns 0.
429 * Get the USB product ID of an opened joystick, if available.
430 *
431 * If the product ID isn't available this function returns 0.
432 *
433 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
434 * \returns the USB product ID of the selected joystick, or 0 if unavailable.
274 435 */ */
275 436 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
276 437
277 438 /** /**
278 * Get the product version of an opened joystick, if available.
279 * If the product version isn't available this function returns 0.
439 * Get the product version of an opened joystick, if available.
440 *
441 * If the product version isn't available this function returns 0.
442 *
443 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
444 * \returns the product version of the selected joystick, or 0 if unavailable.
280 445 */ */
281 446 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick); extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
282 447
283 448 /** /**
284 * Get the serial number of an opened joystick, if available.
285 *
286 * Returns the serial number of the joystick, or NULL if it is not available.
449 * Get the serial number of an opened joystick, if available.
450 *
451 * Returns the serial number of the joystick, or NULL if it is not available.
452 *
453 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
454 * \returns the serial number of the selected joystick, or NULL if
455 * unavailable.
287 456 */ */
288 457 extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick); extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
289 458
290 459 /** /**
291 * Get the type of an opened joystick.
460 * Get the type of an opened joystick.
461 *
462 * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
463 * \returns the SDL_JoystickType of the selected joystick.
292 464 */ */
293 465 extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick); extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
294 466
295 467 /** /**
296 * Return a string representation for this guid. pszGUID must point to at least 33 bytes
297 * (32 for the string plus a NULL terminator).
468 * Get an ASCII string representation for a given SDL_JoystickGUID.
469 *
470 * You should supply at least 33 bytes for pszGUID.
471 *
472 * \param guid the SDL_JoystickGUID you wish to convert to string
473 * \param pszGUID buffer in which to write the ASCII string
474 * \param cbGUID the size of pszGUID
475 *
476 * \sa SDL_JoystickGetDeviceGUID
477 * \sa SDL_JoystickGetGUID
478 * \sa SDL_JoystickGetGUIDFromString
298 479 */ */
299 480 extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID); extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
300 481
301 482 /** /**
302 * Convert a string into a joystick guid
483 * Convert a GUID string into a SDL_JoystickGUID structure.
484 *
485 * Performs no error checking. If this function is given a string containing
486 * an invalid GUID, the function will silently succeed, but the GUID generated
487 * will not be useful.
488 *
489 * \param pchGUID string containing an ASCII representation of a GUID
490 * \returns a SDL_JoystickGUID structure.
491 *
492 * \sa SDL_JoystickGetGUIDString
303 493 */ */
304 494 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID); extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
305 495
306 496 /** /**
307 * Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
497 * Get the status of a specified joystick.
498 *
499 * \param joystick the joystick to query
500 * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
501 * call SDL_GetError() for more information.
502 *
503 * \sa SDL_JoystickClose
504 * \sa SDL_JoystickOpen
308 505 */ */
309 506 extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick); extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
310 507
311 508 /** /**
312 * Get the instance ID of an opened joystick or -1 if the joystick is invalid.
509 * Get the instance ID of an opened joystick.
510 *
511 * \param joystick an SDL_Joystick structure containing joystick information
512 * \returns the instance ID of the specified joystick on success or a negative
513 * error code on failure; call SDL_GetError() for more information.
514 *
515 * \sa SDL_JoystickOpen
313 516 */ */
314 517 extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick); extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
315 518
316 519 /** /**
317 * Get the number of general axis controls on a joystick.
520 * Get the number of general axis controls on a joystick.
521 *
522 * Often, the directional pad on a game controller will either look like 4
523 * separate buttons or a POV hat, and not axes, but all of this is up to the
524 * device and platform.
525 *
526 * \param joystick an SDL_Joystick structure containing joystick information
527 * \returns the number of axis controls/number of axes on success or a
528 * negative error code on failure; call SDL_GetError() for more
529 * information.
530 *
531 * \sa SDL_JoystickGetAxis
532 * \sa SDL_JoystickOpen
318 533 */ */
319 534 extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
320 535
321 536 /** /**
322 * Get the number of trackballs on a joystick.
537 * Get the number of trackballs on a joystick.
538 *
539 * Joystick trackballs have only relative motion events associated with them
540 * and their state cannot be polled.
323 541 * *
324 * Joystick trackballs have only relative motion events associated
325 * with them and their state cannot be polled.
542 * Most joysticks do not have trackballs.
543 *
544 * \param joystick an SDL_Joystick structure containing joystick information
545 * \returns the number of trackballs on success or a negative error code on
546 * failure; call SDL_GetError() for more information.
547 *
548 * \sa SDL_JoystickGetBall
326 549 */ */
327 550 extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
328 551
329 552 /** /**
330 * Get the number of POV hats on a joystick.
553 * Get the number of POV hats on a joystick.
554 *
555 * \param joystick an SDL_Joystick structure containing joystick information
556 * \returns the number of POV hats on success or a negative error code on
557 * failure; call SDL_GetError() for more information.
558 *
559 * \sa SDL_JoystickGetHat
560 * \sa SDL_JoystickOpen
331 561 */ */
332 562 extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
333 563
334 564 /** /**
335 * Get the number of buttons on a joystick.
565 * Get the number of buttons on a joystick.
566 *
567 * \param joystick an SDL_Joystick structure containing joystick information
568 * \returns the number of buttons on success or a negative error code on
569 * failure; call SDL_GetError() for more information.
570 *
571 * \sa SDL_JoystickGetButton
572 * \sa SDL_JoystickOpen
336 573 */ */
337 574 extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick); extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
338 575
339 576 /** /**
340 * Update the current state of the open joysticks.
577 * Update the current state of the open joysticks.
578 *
579 * This is called automatically by the event loop if any joystick events are
580 * enabled.
341 581 * *
342 * This is called automatically by the event loop if any joystick
343 * events are enabled.
582 * \sa SDL_JoystickEventState
344 583 */ */
345 584 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
346 585
347 586 /** /**
348 * Enable/disable joystick event polling.
587 * Enable/disable joystick event polling.
349 588 * *
350 * If joystick events are disabled, you must call SDL_JoystickUpdate()
351 * yourself and check the state of the joystick when you want joystick
352 * information.
589 * If joystick events are disabled, you must call SDL_JoystickUpdate()
590 * yourself and manually check the state of the joystick when you want
591 * joystick information.
353 592 * *
354 * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
593 * It is recommended that you leave joystick event handling enabled.
594 *
595 * **WARNING**: Calling this function may delete all events currently in SDL's
596 * event queue.
597 *
598 * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
599 * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
600 * call SDL_GetError() for more information.
601 *
602 * If `state` is `SDL_QUERY` then the current state is returned,
603 * otherwise the new processing state is returned.
604 *
605 * \sa SDL_GameControllerEventState
355 606 */ */
356 607 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
357 608
358 609 #define SDL_JOYSTICK_AXIS_MAX 32767 #define SDL_JOYSTICK_AXIS_MAX 32767
359 610 #define SDL_JOYSTICK_AXIS_MIN -32768 #define SDL_JOYSTICK_AXIS_MIN -32768
360 611 /** /**
361 * Get the current state of an axis control on a joystick.
612 * Get the current state of an axis control on a joystick.
362 613 * *
363 * The state is a value ranging from -32768 to 32767.
614 * SDL makes no promises about what part of the joystick any given axis refers
615 * to. Your game should have some sort of configuration UI to let users
616 * specify what each axis should be bound to. Alternately, SDL's higher-level
617 * Game Controller API makes a great effort to apply order to this lower-level
618 * interface, so you know that a specific axis is the "left thumb stick," etc.
364 619 * *
365 * The axis indices start at index 0.
620 * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
621 * 32767) representing the current position of the axis. It may be necessary
622 * to impose certain tolerances on these values to account for jitter.
623 *
624 * \param joystick an SDL_Joystick structure containing joystick information
625 * \param axis the axis to query; the axis indices start at index 0
626 * \returns a 16-bit signed integer representing the current position of the
627 * axis or 0 on failure; call SDL_GetError() for more information.
628 *
629 * \sa SDL_JoystickNumAxes
366 630 */ */
367 631 extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
368 632 int axis); int axis);
369 633
370 634 /** /**
371 * Get the initial state of an axis control on a joystick.
635 * Get the initial state of an axis control on a joystick.
372 636 * *
373 * The state is a value ranging from -32768 to 32767.
637 * The state is a value ranging from -32768 to 32767.
374 638 * *
375 * The axis indices start at index 0.
639 * The axis indices start at index 0.
376 640 * *
377 * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
641 * \param joystick an SDL_Joystick structure containing joystick information
642 * \param axis the axis to query; the axis indices start at index 0
643 * \param state Upon return, the initial value is supplied here.
644 * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
378 645 */ */
379 646 extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick, extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
380 647 int axis, Sint16 *state); int axis, Sint16 *state);
 
... ... extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j
395 662 /* @} */ /* @} */
396 663
397 664 /** /**
398 * Get the current state of a POV hat on a joystick.
665 * Get the current state of a POV hat on a joystick.
666 *
667 * The returned value will be one of the following positions:
399 668 * *
400 * The hat indices start at index 0.
669 * - `SDL_HAT_CENTERED`
670 * - `SDL_HAT_UP`
671 * - `SDL_HAT_RIGHT`
672 * - `SDL_HAT_DOWN`
673 * - `SDL_HAT_LEFT`
674 * - `SDL_HAT_RIGHTUP`
675 * - `SDL_HAT_RIGHTDOWN`
676 * - `SDL_HAT_LEFTUP`
677 * - `SDL_HAT_LEFTDOWN`
401 678 * *
402 * \return The return value is one of the following positions:
403 * - ::SDL_HAT_CENTERED
404 * - ::SDL_HAT_UP
405 * - ::SDL_HAT_RIGHT
406 * - ::SDL_HAT_DOWN
407 * - ::SDL_HAT_LEFT
408 * - ::SDL_HAT_RIGHTUP
409 * - ::SDL_HAT_RIGHTDOWN
410 * - ::SDL_HAT_LEFTUP
411 * - ::SDL_HAT_LEFTDOWN
679 * \param joystick an SDL_Joystick structure containing joystick information
680 * \param hat the hat index to get the state from; indices start at index 0
681 * \returns the current hat position.
682 *
683 * \sa SDL_JoystickNumHats
412 684 */ */
413 685 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
414 686 int hat); int hat);
415 687
416 688 /** /**
417 * Get the ball axis change since the last poll.
689 * Get the ball axis change since the last poll.
690 *
691 * Trackballs can only return relative motion since the last call to
692 * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`.
418 693 * *
419 * \return 0, or -1 if you passed it invalid parameters.
694 * Most joysticks do not have trackballs.
420 695 * *
421 * The ball indices start at index 0.
696 * \param joystick the SDL_Joystick to query
697 * \param ball the ball index to query; ball indices start at index 0
698 * \param dx stores the difference in the x axis position since the last poll
699 * \param dy stores the difference in the y axis position since the last poll
700 * \returns 0 on success or a negative error code on failure; call
701 * SDL_GetError() for more information.
702 *
703 * \sa SDL_JoystickNumBalls
422 704 */ */
423 705 extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
424 706 int ball, int *dx, int *dy); int ball, int *dx, int *dy);
425 707
426 708 /** /**
427 * Get the current state of a button on a joystick.
709 * Get the current state of a button on a joystick.
710 *
711 * \param joystick an SDL_Joystick structure containing joystick information
712 * \param button the button index to get the state from; indices start at
713 * index 0
714 * \returns 1 if the specified button is pressed, 0 otherwise.
428 715 * *
429 * The button indices start at index 0.
716 * \sa SDL_JoystickNumButtons
430 717 */ */
431 718 extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
432 719 int button); int button);
433 720
434 721 /** /**
435 * Start a rumble effect
436 * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
722 * Start a rumble effect.
437 723 * *
438 * \param joystick The joystick to vibrate
439 * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
440 * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
441 * \param duration_ms The duration of the rumble effect, in milliseconds
724 * Each call to this function cancels any previous rumble effect, and calling
725 * it with 0 intensity stops any rumbling.
442 726 * *
443 * \return 0, or -1 if rumble isn't supported on this joystick
727 * \param joystick The joystick to vibrate
728 * \param low_frequency_rumble The intensity of the low frequency (left)
729 * rumble motor, from 0 to 0xFFFF
730 * \param high_frequency_rumble The intensity of the high frequency (right)
731 * rumble motor, from 0 to 0xFFFF
732 * \param duration_ms The duration of the rumble effect, in milliseconds
733 * \returns 0, or -1 if rumble isn't supported on this joystick
444 734 */ */
445 735 extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
446 736
447 737 /** /**
448 * Start a rumble effect in the joystick's triggers
449 * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
738 * Start a rumble effect in the joystick's triggers
450 739 * *
451 * \param joystick The joystick to vibrate
452 * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
453 * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
454 * \param duration_ms The duration of the rumble effect, in milliseconds
740 * Each call to this function cancels any previous trigger rumble effect, and
741 * calling it with 0 intensity stops any rumbling.
455 742 * *
456 * \return 0, or -1 if trigger rumble isn't supported on this joystick
743 * Note that this function is for _trigger_ rumble; the first joystick to
744 * support this was the PlayStation 5's DualShock 5 controller. If you want
745 * the (more common) whole-controller rumble, use SDL_JoystickRumble()
746 * instead.
747 *
748 * \param joystick The joystick to vibrate
749 * \param left_rumble The intensity of the left trigger rumble motor, from 0
750 * to 0xFFFF
751 * \param right_rumble The intensity of the right trigger rumble motor, from 0
752 * to 0xFFFF
753 * \param duration_ms The duration of the rumble effect, in milliseconds
754 * \returns 0, or -1 if trigger rumble isn't supported on this joystick
457 755 */ */
458 756 extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
459 757
460 758 /** /**
461 * Return whether a joystick has an LED
759 * Query whether a joystick has an LED.
462 760 * *
463 * \param joystick The joystick to query
761 * An example of a joystick LED is the light on the back of a PlayStation 4's
762 * DualShock 4 controller.
464 763 * *
465 * \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED
764 * \param joystick The joystick to query
765 * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
466 766 */ */
467 767 extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick); extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
468 768
469 769 /** /**
470 * Update a joystick's LED color.
770 * Update a joystick's LED color.
471 771 * *
472 * \param joystick The joystick to update
473 * \param red The intensity of the red LED
474 * \param green The intensity of the green LED
475 * \param blue The intensity of the blue LED
772 * An example of a joystick LED is the light on the back of a PlayStation 4's
773 * DualShock 4 controller.
476 774 * *
477 * \return 0, or -1 if this joystick does not have a modifiable LED
775 * \param joystick The joystick to update
776 * \param red The intensity of the red LED
777 * \param green The intensity of the green LED
778 * \param blue The intensity of the blue LED
779 * \returns 0 on success, -1 if this joystick does not have a modifiable LED
478 780 */ */
479 781 extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
480 782
481 783 /** /**
482 * Close a joystick previously opened with SDL_JoystickOpen().
784 * Send a joystick specific effect packet
785 *
786 * \param joystick The joystick to affect
787 * \param data The data to send to the joystick
788 * \param size The size of the data to send to the joystick
789 * \returns 0, or -1 if this joystick or driver doesn't support effect packets
790 */
791 extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const void *data, int size);
792
793 /**
794 * Close a joystick previously opened with SDL_JoystickOpen().
795 *
796 * \param joystick The joystick device to close
797 *
798 * \sa SDL_JoystickOpen
483 799 */ */
484 800 extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
485 801
486 802 /** /**
487 * Return the battery level of this joystick
803 * Get the battery level of a joystick as SDL_JoystickPowerLevel.
804 *
805 * \param joystick the SDL_Joystick to query
806 * \returns the current battery level as SDL_JoystickPowerLevel on success or
807 * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
808 *
809 * \since This function is available since SDL 2.0.4.
488 810 */ */
489 811 extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick); extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);
490 812
File include/SDL2/SDL_keyboard.h changed (mode: 100644) (index f6853c6..4260b5e)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct SDL_Keysym
55 55 /* Function prototypes */ /* Function prototypes */
56 56
57 57 /** /**
58 * \brief Get the window which currently has keyboard focus.
58 * Query the window which currently has keyboard focus.
59 *
60 * \returns the window with keyboard focus.
59 61 */ */
60 62 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
61 63
62 64 /** /**
63 * \brief Get a snapshot of the current state of the keyboard.
65 * Get a snapshot of the current state of the keyboard.
66 *
67 * The pointer returned is a pointer to an internal SDL array. It will be
68 * valid for the whole lifetime of the application and should not be freed by
69 * the caller.
70 *
71 * A array element with a value of 1 means that the key is pressed and a value
72 * of 0 means that it is not. Indexes into this array are obtained by using
73 * SDL_Scancode values.
64 74 * *
65 * \param numkeys if non-NULL, receives the length of the returned array.
75 * Use SDL_PumpEvents() to update the state array.
66 76 * *
67 * \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
77 * This function gives you the current state after all events have been
78 * processed, so if a key or button has been pressed and released before you
79 * process events, then the pressed state will never show up in the
80 * SDL_GetKeyboardState() calls.
68 81 * *
69 * \b Example:
70 * \code
71 * const Uint8 *state = SDL_GetKeyboardState(NULL);
72 * if ( state[SDL_SCANCODE_RETURN] ) {
73 * printf("<RETURN> is pressed.\n");
74 * }
75 * \endcode
82 * Note: This function doesn't take into account whether shift has been
83 * pressed or not.
84 *
85 * \param numkeys if non-NULL, receives the length of the returned array
86 * \returns a pointer to an array of key states.
87 *
88 * \sa SDL_PumpEvents
76 89 */ */
77 90 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys); extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
78 91
79 92 /** /**
80 * \brief Get the current key modifier state for the keyboard.
93 * Get the current key modifier state for the keyboard.
94 *
95 * \returns an OR'd combination of the modifier keys for the keyboard. See
96 * SDL_Keymod for details.
97 *
98 * \sa SDL_GetKeyboardState
99 * \sa SDL_SetModState
81 100 */ */
82 101 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
83 102
84 103 /** /**
85 * \brief Set the current key modifier state for the keyboard.
104 * Set the current key modifier state for the keyboard.
105 *
106 * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
107 * modifier key states on your application. Simply pass your desired modifier
108 * states into `modstate`. This value may be a bitwise, OR'd combination of
109 * SDL_Keymod values.
110 *
111 * This does not change the keyboard state, only the key modifier flags that
112 * SDL reports.
86 113 * *
87 * \note This does not change the keyboard state, only the key modifier flags.
114 * \param modstate the desired SDL_Keymod for the keyboard
115 *
116 * \sa SDL_GetModState
88 117 */ */
89 118 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
90 119
91 120 /** /**
92 * \brief Get the key code corresponding to the given scancode according
93 * to the current keyboard layout.
121 * Get the key code corresponding to the given scancode according to the
122 * current keyboard layout.
123 *
124 * See SDL_Keycode for details.
94 125 * *
95 * See ::SDL_Keycode for details.
126 * \param scancode the desired SDL_Scancode to query
127 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
96 128 * *
97 * \sa SDL_GetKeyName()
129 * \sa SDL_GetKeyName
130 * \sa SDL_GetScancodeFromKey
98 131 */ */
99 132 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode); extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
100 133
101 134 /** /**
102 * \brief Get the scancode corresponding to the given key code according to the
103 * current keyboard layout.
135 * Get the scancode corresponding to the given key code according to the
136 * current keyboard layout.
104 137 * *
105 * See ::SDL_Scancode for details.
138 * See SDL_Scancode for details.
106 139 * *
107 * \sa SDL_GetScancodeName()
140 * \param key the desired SDL_Keycode to query
141 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
142 *
143 * \sa SDL_GetKeyFromScancode
144 * \sa SDL_GetScancodeName
108 145 */ */
109 146 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key); extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
110 147
111 148 /** /**
112 * \brief Get a human-readable name for a scancode.
149 * Get a human-readable name for a scancode.
150 *
151 * See SDL_Scancode for details.
152 *
153 * **Warning**: The returned name is by design not stable across platforms,
154 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
155 * Windows" under Microsoft Windows, and some scancodes like
156 * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
157 * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
158 * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
159 * unsuitable for creating a stable cross-platform two-way mapping between
160 * strings and scancodes.
113 161 * *
114 * \return A pointer to the name for the scancode.
115 * If the scancode doesn't have a name, this function returns
116 * an empty string ("").
162 * \param scancode the desired SDL_Scancode to query
163 * \returns a pointer to the name for the scancode. If the scancode doesn't
164 * have a name this function returns an empty string ("").
117 165 * *
118 * \sa SDL_Scancode
166 * \since This function is available since SDL 2.0.0.
167 *
168 * \sa SDL_GetScancodeFromKey
169 * \sa SDL_GetScancodeFromName
119 170 */ */
120 171 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
121 172
122 173 /** /**
123 * \brief Get a scancode from a human-readable name
174 * Get a scancode from a human-readable name.
175 *
176 * \param name the human-readable scancode name
177 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
178 * recognized; call SDL_GetError() for more information.
124 179 * *
125 * \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
180 * \since This function is available since SDL 2.0.0.
126 181 * *
127 * \sa SDL_Scancode
182 * \sa SDL_GetKeyFromName
183 * \sa SDL_GetScancodeFromKey
184 * \sa SDL_GetScancodeName
128 185 */ */
129 186 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
130 187
131 188 /** /**
132 * \brief Get a human-readable name for a key.
189 * Get a human-readable name for a key.
190 *
191 * See SDL_Scancode and SDL_Keycode for details.
133 192 * *
134 * \return A pointer to a UTF-8 string that stays valid at least until the next
135 * call to this function. If you need it around any longer, you must
136 * copy it. If the key doesn't have a name, this function returns an
137 * empty string ("").
193 * \param key the desired SDL_Keycode to query
194 * \returns a pointer to a UTF-8 string that stays valid at least until the
195 * next call to this function. If you need it around any longer, you
196 * must copy it. If the key doesn't have a name, this function
197 * returns an empty string ("").
138 198 * *
139 * \sa SDL_Keycode
199 * \sa SDL_GetKeyFromName
200 * \sa SDL_GetKeyFromScancode
201 * \sa SDL_GetScancodeFromKey
140 202 */ */
141 203 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key); extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
142 204
143 205 /** /**
144 * \brief Get a key code from a human-readable name
206 * Get a key code from a human-readable name.
145 207 * *
146 * \return key code, or SDLK_UNKNOWN if the name wasn't recognized
208 * \param name the human-readable key name
209 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
210 * SDL_GetError() for more information.
147 211 * *
148 * \sa SDL_Keycode
212 * \sa SDL_GetKeyFromScancode
213 * \sa SDL_GetKeyName
214 * \sa SDL_GetScancodeFromName
149 215 */ */
150 216 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
151 217
152 218 /** /**
153 * \brief Start accepting Unicode text input events.
154 * This function will show the on-screen keyboard if supported.
219 * Start accepting Unicode text input events.
155 220 * *
156 * \sa SDL_StopTextInput()
157 * \sa SDL_SetTextInputRect()
158 * \sa SDL_HasScreenKeyboardSupport()
221 * This function will start accepting Unicode text input events in the focused
222 * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
223 * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
224 * pair with SDL_StopTextInput().
225 *
226 * On some platforms using this function activates the screen keyboard.
227 *
228 * \sa SDL_SetTextInputRect
229 * \sa SDL_StopTextInput
159 230 */ */
160 231 extern DECLSPEC void SDLCALL SDL_StartTextInput(void); extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
161 232
162 233 /** /**
163 * \brief Return whether or not Unicode text input events are enabled.
234 * Check whether or not Unicode text input events are enabled.
235 *
236 * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
164 237 * *
165 * \sa SDL_StartTextInput()
166 * \sa SDL_StopTextInput()
238 * \since This function is available since SDL 2.0.0.
239 *
240 * \sa SDL_StartTextInput
167 241 */ */
168 242 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
169 243
170 244 /** /**
171 * \brief Stop receiving any text input events.
172 * This function will hide the on-screen keyboard if supported.
245 * Stop receiving any text input events.
173 246 * *
174 * \sa SDL_StartTextInput()
175 * \sa SDL_HasScreenKeyboardSupport()
247 * \sa SDL_StartTextInput
176 248 */ */
177 249 extern DECLSPEC void SDLCALL SDL_StopTextInput(void); extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
178 250
179 251 /** /**
180 * \brief Set the rectangle used to type Unicode text inputs.
181 * This is used as a hint for IME and on-screen keyboard placement.
252 * Set the rectangle used to type Unicode text inputs.
253 *
254 * \param rect the SDL_Rect structure representing the rectangle to receive
255 * text (ignored if NULL)
182 256 * *
183 * \sa SDL_StartTextInput()
257 * \sa SDL_StartTextInput
184 258 */ */
185 259 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect); extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
186 260
187 261 /** /**
188 * \brief Returns whether the platform has some screen keyboard support.
262 * Check whether the platform has screen keyboard support.
189 263 * *
190 * \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
264 * \returns SDL_TRUE if the platform has some screen keyboard support or
265 * SDL_FALSE if not.
191 266 * *
192 * \note Not all screen keyboard functions are supported on all platforms.
267 * \since This function is available since SDL 2.0.0.
193 268 * *
194 * \sa SDL_IsScreenKeyboardShown()
269 * \sa SDL_StartTextInput
270 * \sa SDL_IsScreenKeyboardShown
195 271 */ */
196 272 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
197 273
198 274 /** /**
199 * \brief Returns whether the screen keyboard is shown for given window.
275 * Check whether the screen keyboard is shown for given window.
200 276 * *
201 * \param window The window for which screen keyboard should be queried.
277 * \param window the window for which screen keyboard should be queried
278 * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
202 279 * *
203 * \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
280 * \since This function is available since SDL 2.0.0.
204 281 * *
205 * \sa SDL_HasScreenKeyboardSupport()
282 * \sa SDL_HasScreenKeyboardSupport
206 283 */ */
207 284 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window); extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
208 285
File include/SDL2/SDL_keycode.h changed (mode: 100644) (index 6f6b65c..4fb0d39)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
52 52 SDLK_UNKNOWN = 0, SDLK_UNKNOWN = 0,
53 53
54 54 SDLK_RETURN = '\r', SDLK_RETURN = '\r',
55 SDLK_ESCAPE = '\033',
55 SDLK_ESCAPE = '\x1B',
56 56 SDLK_BACKSPACE = '\b', SDLK_BACKSPACE = '\b',
57 57 SDLK_TAB = '\t', SDLK_TAB = '\t',
58 58 SDLK_SPACE = ' ', SDLK_SPACE = ' ',
 
... ... typedef enum
147 147 SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT), SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT),
148 148 SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME), SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME),
149 149 SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP), SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP),
150 SDLK_DELETE = '\177',
150 SDLK_DELETE = '\x7F',
151 151 SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END), SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END),
152 152 SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN), SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN),
153 153 SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT), SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT),
File include/SDL2/SDL_loadso.h changed (mode: 100644) (index 89578a9..e6a33a0)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
51 51 #endif #endif
52 52
53 53 /** /**
54 * This function dynamically loads a shared object and returns a pointer
55 * to the object handle (or NULL if there was an error).
56 * The 'sofile' parameter is a system dependent name of the object file.
54 * Dynamically load a shared object.
55 *
56 * \param sofile a system-dependent name of the object file
57 * \returns an opaque pointer to the object handle or NULL if there was an
58 * error; call SDL_GetError() for more information.
59 *
60 * \sa SDL_LoadFunction
61 * \sa SDL_UnloadObject
57 62 */ */
58 63 extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile); extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
59 64
60 65 /** /**
61 * Given an object handle, this function looks up the address of the
62 * named function in the shared object and returns it. This address
63 * is no longer valid after calling SDL_UnloadObject().
66 * Look up the address of the named function in a shared object.
67 *
68 * This function pointer is no longer valid after calling SDL_UnloadObject().
69 *
70 * This function can only look up C function names. Other languages may have
71 * name mangling and intrinsic language support that varies from compiler to
72 * compiler.
73 *
74 * Make sure you declare your function pointers with the same calling
75 * convention as the actual library function. Your code will crash
76 * mysteriously if you do not do this.
77 *
78 * If the requested function doesn't exist, NULL is returned.
79 *
80 * \param handle a valid shared object handle returned by SDL_LoadObject()
81 * \param name the name of the function to look up
82 * \returns a pointer to the function or NULL if there was an error; call
83 * SDL_GetError() for more information.
84 *
85 * \sa SDL_LoadObject
86 * \sa SDL_UnloadObject
64 87 */ */
65 88 extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle, extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
66 89 const char *name); const char *name);
67 90
68 91 /** /**
69 * Unload a shared object from memory.
92 * Unload a shared object from memory.
93 *
94 * \param handle a valid shared object handle returned by SDL_LoadObject()
95 *
96 * \sa SDL_LoadFunction
97 * \sa SDL_LoadObject
70 98 */ */
71 99 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
72 100
File include/SDL2/SDL_locale.h changed (mode: 100644) (index 1f4b0c4..cb4b043)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct SDL_Locale
47 47 } SDL_Locale; } SDL_Locale;
48 48
49 49 /** /**
50 * \brief Report the user's preferred locale.
50 * Report the user's preferred locale.
51 51 * *
52 * This returns an array of SDL_Locale structs, the final item zeroed out.
53 * When the caller is done with this array, it should call SDL_free() on
54 * the returned value; all the memory involved is allocated in a single
55 * block, so a single SDL_free() will suffice.
52 * This returns an array of SDL_Locale structs, the final item zeroed out.
53 * When the caller is done with this array, it should call SDL_free() on the
54 * returned value; all the memory involved is allocated in a single block, so
55 * a single SDL_free() will suffice.
56 56 * *
57 * Returned language strings are in the format xx, where 'xx' is an ISO-639
58 * language specifier (such as "en" for English, "de" for German, etc).
59 * Country strings are in the format YY, where "YY" is an ISO-3166 country
60 * code (such as "US" for the United States, "CA" for Canada, etc). Country
61 * might be NULL if there's no specific guidance on them (so you might get
62 * { "en", "US" } for American English, but { "en", NULL } means "English
63 * language, generically"). Language strings are never NULL, except to
64 * terminate the array.
57 * Returned language strings are in the format xx, where 'xx' is an ISO-639
58 * language specifier (such as "en" for English, "de" for German, etc).
59 * Country strings are in the format YY, where "YY" is an ISO-3166 country
60 * code (such as "US" for the United States, "CA" for Canada, etc). Country
61 * might be NULL if there's no specific guidance on them (so you might get {
62 * "en", "US" } for American English, but { "en", NULL } means "English
63 * language, generically"). Language strings are never NULL, except to
64 * terminate the array.
65 65 * *
66 * Please note that not all of these strings are 2 characters; some are
67 * three or more.
66 * Please note that not all of these strings are 2 characters; some are three
67 * or more.
68 68 * *
69 * The returned list of locales are in the order of the user's preference.
70 * For example, a German citizen that is fluent in US English and knows
71 * enough Japanese to navigate around Tokyo might have a list like:
72 * { "de", "en_US", "jp", NULL }. Someone from England might prefer British
73 * English (where "color" is spelled "colour", etc), but will settle for
74 * anything like it: { "en_GB", "en", NULL }.
69 * The returned list of locales are in the order of the user's preference. For
70 * example, a German citizen that is fluent in US English and knows enough
71 * Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
72 * "jp", NULL }. Someone from England might prefer British English (where
73 * "color" is spelled "colour", etc), but will settle for anything like it: {
74 * "en_GB", "en", NULL }.
75 75 * *
76 * This function returns NULL on error, including when the platform does not
77 * supply this information at all.
76 * This function returns NULL on error, including when the platform does not
77 * supply this information at all.
78 78 * *
79 * This might be a "slow" call that has to query the operating system. It's
80 * best to ask for this once and save the results. However, this list can
81 * change, usually because the user has changed a system preference outside
82 * of your program; SDL will send an SDL_LOCALECHANGED event in this case,
83 * if possible, and you can call this function again to get an updated copy
84 * of preferred locales.
79 * This might be a "slow" call that has to query the operating system. It's
80 * best to ask for this once and save the results. However, this list can
81 * change, usually because the user has changed a system preference outside of
82 * your program; SDL will send an SDL_LOCALECHANGED event in this case, if
83 * possible, and you can call this function again to get an updated copy of
84 * preferred locales.
85 85 * *
86 * \return array of locales, terminated with a locale with a NULL language
87 * field. Will return NULL on error.
86 * \return array of locales, terminated with a locale with a NULL language
87 * field. Will return NULL on error.
88 88 */ */
89 89 extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void); extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);
90 90
File include/SDL2/SDL_log.h changed (mode: 100644) (index c1751fd..e85961a)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
112 112
113 113
114 114 /** /**
115 * \brief Set the priority of all log categories
115 * Set the priority of all log categories.
116 *
117 * \param priority the SDL_LogPriority to assign
118 *
119 * \sa SDL_LogSetPriority
116 120 */ */
117 121 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority); extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
118 122
119 123 /** /**
120 * \brief Set the priority of a particular log category
124 * Set the priority of a particular log category.
125 *
126 * \param category the category to assign a priority to
127 * \param priority the SDL_LogPriority to assign
128 *
129 * \sa SDL_LogGetPriority
130 * \sa SDL_LogSetAllPriority
121 131 */ */
122 132 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category, extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
123 133 SDL_LogPriority priority); SDL_LogPriority priority);
124 134
125 135 /** /**
126 * \brief Get the priority of a particular log category
136 * Get the priority of a particular log category.
137 *
138 * \param category the category to query
139 * \returns the SDL_LogPriority for the requested category
140 *
141 * \sa SDL_LogSetPriority
127 142 */ */
128 143 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category); extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
129 144
130 145 /** /**
131 * \brief Reset all priorities to default.
146 * Reset all priorities to default.
147 *
148 * This is called by SDL_Quit().
132 149 * *
133 * \note This is called in SDL_Quit().
150 * \sa SDL_LogSetAllPriority
151 * \sa SDL_LogSetPriority
134 152 */ */
135 153 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void); extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
136 154
137 155 /** /**
138 * \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
156 * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
157 *
158 * = * \param fmt a printf() style message format string
159 *
160 * \param ... additional parameters matching % tokens in the `fmt` string, if
161 * any
162 *
163 * \sa SDL_LogCritical
164 * \sa SDL_LogDebug
165 * \sa SDL_LogError
166 * \sa SDL_LogInfo
167 * \sa SDL_LogMessage
168 * \sa SDL_LogMessageV
169 * \sa SDL_LogVerbose
170 * \sa SDL_LogWarn
139 171 */ */
140 172 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
141 173
142 174 /** /**
143 * \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
175 * Log a message with SDL_LOG_PRIORITY_VERBOSE.
176 *
177 * \param category the category of the message
178 * \param fmt a printf() style message format string
179 * \param ... additional parameters matching % tokens in the **fmt** string,
180 * if any
181 *
182 * \sa SDL_Log
183 * \sa SDL_LogCritical
184 * \sa SDL_LogDebug
185 * \sa SDL_LogError
186 * \sa SDL_LogInfo
187 * \sa SDL_LogMessage
188 * \sa SDL_LogMessageV
189 * \sa SDL_LogWarn
144 190 */ */
145 191 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
146 192
147 193 /** /**
148 * \brief Log a message with SDL_LOG_PRIORITY_DEBUG
194 * Log a message with SDL_LOG_PRIORITY_DEBUG.
195 *
196 * \param category the category of the message
197 * \param fmt a printf() style message format string
198 * \param ... additional parameters matching % tokens in the **fmt** string,
199 * if any
200 *
201 * \sa SDL_Log
202 * \sa SDL_LogCritical
203 * \sa SDL_LogError
204 * \sa SDL_LogInfo
205 * \sa SDL_LogMessage
206 * \sa SDL_LogMessageV
207 * \sa SDL_LogVerbose
208 * \sa SDL_LogWarn
149 209 */ */
150 210 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
151 211
152 212 /** /**
153 * \brief Log a message with SDL_LOG_PRIORITY_INFO
213 * Log a message with SDL_LOG_PRIORITY_INFO.
214 *
215 * \param category the category of the message
216 * \param fmt a printf() style message format string
217 * \param ... additional parameters matching % tokens in the **fmt** string,
218 * if any
219 *
220 * \sa SDL_Log
221 * \sa SDL_LogCritical
222 * \sa SDL_LogDebug
223 * \sa SDL_LogError
224 * \sa SDL_LogMessage
225 * \sa SDL_LogMessageV
226 * \sa SDL_LogVerbose
227 * \sa SDL_LogWarn
154 228 */ */
155 229 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
156 230
157 231 /** /**
158 * \brief Log a message with SDL_LOG_PRIORITY_WARN
232 * Log a message with SDL_LOG_PRIORITY_WARN.
233 *
234 * \param category the category of the message
235 * \param fmt a printf() style message format string
236 * \param ... additional parameters matching % tokens in the **fmt** string,
237 * if any
238 *
239 * \sa SDL_Log
240 * \sa SDL_LogCritical
241 * \sa SDL_LogDebug
242 * \sa SDL_LogError
243 * \sa SDL_LogInfo
244 * \sa SDL_LogMessage
245 * \sa SDL_LogMessageV
246 * \sa SDL_LogVerbose
159 247 */ */
160 248 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
161 249
162 250 /** /**
163 * \brief Log a message with SDL_LOG_PRIORITY_ERROR
251 * Log a message with SDL_LOG_PRIORITY_ERROR.
252 *
253 * \param category the category of the message
254 * \param fmt a printf() style message format string
255 * \param ... additional parameters matching % tokens in the **fmt** string,
256 * if any
257 *
258 * \sa SDL_Log
259 * \sa SDL_LogCritical
260 * \sa SDL_LogDebug
261 * \sa SDL_LogInfo
262 * \sa SDL_LogMessage
263 * \sa SDL_LogMessageV
264 * \sa SDL_LogVerbose
265 * \sa SDL_LogWarn
164 266 */ */
165 267 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
166 268
167 269 /** /**
168 * \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
270 * Log a message with SDL_LOG_PRIORITY_CRITICAL.
271 *
272 * \param category the category of the message
273 * \param fmt a printf() style message format string
274 * \param ... additional parameters matching % tokens in the **fmt** string,
275 * if any
276 *
277 * \sa SDL_Log
278 * \sa SDL_LogDebug
279 * \sa SDL_LogError
280 * \sa SDL_LogInfo
281 * \sa SDL_LogMessage
282 * \sa SDL_LogMessageV
283 * \sa SDL_LogVerbose
284 * \sa SDL_LogWarn
169 285 */ */
170 286 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
171 287
172 288 /** /**
173 * \brief Log a message with the specified category and priority.
289 * Log a message with the specified category and priority.
290 *
291 * \param category the category of the message
292 * \param priority the priority of the message
293 * \param fmt a printf() style message format string
294 * \param ... additional parameters matching % tokens in the **fmt** string,
295 * if any
296 *
297 * \sa SDL_Log
298 * \sa SDL_LogCritical
299 * \sa SDL_LogDebug
300 * \sa SDL_LogError
301 * \sa SDL_LogInfo
302 * \sa SDL_LogMessageV
303 * \sa SDL_LogVerbose
304 * \sa SDL_LogWarn
174 305 */ */
175 306 extern DECLSPEC void SDLCALL SDL_LogMessage(int category, extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
176 307 SDL_LogPriority priority, SDL_LogPriority priority,
177 308 SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
178 309
179 310 /** /**
180 * \brief Log a message with the specified category and priority.
311 * Log a message with the specified category and priority.
312 *
313 * \param category the category of the message
314 * \param priority the priority of the message
315 * \param fmt a printf() style message format string
316 * \param ap a variable argument list
317 *
318 * \since This function is available since SDL 2.0.0.
319 *
320 * \sa SDL_Log
321 * \sa SDL_LogCritical
322 * \sa SDL_LogDebug
323 * \sa SDL_LogError
324 * \sa SDL_LogInfo
325 * \sa SDL_LogMessage
326 * \sa SDL_LogVerbose
327 * \sa SDL_LogWarn
181 328 */ */
182 329 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category, extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
183 330 SDL_LogPriority priority, SDL_LogPriority priority,
184 331 const char *fmt, va_list ap); const char *fmt, va_list ap);
185 332
186 333 /** /**
187 * \brief The prototype for the log output function
334 * The prototype for the log output callback function.
335 *
336 * This function is called by SDL when there is new text to be logged.
337 *
338 * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
339 * \param category the category of the message
340 * \param priority the priority of the message
341 * \param message the message being output
188 342 */ */
189 343 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
190 344
191 345 /** /**
192 * \brief Get the current log output function.
346 * Get the current log output function.
347 *
348 * \param callback an SDL_LogOutputFunction filled in with the current log
349 * callback
350 * \param userdata a pointer filled in with the pointer that is passed to
351 * `callback`
352 *
353 * \sa SDL_LogSetOutputFunction
193 354 */ */
194 355 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata); extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
195 356
196 357 /** /**
197 * \brief This function allows you to replace the default log output
198 * function with one of your own.
358 * Replace the default log output function with one of your own.
359 *
360 * \param callback an SDL_LogOutputFunction to call instead of the default
361 * \param userdata a pointer that is passed to `callback`
362 *
363 * \sa SDL_LogGetOutputFunction
199 364 */ */
200 365 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata); extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
201 366
File include/SDL2/SDL_main.h changed (mode: 100644) (index fcb5c17..087193b)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
122 122
123 123
124 124 /** /**
125 * This is called by the real SDL main function to let the rest of the
126 * library know that initialization was done properly.
125 * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
126 * point.
127 127 * *
128 * Calling this yourself without knowing what you're doing can cause
129 * crashes and hard to diagnose problems with your application.
128 * This function is defined in SDL_main.h, along with the preprocessor rule to
129 * redefine main() as SDL_main(). Thus to ensure that your main() function
130 * will not be changed it is necessary to define SDL_MAIN_HANDLED before
131 * including SDL.h.
132 *
133 * \sa SDL_Init
130 134 */ */
131 135 extern DECLSPEC void SDLCALL SDL_SetMainReady(void); extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
132 136
133 137 #ifdef __WIN32__ #ifdef __WIN32__
134 138
135 139 /** /**
136 * This can be called to set the application class at startup
140 * This can be called to set the application class at startup
137 141 */ */
138 142 extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst); extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
139 143 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 
... ... extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
144 148 #ifdef __WINRT__ #ifdef __WINRT__
145 149
146 150 /** /**
147 * \brief Initializes and launches an SDL/WinRT application.
151 * Initialize and launch an SDL/WinRT application.
152 *
153 * \param mainFunction the SDL app's C-style main(), an SDL_main_func
154 * \param reserved reserved for future use; should be NULL
155 * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
156 * more information on the failure.
148 157 * *
149 * \param mainFunction The SDL app's C-style main().
150 * \param reserved Reserved for future use; should be NULL
151 * \return 0 on success, -1 on failure. On failure, use SDL_GetError to retrieve more
152 * information on the failure.
158 * \since This function is available since SDL 2.0.3.
153 159 */ */
154 160 extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved); extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
155 161
 
... ... extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r
158 164 #if defined(__IPHONEOS__) #if defined(__IPHONEOS__)
159 165
160 166 /** /**
161 * \brief Initializes and launches an SDL application.
167 * Initializes and launches an SDL application.
162 168 * *
163 * \param argc The argc parameter from the application's main() function
164 * \param argv The argv parameter from the application's main() function
165 * \param mainFunction The SDL app's C-style main().
166 * \return the return value from mainFunction
169 * \param argc The argc parameter from the application's main() function
170 * \param argv The argv parameter from the application's main() function
171 * \param mainFunction The SDL app's C-style main(), an SDL_main_func
172 * \return the return value from mainFunction
167 173 */ */
168 174 extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction); extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);
169 175
File include/SDL2/SDL_messagebox.h changed (mode: 100644) (index 03639ce..c2aef70)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
32 32 #endif #endif
33 33
34 34 /** /**
35 * \brief SDL_MessageBox flags. If supported will display warning icon, etc.
35 * SDL_MessageBox flags. If supported will display warning icon, etc.
36 36 */ */
37 37 typedef enum typedef enum
38 38 { {
 
... ... typedef enum
44 44 } SDL_MessageBoxFlags; } SDL_MessageBoxFlags;
45 45
46 46 /** /**
47 * \brief Flags for SDL_MessageBoxButtonData.
47 * Flags for SDL_MessageBoxButtonData.
48 48 */ */
49 49 typedef enum typedef enum
50 50 { {
 
... ... typedef enum
53 53 } SDL_MessageBoxButtonFlags; } SDL_MessageBoxButtonFlags;
54 54
55 55 /** /**
56 * \brief Individual button data.
56 * Individual button data.
57 57 */ */
58 58 typedef struct typedef struct
59 59 { {
 
... ... typedef struct
63 63 } SDL_MessageBoxButtonData; } SDL_MessageBoxButtonData;
64 64
65 65 /** /**
66 * \brief RGB value used in a message box color scheme
66 * RGB value used in a message box color scheme
67 67 */ */
68 68 typedef struct typedef struct
69 69 { {
 
... ... typedef enum
81 81 } SDL_MessageBoxColorType; } SDL_MessageBoxColorType;
82 82
83 83 /** /**
84 * \brief A set of colors to use for message box dialogs
84 * A set of colors to use for message box dialogs
85 85 */ */
86 86 typedef struct typedef struct
87 87 { {
 
... ... typedef struct
89 89 } SDL_MessageBoxColorScheme; } SDL_MessageBoxColorScheme;
90 90
91 91 /** /**
92 * \brief MessageBox structure containing title, text, window, etc.
92 * MessageBox structure containing title, text, window, etc.
93 93 */ */
94 94 typedef struct typedef struct
95 95 { {
 
... ... typedef struct
105 105 } SDL_MessageBoxData; } SDL_MessageBoxData;
106 106
107 107 /** /**
108 * \brief Create a modal message box.
108 * Create a modal message box.
109 109 * *
110 * \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
111 * \param buttonid The pointer to which user id of hit button should be copied.
110 * If your needs aren't complex, it might be easier to use
111 * SDL_ShowSimpleMessageBox.
112 112 * *
113 * \return -1 on error, otherwise 0 and buttonid contains user id of button
114 * hit or -1 if dialog was closed.
113 * This function should be called on the thread that created the parent
114 * window, or on the main thread if the messagebox has no parent. It will
115 * block execution of that thread until the user clicks a button or closes the
116 * messagebox.
115 117 * *
116 * \note This function should be called on the thread that created the parent
117 * window, or on the main thread if the messagebox has no parent. It will
118 * block execution of that thread until the user clicks a button or
119 * closes the messagebox.
118 * This function may be called at any time, even before SDL_Init(). This makes
119 * it useful for reporting errors like a failure to create a renderer or
120 * OpenGL context.
121 *
122 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
123 * formal toolkit like GTK+ or Qt.
124 *
125 * Note that if SDL_Init() would fail because there isn't any available video
126 * target, this function is likely to fail for the same reasons. If this is a
127 * concern, check the return value from this function and fall back to writing
128 * to stderr if you can.
129 *
130 * \param messageboxdata the SDL_MessageBoxData structure with title, text and
131 * other options
132 * \param buttonid the pointer to which user id of hit button should be copied
133 * \returns 0 on success or a negative error code on failure; call
134 * SDL_GetError() for more information.
135 *
136 * \since This function is available since SDL 2.0.0.
137 *
138 * \sa SDL_ShowSimpleMessageBox
120 139 */ */
121 140 extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
122 141
123 142 /** /**
124 * \brief Create a simple modal message box
143 * Display a simple modal message box.
144 *
145 * If your needs aren't complex, this function is preferred over
146 * SDL_ShowMessageBox.
147 *
148 * `flags` may be any of the following:
149 *
150 * - `SDL_MESSAGEBOX_ERROR`: error dialog
151 * - `SDL_MESSAGEBOX_WARNING`: warning dialog
152 * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
153 *
154 * This function should be called on the thread that created the parent
155 * window, or on the main thread if the messagebox has no parent. It will
156 * block execution of that thread until the user clicks a button or closes the
157 * messagebox.
158 *
159 * This function may be called at any time, even before SDL_Init(). This makes
160 * it useful for reporting errors like a failure to create a renderer or
161 * OpenGL context.
162 *
163 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
164 * formal toolkit like GTK+ or Qt.
125 165 * *
126 * \param flags ::SDL_MessageBoxFlags
127 * \param title UTF-8 title text
128 * \param message UTF-8 message text
129 * \param window The parent window, or NULL for no parent
166 * Note that if SDL_Init() would fail because there isn't any available video
167 * target, this function is likely to fail for the same reasons. If this is a
168 * concern, check the return value from this function and fall back to writing
169 * to stderr if you can.
130 170 * *
131 * \return 0 on success, -1 on error
171 * \param flags an SDL_MessageBoxFlags value
172 * \param title UTF-8 title text
173 * \param message UTF-8 message text
174 * \param window the parent window, or NULL for no parent
175 * \returns 0 on success or a negative error code on failure; call
176 * SDL_GetError() for more information.
132 177 * *
133 * \sa SDL_ShowMessageBox
178 * \sa SDL_ShowMessageBox
134 179 */ */
135 180 extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window); extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window);
136 181
File include/SDL2/SDL_metal.h changed (mode: 100644) (index f967357..60bcb6e)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef void *SDL_MetalView;
49 49 /* @{ */ /* @{ */
50 50
51 51 /** /**
52 * \brief Create a CAMetalLayer-backed NSView/UIView and attach it to the
53 * specified window.
52 * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified
53 * window.
54 54 * *
55 * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on its
56 * own. It is up to user code to do that.
55 * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on
56 * its own. It is up to user code to do that.
57 57 * *
58 * The returned handle can be casted directly to a NSView or UIView.
59 * To access the backing CAMetalLayer, call SDL_Metal_GetLayer().
58 * The returned handle can be casted directly to a NSView or UIView. To access
59 * the backing CAMetalLayer, call SDL_Metal_GetLayer().
60 60 * *
61 * \note \a window must be created with the SDL_WINDOW_METAL flag.
62 *
63 * \sa SDL_Metal_DestroyView
64 * \sa SDL_Metal_GetLayer
61 * \sa SDL_Metal_DestroyView
62 * \sa SDL_Metal_GetLayer
65 63 */ */
66 64 extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window); extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
67 65
68 66 /** /**
69 * \brief Destroy an existing SDL_MetalView object.
67 * Destroy an existing SDL_MetalView object.
70 68 * *
71 * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
72 * called after SDL_CreateWindow.
69 * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
70 * called after SDL_CreateWindow.
73 71 * *
74 * \sa SDL_Metal_CreateView
72 * \sa SDL_Metal_CreateView
75 73 */ */
76 74 extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
77 75
78 76 /** /**
79 * \brief Get a pointer to the backing CAMetalLayer for the given view.
77 * Get a pointer to the backing CAMetalLayer for the given view.
80 78 * *
81 * \sa SDL_MetalCreateView
79 * \sa SDL_MetalCreateView
82 80 */ */
83 81 extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
84 82
85 83 /** /**
86 * \brief Get the size of a window's underlying drawable in pixels (for use
87 * with setting viewport, scissor & etc).
88 *
89 * \param window SDL_Window from which the drawable size should be queried
90 * \param w Pointer to variable for storing the width in pixels,
91 * may be NULL
92 * \param h Pointer to variable for storing the height in pixels,
93 * may be NULL
94 *
95 * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
96 * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
97 * platform with high-DPI support (Apple calls this "Retina"), and not disabled
98 * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
84 * Get the size of a window's underlying drawable in pixels (for use with
85 * setting viewport, scissor & etc).
99 86 * *
100 * \note On macOS high-DPI support must be enabled for an application by
101 * setting NSHighResolutionCapable to true in its Info.plist.
87 * \param window SDL_Window from which the drawable size should be queried
88 * \param w Pointer to variable for storing the width in pixels, may be NULL
102 89 * *
103 * \sa SDL_GetWindowSize()
104 * \sa SDL_CreateWindow()
90 * \sa SDL_GetWindowSize
91 * \sa SDL_CreateWindow
105 92 */ */
106 93 extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w, extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w,
107 94 int *h); int *h);
File include/SDL2/SDL_misc.h changed (mode: 100644) (index a04f19b..7cd4d57)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
38 38 #endif #endif
39 39
40 40 /** /**
41 * \brief Open an URL / URI in the browser or other
41 * Open a URL/URI in the browser or other appropriate external application.
42 42 * *
43 43 * Open a URL in a separate, system-provided application. How this works will * Open a URL in a separate, system-provided application. How this works will
44 * vary wildly depending on the platform. This will likely launch what
45 * makes sense to handle a specific URL's protocol (a web browser for http://,
46 * etc), but it might also be able to launch file managers for directories
47 * and other things.
44 * vary wildly depending on the platform. This will likely launch what makes
45 * sense to handle a specific URL's protocol (a web browser for `http://`,
46 * etc), but it might also be able to launch file managers for directories and
47 * other things.
48 48 * *
49 49 * What happens when you open a URL varies wildly as well: your game window * What happens when you open a URL varies wildly as well: your game window
50 * may lose focus (and may or may not lose focus if your game was fullscreen
51 * or grabbing input at the time). On mobile devices, your app will likely
52 * move to the background or your process might be paused. Any given platform
53 * may or may not handle a given URL.
50 * may lose focus (and may or may not lose focus if your game was fullscreen
51 * or grabbing input at the time). On mobile devices, your app will likely
52 * move to the background or your process might be paused. Any given platform
53 * may or may not handle a given URL.
54 54 * *
55 55 * If this is unimplemented (or simply unavailable) for a platform, this will * If this is unimplemented (or simply unavailable) for a platform, this will
56 * fail with an error. A successful result does not mean the URL loaded, just
57 * that we launched something to handle it (or at least believe we did).
56 * fail with an error. A successful result does not mean the URL loaded, just
57 * that we launched _something_ to handle it (or at least believe we did).
58 58 * *
59 59 * All this to say: this function can be useful, but you should definitely * All this to say: this function can be useful, but you should definitely
60 * test it on every platform you target.
60 * test it on every platform you target.
61 61 * *
62 * \param url A valid URL to open.
63 * \return 0 on success, or -1 on error.
62 * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
63 * local files, if supported.
64 * \returns 0 on success, or -1 on error; call SDL_GetError() for more
65 * information.
66 *
67 * \since This function is available in SDL 2.0.14 and newer
64 68 */ */
65 69 extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url); extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url);
66 70
File include/SDL2/SDL_mouse.h changed (mode: 100644) (index 99b658e..8fbe38f)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
72 72 /* Function prototypes */ /* Function prototypes */
73 73
74 74 /** /**
75 * \brief Get the window which currently has mouse focus.
75 * Get the window which currently has mouse focus.
76 *
77 * \returns the window with mouse focus.
76 78 */ */
77 79 extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
78 80
79 81 /** /**
80 * \brief Retrieve the current state of the mouse.
82 * Retrieve the current state of the mouse.
83 *
84 * The current button state is returned as a button bitmask, which can be
85 * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
86 * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
87 * mouse cursor position relative to the focus window. You can pass NULL for
88 * either `x` or `y`.
89 *
90 * \param x the x coordinate of the mouse cursor position relative to the
91 * focus window
92 * \param y the y coordinate of the mouse cursor position relative to the
93 * focus window
94 * \returns a 32-bit button bitmask of the current button state.
81 95 * *
82 * The current button state is returned as a button bitmask, which can
83 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
84 * mouse cursor position relative to the focus window for the currently
85 * selected mouse. You can pass NULL for either x or y.
96 * \sa SDL_GetGlobalMouseState
97 * \sa SDL_GetRelativeMouseState
98 * \sa SDL_PumpEvents
86 99 */ */
87 100 extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y); extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
88 101
89 102 /** /**
90 * \brief Get the current state of the mouse, in relation to the desktop
91 *
92 * This works just like SDL_GetMouseState(), but the coordinates will be
93 * reported relative to the top-left of the desktop. This can be useful if
94 * you need to track the mouse outside of a specific window and
95 * SDL_CaptureMouse() doesn't fit your needs. For example, it could be
96 * useful if you need to track the mouse while dragging a window, where
97 * coordinates relative to a window might not be in sync at all times.
98 *
99 * \note SDL_GetMouseState() returns the mouse position as SDL understands
100 * it from the last pump of the event queue. This function, however,
101 * queries the OS for the current mouse position, and as such, might
102 * be a slightly less efficient function. Unless you know what you're
103 * doing and have a good reason to use this function, you probably want
104 * SDL_GetMouseState() instead.
105 *
106 * \param x Returns the current X coord, relative to the desktop. Can be NULL.
107 * \param y Returns the current Y coord, relative to the desktop. Can be NULL.
108 * \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
109 *
110 * \sa SDL_GetMouseState
103 * Get the current state of the mouse in relation to the desktop.
104 *
105 * This works similarly to SDL_GetMouseState(), but the coordinates will be
106 * reported relative to the top-left of the desktop. This can be useful if you
107 * need to track the mouse outside of a specific window and SDL_CaptureMouse()
108 * doesn't fit your needs. For example, it could be useful if you need to
109 * track the mouse while dragging a window, where coordinates relative to a
110 * window might not be in sync at all times.
111 *
112 * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
113 * from the last pump of the event queue. This function, however, queries the
114 * OS for the current mouse position, and as such, might be a slightly less
115 * efficient function. Unless you know what you're doing and have a good
116 * reason to use this function, you probably want SDL_GetMouseState() instead.
117 *
118 * \param x filled in with the current X coord relative to the desktop; can be
119 * NULL
120 * \param y filled in with the current Y coord relative to the desktop; can be
121 * NULL
122 * \returns the current button state as a bitmask which can be tested using
123 * the SDL_BUTTON(X) macros.
124 *
125 * \since This function is available since SDL 2.0.4.
126 *
127 * \sa SDL_CaptureMouse
111 128 */ */
112 129 extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y); extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
113 130
114 131 /** /**
115 * \brief Retrieve the relative state of the mouse.
132 * Retrieve the relative state of the mouse.
133 *
134 * The current button state is returned as a button bitmask, which can be
135 * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
136 * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
137 * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
138 * event initialization. You can pass NULL for either `x` or `y`.
116 139 * *
117 * The current button state is returned as a button bitmask, which can
118 * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
119 * mouse deltas since the last call to SDL_GetRelativeMouseState().
140 * \param x a pointer filled with the last recorded x coordinate of the mouse
141 * \param y a pointer filled with the last recorded y coordinate of the mouse
142 * \returns a 32-bit button bitmask of the relative button state.
143 *
144 * \sa SDL_GetMouseState
120 145 */ */
121 146 extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y); extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
122 147
123 148 /** /**
124 * \brief Moves the mouse to the given position within the window.
149 * Move the mouse cursor to the given position within the window.
150 *
151 * This function generates a mouse motion event.
152 *
153 * Note that this function will appear to succeed, but not actually move the
154 * mouse when used over Microsoft Remote Desktop.
125 155 * *
126 * \param window The window to move the mouse into, or NULL for the current mouse focus
127 * \param x The x coordinate within the window
128 * \param y The y coordinate within the window
156 * \param window the window to move the mouse into, or NULL for the current
157 * mouse focus
158 * \param x the x coordinate within the window
159 * \param y the y coordinate within the window
129 160 * *
130 * \note This function generates a mouse motion event
161 * \sa SDL_WarpMouseGlobal
131 162 */ */
132 163 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
133 164 int x, int y); int x, int y);
134 165
135 166 /** /**
136 * \brief Moves the mouse to the given position in global screen space.
167 * Move the mouse to the given position in global screen space.
137 168 * *
138 * \param x The x coordinate
139 * \param y The y coordinate
140 * \return 0 on success, -1 on error (usually: unsupported by a platform).
169 * This function generates a mouse motion event.
141 170 * *
142 * \note This function generates a mouse motion event
171 * A failure of this function usually means that it is unsupported by a
172 * platform.
173 *
174 * Note that this function will appear to succeed, but not actually move the
175 * mouse when used over Microsoft Remote Desktop.
176 *
177 * \param x the x coordinate
178 * \param y the y coordinate
179 * \returns 0 on success or a negative error code on failure; call
180 * SDL_GetError() for more information.
181 *
182 * \since This function is available since SDL 2.0.4.
183 *
184 * \sa SDL_WarpMouseInWindow
143 185 */ */
144 186 extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y); extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
145 187
146 188 /** /**
147 * \brief Set relative mouse mode.
189 * Set relative mouse mode.
190 *
191 * While the mouse is in relative mode, the cursor is hidden, and the driver
192 * will try to report continuous motion in the current window. Only relative
193 * motion events will be delivered, the mouse position will not change.
148 194 * *
149 * \param enabled Whether or not to enable relative mode
195 * Note that this function will not be able to provide continuous relative
196 * motion when used over Microsoft Remote Desktop, instead motion is limited
197 * to the bounds of the screen.
150 198 * *
151 * \return 0 on success, or -1 if relative mode is not supported.
199 * This function will flush any pending mouse motion.
152 200 * *
153 * While the mouse is in relative mode, the cursor is hidden, and the
154 * driver will try to report continuous motion in the current window.
155 * Only relative motion events will be delivered, the mouse position
156 * will not change.
201 * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
202 * \returns 0 on success or a negative error code on failure; call
203 * SDL_GetError() for more information.
157 204 * *
158 * \note This function will flush any pending mouse motion.
205 * If relative mode is not supported, this returns -1.
159 206 * *
160 * \sa SDL_GetRelativeMouseMode()
207 * \sa SDL_GetRelativeMouseMode
161 208 */ */
162 209 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled); extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
163 210
164 211 /** /**
165 * \brief Capture the mouse, to track input outside an SDL window.
212 * Capture the mouse and to track input outside an SDL window.
213 *
214 * Capturing enables your app to obtain mouse events globally, instead of just
215 * within your window. Not all video targets support this function. When
216 * capturing is enabled, the current window will get all mouse events, but
217 * unlike relative mode, no change is made to the cursor and it is not
218 * restrained to your window.
166 219 * *
167 * \param enabled Whether or not to enable capturing
220 * This function may also deny mouse input to other windows--both those in
221 * your application and others on the system--so you should use this function
222 * sparingly, and in small bursts. For example, you might want to track the
223 * mouse while the user is dragging something, until the user releases a mouse
224 * button. It is not recommended that you capture the mouse for long periods
225 * of time, such as the entire time your app is running. For that, you should
226 * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
227 * on your goals.
168 228 * *
169 * Capturing enables your app to obtain mouse events globally, instead of
170 * just within your window. Not all video targets support this function.
171 * When capturing is enabled, the current window will get all mouse events,
172 * but unlike relative mode, no change is made to the cursor and it is
173 * not restrained to your window.
229 * While captured, mouse events still report coordinates relative to the
230 * current (foreground) window, but those coordinates may be outside the
231 * bounds of the window (including negative values). Capturing is only allowed
232 * for the foreground window. If the window loses focus while capturing, the
233 * capture will be disabled automatically.
174 234 * *
175 * This function may also deny mouse input to other windows--both those in
176 * your application and others on the system--so you should use this
177 * function sparingly, and in small bursts. For example, you might want to
178 * track the mouse while the user is dragging something, until the user
179 * releases a mouse button. It is not recommended that you capture the mouse
180 * for long periods of time, such as the entire time your app is running.
235 * While capturing is enabled, the current window will have the
236 * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
181 237 * *
182 * While captured, mouse events still report coordinates relative to the
183 * current (foreground) window, but those coordinates may be outside the
184 * bounds of the window (including negative values). Capturing is only
185 * allowed for the foreground window. If the window loses focus while
186 * capturing, the capture will be disabled automatically.
238 * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
239 * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
240 * information.
187 241 * *
188 * While capturing is enabled, the current window will have the
189 * SDL_WINDOW_MOUSE_CAPTURE flag set.
242 * \since This function is available since SDL 2.0.4.
190 243 * *
191 * \return 0 on success, or -1 if not supported.
244 * \sa SDL_GetGlobalMouseState
192 245 */ */
193 246 extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled); extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
194 247
195 248 /** /**
196 * \brief Query whether relative mouse mode is enabled.
249 * Query whether relative mouse mode is enabled.
197 250 * *
198 * \sa SDL_SetRelativeMouseMode()
251 * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
252 *
253 * \sa SDL_SetRelativeMouseMode
199 254 */ */
200 255 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
201 256
202 257 /** /**
203 * \brief Create a cursor, using the specified bitmap data and
204 * mask (in MSB format).
205 *
206 * The cursor width must be a multiple of 8 bits.
207 *
208 * The cursor is created in black and white according to the following:
209 * <table>
210 * <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
211 * <tr><td> 0 </td><td> 1 </td><td> White </td></tr>
212 * <tr><td> 1 </td><td> 1 </td><td> Black </td></tr>
213 * <tr><td> 0 </td><td> 0 </td><td> Transparent </td></tr>
214 * <tr><td> 1 </td><td> 0 </td><td> Inverted color if possible, black
215 * if not. </td></tr>
216 * </table>
217 *
218 * \sa SDL_FreeCursor()
258 * Create a cursor using the specified bitmap data and mask (in MSB format).
259 *
260 * `mask` has to be in MSB (Most Significant Bit) format.
261 *
262 * The cursor width (`w`) must be a multiple of 8 bits.
263 *
264 * The cursor is created in black and white according to the following:
265 *
266 * - data=0, mask=1: white
267 * - data=1, mask=1: black
268 * - data=0, mask=0: transparent
269 * - data=1, mask=0: inverted color if possible, black if not.
270 *
271 * Cursors created with this function must be freed with SDL_FreeCursor().
272 *
273 * If you want to have a color cursor, or create your cursor from an
274 * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
275 * hide the cursor and draw your own as part of your game's rendering, but it
276 * will be bound to the framerate.
277 *
278 * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
279 * provides twelve readily available system cursors to pick from.
280 *
281 * \param data the color value for each pixel of the cursor
282 * \param mask the mask value for each pixel of the cursor
283 * \param w the width of the cursor
284 * \param h the height of the cursor
285 * \param hot_x the X-axis location of the upper left corner of the cursor
286 * relative to the actual mouse position
287 * \param hot_y the Y-axis location of the upper left corner of the cursor
288 * relative to the actual mouse position
289 * \returns a new cursor with the specified parameters on success or NULL on
290 * failure; call SDL_GetError() for more information.
291 *
292 * \sa SDL_FreeCursor
293 * \sa SDL_SetCursor
294 * \sa SDL_ShowCursor
219 295 */ */
220 296 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data, extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
221 297 const Uint8 * mask, const Uint8 * mask,
 
... ... extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
223 299 int hot_y); int hot_y);
224 300
225 301 /** /**
226 * \brief Create a color cursor.
302 * Create a color cursor.
303 *
304 * \param surface an SDL_Surface structure representing the cursor image
305 * \param hot_x the x position of the cursor hot spot
306 * \param hot_y the y position of the cursor hot spot
307 * \returns the new cursor on success or NULL on failure; call SDL_GetError()
308 * for more information.
309 *
310 * \since This function is available since SDL 2.0.0.
227 311 * *
228 * \sa SDL_FreeCursor()
312 * \sa SDL_CreateCursor
313 * \sa SDL_FreeCursor
229 314 */ */
230 315 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
231 316 int hot_x, int hot_x,
232 317 int hot_y); int hot_y);
233 318
234 319 /** /**
235 * \brief Create a system cursor.
320 * Create a system cursor.
236 321 * *
237 * \sa SDL_FreeCursor()
322 * \param id an SDL_SystemCursor enum value
323 * \returns a cursor on success or NULL on failure; call SDL_GetError() for
324 * more information.
325 *
326 * \since This function is available since SDL 2.0.0.
327 *
328 * \sa SDL_FreeCursor
238 329 */ */
239 330 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
240 331
241 332 /** /**
242 * \brief Set the active cursor.
333 * Set the active cursor.
334 *
335 * This function sets the currently active cursor to the specified one. If the
336 * cursor is currently visible, the change will be immediately represented on
337 * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
338 * this is desired for any reason.
339 *
340 * \param cursor a cursor to make active
341 *
342 * \sa SDL_CreateCursor
343 * \sa SDL_GetCursor
344 * \sa SDL_ShowCursor
243 345 */ */
244 346 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor); extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
245 347
246 348 /** /**
247 * \brief Return the active cursor.
349 * Get the active cursor.
350 *
351 * This function returns a pointer to the current cursor which is owned by the
352 * library. It is not necessary to free the cursor with SDL_FreeCursor().
353 *
354 * \returns the active cursor or NULL if there is no mouse.
355 *
356 * \sa SDL_SetCursor
248 357 */ */
249 358 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void); extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
250 359
251 360 /** /**
252 * \brief Return the default cursor.
361 * Get the default cursor.
362 *
363 * \returns the default cursor on success or NULL on failure.
364 *
365 * \since This function is available since SDL 2.0.0.
366 *
367 * \sa SDL_CreateSystemCursor
253 368 */ */
254 369 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void); extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
255 370
256 371 /** /**
257 * \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
372 * Free a previously-created cursor.
373 *
374 * Use this function to free cursor resources created with SDL_CreateCursor(),
375 * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
258 376 * *
259 * \sa SDL_CreateCursor()
260 * \sa SDL_CreateColorCursor()
261 * \sa SDL_CreateSystemCursor()
377 * \param cursor the cursor to free
378 *
379 * \sa SDL_CreateColorCursor
380 * \sa SDL_CreateCursor
381 * \sa SDL_CreateSystemCursor
262 382 */ */
263 383 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor); extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
264 384
265 385 /** /**
266 * \brief Toggle whether or not the cursor is shown.
386 * Toggle whether or not the cursor is shown.
387 *
388 * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
389 * displays the cursor and passing `SDL_DISABLE` hides it.
390 *
391 * The current state of the mouse cursor can be queried by passing
392 * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
267 393 * *
268 * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
269 * state.
394 * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
395 * `SDL_QUERY` to query the current state without changing it.
396 * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
397 * cursor is hidden, or a negative error code on failure; call
398 * SDL_GetError() for more information.
270 399 * *
271 * \return 1 if the cursor is shown, or 0 if the cursor is hidden.
400 * \sa SDL_CreateCursor
401 * \sa SDL_SetCursor
272 402 */ */
273 403 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle); extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
274 404
275 405 /** /**
276 * Used as a mask when testing buttons in buttonstate.
277 * - Button 1: Left mouse button
278 * - Button 2: Middle mouse button
279 * - Button 3: Right mouse button
406 * Used as a mask when testing buttons in buttonstate.
407 *
408 * - Button 1: Left mouse button
409 * - Button 2: Middle mouse button
410 * - Button 3: Right mouse button
280 411 */ */
281 412 #define SDL_BUTTON(X) (1 << ((X)-1)) #define SDL_BUTTON(X) (1 << ((X)-1))
282 413 #define SDL_BUTTON_LEFT 1 #define SDL_BUTTON_LEFT 1
 
... ... extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
290 421 #define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) #define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1)
291 422 #define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) #define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2)
292 423
293
294 424 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
295 425 #ifdef __cplusplus #ifdef __cplusplus
296 426 } }
File include/SDL2/SDL_mutex.h changed (mode: 100644) (index 3c5b955..2f27f19)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... struct SDL_mutex;
59 59 typedef struct SDL_mutex SDL_mutex; typedef struct SDL_mutex SDL_mutex;
60 60
61 61 /** /**
62 * Create a mutex, initialized unlocked.
62 * Create a new mutex.
63 *
64 * All newly-created mutexes begin in the _unlocked_ state.
65 *
66 * Calls to SDL_LockMutex() will not return while the mutex is locked by
67 * another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
68 *
69 * SDL mutexes are reentrant.
70 *
71 * \returns the initialized and unlocked mutex or NULL on failure; call
72 * SDL_GetError() for more information.
73 *
74 * \sa SDL_DestroyMutex
75 * \sa SDL_LockMutex
76 * \sa SDL_TryLockMutex
77 * \sa SDL_UnlockMutex
63 78 */ */
64 79 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
65 80
66 81 /** /**
67 * Lock the mutex.
82 * Lock the mutex.
83 *
84 * This will block until the mutex is available, which is to say it is in the
85 * unlocked state and the OS has chosen the caller as the next thread to lock
86 * it. Of all threads waiting to lock the mutex, only one may do so at a time.
68 87 * *
69 * \return 0, or -1 on error.
88 * It is legal for the owning thread to lock an already-locked mutex. It must
89 * unlock it the same number of times before it is actually made available for
90 * other threads in the system (this is known as a "recursive mutex").
91 *
92 * \param mutex the mutex to lock
93 * \return 0, or -1 on error.
70 94 */ */
71 #define SDL_mutexP(m) SDL_LockMutex(m)
72 95 extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex); extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
96 #define SDL_mutexP(m) SDL_LockMutex(m)
73 97
74 98 /** /**
75 * Try to lock the mutex
99 * Try to lock a mutex without blocking.
100 *
101 * This works just like SDL_LockMutex(), but if the mutex is not available,
102 * this function returns `SDL_MUTEX_TIMEOUT` immediately.
103 *
104 * This technique is useful if you need exclusive access to a resource but
105 * don't want to wait for it, and will return to it to try again later.
106 *
107 * \param mutex the mutex to try to lock
108 * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
109 * more information.
76 110 * *
77 * \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
111 * \sa SDL_CreateMutex
112 * \sa SDL_DestroyMutex
113 * \sa SDL_LockMutex
114 * \sa SDL_UnlockMutex
78 115 */ */
79 116 extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex); extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
80 117
81 118 /** /**
82 * Unlock the mutex.
119 * Unlock the mutex.
83 120 * *
84 * \return 0, or -1 on error.
121 * It is legal for the owning thread to lock an already-locked mutex. It must
122 * unlock it the same number of times before it is actually made available for
123 * other threads in the system (this is known as a "recursive mutex").
85 124 * *
86 * \warning It is an error to unlock a mutex that has not been locked by
87 * the current thread, and doing so results in undefined behavior.
125 * It is an error to unlock a mutex that has not been locked by the current
126 * thread, and doing so results in undefined behavior.
127 *
128 * It is also an error to unlock a mutex that isn't locked at all.
129 *
130 * \param mutex the mutex to unlock.
131 * \returns 0, or -1 on error.
88 132 */ */
89 #define SDL_mutexV(m) SDL_UnlockMutex(m)
90 133 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex); extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
134 #define SDL_mutexV(m) SDL_UnlockMutex(m)
91 135
92 136 /** /**
93 * Destroy a mutex.
137 * Destroy a mutex created with SDL_CreateMutex().
138 *
139 * This function must be called on any mutex that is no longer needed. Failure
140 * to destroy a mutex will result in a system memory or resource leak. While
141 * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
142 * to destroy a locked mutex, and may result in undefined behavior depending
143 * on the platform.
144 *
145 * \param mutex the mutex to destroy
146 *
147 * \sa SDL_CreateMutex
148 * \sa SDL_LockMutex
149 * \sa SDL_TryLockMutex
150 * \sa SDL_UnlockMutex
94 151 */ */
95 152 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
96 153
 
... ... struct SDL_semaphore;
107 164 typedef struct SDL_semaphore SDL_sem; typedef struct SDL_semaphore SDL_sem;
108 165
109 166 /** /**
110 * Create a semaphore, initialized with value, returns NULL on failure.
167 * Create a semaphore.
168 *
169 * This function creates a new semaphore and initializes it with the value
170 * `initial_value`. Each wait operation on the semaphore will atomically
171 * decrement the semaphore value and potentially block if the semaphore value
172 * is 0. Each post operation will atomically increment the semaphore value and
173 * wake waiting threads and allow them to retry the wait operation.
174 *
175 * \param initial_value the starting value of the semaphore
176 * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
177 * information.
178 *
179 * \sa SDL_DestroySemaphore
180 * \sa SDL_SemPost
181 * \sa SDL_SemTryWait
182 * \sa SDL_SemValue
183 * \sa SDL_SemWait
184 * \sa SDL_SemWaitTimeout
111 185 */ */
112 186 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
113 187
114 188 /** /**
115 * Destroy a semaphore.
189 * Destroy a semaphore.
190 *
191 * It is not safe to destroy a semaphore if there are threads currently
192 * waiting on it.
193 *
194 * \param sem the semaphore to destroy
195 *
196 * \sa SDL_CreateSemaphore
197 * \sa SDL_SemPost
198 * \sa SDL_SemTryWait
199 * \sa SDL_SemValue
200 * \sa SDL_SemWait
201 * \sa SDL_SemWaitTimeout
116 202 */ */
117 203 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
118 204
119 205 /** /**
120 * This function suspends the calling thread until the semaphore pointed
121 * to by \c sem has a positive count. It then atomically decreases the
122 * semaphore count.
206 * Wait until a semaphore has a positive value and then decrements it.
207 *
208 * This function suspends the calling thread until either the semaphore
209 * pointed to by `sem` has a positive value or the call is interrupted by a
210 * signal or error. If the call is successful it will atomically decrement the
211 * semaphore value.
212 *
213 * This function is the equivalent of calling SDL_SemWaitTimeout() with a time
214 * length of `SDL_MUTEX_MAXWAIT`.
215 *
216 * \param sem the semaphore wait on
217 * \returns 0 on success or a negative error code on failure; call
218 * SDL_GetError() for more information.
219 *
220 * \sa SDL_CreateSemaphore
221 * \sa SDL_DestroySemaphore
222 * \sa SDL_SemPost
223 * \sa SDL_SemTryWait
224 * \sa SDL_SemValue
225 * \sa SDL_SemWait
226 * \sa SDL_SemWaitTimeout
123 227 */ */
124 228 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
125 229
126 230 /** /**
127 * Non-blocking variant of SDL_SemWait().
231 * See if a semaphore has a positive value and decrement it if it does.
232 *
233 * This function checks to see if the semaphore pointed to by `sem` has a
234 * positive value and atomically decrements the semaphore value if it does. If
235 * the semaphore doesn't have a positive value, the function immediately
236 * returns SDL_MUTEX_TIMEDOUT.
128 237 * *
129 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
130 * block, and -1 on error.
238 * \param sem the semaphore to wait on
239 * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
240 * block, or a negative error code on failure; call SDL_GetError()
241 * for more information.
242 *
243 * \sa SDL_CreateSemaphore
244 * \sa SDL_DestroySemaphore
245 * \sa SDL_SemPost
246 * \sa SDL_SemValue
247 * \sa SDL_SemWait
248 * \sa SDL_SemWaitTimeout
131 249 */ */
132 250 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
133 251
134 252 /** /**
135 * Variant of SDL_SemWait() with a timeout in milliseconds.
253 * Wait until a semaphore has a positive value and then decrements it.
254 *
255 * This function suspends the calling thread until either the semaphore
256 * pointed to by `sem` has a positive value, the call is interrupted by a
257 * signal or error, or the specified time has elapsed. If the call is
258 * successful it will atomically decrement the semaphore value.
136 259 * *
137 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
138 * succeed in the allotted time, and -1 on error.
260 * \param sem the semaphore to wait on
261 * \param ms the length of the timeout, in milliseconds
262 * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
263 * succeed in the allotted time, or a negative error code on failure;
264 * call SDL_GetError() for more information.
139 265 * *
140 * \warning On some platforms this function is implemented by looping with a
141 * delay of 1 ms, and so should be avoided if possible.
266 * \sa SDL_CreateSemaphore
267 * \sa SDL_DestroySemaphore
268 * \sa SDL_SemPost
269 * \sa SDL_SemTryWait
270 * \sa SDL_SemValue
271 * \sa SDL_SemWait
142 272 */ */
143 273 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms); extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
144 274
145 275 /** /**
146 * Atomically increases the semaphore's count (not blocking).
276 * Atomically increment a semaphore's value and wake waiting threads.
277 *
278 * \param sem the semaphore to increment
279 * \returns 0 on success or a negative error code on failure; call
280 * SDL_GetError() for more information.
147 281 * *
148 * \return 0, or -1 on error.
282 * \sa SDL_CreateSemaphore
283 * \sa SDL_DestroySemaphore
284 * \sa SDL_SemTryWait
285 * \sa SDL_SemValue
286 * \sa SDL_SemWait
287 * \sa SDL_SemWaitTimeout
149 288 */ */
150 289 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
151 290
152 291 /** /**
153 * Returns the current count of the semaphore.
292 * Get the current value of a semaphore.
293 *
294 * \param sem the semaphore to query
295 * \returns the current value of the semaphore.
296 *
297 * \sa SDL_CreateSemaphore
154 298 */ */
155 299 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
156 300
 
... ... struct SDL_cond;
167 311 typedef struct SDL_cond SDL_cond; typedef struct SDL_cond SDL_cond;
168 312
169 313 /** /**
170 * Create a condition variable.
171 *
172 * Typical use of condition variables:
314 * Create a condition variable.
173 315 * *
174 * Thread A:
175 * SDL_LockMutex(lock);
176 * while ( ! condition ) {
177 * SDL_CondWait(cond, lock);
178 * }
179 * SDL_UnlockMutex(lock);
316 * \returns a new condition variable or NULL on failure; call SDL_GetError()
317 * for more information.
180 318 * *
181 * Thread B:
182 * SDL_LockMutex(lock);
183 * ...
184 * condition = true;
185 * ...
186 * SDL_CondSignal(cond);
187 * SDL_UnlockMutex(lock);
188 *
189 * There is some discussion whether to signal the condition variable
190 * with the mutex locked or not. There is some potential performance
191 * benefit to unlocking first on some platforms, but there are some
192 * potential race conditions depending on how your code is structured.
193 *
194 * In general it's safer to signal the condition variable while the
195 * mutex is locked.
319 * \sa SDL_CondBroadcast
320 * \sa SDL_CondSignal
321 * \sa SDL_CondWait
322 * \sa SDL_CondWaitTimeout
323 * \sa SDL_DestroyCond
196 324 */ */
197 325 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
198 326
199 327 /** /**
200 * Destroy a condition variable.
328 * Destroy a condition variable.
329 *
330 * \param cond the condition variable to destroy
331 *
332 * \sa SDL_CondBroadcast
333 * \sa SDL_CondSignal
334 * \sa SDL_CondWait
335 * \sa SDL_CondWaitTimeout
336 * \sa SDL_CreateCond
201 337 */ */
202 338 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
203 339
204 340 /** /**
205 * Restart one of the threads that are waiting on the condition variable.
341 * Restart one of the threads that are waiting on the condition variable.
342 *
343 * \param cond the condition variable to signal
344 * \returns 0 on success or a negative error code on failure; call
345 * SDL_GetError() for more information.
206 346 * *
207 * \return 0 or -1 on error.
347 * \sa SDL_CondBroadcast
348 * \sa SDL_CondWait
349 * \sa SDL_CondWaitTimeout
350 * \sa SDL_CreateCond
351 * \sa SDL_DestroyCond
208 352 */ */
209 353 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
210 354
211 355 /** /**
212 * Restart all threads that are waiting on the condition variable.
356 * Restart all threads that are waiting on the condition variable.
357 *
358 * \param cond the condition variable to signal
359 * \returns 0 on success or a negative error code on failure; call
360 * SDL_GetError() for more information.
213 361 * *
214 * \return 0 or -1 on error.
362 * \sa SDL_CondSignal
363 * \sa SDL_CondWait
364 * \sa SDL_CondWaitTimeout
365 * \sa SDL_CreateCond
366 * \sa SDL_DestroyCond
215 367 */ */
216 368 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
217 369
218 370 /** /**
219 * Wait on the condition variable, unlocking the provided mutex.
371 * Wait until a condition variable is signaled.
220 372 * *
221 * \warning The mutex must be locked before entering this function!
373 * This function unlocks the specified `mutex` and waits for another thread to
374 * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
375 * `cond`. Once the condition variable is signaled, the mutex is re-locked and
376 * the function returns.
222 377 * *
223 * The mutex is re-locked once the condition variable is signaled.
378 * The mutex must be locked before calling this function.
224 379 * *
225 * \return 0 when it is signaled, or -1 on error.
380 * This function is the equivalent of calling SDL_CondWaitTimeout() with a
381 * time length of `SDL_MUTEX_MAXWAIT`.
382 *
383 * \param cond the condition variable to wait on
384 * \param mutex the mutex used to coordinate thread access
385 * \returns 0 when it is signaled or a negative error code on failure; call
386 * SDL_GetError() for more information.
387 *
388 * \sa SDL_CondBroadcast
389 * \sa SDL_CondSignal
390 * \sa SDL_CondWaitTimeout
391 * \sa SDL_CreateCond
392 * \sa SDL_DestroyCond
226 393 */ */
227 394 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
228 395
229 396 /** /**
230 * Waits for at most \c ms milliseconds, and returns 0 if the condition
231 * variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
232 * signaled in the allotted time, and -1 on error.
397 * Wait until a condition variable is signaled or a certain time has passed.
398 *
399 * This function unlocks the specified `mutex` and waits for another thread to
400 * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
401 * `cond`, or for the specified time to elapse. Once the condition variable is
402 * signaled or the time elapsed, the mutex is re-locked and the function
403 * returns.
404 *
405 * The mutex must be locked before calling this function.
406 *
407 * \param cond the condition variable to wait on
408 * \param mutex the mutex used to coordinate thread access
409 * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
410 * to wait indefinitely
411 * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
412 * the condition is not signaled in the allotted time, or a negative
413 * error code on failure; call SDL_GetError() for more information.
233 414 * *
234 * \warning On some platforms this function is implemented by looping with a
235 * delay of 1 ms, and so should be avoided if possible.
415 * \sa SDL_CondBroadcast
416 * \sa SDL_CondSignal
417 * \sa SDL_CondWait
418 * \sa SDL_CreateCond
419 * \sa SDL_DestroyCond
236 420 */ */
237 421 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
238 422 SDL_mutex * mutex, Uint32 ms); SDL_mutex * mutex, Uint32 ms);
File include/SDL2/SDL_name.h changed (mode: 100644) (index a49c488..21e1b79)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_opengl.h changed (mode: 100644) (index 5cd302c..95b51ae)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_opengles.h changed (mode: 100644) (index 5c2a3e6..7ebf4cc)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_opengles2.h changed (mode: 100644) (index 00bc180..ce114ae)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_pixels.h changed (mode: 100644) (index aa90cbc..a6d464c)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct SDL_PixelFormat
345 345 } SDL_PixelFormat; } SDL_PixelFormat;
346 346
347 347 /** /**
348 * \brief Get the human readable name of a pixel format
348 * Get the human readable name of a pixel format.
349 *
350 * \param format the pixel format to query
351 * \returns the human readable name of the specified pixel format or
352 * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
353 *
354 * \since This function is available since SDL 2.0.0.
349 355 */ */
350 356 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
351 357
352 358 /** /**
353 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
359 * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
354 360 * *
355 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
361 * \param format one of the SDL_PixelFormatEnum values
362 * \param bpp a bits per pixel value; usually 15, 16, or 32
363 * \param Rmask a pointer filled in with the red mask for the format
364 * \param Gmask a pointer filled in with the green mask for the format
365 * \param Bmask a pointer filled in with the blue mask for the format
366 * \param Amask a pointer filled in with the alpha mask for the format
367 * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
368 * possible; call SDL_GetError() for more information.
356 369 * *
357 * \sa SDL_MasksToPixelFormatEnum()
370 * \sa SDL_MasksToPixelFormatEnum
358 371 */ */
359 372 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
360 373 int *bpp, int *bpp,
 
... ... extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
364 377 Uint32 * Amask); Uint32 * Amask);
365 378
366 379 /** /**
367 * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
380 * Convert a bpp value and RGBA masks to an enumerated pixel format.
368 381 * *
369 * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
370 * wasn't possible.
382 * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
383 * possible.
371 384 * *
372 * \sa SDL_PixelFormatEnumToMasks()
385 * \param bpp a bits per pixel value; usually 15, 16, or 32
386 * \param Rmask the red mask for the format
387 * \param Gmask the green mask for the format
388 * \param Bmask the blue mask for the format
389 * \param Amask the alpha mask for the format
390 * \returns one of the SDL_PixelFormatEnum values
391 *
392 * \sa SDL_PixelFormatEnumToMasks
373 393 */ */
374 394 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
375 395 Uint32 Rmask, Uint32 Rmask,
 
... ... extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
378 398 Uint32 Amask); Uint32 Amask);
379 399
380 400 /** /**
381 * \brief Create an SDL_PixelFormat structure from a pixel format enum.
401 * Create an SDL_PixelFormat structure corresponding to a pixel format.
402 *
403 * Returned structure may come from a shared global cache (i.e. not newly
404 * allocated), and hence should not be modified, especially the palette. Weird
405 * errors such as `Blit combination not supported` may occur.
406 *
407 * \param pixel_format one of the SDL_PixelFormatEnum values
408 * \returns the new SDL_PixelFormat structure or NULL on failure; call
409 * SDL_GetError() for more information.
410 *
411 * \sa SDL_FreeFormat
382 412 */ */
383 413 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
384 414
385 415 /** /**
386 * \brief Free an SDL_PixelFormat structure.
416 * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
417 *
418 * \param format the SDL_PixelFormat structure to free
419 *
420 * \sa SDL_AllocFormat
387 421 */ */
388 422 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format); extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
389 423
390 424 /** /**
391 * \brief Create a palette structure with the specified number of color
392 * entries.
425 * Create a palette structure with the specified number of color entries.
393 426 * *
394 * \return A new palette, or NULL if there wasn't enough memory.
427 * The palette entries are initialized to white.
395 428 * *
396 * \note The palette entries are initialized to white.
429 * \param ncolors represents the number of color entries in the color palette
430 * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
431 * there wasn't enough memory); call SDL_GetError() for more
432 * information.
397 433 * *
398 * \sa SDL_FreePalette()
434 * \sa SDL_FreePalette
399 435 */ */
400 436 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
401 437
402 438 /** /**
403 * \brief Set the palette for a pixel format structure.
439 * Set the palette for a pixel format structure.
440 *
441 * \param format the SDL_PixelFormat structure that will use the palette
442 * \param palette the SDL_Palette structure that will be used
443 * \returns 0 on success or a negative error code on failure; call
444 * SDL_GetError() for more information.
445 *
446 * \sa SDL_AllocPalette
447 * \sa SDL_FreePalette
404 448 */ */
405 449 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
406 450 SDL_Palette *palette); SDL_Palette *palette);
407 451
408 452 /** /**
409 * \brief Set a range of colors in a palette.
453 * Set a range of colors in a palette.
410 454 * *
411 * \param palette The palette to modify.
412 * \param colors An array of colors to copy into the palette.
413 * \param firstcolor The index of the first palette entry to modify.
414 * \param ncolors The number of entries to modify.
455 * \param palette the SDL_Palette structure to modify
456 * \param colors an array of SDL_Color structures to copy into the palette
457 * \param firstcolor the index of the first palette entry to modify
458 * \param ncolors the number of entries to modify
459 * \returns 0 on success or a negative error code if not all of the colors
460 * could be set; call SDL_GetError() for more information.
415 461 * *
416 * \return 0 on success, or -1 if not all of the colors could be set.
462 * \sa SDL_AllocPalette
463 * \sa SDL_CreateRGBSurface
417 464 */ */
418 465 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
419 466 const SDL_Color * colors, const SDL_Color * colors,
420 467 int firstcolor, int ncolors); int firstcolor, int ncolors);
421 468
422 469 /** /**
423 * \brief Free a palette created with SDL_AllocPalette().
470 * Free a palette created with SDL_AllocPalette().
471 *
472 * \param palette the SDL_Palette structure to be freed
424 473 * *
425 * \sa SDL_AllocPalette()
474 * \sa SDL_AllocPalette
426 475 */ */
427 476 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
428 477
429 478 /** /**
430 * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
479 * Map an RGB triple to an opaque pixel value for a given pixel format.
480 *
481 * This function maps the RGB color value to the specified pixel format and
482 * returns the pixel value best approximating the given RGB color value for
483 * the given pixel format.
484 *
485 * If the format has a palette (8-bit) the index of the closest matching color
486 * in the palette will be returned.
487 *
488 * If the specified pixel format has an alpha component it will be returned as
489 * all 1 bits (fully opaque).
431 490 * *
432 * \sa SDL_MapRGBA
491 * If the pixel format bpp (color depth) is less than 32-bpp then the unused
492 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
493 * format the return value can be assigned to a Uint16, and similarly a Uint8
494 * for an 8-bpp format).
495 *
496 * \param format an SDL_PixelFormat structure describing the pixel format
497 * \param r the red component of the pixel in the range 0-255
498 * \param g the green component of the pixel in the range 0-255
499 * \param b the blue component of the pixel in the range 0-255
500 * \returns a pixel value
501 *
502 * \sa SDL_GetRGB
503 * \sa SDL_GetRGBA
504 * \sa SDL_MapRGBA
433 505 */ */
434 506 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
435 507 Uint8 r, Uint8 g, Uint8 b); Uint8 r, Uint8 g, Uint8 b);
436 508
437 509 /** /**
438 * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
510 * Map an RGBA quadruple to a pixel value for a given pixel format.
511 *
512 * This function maps the RGBA color value to the specified pixel format and
513 * returns the pixel value best approximating the given RGBA color value for
514 * the given pixel format.
515 *
516 * If the specified pixel format has no alpha component the alpha value will
517 * be ignored (as it will be in formats with a palette).
518 *
519 * If the format has a palette (8-bit) the index of the closest matching color
520 * in the palette will be returned.
521 *
522 * If the pixel format bpp (color depth) is less than 32-bpp then the unused
523 * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
524 * format the return value can be assigned to a Uint16, and similarly a Uint8
525 * for an 8-bpp format).
526 *
527 * \param format an SDL_PixelFormat structure describing the format of the
528 * pixel
529 * \param r the red component of the pixel in the range 0-255
530 * \param g the green component of the pixel in the range 0-255
531 * \param b the blue component of the pixel in the range 0-255
532 * \param a the alpha component of the pixel in the range 0-255
533 * \returns a pixel value
439 534 * *
440 * \sa SDL_MapRGB
535 * \sa SDL_GetRGB
536 * \sa SDL_GetRGBA
537 * \sa SDL_MapRGB
441 538 */ */
442 539 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
443 540 Uint8 r, Uint8 g, Uint8 b, Uint8 r, Uint8 g, Uint8 b,
444 541 Uint8 a); Uint8 a);
445 542
446 543 /** /**
447 * \brief Get the RGB components from a pixel of the specified format.
544 * Get RGB values from a pixel in the specified format.
448 545 * *
449 * \sa SDL_GetRGBA
546 * This function uses the entire 8-bit [0..255] range when converting color
547 * components from pixel formats with less than 8-bits per RGB component
548 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
549 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
550 *
551 * \param pixel a pixel value
552 * \param format an SDL_PixelFormat structure describing the format of the
553 * pixel
554 * \param r a pointer filled in with the red component
555 * \param g a pointer filled in with the green component
556 * \param b a pointer filled in with the blue component
557 *
558 * \sa SDL_GetRGBA
559 * \sa SDL_MapRGB
560 * \sa SDL_MapRGBA
450 561 */ */
451 562 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
452 563 const SDL_PixelFormat * format, const SDL_PixelFormat * format,
453 564 Uint8 * r, Uint8 * g, Uint8 * b); Uint8 * r, Uint8 * g, Uint8 * b);
454 565
455 566 /** /**
456 * \brief Get the RGBA components from a pixel of the specified format.
567 * Get RGBA values from a pixel in the specified format.
568 *
569 * This function uses the entire 8-bit [0..255] range when converting color
570 * components from pixel formats with less than 8-bits per RGB component
571 * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
572 * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
573 *
574 * If the surface has no alpha component, the alpha will be returned as 0xff
575 * (100% opaque).
457 576 * *
458 * \sa SDL_GetRGB
577 * \param pixel a pixel value
578 * \param format an SDL_PixelFormat structure describing the format of the
579 * pixel
580 * \param r a pointer filled in with the red component
581 * \param g a pointer filled in with the green component
582 * \param b a pointer filled in with the blue component
583 * \param a a pointer filled in with the alpha component
584 *
585 * \sa SDL_GetRGB
586 * \sa SDL_MapRGB
587 * \sa SDL_MapRGBA
459 588 */ */
460 589 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
461 590 const SDL_PixelFormat * format, const SDL_PixelFormat * format,
 
... ... extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
463 592 Uint8 * a); Uint8 * a);
464 593
465 594 /** /**
466 * \brief Calculate a 256 entry gamma ramp for a gamma value.
595 * Calculate a 256 entry gamma ramp for a gamma value.
596 *
597 * \param gamma a gamma value where 0.0 is black and 1.0 is identity
598 * \param ramp an array of 256 values filled in with the gamma ramp
599 *
600 * \sa SDL_SetWindowGammaRamp
467 601 */ */
468 602 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp); extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
469 603
File include/SDL2/SDL_platform.h changed (mode: 100644) (index 7166557..1516da3)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
70 70 /* lets us know what version of Mac OS X we're compiling on */ /* lets us know what version of Mac OS X we're compiling on */
71 71 #include "AvailabilityMacros.h" #include "AvailabilityMacros.h"
72 72 #include "TargetConditionals.h" #include "TargetConditionals.h"
73
74 /* Fix building with older SDKs that don't define these
75 See this for more information:
76 https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets
77 */
78 #ifndef TARGET_OS_MACCATALYST
79 #define TARGET_OS_MACCATALYST 0
80 #endif
81 #ifndef TARGET_OS_IOS
82 #define TARGET_OS_IOS 0
83 #endif
84 #ifndef TARGET_OS_IPHONE
85 #define TARGET_OS_IPHONE 0
86 #endif
87 #ifndef TARGET_OS_TV
88 #define TARGET_OS_TV 0
89 #endif
90 #ifndef TARGET_OS_SIMULATOR
91 #define TARGET_OS_SIMULATOR 0
92 #endif
93
73 94 #if TARGET_OS_TV #if TARGET_OS_TV
74 95 #undef __TVOS__ #undef __TVOS__
75 96 #define __TVOS__ 1 #define __TVOS__ 1
 
175 196 #define __SDL_NOGETPROCADDR__ #define __SDL_NOGETPROCADDR__
176 197 #endif #endif
177 198
199 #if defined(__vita__)
200 #define __VITA__ 1
201 #endif
178 202
179 203 #include "begin_code.h" #include "begin_code.h"
180 204 /* Set up for C function definitions, even when using C++ */ /* Set up for C function definitions, even when using C++ */
 
... ... extern "C" {
183 207 #endif #endif
184 208
185 209 /** /**
186 * \brief Gets the name of the platform.
210 * Get the name of the platform.
211 *
212 * Here are the names returned for some (but not all) supported platforms:
213 *
214 * - "Windows"
215 * - "Mac OS X"
216 * - "Linux"
217 * - "iOS"
218 * - "Android"
219 *
220 * \returns the name of the platform. If the correct platform name is not
221 * available, returns a string beginning with the text "Unknown".
187 222 */ */
188 223 extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void); extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
189 224
File include/SDL2/SDL_power.h changed (mode: 100644) (index 39884cc..872be18)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
37 37 #endif #endif
38 38
39 39 /** /**
40 * \brief The basic state for the system's power supply.
40 * The basic state for the system's power supply.
41 41 */ */
42 42 typedef enum typedef enum
43 43 { {
 
... ... typedef enum
50 50
51 51
52 52 /** /**
53 * \brief Get the current power supply details.
53 * Get the current power supply details.
54 54 * *
55 * \param secs Seconds of battery life left. You can pass a NULL here if
56 * you don't care. Will return -1 if we can't determine a
57 * value, or we're not running on a battery.
55 * You should never take a battery status as absolute truth. Batteries
56 * (especially failing batteries) are delicate hardware, and the values
57 * reported here are best estimates based on what that hardware reports. It's
58 * not uncommon for older batteries to lose stored power much faster than it
59 * reports, or completely drain when reporting it has 20 percent left, etc.
58 60 * *
59 * \param pct Percentage of battery life left, between 0 and 100. You can
60 * pass a NULL here if you don't care. Will return -1 if we
61 * can't determine a value, or we're not running on a battery.
61 * Battery status can change at any time; if you are concerned with power
62 * state, you should call this function frequently, and perhaps ignore changes
63 * until they seem to be stable for a few seconds.
62 64 * *
63 * \return The state of the battery (if any).
65 * It's possible a platform can only report battery percentage or time left
66 * but not both.
67 *
68 * \param secs seconds of battery life left, you can pass a NULL here if you
69 * don't care, will return -1 if we can't determine a value, or
70 * we're not running on a battery
71 * \param pct percentage of battery life left, between 0 and 100, you can pass
72 * a NULL here if you don't care, will return -1 if we can't
73 * determine a value, or we're not running on a battery
74 * \returns an SDL_PowerState enum representing the current battery state.
64 75 */ */
65 76 extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct); extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
66 77
File include/SDL2/SDL_quit.h changed (mode: 100644) (index b2bd5da..2825050)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_rect.h changed (mode: 100644) (index 47f0d20..a17ea44)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
40 40 #endif #endif
41 41
42 42 /** /**
43 * \brief The structure that defines a point (integer)
43 * The structure that defines a point (integer)
44 44 * *
45 * \sa SDL_EnclosePoints
46 * \sa SDL_PointInRect
45 * \sa SDL_EnclosePoints
46 * \sa SDL_PointInRect
47 47 */ */
48 48 typedef struct SDL_Point typedef struct SDL_Point
49 49 { {
 
... ... typedef struct SDL_Point
52 52 } SDL_Point; } SDL_Point;
53 53
54 54 /** /**
55 * \brief The structure that defines a point (floating point)
55 * The structure that defines a point (floating point)
56 56 * *
57 * \sa SDL_EnclosePoints
58 * \sa SDL_PointInRect
57 * \sa SDL_EnclosePoints
58 * \sa SDL_PointInRect
59 59 */ */
60 60 typedef struct SDL_FPoint typedef struct SDL_FPoint
61 61 { {
 
... ... typedef struct SDL_FPoint
65 65
66 66
67 67 /** /**
68 * \brief A rectangle, with the origin at the upper left (integer).
69 *
70 * \sa SDL_RectEmpty
71 * \sa SDL_RectEquals
72 * \sa SDL_HasIntersection
73 * \sa SDL_IntersectRect
74 * \sa SDL_UnionRect
75 * \sa SDL_EnclosePoints
68 * A rectangle, with the origin at the upper left (integer).
69 *
70 * \sa SDL_RectEmpty
71 * \sa SDL_RectEquals
72 * \sa SDL_HasIntersection
73 * \sa SDL_IntersectRect
74 * \sa SDL_UnionRect
75 * \sa SDL_EnclosePoints
76 76 */ */
77 77 typedef struct SDL_Rect typedef struct SDL_Rect
78 78 { {
 
... ... typedef struct SDL_Rect
82 82
83 83
84 84 /** /**
85 * \brief A rectangle, with the origin at the upper left (floating point).
85 * A rectangle, with the origin at the upper left (floating point).
86 86 */ */
87 87 typedef struct SDL_FRect typedef struct SDL_FRect
88 88 { {
 
... ... typedef struct SDL_FRect
94 94
95 95
96 96 /** /**
97 * \brief Returns true if point resides inside a rectangle.
97 * Returns true if point resides inside a rectangle.
98 98 */ */
99 99 SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
100 100 { {
 
... ... SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
103 103 } }
104 104
105 105 /** /**
106 * \brief Returns true if the rectangle has no area.
106 * Returns true if the rectangle has no area.
107 107 */ */
108 108 SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
109 109 { {
 
... ... SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
111 111 } }
112 112
113 113 /** /**
114 * \brief Returns true if the two rectangles are equal.
114 * Returns true if the two rectangles are equal.
115 115 */ */
116 116 SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b) SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
117 117 { {
 
... ... SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
120 120 } }
121 121
122 122 /** /**
123 * \brief Determine whether two rectangles intersect.
123 * Determine whether two rectangles intersect.
124 *
125 * If either pointer is NULL the function will return SDL_FALSE.
126 *
127 * \param A an SDL_Rect structure representing the first rectangle
128 * \param B an SDL_Rect structure representing the second rectangle
129 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
124 130 * *
125 * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
131 * \since This function is available since SDL 2.0.0.
132 *
133 * \sa SDL_IntersectRect
126 134 */ */
127 135 extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A, extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
128 136 const SDL_Rect * B); const SDL_Rect * B);
129 137
130 138 /** /**
131 * \brief Calculate the intersection of two rectangles.
139 * Calculate the intersection of two rectangles.
140 *
141 * If `result` is NULL then this function will return SDL_FALSE.
132 142 * *
133 * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
143 * \param A an SDL_Rect structure representing the first rectangle
144 * \param B an SDL_Rect structure representing the second rectangle
145 * \param result an SDL_Rect structure filled in with the intersection of
146 * rectangles `A` and `B`
147 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
148 *
149 * \since This function is available since SDL 2.0.0.
150 *
151 * \sa SDL_HasIntersection
134 152 */ */
135 153 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A, extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
136 154 const SDL_Rect * B, const SDL_Rect * B,
137 155 SDL_Rect * result); SDL_Rect * result);
138 156
139 157 /** /**
140 * \brief Calculate the union of two rectangles.
158 * Calculate the union of two rectangles.
159 *
160 * \param A an SDL_Rect structure representing the first rectangle
161 * \param B an SDL_Rect structure representing the second rectangle
162 * \param result an SDL_Rect structure filled in with the union of rectangles
163 * `A` and `B`
141 164 */ */
142 165 extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A, extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
143 166 const SDL_Rect * B, const SDL_Rect * B,
144 167 SDL_Rect * result); SDL_Rect * result);
145 168
146 169 /** /**
147 * \brief Calculate a minimal rectangle enclosing a set of points
170 * Calculate a minimal rectangle enclosing a set of points.
148 171 * *
149 * \return SDL_TRUE if any points were within the clipping rect
172 * If `clip` is not NULL then only points inside of the clipping rectangle are
173 * considered.
174 *
175 * \param points an array of SDL_Point structures representing points to be
176 * enclosed
177 * \param count the number of structures in the `points` array
178 * \param clip an SDL_Rect used for clipping or NULL to enclose all points
179 * \param result an SDL_Rect structure filled in with the minimal enclosing
180 * rectangle
181 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
182 * points were outside of the clipping rectangle.
150 183 */ */
151 184 extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points, extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
152 185 int count, int count,
 
... ... extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
154 187 SDL_Rect * result); SDL_Rect * result);
155 188
156 189 /** /**
157 * \brief Calculate the intersection of a rectangle and line segment.
190 * Calculate the intersection of a rectangle and line segment.
191 *
192 * This function is used to clip a line segment to a rectangle. A line segment
193 * contained entirely within the rectangle or that does not intersect will
194 * remain unchanged. A line segment that crosses the rectangle at either or
195 * both ends will be clipped to the boundary of the rectangle and the new
196 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
158 197 * *
159 * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
198 * \param rect an SDL_Rect structure representing the rectangle to intersect
199 * \param X1 a pointer to the starting X-coordinate of the line
200 * \param Y1 a pointer to the starting Y-coordinate of the line
201 * \param X2 a pointer to the ending X-coordinate of the line
202 * \param Y2 a pointer to the ending Y-coordinate of the line
203 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
160 204 */ */
161 205 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect * extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
162 206 rect, int *X1, rect, int *X1,
File include/SDL2/SDL_render.h changed (mode: 100644) (index f26fb7e..d80f4d3)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
59 59 #endif #endif
60 60
61 61 /** /**
62 * \brief Flags used when creating a rendering context
62 * Flags used when creating a rendering context
63 63 */ */
64 64 typedef enum typedef enum
65 65 { {
 
... ... typedef enum
73 73 } SDL_RendererFlags; } SDL_RendererFlags;
74 74
75 75 /** /**
76 * \brief Information on the capabilities of a render driver or context.
76 * Information on the capabilities of a render driver or context.
77 77 */ */
78 78 typedef struct SDL_RendererInfo typedef struct SDL_RendererInfo
79 79 { {
 
... ... typedef struct SDL_RendererInfo
86 86 } SDL_RendererInfo; } SDL_RendererInfo;
87 87
88 88 /** /**
89 * \brief The scaling mode for a texture.
89 * The scaling mode for a texture.
90 90 */ */
91 91 typedef enum typedef enum
92 92 { {
 
... ... typedef enum
96 96 } SDL_ScaleMode; } SDL_ScaleMode;
97 97
98 98 /** /**
99 * \brief The access pattern allowed for a texture.
99 * The access pattern allowed for a texture.
100 100 */ */
101 101 typedef enum typedef enum
102 102 { {
 
... ... typedef enum
106 106 } SDL_TextureAccess; } SDL_TextureAccess;
107 107
108 108 /** /**
109 * \brief The texture channel modulation used in SDL_RenderCopy().
109 * The texture channel modulation used in SDL_RenderCopy().
110 110 */ */
111 111 typedef enum typedef enum
112 112 { {
 
... ... typedef enum
116 116 } SDL_TextureModulate; } SDL_TextureModulate;
117 117
118 118 /** /**
119 * \brief Flip constants for SDL_RenderCopyEx
119 * Flip constants for SDL_RenderCopyEx
120 120 */ */
121 121 typedef enum typedef enum
122 122 { {
 
... ... typedef enum
126 126 } SDL_RendererFlip; } SDL_RendererFlip;
127 127
128 128 /** /**
129 * \brief A structure representing rendering state
129 * A structure representing rendering state
130 130 */ */
131 131 struct SDL_Renderer; struct SDL_Renderer;
132 132 typedef struct SDL_Renderer SDL_Renderer; typedef struct SDL_Renderer SDL_Renderer;
133 133
134 134 /** /**
135 * \brief An efficient driver-specific representation of pixel data
135 * An efficient driver-specific representation of pixel data
136 136 */ */
137 137 struct SDL_Texture; struct SDL_Texture;
138 138 typedef struct SDL_Texture SDL_Texture; typedef struct SDL_Texture SDL_Texture;
 
... ... typedef struct SDL_Texture SDL_Texture;
141 141 /* Function prototypes */ /* Function prototypes */
142 142
143 143 /** /**
144 * \brief Get the number of 2D rendering drivers available for the current
145 * display.
144 * Get the number of 2D rendering drivers available for the current display.
146 145 * *
147 * A render driver is a set of code that handles rendering and texture
148 * management on a particular display. Normally there is only one, but
149 * some drivers may have several available with different capabilities.
146 * A render driver is a set of code that handles rendering and texture
147 * management on a particular display. Normally there is only one, but some
148 * drivers may have several available with different capabilities.
150 149 * *
151 * \sa SDL_GetRenderDriverInfo()
152 * \sa SDL_CreateRenderer()
150 * There may be none if SDL was compiled without render support.
151 *
152 * \returns a number >= 0 on success or a negative error code on failure; call
153 * SDL_GetError() for more information.
154 *
155 * \since This function is available since SDL 2.0.0.
156 *
157 * \sa SDL_CreateRenderer
158 * \sa SDL_GetRenderDriverInfo
153 159 */ */
154 160 extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
155 161
156 162 /** /**
157 * \brief Get information about a specific 2D rendering driver for the current
158 * display.
159 *
160 * \param index The index of the driver to query information about.
161 * \param info A pointer to an SDL_RendererInfo struct to be filled with
162 * information on the rendering driver.
163 * Get info about a specific 2D rendering driver for the current display.
163 164 * *
164 * \return 0 on success, -1 if the index was out of range.
165 * \param index the index of the driver to query information about
166 * \param info an SDL_RendererInfo structure to be filled with information on
167 * the rendering driver
168 * \returns 0 on success or a negative error code on failure; call
169 * SDL_GetError() for more information.
165 170 * *
166 * \sa SDL_CreateRenderer()
171 * \sa SDL_CreateRenderer
172 * \sa SDL_GetNumRenderDrivers
167 173 */ */
168 174 extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
169 175 SDL_RendererInfo * info); SDL_RendererInfo * info);
170 176
171 177 /** /**
172 * \brief Create a window and default renderer
178 * Create a window and default renderer.
173 179 * *
174 * \param width The width of the window
175 * \param height The height of the window
176 * \param window_flags The flags used to create the window
177 * \param window A pointer filled with the window, or NULL on error
178 * \param renderer A pointer filled with the renderer, or NULL on error
180 * \param width the width of the window
181 * \param height the height of the window
182 * \param window_flags the flags used to create the window (see
183 * SDL_CreateWindow())
184 * \param window a pointer filled with the window, or NULL on error
185 * \param renderer a pointer filled with the renderer, or NULL on error
186 * \returns 0 on success, or -1 on error; call SDL_GetError() for more
187 * information.
179 188 * *
180 * \return 0 on success, or -1 on error
189 * \sa SDL_CreateRenderer
190 * \sa SDL_CreateWindow
181 191 */ */
182 192 extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
183 193 int width, int height, Uint32 window_flags, int width, int height, Uint32 window_flags,
 
... ... extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
185 195
186 196
187 197 /** /**
188 * \brief Create a 2D rendering context for a window.
198 * Create a 2D rendering context for a window.
189 199 * *
190 * \param window The window where rendering is displayed.
191 * \param index The index of the rendering driver to initialize, or -1 to
192 * initialize the first one supporting the requested flags.
193 * \param flags ::SDL_RendererFlags.
200 * \param window the window where rendering is displayed
201 * \param index the index of the rendering driver to initialize, or -1 to
202 * initialize the first one supporting the requested flags
203 * \param flags 0, or one or more SDL_RendererFlags OR'd together
204 * \returns a valid rendering context or NULL if there was an error; call
205 * SDL_GetError() for more information.
194 206 * *
195 * \return A valid rendering context or NULL if there was an error.
196 *
197 * \sa SDL_CreateSoftwareRenderer()
198 * \sa SDL_GetRendererInfo()
199 * \sa SDL_DestroyRenderer()
207 * \sa SDL_CreateSoftwareRenderer
208 * \sa SDL_DestroyRenderer
209 * \sa SDL_GetNumRenderDrivers
210 * \sa SDL_GetRendererInfo
200 211 */ */
201 212 extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window,
202 213 int index, Uint32 flags); int index, Uint32 flags);
203 214
204 215 /** /**
205 * \brief Create a 2D software rendering context for a surface.
216 * Create a 2D software rendering context for a surface.
206 217 * *
207 * \param surface The surface where rendering is done.
218 * Two other API which can be used to create SDL_Renderer:
219 * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
220 * create a software renderer, but they are intended to be used with an
221 * SDL_Window as the final destination and not an SDL_Surface.
208 222 * *
209 * \return A valid rendering context or NULL if there was an error.
223 * \param surface the SDL_Surface structure representing the surface where
224 * rendering is done
225 * \returns a valid rendering context or NULL if there was an error; call
226 * SDL_GetError() for more information.
210 227 * *
211 * \sa SDL_CreateRenderer()
212 * \sa SDL_DestroyRenderer()
228 * \sa SDL_CreateRenderer
229 * \sa SDL_CreateWindowRenderer
230 * \sa SDL_DestroyRenderer
213 231 */ */
214 232 extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface); extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface);
215 233
216 234 /** /**
217 * \brief Get the renderer associated with a window.
235 * Get the renderer associated with a window.
236 *
237 * \param window the window to query
238 * \returns the rendering context on success or NULL on failure; call
239 * SDL_GetError() for more information.
240 *
241 * \sa SDL_CreateRenderer
218 242 */ */
219 243 extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window); extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window);
220 244
221 245 /** /**
222 * \brief Get information about a rendering context.
246 * Get information about a rendering context.
247 *
248 * \param renderer the rendering context
249 * \param info an SDL_RendererInfo structure filled with information about the
250 * current renderer
251 * \returns 0 on success or a negative error code on failure; call
252 * SDL_GetError() for more information.
253 *
254 * \sa SDL_CreateRenderer
223 255 */ */
224 256 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer,
225 257 SDL_RendererInfo * info); SDL_RendererInfo * info);
226 258
227 259 /** /**
228 * \brief Get the output size in pixels of a rendering context.
260 * Get the output size in pixels of a rendering context.
261 *
262 * Due to high-dpi displays, you might end up with a rendering context that
263 * has more pixels than the window that contains it, so use this instead of
264 * SDL_GetWindowSize() to decide how much drawing area you have.
265 *
266 * \param renderer the rendering context
267 * \param w an int filled with the width
268 * \param h an int filled with the height
269 * \returns 0 on success or a negative error code on failure; call
270 * SDL_GetError() for more information.
271 *
272 * \since This function is available since SDL 2.0.0.
273 *
274 * \sa SDL_GetRenderer
229 275 */ */
230 276 extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer,
231 277 int *w, int *h); int *w, int *h);
232 278
233 279 /** /**
234 * \brief Create a texture for a rendering context.
235 *
236 * \param renderer The renderer.
237 * \param format The format of the texture.
238 * \param access One of the enumerated values in ::SDL_TextureAccess.
239 * \param w The width of the texture in pixels.
240 * \param h The height of the texture in pixels.
280 * Create a texture for a rendering context.
241 281 * *
242 * \return The created texture is returned, or NULL if no rendering context was
243 * active, the format was unsupported, or the width or height were out
244 * of range.
282 * You can set the texture scaling method by setting
283 * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture.
245 284 * *
246 * \note The contents of the texture are not defined at creation.
285 * \param renderer the rendering context
286 * \param format one of the enumerated values in SDL_PixelFormatEnum
287 * \param access one of the enumerated values in SDL_TextureAccess
288 * \param w the width of the texture in pixels
289 * \param h the height of the texture in pixels
290 * \returns a pointer to the created texture or NULL if no rendering context
291 * was active, the format was unsupported, or the width or height
292 * were out of range; call SDL_GetError() for more information.
247 293 * *
248 * \sa SDL_QueryTexture()
249 * \sa SDL_UpdateTexture()
250 * \sa SDL_DestroyTexture()
294 * \sa SDL_CreateTextureFromSurface
295 * \sa SDL_DestroyTexture
296 * \sa SDL_QueryTexture
297 * \sa SDL_UpdateTexture
251 298 */ */
252 299 extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
253 300 Uint32 format, Uint32 format,
 
... ... extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
255 302 int h); int h);
256 303
257 304 /** /**
258 * \brief Create a texture from an existing surface.
305 * Create a texture from an existing surface.
306 *
307 * The surface is not modified or freed by this function.
259 308 * *
260 * \param renderer The renderer.
261 * \param surface The surface containing pixel data used to fill the texture.
309 * The SDL_TextureAccess hint for the created texture is
310 * `SDL_TEXTUREACCESS_STATIC`.
262 311 * *
263 * \return The created texture is returned, or NULL on error.
312 * The pixel format of the created texture may be different from the pixel
313 * format of the surface. Use SDL_QueryTexture() to query the pixel format of
314 * the texture.
264 315 * *
265 * \note The surface is not modified or freed by this function.
316 * \param renderer the rendering context
317 * \param surface the SDL_Surface structure containing pixel data used to fill
318 * the texture
319 * \returns the created texture or NULL on failure; call SDL_GetError() for
320 * more information.
266 321 * *
267 * \sa SDL_QueryTexture()
268 * \sa SDL_DestroyTexture()
322 * \sa SDL_CreateTexture
323 * \sa SDL_DestroyTexture
324 * \sa SDL_QueryTexture
269 325 */ */
270 326 extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface); extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface);
271 327
272 328 /** /**
273 * \brief Query the attributes of a texture
329 * Query the attributes of a texture.
274 330 * *
275 * \param texture A texture to be queried.
276 * \param format A pointer filled in with the raw format of the texture. The
277 * actual format may differ, but pixel transfers will use this
278 * format.
279 * \param access A pointer filled in with the actual access to the texture.
280 * \param w A pointer filled in with the width of the texture in pixels.
281 * \param h A pointer filled in with the height of the texture in pixels.
331 * \param texture the texture to query
332 * \param format a pointer filled in with the raw format of the texture; the
333 * actual format may differ, but pixel transfers will use this
334 * format (one of the SDL_PixelFormatEnum values)
335 * \param access a pointer filled in with the actual access to the texture
336 * (one of the SDL_TextureAccess values)
337 * \param w a pointer filled in with the width of the texture in pixels
338 * \param h a pointer filled in with the height of the texture in pixels
339 * \returns 0 on success or a negative error code on failure; call
340 * SDL_GetError() for more information.
282 341 * *
283 * \return 0 on success, or -1 if the texture is not valid.
342 * \sa SDL_CreateTexture
284 343 */ */
285 344 extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture,
286 345 Uint32 * format, int *access, Uint32 * format, int *access,
287 346 int *w, int *h); int *w, int *h);
288 347
289 348 /** /**
290 * \brief Set an additional color value used in render copy operations.
349 * Set an additional color value multiplied into render copy operations.
291 350 * *
292 * \param texture The texture to update.
293 * \param r The red color value multiplied into copy operations.
294 * \param g The green color value multiplied into copy operations.
295 * \param b The blue color value multiplied into copy operations.
351 * When this texture is rendered, during the copy operation each source color
352 * channel is modulated by the appropriate color value according to the
353 * following formula:
296 354 * *
297 * \return 0 on success, or -1 if the texture is not valid or color modulation
298 * is not supported.
355 * `srcC = srcC * (color / 255)`
299 356 * *
300 * \sa SDL_GetTextureColorMod()
357 * Color modulation is not always supported by the renderer; it will return -1
358 * if color modulation is not supported.
359 *
360 * \param texture the texture to update
361 * \param r the red color value multiplied into copy operations
362 * \param g the green color value multiplied into copy operations
363 * \param b the blue color value multiplied into copy operations
364 * \returns 0 on success or a negative error code on failure; call
365 * SDL_GetError() for more information.
366 *
367 * \sa SDL_GetTextureColorMod
368 * \sa SDL_SetTextureAlphaMod
301 369 */ */
302 370 extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture,
303 371 Uint8 r, Uint8 g, Uint8 b); Uint8 r, Uint8 g, Uint8 b);
304 372
305 373
306 374 /** /**
307 * \brief Get the additional color value used in render copy operations.
375 * Get the additional color value multiplied into render copy operations.
308 376 * *
309 * \param texture The texture to query.
310 * \param r A pointer filled in with the current red color value.
311 * \param g A pointer filled in with the current green color value.
312 * \param b A pointer filled in with the current blue color value.
377 * \param texture the texture to query
378 * \param r a pointer filled in with the current red color value
379 * \param g a pointer filled in with the current green color value
380 * \param b a pointer filled in with the current blue color value
381 * \returns 0 on success or a negative error code on failure; call
382 * SDL_GetError() for more information.
313 383 * *
314 * \return 0 on success, or -1 if the texture is not valid.
315 *
316 * \sa SDL_SetTextureColorMod()
384 * \sa SDL_GetTextureAlphaMod
385 * \sa SDL_SetTextureColorMod
317 386 */ */
318 387 extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture,
319 388 Uint8 * r, Uint8 * g, Uint8 * r, Uint8 * g,
320 389 Uint8 * b); Uint8 * b);
321 390
322 391 /** /**
323 * \brief Set an additional alpha value used in render copy operations.
392 * Set an additional alpha value multiplied into render copy operations.
393 *
394 * When this texture is rendered, during the copy operation the source alpha
395 * value is modulated by this alpha value according to the following formula:
324 396 * *
325 * \param texture The texture to update.
326 * \param alpha The alpha value multiplied into copy operations.
397 * `srcA = srcA * (alpha / 255)`
327 398 * *
328 * \return 0 on success, or -1 if the texture is not valid or alpha modulation
329 * is not supported.
399 * Alpha modulation is not always supported by the renderer; it will return -1
400 * if alpha modulation is not supported.
330 401 * *
331 * \sa SDL_GetTextureAlphaMod()
402 * \param texture the texture to update
403 * \param alpha the source alpha value multiplied into copy operations
404 * \returns 0 on success or a negative error code on failure; call
405 * SDL_GetError() for more information.
406 *
407 * \sa SDL_GetTextureAlphaMod
408 * \sa SDL_SetTextureColorMod
332 409 */ */
333 410 extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
334 411 Uint8 alpha); Uint8 alpha);
335 412
336 413 /** /**
337 * \brief Get the additional alpha value used in render copy operations.
338 *
339 * \param texture The texture to query.
340 * \param alpha A pointer filled in with the current alpha value.
414 * Get the additional alpha value multiplied into render copy operations.
341 415 * *
342 * \return 0 on success, or -1 if the texture is not valid.
416 * \param texture the texture to query
417 * \param alpha a pointer filled in with the current alpha value
418 * \returns 0 on success or a negative error code on failure; call
419 * SDL_GetError() for more information.
343 420 * *
344 * \sa SDL_SetTextureAlphaMod()
421 * \sa SDL_GetTextureColorMod
422 * \sa SDL_SetTextureAlphaMod
345 423 */ */
346 424 extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
347 425 Uint8 * alpha); Uint8 * alpha);
348 426
349 427 /** /**
350 * \brief Set the blend mode used for texture copy operations.
428 * Set the blend mode for a texture, used by SDL_RenderCopy().
351 429 * *
352 * \param texture The texture to update.
353 * \param blendMode ::SDL_BlendMode to use for texture blending.
430 * If the blend mode is not supported, the closest supported mode is chosen
431 * and this function returns -1.
354 432 * *
355 * \return 0 on success, or -1 if the texture is not valid or the blend mode is
356 * not supported.
433 * \param texture the texture to update
434 * \param blendMode the SDL_BlendMode to use for texture blending
435 * \returns 0 on success or a negative error code on failure; call
436 * SDL_GetError() for more information.
357 437 * *
358 * \note If the blend mode is not supported, the closest supported mode is
359 * chosen.
360 *
361 * \sa SDL_GetTextureBlendMode()
438 * \sa SDL_GetTextureBlendMode
439 * \sa SDL_RenderCopy
362 440 */ */
363 441 extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
364 442 SDL_BlendMode blendMode); SDL_BlendMode blendMode);
365 443
366 444 /** /**
367 * \brief Get the blend mode used for texture copy operations.
368 *
369 * \param texture The texture to query.
370 * \param blendMode A pointer filled in with the current blend mode.
445 * Get the blend mode used for texture copy operations.
371 446 * *
372 * \return 0 on success, or -1 if the texture is not valid.
447 * \param texture the texture to query
448 * \param blendMode a pointer filled in with the current SDL_BlendMode
449 * \returns 0 on success or a negative error code on failure; call
450 * SDL_GetError() for more information.
373 451 * *
374 * \sa SDL_SetTextureBlendMode()
452 * \sa SDL_SetTextureBlendMode
375 453 */ */
376 454 extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
377 455 SDL_BlendMode *blendMode); SDL_BlendMode *blendMode);
378 456
379 457 /** /**
380 * \brief Set the scale mode used for texture scale operations.
458 * Set the scale mode used for texture scale operations.
381 459 * *
382 * \param texture The texture to update.
383 * \param scaleMode ::SDL_ScaleMode to use for texture scaling.
460 * If the scale mode is not supported, the closest supported mode is chosen.
384 461 * *
385 * \return 0 on success, or -1 if the texture is not valid.
462 * \param texture The texture to update.
463 * \param scaleMode the SDL_ScaleMode to use for texture scaling.
464 * \returns 0 on success, or -1 if the texture is not valid.
386 465 * *
387 * \note If the scale mode is not supported, the closest supported mode is
388 * chosen.
389 *
390 * \sa SDL_GetTextureScaleMode()
466 * \sa SDL_GetTextureScaleMode
391 467 */ */
392 468 extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
393 469 SDL_ScaleMode scaleMode); SDL_ScaleMode scaleMode);
394 470
395 471 /** /**
396 * \brief Get the scale mode used for texture scale operations.
397 *
398 * \param texture The texture to query.
399 * \param scaleMode A pointer filled in with the current scale mode.
472 * Get the scale mode used for texture scale operations.
400 473 * *
401 * \return 0 on success, or -1 if the texture is not valid.
474 * \param texture the texture to query.
475 * \param scaleMode a pointer filled in with the current scale mode.
476 * \return 0 on success, or -1 if the texture is not valid.
402 477 * *
403 * \sa SDL_SetTextureScaleMode()
478 * \sa SDL_SetTextureScaleMode
404 479 */ */
405 480 extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
406 481 SDL_ScaleMode *scaleMode); SDL_ScaleMode *scaleMode);
407 482
408 483 /** /**
409 * \brief Update the given texture rectangle with new pixel data.
484 * Update the given texture rectangle with new pixel data.
410 485 * *
411 * \param texture The texture to update
412 * \param rect A pointer to the rectangle of pixels to update, or NULL to
413 * update the entire texture.
414 * \param pixels The raw pixel data in the format of the texture.
415 * \param pitch The number of bytes in a row of pixel data, including padding between lines.
486 * The pixel data must be in the pixel format of the texture. Use
487 * SDL_QueryTexture() to query the pixel format of the texture.
416 488 * *
417 * The pixel data must be in the format of the texture. The pixel format can be
418 * queried with SDL_QueryTexture.
489 * This is a fairly slow function, intended for use with static textures that
490 * do not change often.
419 491 * *
420 * \return 0 on success, or -1 if the texture is not valid.
492 * If the texture is intended to be updated often, it is preferred to create
493 * the texture as streaming and use the locking functions referenced below.
494 * While this function will work with streaming textures, for optimization
495 * reasons you may not get the pixels back if you lock the texture afterward.
421 496 * *
422 * \note This is a fairly slow function.
497 * \param texture the texture to update
498 * \param rect an SDL_Rect structure representing the area to update, or NULL
499 * to update the entire texture
500 * \param pixels the raw pixel data in the format of the texture
501 * \param pitch the number of bytes in a row of pixel data, including padding
502 * between lines
503 * \returns 0 on success or a negative error code on failure; call
504 * SDL_GetError() for more information.
505 *
506 * \sa SDL_CreateTexture
507 * \sa SDL_LockTexture
508 * \sa SDL_UnlockTexture
423 509 */ */
424 510 extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
425 511 const SDL_Rect * rect, const SDL_Rect * rect,
426 512 const void *pixels, int pitch); const void *pixels, int pitch);
427 513
428 514 /** /**
429 * \brief Update a rectangle within a planar YV12 or IYUV texture with new pixel data.
515 * Update a rectangle within a planar YV12 or IYUV texture with new pixel
516 * data.
517 *
518 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
519 * block of Y and U/V planes in the proper order, but this function is
520 * available if your pixel data is not contiguous.
430 521 * *
431 * \param texture The texture to update
432 * \param rect A pointer to the rectangle of pixels to update, or NULL to
433 * update the entire texture.
434 * \param Yplane The raw pixel data for the Y plane.
435 * \param Ypitch The number of bytes between rows of pixel data for the Y plane.
436 * \param Uplane The raw pixel data for the U plane.
437 * \param Upitch The number of bytes between rows of pixel data for the U plane.
438 * \param Vplane The raw pixel data for the V plane.
439 * \param Vpitch The number of bytes between rows of pixel data for the V plane.
522 * \param texture the texture to update
523 * \param rect a pointer to the rectangle of pixels to update, or NULL to
524 * update the entire texture
525 * \param Yplane the raw pixel data for the Y plane
526 * \param Ypitch the number of bytes between rows of pixel data for the Y
527 * plane
528 * \param Uplane the raw pixel data for the U plane
529 * \param Upitch the number of bytes between rows of pixel data for the U
530 * plane
531 * \param Vplane the raw pixel data for the V plane
532 * \param Vpitch the number of bytes between rows of pixel data for the V
533 * plane
534 * \returns 0 on success or -1 if the texture is not valid; call
535 * SDL_GetError() for more information.
440 536 * *
441 * \return 0 on success, or -1 if the texture is not valid.
537 * \since This function is available since SDL 2.0.1.
442 538 * *
443 * \note You can use SDL_UpdateTexture() as long as your pixel data is
444 * a contiguous block of Y and U/V planes in the proper order, but
445 * this function is available if your pixel data is not contiguous.
539 * \sa SDL_UpdateTexture
446 540 */ */
447 541 extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
448 542 const SDL_Rect * rect, const SDL_Rect * rect,
 
... ... extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
451 545 const Uint8 *Vplane, int Vpitch); const Uint8 *Vplane, int Vpitch);
452 546
453 547 /** /**
454 * \brief Lock a portion of the texture for write-only pixel access.
548 * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
455 549 * *
456 * \param texture The texture to lock for access, which was created with
457 * ::SDL_TEXTUREACCESS_STREAMING.
458 * \param rect A pointer to the rectangle to lock for access. If the rect
459 * is NULL, the entire texture will be locked.
460 * \param pixels This is filled in with a pointer to the locked pixels,
461 * appropriately offset by the locked area.
462 * \param pitch This is filled in with the pitch of the locked pixels.
550 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
551 * block of NV12/21 planes in the proper order, but this function is available
552 * if your pixel data is not contiguous.
463 553 * *
464 * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
554 * \param texture the texture to update
555 * \param rect a pointer to the rectangle of pixels to update, or NULL to
556 * update the entire texture.
557 * \param Yplane the raw pixel data for the Y plane.
558 * \param Ypitch the number of bytes between rows of pixel data for the Y
559 * plane.
560 * \param UVplane the raw pixel data for the UV plane.
561 * \param UVpitch the number of bytes between rows of pixel data for the UV
562 * plane.
563 * \return 0 on success, or -1 if the texture is not valid.
564 */
565 extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
566 const SDL_Rect * rect,
567 const Uint8 *Yplane, int Ypitch,
568 const Uint8 *UVplane, int UVpitch);
569
570 /**
571 * Lock a portion of the texture for **write-only** pixel access.
572 *
573 * As an optimization, the pixels made available for editing don't necessarily
574 * contain the old texture data. This is a write-only operation, and if you
575 * need to keep a copy of the texture data you should do that at the
576 * application level.
577 *
578 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
579 * changes.
465 580 * *
466 * \sa SDL_UnlockTexture()
581 * \param texture the texture to lock for access, which was created with
582 * `SDL_TEXTUREACCESS_STREAMING`
583 * \param rect an SDL_Rect structure representing the area to lock for access;
584 * NULL to lock the entire texture
585 * \param pixels this is filled in with a pointer to the locked pixels,
586 * appropriately offset by the locked area
587 * \param pitch this is filled in with the pitch of the locked pixels; the
588 * pitch is the length of one row in bytes
589 * \returns 0 on success or a negative error code if the texture is not valid
590 * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
591 * SDL_GetError() for more information.
592 *
593 * \sa SDL_UnlockTexture
467 594 */ */
468 595 extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture, extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
469 596 const SDL_Rect * rect, const SDL_Rect * rect,
470 597 void **pixels, int *pitch); void **pixels, int *pitch);
471 598
472 599 /** /**
473 * \brief Lock a portion of the texture for write-only pixel access.
474 * Expose it as a SDL surface.
600 * Lock a portion of the texture for **write-only** pixel access, and expose
601 * it as a SDL surface.
602 *
603 * Besides providing an SDL_Surface instead of raw pixel data, this function
604 * operates like SDL_LockTexture.
605 *
606 * As an optimization, the pixels made available for editing don't necessarily
607 * contain the old texture data. This is a write-only operation, and if you
608 * need to keep a copy of the texture data you should do that at the
609 * application level.
610 *
611 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
612 * changes.
475 613 * *
476 * \param texture The texture to lock for access, which was created with
477 * ::SDL_TEXTUREACCESS_STREAMING.
478 * \param rect A pointer to the rectangle to lock for access. If the rect
479 * is NULL, the entire texture will be locked.
480 * \param surface This is filled in with a SDL surface representing the locked area
481 * Surface is freed internally after calling SDL_UnlockTexture or SDL_DestroyTexture.
614 * The returned surface is freed internally after calling SDL_UnlockTexture()
615 * or SDL_DestroyTexture(). The caller should not free it.
482 616 * *
483 * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
617 * \param texture the texture to lock for access, which was created with
618 * `SDL_TEXTUREACCESS_STREAMING`
619 * \param rect a pointer to the rectangle to lock for access. If the rect is
620 * NULL, the entire texture will be locked
621 * \param surface this is filled in with an SDL surface representing the
622 * locked area
623 * \returns 0 on success, or -1 if the texture is not valid or was not created
624 * with `SDL_TEXTUREACCESS_STREAMING`
484 625 * *
485 * \sa SDL_UnlockTexture()
626 * \sa SDL_LockTexture
627 * \sa SDL_UnlockTexture
486 628 */ */
487 629 extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
488 630 const SDL_Rect *rect, const SDL_Rect *rect,
489 631 SDL_Surface **surface); SDL_Surface **surface);
490 632
491 633 /** /**
492 * \brief Unlock a texture, uploading the changes to video memory, if needed.
493 * If SDL_LockTextureToSurface() was called for locking, the SDL surface is freed.
634 * Unlock a texture, uploading the changes to video memory, if needed.
494 635 * *
495 * \sa SDL_LockTexture()
496 * \sa SDL_LockTextureToSurface()
636 * **Warning**: Please note that SDL_LockTexture() is intended to be
637 * write-only; it will notguarantee the previous contents of the texture will
638 * be provided. You must fully initialize any area of a texture that you lock
639 * before unlocking it, as the pixels might otherwise be uninitialized memory.
640 *
641 * Which is to say: locking and immediately unlocking a texture can result in
642 * corrupted textures, depending on the renderer in use.
643 *
644 * \param texture a texture locked by SDL_LockTexture()
645 *
646 * \sa SDL_LockTexture
497 647 */ */
498 648 extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture);
499 649
500 650 /** /**
501 * \brief Determines whether a window supports the use of render targets
651 * Determine whether a renderer supports the use of render targets.
652 *
653 * \param renderer the renderer that will be checked
654 * \returns SDL_TRUE if supported or SDL_FALSE if not.
502 655 * *
503 * \param renderer The renderer that will be checked
656 * \since This function is available since SDL 2.0.0.
504 657 * *
505 * \return SDL_TRUE if supported, SDL_FALSE if not.
658 * \sa SDL_SetRenderTarget
506 659 */ */
507 660 extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer); extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer);
508 661
509 662 /** /**
510 * \brief Set a texture as the current rendering target.
663 * Set a texture as the current rendering target.
511 664 * *
512 * \param renderer The renderer.
513 * \param texture The targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL for the default render target
665 * Before using this function, you should check the
666 * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
667 * render targets are supported.
514 668 * *
515 * \return 0 on success, or -1 on error
669 * The default render target is the window for which the renderer was created.
670 * To stop rendering to a texture and render to the window again, call this
671 * function with a NULL `texture`.
672 *
673 * \param renderer the rendering context
674 * \param texture the targeted texture, which must be created with the
675 * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
676 * window instead of a texture.
677 * \returns 0 on success or a negative error code on failure; call
678 * SDL_GetError() for more information.
679 *
680 * \since This function is available since SDL 2.0.0.
516 681 * *
517 * \sa SDL_GetRenderTarget()
682 * \sa SDL_GetRenderTarget
518 683 */ */
519 684 extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer,
520 685 SDL_Texture *texture); SDL_Texture *texture);
521 686
522 687 /** /**
523 * \brief Get the current render target or NULL for the default render target.
688 * Get the current render target.
524 689 * *
525 * \return The current render target
690 * The default render target is the window for which the renderer was created,
691 * and is reported a NULL here.
526 692 * *
527 * \sa SDL_SetRenderTarget()
693 * \param renderer the rendering context
694 * \returns the current render target or NULL for the default render target.
695 *
696 * \since This function is available since SDL 2.0.0.
697 *
698 * \sa SDL_SetRenderTarget
528 699 */ */
529 700 extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer); extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
530 701
531 702 /** /**
532 * \brief Set device independent resolution for rendering
703 * Set a device independent resolution for rendering.
533 704 * *
534 * \param renderer The renderer for which resolution should be set.
535 * \param w The width of the logical resolution
536 * \param h The height of the logical resolution
705 * This function uses the viewport and scaling functionality to allow a fixed
706 * logical resolution for rendering, regardless of the actual output
707 * resolution. If the actual output resolution doesn't have the same aspect
708 * ratio the output rendering will be centered within the output display.
537 709 * *
538 * This function uses the viewport and scaling functionality to allow a fixed logical
539 * resolution for rendering, regardless of the actual output resolution. If the actual
540 * output resolution doesn't have the same aspect ratio the output rendering will be
541 * centered within the output display.
710 * If the output display is a window, mouse and touch events in the window
711 * will be filtered and scaled so they seem to arrive within the logical
712 * resolution. The SDL_HINT_MOUSE_RELATIVE_SCALING hint controls whether
713 * relative motion events are also scaled.
542 714 * *
543 * If the output display is a window, mouse events in the window will be filtered
544 * and scaled so they seem to arrive within the logical resolution.
715 * If this function results in scaling or subpixel drawing by the rendering
716 * backend, it will be handled using the appropriate quality hints.
545 717 * *
546 * \note If this function results in scaling or subpixel drawing by the
547 * rendering backend, it will be handled using the appropriate
548 * quality hints.
718 * \param renderer the renderer for which resolution should be set
719 * \param w the width of the logical resolution
720 * \param h the height of the logical resolution
721 * \returns 0 on success or a negative error code on failure; call
722 * SDL_GetError() for more information.
549 723 * *
550 * \sa SDL_RenderGetLogicalSize()
551 * \sa SDL_RenderSetScale()
552 * \sa SDL_RenderSetViewport()
724 * \since This function is available since SDL 2.0.0.
725 *
726 * \sa SDL_RenderGetLogicalSize
553 727 */ */
554 728 extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h); extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h);
555 729
556 730 /** /**
557 * \brief Get device independent resolution for rendering
731 * Get device independent resolution for rendering.
732 *
733 * This may return 0 for `w` and `h` if the SDL_Renderer has never had its
734 * logical size set by SDL_RenderSetLogicalSize() and never had a render
735 * target set.
558 736 * *
559 * \param renderer The renderer from which resolution should be queried.
560 * \param w A pointer filled with the width of the logical resolution
561 * \param h A pointer filled with the height of the logical resolution
737 * \param renderer a rendering context
738 * \param w an int to be filled with the width
739 * \param h an int to be filled with the height
562 740 * *
563 * \sa SDL_RenderSetLogicalSize()
741 * \since This function is available since SDL 2.0.0.
742 *
743 * \sa SDL_RenderSetLogicalSize
564 744 */ */
565 745 extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h); extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h);
566 746
567 747 /** /**
568 * \brief Set whether to force integer scales for resolution-independent rendering
748 * Set whether to force integer scales for resolution-independent rendering.
749 *
750 * This function restricts the logical viewport to integer values - that is,
751 * when a resolution is between two multiples of a logical size, the viewport
752 * size is rounded down to the lower multiple.
569 753 * *
570 * \param renderer The renderer for which integer scaling should be set.
571 * \param enable Enable or disable integer scaling
754 * \param renderer the renderer for which integer scaling should be set
755 * \param enable enable or disable the integer scaling for rendering
756 * \returns 0 on success or a negative error code on failure; call
757 * SDL_GetError() for more information.
572 758 * *
573 * This function restricts the logical viewport to integer values - that is, when
574 * a resolution is between two multiples of a logical size, the viewport size is
575 * rounded down to the lower multiple.
759 * \since This function is available since SDL 2.0.5.
576 760 * *
577 * \sa SDL_RenderSetLogicalSize()
761 * \sa SDL_RenderGetIntegerScale
762 * \sa SDL_RenderSetLogicalSize
578 763 */ */
579 764 extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer,
580 765 SDL_bool enable); SDL_bool enable);
581 766
582 767 /** /**
583 * \brief Get whether integer scales are forced for resolution-independent rendering
768 * Get whether integer scales are forced for resolution-independent rendering.
769 *
770 * \param renderer the renderer from which integer scaling should be queried
771 * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on
772 * failure; call SDL_GetError() for more information.
584 773 * *
585 * \param renderer The renderer from which integer scaling should be queried.
774 * \since This function is available since SDL 2.0.5.
586 775 * *
587 * \sa SDL_RenderSetIntegerScale()
776 * \sa SDL_RenderSetIntegerScale
588 777 */ */
589 778 extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer); extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer);
590 779
591 780 /** /**
592 * \brief Set the drawing area for rendering on the current target.
781 * Set the drawing area for rendering on the current target.
593 782 * *
594 * \param renderer The renderer for which the drawing area should be set.
595 * \param rect The rectangle representing the drawing area, or NULL to set the viewport to the entire target.
783 * When the window is resized, the viewport is reset to fill the entire new
784 * window size.
596 785 * *
597 * The x,y of the viewport rect represents the origin for rendering.
786 * \param renderer the rendering context
787 * \param rect the SDL_Rect structure representing the drawing area, or NULL
788 * to set the viewport to the entire target
789 * \returns 0 on success or a negative error code on failure; call
790 * SDL_GetError() for more information.
598 791 * *
599 * \return 0 on success, or -1 on error
600 *
601 * \note If the window associated with the renderer is resized, the viewport is automatically reset.
602 *
603 * \sa SDL_RenderGetViewport()
604 * \sa SDL_RenderSetLogicalSize()
792 * \sa SDL_RenderGetViewport
605 793 */ */
606 794 extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer,
607 795 const SDL_Rect * rect); const SDL_Rect * rect);
608 796
609 797 /** /**
610 * \brief Get the drawing area for the current target.
798 * Get the drawing area for the current target.
611 799 * *
612 * \sa SDL_RenderSetViewport()
800 * \param renderer the rendering context
801 * \param rect an SDL_Rect structure filled in with the current drawing area
802 *
803 * \sa SDL_RenderSetViewport
613 804 */ */
614 805 extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer,
615 806 SDL_Rect * rect); SDL_Rect * rect);
616 807
617 808 /** /**
618 * \brief Set the clip rectangle for the current target.
619 *
620 * \param renderer The renderer for which clip rectangle should be set.
621 * \param rect A pointer to the rectangle to set as the clip rectangle,
622 * relative to the viewport, or NULL to disable clipping.
809 * Set the clip rectangle for rendering on the specified target.
623 810 * *
624 * \return 0 on success, or -1 on error
811 * \param renderer the rendering context for which clip rectangle should be
812 * set
813 * \param rect an SDL_Rect structure representing the clip area, relative to
814 * the viewport, or NULL to disable clipping
815 * \returns 0 on success or a negative error code on failure; call
816 * SDL_GetError() for more information.
625 817 * *
626 * \sa SDL_RenderGetClipRect()
818 * \sa SDL_RenderGetClipRect
819 * \sa SDL_RenderIsClipEnabled
627 820 */ */
628 821 extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer,
629 822 const SDL_Rect * rect); const SDL_Rect * rect);
630 823
631 824 /** /**
632 * \brief Get the clip rectangle for the current target.
825 * Get the clip rectangle for the current target.
633 826 * *
634 * \param renderer The renderer from which clip rectangle should be queried.
635 * \param rect A pointer filled in with the current clip rectangle, or
636 * an empty rectangle if clipping is disabled.
827 * \param renderer the rendering context from which clip rectangle should be
828 * queried
829 * \param rect an SDL_Rect structure filled in with the current clipping area
830 * or an empty rectangle if clipping is disabled
637 831 * *
638 * \sa SDL_RenderSetClipRect()
832 * \sa SDL_RenderIsClipEnabled
833 * \sa SDL_RenderSetClipRect
639 834 */ */
640 835 extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer, extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
641 836 SDL_Rect * rect); SDL_Rect * rect);
642 837
643 838 /** /**
644 * \brief Get whether clipping is enabled on the given renderer.
839 * Get whether clipping is enabled on the given renderer.
645 840 * *
646 * \param renderer The renderer from which clip state should be queried.
841 * \param renderer the renderer from which clip state should be queried
842 * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
843 * SDL_GetError() for more information.
647 844 * *
648 * \sa SDL_RenderGetClipRect()
845 * \since This function is available since SDL 2.0.4.
846 *
847 * \sa SDL_RenderGetClipRect
848 * \sa SDL_RenderSetClipRect
649 849 */ */
650 850 extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer); extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer);
651 851
652 852
653 853 /** /**
654 * \brief Set the drawing scale for rendering on the current target.
854 * Set the drawing scale for rendering on the current target.
855 *
856 * The drawing coordinates are scaled by the x/y scaling factors before they
857 * are used by the renderer. This allows resolution independent drawing with a
858 * single coordinate system.
655 859 * *
656 * \param renderer The renderer for which the drawing scale should be set.
657 * \param scaleX The horizontal scaling factor
658 * \param scaleY The vertical scaling factor
860 * If this results in scaling or subpixel drawing by the rendering backend, it
861 * will be handled using the appropriate quality hints. For best results use
862 * integer scaling factors.
659 863 * *
660 * The drawing coordinates are scaled by the x/y scaling factors
661 * before they are used by the renderer. This allows resolution
662 * independent drawing with a single coordinate system.
864 * \param renderer a rendering context
865 * \param scaleX the horizontal scaling factor
866 * \param scaleY the vertical scaling factor
867 * \returns 0 on success or a negative error code on failure; call
868 * SDL_GetError() for more information.
663 869 * *
664 * \note If this results in scaling or subpixel drawing by the
665 * rendering backend, it will be handled using the appropriate
666 * quality hints. For best results use integer scaling factors.
870 * \since This function is available since SDL 2.0.0.
667 871 * *
668 * \sa SDL_RenderGetScale()
669 * \sa SDL_RenderSetLogicalSize()
872 * \sa SDL_RenderGetScale
873 * \sa SDL_RenderSetLogicalSize
670 874 */ */
671 875 extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer,
672 876 float scaleX, float scaleY); float scaleX, float scaleY);
673 877
674 878 /** /**
675 * \brief Get the drawing scale for the current target.
879 * Get the drawing scale for the current target.
880 *
881 * \param renderer the renderer from which drawing scale should be queried
882 * \param scaleX a pointer filled in with the horizontal scaling factor
883 * \param scaleY a pointer filled in with the vertical scaling factor
676 884 * *
677 * \param renderer The renderer from which drawing scale should be queried.
678 * \param scaleX A pointer filled in with the horizontal scaling factor
679 * \param scaleY A pointer filled in with the vertical scaling factor
885 * \since This function is available since SDL 2.0.0.
680 886 * *
681 * \sa SDL_RenderSetScale()
887 * \sa SDL_RenderSetScale
682 888 */ */
683 889 extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
684 890 float *scaleX, float *scaleY); float *scaleX, float *scaleY);
685 891
686 892 /** /**
687 * \brief Set the color used for drawing operations (Rect, Line and Clear).
688 *
689 * \param renderer The renderer for which drawing color should be set.
690 * \param r The red value used to draw on the rendering target.
691 * \param g The green value used to draw on the rendering target.
692 * \param b The blue value used to draw on the rendering target.
693 * \param a The alpha value used to draw on the rendering target, usually
694 * ::SDL_ALPHA_OPAQUE (255).
695 *
696 * \return 0 on success, or -1 on error
893 * Set the color used for drawing operations (Rect, Line and Clear).
894 *
895 * Set the color for drawing or filling rectangles, lines, and points, and for
896 * SDL_RenderClear().
897 *
898 * \param renderer the rendering context
899 * \param r the red value used to draw on the rendering target
900 * \param g the green value used to draw on the rendering target
901 * \param b the blue value used to draw on the rendering target
902 * \param a the alpha value used to draw on the rendering target; usually
903 * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
904 * specify how the alpha channel is used
905 * \returns 0 on success or a negative error code on failure; call
906 * SDL_GetError() for more information.
907 *
908 * \sa SDL_GetRenderDrawColor
909 * \sa SDL_RenderClear
910 * \sa SDL_RenderDrawLine
911 * \sa SDL_RenderDrawLines
912 * \sa SDL_RenderDrawPoint
913 * \sa SDL_RenderDrawPoints
914 * \sa SDL_RenderDrawRect
915 * \sa SDL_RenderDrawRects
916 * \sa SDL_RenderFillRect
917 * \sa SDL_RenderFillRects
697 918 */ */
698 919 extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer,
699 920 Uint8 r, Uint8 g, Uint8 b, Uint8 r, Uint8 g, Uint8 b,
700 921 Uint8 a); Uint8 a);
701 922
702 923 /** /**
703 * \brief Get the color used for drawing operations (Rect, Line and Clear).
924 * Get the color used for drawing operations (Rect, Line and Clear).
704 925 * *
705 * \param renderer The renderer from which drawing color should be queried.
706 * \param r A pointer to the red value used to draw on the rendering target.
707 * \param g A pointer to the green value used to draw on the rendering target.
708 * \param b A pointer to the blue value used to draw on the rendering target.
709 * \param a A pointer to the alpha value used to draw on the rendering target,
710 * usually ::SDL_ALPHA_OPAQUE (255).
926 * \param renderer the rendering context
927 * \param r a pointer filled in with the red value used to draw on the
928 * rendering target
929 * \param g a pointer filled in with the green value used to draw on the
930 * rendering target
931 * \param b a pointer filled in with the blue value used to draw on the
932 * rendering target
933 * \param a a pointer filled in with the alpha value used to draw on the
934 * rendering target; usually `SDL_ALPHA_OPAQUE` (255)
935 * \returns 0 on success or a negative error code on failure; call
936 * SDL_GetError() for more information.
711 937 * *
712 * \return 0 on success, or -1 on error
938 * \sa SDL_SetRenderDrawColor
713 939 */ */
714 940 extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer,
715 941 Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * r, Uint8 * g, Uint8 * b,
716 942 Uint8 * a); Uint8 * a);
717 943
718 944 /** /**
719 * \brief Set the blend mode used for drawing operations (Fill and Line).
945 * Set the blend mode used for drawing operations (Fill and Line).
720 946 * *
721 * \param renderer The renderer for which blend mode should be set.
722 * \param blendMode ::SDL_BlendMode to use for blending.
947 * If the blend mode is not supported, the closest supported mode is chosen.
723 948 * *
724 * \return 0 on success, or -1 on error
949 * \param renderer the rendering context
950 * \param blendMode the SDL_BlendMode to use for blending
951 * \returns 0 on success or a negative error code on failure; call
952 * SDL_GetError() for more information.
725 953 * *
726 * \note If the blend mode is not supported, the closest supported mode is
727 * chosen.
728 *
729 * \sa SDL_GetRenderDrawBlendMode()
954 * \sa SDL_GetRenderDrawBlendMode
955 * \sa SDL_RenderDrawLine
956 * \sa SDL_RenderDrawLines
957 * \sa SDL_RenderDrawPoint
958 * \sa SDL_RenderDrawPoints
959 * \sa SDL_RenderDrawRect
960 * \sa SDL_RenderDrawRects
961 * \sa SDL_RenderFillRect
962 * \sa SDL_RenderFillRects
730 963 */ */
731 964 extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer,
732 965 SDL_BlendMode blendMode); SDL_BlendMode blendMode);
733 966
734 967 /** /**
735 * \brief Get the blend mode used for drawing operations.
736 *
737 * \param renderer The renderer from which blend mode should be queried.
738 * \param blendMode A pointer filled in with the current blend mode.
968 * Get the blend mode used for drawing operations.
739 969 * *
740 * \return 0 on success, or -1 on error
970 * \param renderer the rendering context
971 * \param blendMode a pointer filled in with the current SDL_BlendMode
972 * \returns 0 on success or a negative error code on failure; call
973 * SDL_GetError() for more information.
741 974 * *
742 * \sa SDL_SetRenderDrawBlendMode()
975 * \sa SDL_SetRenderDrawBlendMode
743 976 */ */
744 977 extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer,
745 978 SDL_BlendMode *blendMode); SDL_BlendMode *blendMode);
746 979
747 980 /** /**
748 * \brief Clear the current rendering target with the drawing color
981 * Clear the current rendering target with the drawing color.
749 982 * *
750 * This function clears the entire rendering target, ignoring the viewport and
751 * the clip rectangle.
983 * This function clears the entire rendering target, ignoring the viewport and
984 * the clip rectangle.
752 985 * *
753 * \return 0 on success, or -1 on error
986 * \param renderer the rendering context
987 * \returns 0 on success or a negative error code on failure; call
988 * SDL_GetError() for more information.
989 *
990 * \since This function is available since SDL 2.0.0.
991 *
992 * \sa SDL_SetRenderDrawColor
754 993 */ */
755 994 extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer);
756 995
757 996 /** /**
758 * \brief Draw a point on the current rendering target.
997 * Draw a point on the current rendering target.
759 998 * *
760 * \param renderer The renderer which should draw a point.
761 * \param x The x coordinate of the point.
762 * \param y The y coordinate of the point.
999 * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple,
1000 * use SDL_RenderDrawPoints() instead.
763 1001 * *
764 * \return 0 on success, or -1 on error
1002 * \param renderer the rendering context
1003 * \param x the x coordinate of the point
1004 * \param y the y coordinate of the point
1005 * \returns 0 on success or a negative error code on failure; call
1006 * SDL_GetError() for more information.
1007 *
1008 * \sa SDL_RenderDrawLine
1009 * \sa SDL_RenderDrawLines
1010 * \sa SDL_RenderDrawPoints
1011 * \sa SDL_RenderDrawRect
1012 * \sa SDL_RenderDrawRects
1013 * \sa SDL_RenderFillRect
1014 * \sa SDL_RenderFillRects
1015 * \sa SDL_RenderPresent
1016 * \sa SDL_SetRenderDrawBlendMode
1017 * \sa SDL_SetRenderDrawColor
765 1018 */ */
766 1019 extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer,
767 1020 int x, int y); int x, int y);
768 1021
769 1022 /** /**
770 * \brief Draw multiple points on the current rendering target.
1023 * Draw multiple points on the current rendering target.
771 1024 * *
772 * \param renderer The renderer which should draw multiple points.
773 * \param points The points to draw
774 * \param count The number of points to draw
1025 * \param renderer the rendering context
1026 * \param points an array of SDL_Point structures that represent the points to
1027 * draw
1028 * \param count the number of points to draw
1029 * \returns 0 on success or a negative error code on failure; call
1030 * SDL_GetError() for more information.
775 1031 * *
776 * \return 0 on success, or -1 on error
1032 * \sa SDL_RenderDrawLine
1033 * \sa SDL_RenderDrawLines
1034 * \sa SDL_RenderDrawPoint
1035 * \sa SDL_RenderDrawRect
1036 * \sa SDL_RenderDrawRects
1037 * \sa SDL_RenderFillRect
1038 * \sa SDL_RenderFillRects
1039 * \sa SDL_RenderPresent
1040 * \sa SDL_SetRenderDrawBlendMode
1041 * \sa SDL_SetRenderDrawColor
777 1042 */ */
778 1043 extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer,
779 1044 const SDL_Point * points, const SDL_Point * points,
780 1045 int count); int count);
781 1046
782 1047 /** /**
783 * \brief Draw a line on the current rendering target.
1048 * Draw a line on the current rendering target.
1049 *
1050 * SDL_RenderDrawLine() draws the line to include both end points. If you want
1051 * to draw multiple, connecting lines use SDL_RenderDrawLines() instead.
784 1052 * *
785 * \param renderer The renderer which should draw a line.
786 * \param x1 The x coordinate of the start point.
787 * \param y1 The y coordinate of the start point.
788 * \param x2 The x coordinate of the end point.
789 * \param y2 The y coordinate of the end point.
1053 * \param renderer the rendering context
1054 * \param x1 the x coordinate of the start point
1055 * \param y1 the y coordinate of the start point
1056 * \param x2 the x coordinate of the end point
1057 * \param y2 the y coordinate of the end point
1058 * \returns 0 on success or a negative error code on failure; call
1059 * SDL_GetError() for more information.
790 1060 * *
791 * \return 0 on success, or -1 on error
1061 * \since This function is available since SDL 2.0.0.
1062 *
1063 * \sa SDL_RenderDrawLines
1064 * \sa SDL_RenderDrawPoint
1065 * \sa SDL_RenderDrawPoints
1066 * \sa SDL_RenderDrawRect
1067 * \sa SDL_RenderDrawRects
1068 * \sa SDL_RenderFillRect
1069 * \sa SDL_RenderFillRects
1070 * \sa SDL_RenderPresent
1071 * \sa SDL_SetRenderDrawBlendMode
1072 * \sa SDL_SetRenderDrawColor
792 1073 */ */
793 1074 extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer,
794 1075 int x1, int y1, int x2, int y2); int x1, int y1, int x2, int y2);
795 1076
796 1077 /** /**
797 * \brief Draw a series of connected lines on the current rendering target.
1078 * Draw a series of connected lines on the current rendering target.
1079 *
1080 * \param renderer the rendering context
1081 * \param points an array of SDL_Point structures representing points along
1082 * the lines
1083 * \param count the number of points, drawing count-1 lines
1084 * \returns 0 on success or a negative error code on failure; call
1085 * SDL_GetError() for more information.
798 1086 * *
799 * \param renderer The renderer which should draw multiple lines.
800 * \param points The points along the lines
801 * \param count The number of points, drawing count-1 lines
1087 * \since This function is available since SDL 2.0.0.
802 1088 * *
803 * \return 0 on success, or -1 on error
1089 * \sa SDL_RenderDrawLine
1090 * \sa SDL_RenderDrawPoint
1091 * \sa SDL_RenderDrawPoints
1092 * \sa SDL_RenderDrawRect
1093 * \sa SDL_RenderDrawRects
1094 * \sa SDL_RenderFillRect
1095 * \sa SDL_RenderFillRects
1096 * \sa SDL_RenderPresent
1097 * \sa SDL_SetRenderDrawBlendMode
1098 * \sa SDL_SetRenderDrawColor
804 1099 */ */
805 1100 extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer,
806 1101 const SDL_Point * points, const SDL_Point * points,
807 1102 int count); int count);
808 1103
809 1104 /** /**
810 * \brief Draw a rectangle on the current rendering target.
1105 * Draw a rectangle on the current rendering target.
811 1106 * *
812 * \param renderer The renderer which should draw a rectangle.
813 * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
1107 * \param renderer the rendering context
1108 * \param rect an SDL_Rect structure representing the rectangle to draw, or
1109 * NULL to outline the entire rendering target
1110 * \returns 0 on success or a negative error code on failure; call
1111 * SDL_GetError() for more information.
814 1112 * *
815 * \return 0 on success, or -1 on error
1113 * \sa SDL_RenderDrawLine
1114 * \sa SDL_RenderDrawLines
1115 * \sa SDL_RenderDrawPoint
1116 * \sa SDL_RenderDrawPoints
1117 * \sa SDL_RenderDrawRects
1118 * \sa SDL_RenderFillRect
1119 * \sa SDL_RenderFillRects
1120 * \sa SDL_RenderPresent
1121 * \sa SDL_SetRenderDrawBlendMode
1122 * \sa SDL_SetRenderDrawColor
816 1123 */ */
817 1124 extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer,
818 1125 const SDL_Rect * rect); const SDL_Rect * rect);
819 1126
820 1127 /** /**
821 * \brief Draw some number of rectangles on the current rendering target.
1128 * Draw some number of rectangles on the current rendering target.
822 1129 * *
823 * \param renderer The renderer which should draw multiple rectangles.
824 * \param rects A pointer to an array of destination rectangles.
825 * \param count The number of rectangles.
1130 * \param renderer the rendering context
1131 * \param rects an array of SDL_Rect structures representing the rectangles to
1132 * be drawn
1133 * \param count the number of rectangles
1134 * \returns 0 on success or a negative error code on failure; call
1135 * SDL_GetError() for more information.
826 1136 * *
827 * \return 0 on success, or -1 on error
1137 * \sa SDL_RenderDrawLine
1138 * \sa SDL_RenderDrawLines
1139 * \sa SDL_RenderDrawPoint
1140 * \sa SDL_RenderDrawPoints
1141 * \sa SDL_RenderDrawRect
1142 * \sa SDL_RenderFillRect
1143 * \sa SDL_RenderFillRects
1144 * \sa SDL_RenderPresent
1145 * \sa SDL_SetRenderDrawBlendMode
1146 * \sa SDL_SetRenderDrawColor
828 1147 */ */
829 1148 extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer,
830 1149 const SDL_Rect * rects, const SDL_Rect * rects,
831 1150 int count); int count);
832 1151
833 1152 /** /**
834 * \brief Fill a rectangle on the current rendering target with the drawing color.
1153 * Fill a rectangle on the current rendering target with the drawing color.
835 1154 * *
836 * \param renderer The renderer which should fill a rectangle.
837 * \param rect A pointer to the destination rectangle, or NULL for the entire
838 * rendering target.
1155 * The current drawing color is set by SDL_SetRenderDrawColor(), and the
1156 * color's alpha value is ignored unless blending is enabled with the
1157 * appropriate call to SDL_SetRenderDrawBlendMode().
839 1158 * *
840 * \return 0 on success, or -1 on error
1159 * \param renderer the rendering context
1160 * \param rect the SDL_Rect structure representing the rectangle to fill, or
1161 * NULL for the entire rendering target
1162 * \returns 0 on success or a negative error code on failure; call
1163 * SDL_GetError() for more information.
1164 *
1165 * \sa SDL_RenderDrawLine
1166 * \sa SDL_RenderDrawLines
1167 * \sa SDL_RenderDrawPoint
1168 * \sa SDL_RenderDrawPoints
1169 * \sa SDL_RenderDrawRect
1170 * \sa SDL_RenderDrawRects
1171 * \sa SDL_RenderFillRects
1172 * \sa SDL_RenderPresent
1173 * \sa SDL_SetRenderDrawBlendMode
1174 * \sa SDL_SetRenderDrawColor
841 1175 */ */
842 1176 extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer,
843 1177 const SDL_Rect * rect); const SDL_Rect * rect);
844 1178
845 1179 /** /**
846 * \brief Fill some number of rectangles on the current rendering target with the drawing color.
1180 * Fill some number of rectangles on the current rendering target with the
1181 * drawing color.
847 1182 * *
848 * \param renderer The renderer which should fill multiple rectangles.
849 * \param rects A pointer to an array of destination rectangles.
850 * \param count The number of rectangles.
1183 * \param renderer the rendering context
1184 * \param rects an array of SDL_Rect structures representing the rectangles to
1185 * be filled
1186 * \param count the number of rectangles
1187 * \returns 0 on success or a negative error code on failure; call
1188 * SDL_GetError() for more information.
851 1189 * *
852 * \return 0 on success, or -1 on error
1190 * \sa SDL_RenderDrawLine
1191 * \sa SDL_RenderDrawLines
1192 * \sa SDL_RenderDrawPoint
1193 * \sa SDL_RenderDrawPoints
1194 * \sa SDL_RenderDrawRect
1195 * \sa SDL_RenderDrawRects
1196 * \sa SDL_RenderFillRect
1197 * \sa SDL_RenderPresent
853 1198 */ */
854 1199 extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer,
855 1200 const SDL_Rect * rects, const SDL_Rect * rects,
856 1201 int count); int count);
857 1202
858 1203 /** /**
859 * \brief Copy a portion of the texture to the current rendering target.
1204 * Copy a portion of the texture to the current rendering target.
1205 *
1206 * The texture is blended with the destination based on its blend mode set
1207 * with SDL_SetTextureBlendMode().
860 1208 * *
861 * \param renderer The renderer which should copy parts of a texture.
862 * \param texture The source texture.
863 * \param srcrect A pointer to the source rectangle, or NULL for the entire
864 * texture.
865 * \param dstrect A pointer to the destination rectangle, or NULL for the
866 * entire rendering target.
1209 * The texture color is affected based on its color modulation set by
1210 * SDL_SetTextureColorMod().
867 1211 * *
868 * \return 0 on success, or -1 on error
1212 * The texture alpha is affected based on its alpha modulation set by
1213 * SDL_SetTextureAlphaMod().
1214 *
1215 * \param renderer the rendering context
1216 * \param texture the source texture
1217 * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1218 * \param dstrect the destination SDL_Rect structure or NULL for the entire
1219 * rendering target; the texture will be stretched to fill the
1220 * given rectangle
1221 * \returns 0 on success or a negative error code on failure; call
1222 * SDL_GetError() for more information.
1223 *
1224 * \sa SDL_RenderCopyEx
1225 * \sa SDL_SetTextureAlphaMod
1226 * \sa SDL_SetTextureBlendMode
1227 * \sa SDL_SetTextureColorMod
869 1228 */ */
870 1229 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
871 1230 SDL_Texture * texture, SDL_Texture * texture,
 
... ... extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
873 1232 const SDL_Rect * dstrect); const SDL_Rect * dstrect);
874 1233
875 1234 /** /**
876 * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
1235 * Copy a portion of the texture to the current rendering, with optional
1236 * rotation and flipping.
1237 *
1238 * Copy a portion of the texture to the current rendering target, optionally
1239 * rotating it by angle around the given center and also flipping it
1240 * top-bottom and/or left-right.
877 1241 * *
878 * \param renderer The renderer which should copy parts of a texture.
879 * \param texture The source texture.
880 * \param srcrect A pointer to the source rectangle, or NULL for the entire
881 * texture.
882 * \param dstrect A pointer to the destination rectangle, or NULL for the
883 * entire rendering target.
884 * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
885 * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
886 * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
1242 * The texture is blended with the destination based on its blend mode set
1243 * with SDL_SetTextureBlendMode().
887 1244 * *
888 * \return 0 on success, or -1 on error
1245 * The texture color is affected based on its color modulation set by
1246 * SDL_SetTextureColorMod().
1247 *
1248 * The texture alpha is affected based on its alpha modulation set by
1249 * SDL_SetTextureAlphaMod().
1250 *
1251 * \param renderer the rendering context
1252 * \param texture the source texture
1253 * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1254 * \param dstrect the destination SDL_Rect structure or NULL for the entire
1255 * rendering target
1256 * \param angle an angle in degrees that indicates the rotation that will be
1257 * applied to dstrect, rotating it in a clockwise direction
1258 * \param center a pointer to a point indicating the point around which
1259 * dstrect will be rotated (if NULL, rotation will be done
1260 * around `dstrect.w / 2`, `dstrect.h / 2`)
1261 * \param flip a SDL_RendererFlip value stating which flipping actions should
1262 * be performed on the texture
1263 * \returns 0 on success or a negative error code on failure; call
1264 * SDL_GetError() for more information.
1265 *
1266 * \sa SDL_RenderCopy
1267 * \sa SDL_SetTextureAlphaMod
1268 * \sa SDL_SetTextureBlendMode
1269 * \sa SDL_SetTextureColorMod
889 1270 */ */
890 1271 extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
891 1272 SDL_Texture * texture, SDL_Texture * texture,
 
... ... extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
897 1278
898 1279
899 1280 /** /**
900 * \brief Draw a point on the current rendering target.
901 *
902 * \param renderer The renderer which should draw a point.
903 * \param x The x coordinate of the point.
904 * \param y The y coordinate of the point.
1281 * Draw a point on the current rendering target at subpixel precision.
905 1282 * *
906 * \return 0 on success, or -1 on error
1283 * \param renderer The renderer which should draw a point.
1284 * \param x The x coordinate of the point.
1285 * \param y The y coordinate of the point.
1286 * \return 0 on success, or -1 on error
907 1287 */ */
908 1288 extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer,
909 1289 float x, float y); float x, float y);
910 1290
911 1291 /** /**
912 * \brief Draw multiple points on the current rendering target.
913 *
914 * \param renderer The renderer which should draw multiple points.
915 * \param points The points to draw
916 * \param count The number of points to draw
1292 * Draw multiple points on the current rendering target at subpixel precision.
917 1293 * *
918 * \return 0 on success, or -1 on error
1294 * \param renderer The renderer which should draw multiple points.
1295 * \param points The points to draw
1296 * \param count The number of points to draw
1297 * \return 0 on success, or -1 on error
919 1298 */ */
920 1299 extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer,
921 1300 const SDL_FPoint * points, const SDL_FPoint * points,
922 1301 int count); int count);
923 1302
924 1303 /** /**
925 * \brief Draw a line on the current rendering target.
1304 * Draw a line on the current rendering target at subpixel precision.
926 1305 * *
927 * \param renderer The renderer which should draw a line.
928 * \param x1 The x coordinate of the start point.
929 * \param y1 The y coordinate of the start point.
930 * \param x2 The x coordinate of the end point.
931 * \param y2 The y coordinate of the end point.
932 *
933 * \return 0 on success, or -1 on error
1306 * \param renderer The renderer which should draw a line.
1307 * \param x1 The x coordinate of the start point.
1308 * \param y1 The y coordinate of the start point.
1309 * \param x2 The x coordinate of the end point.
1310 * \param y2 The y coordinate of the end point.
1311 * \return 0 on success, or -1 on error
934 1312 */ */
935 1313 extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer,
936 1314 float x1, float y1, float x2, float y2); float x1, float y1, float x2, float y2);
937 1315
938 1316 /** /**
939 * \brief Draw a series of connected lines on the current rendering target.
1317 * Draw a series of connected lines on the current rendering target at
1318 * subpixel precision.
940 1319 * *
941 * \param renderer The renderer which should draw multiple lines.
942 * \param points The points along the lines
943 * \param count The number of points, drawing count-1 lines
944 *
945 * \return 0 on success, or -1 on error
1320 * \param renderer The renderer which should draw multiple lines.
1321 * \param points The points along the lines
1322 * \param count The number of points, drawing count-1 lines
1323 * \return 0 on success, or -1 on error
946 1324 */ */
947 1325 extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
948 const SDL_FPoint * points,
949 int count);
1326 const SDL_FPoint * points,
1327 int count);
950 1328
951 1329 /** /**
952 * \brief Draw a rectangle on the current rendering target.
953 *
954 * \param renderer The renderer which should draw a rectangle.
955 * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
1330 * Draw a rectangle on the current rendering target at subpixel precision.
956 1331 * *
957 * \return 0 on success, or -1 on error
1332 * \param renderer The renderer which should draw a rectangle.
1333 * \param rect A pointer to the destination rectangle, or NULL to outline the
1334 * entire rendering target.
1335 * \return 0 on success, or -1 on error
958 1336 */ */
959 1337 extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
960 const SDL_FRect * rect);
1338 const SDL_FRect * rect);
961 1339
962 1340 /** /**
963 * \brief Draw some number of rectangles on the current rendering target.
1341 * Draw some number of rectangles on the current rendering target at subpixel
1342 * precision.
964 1343 * *
965 * \param renderer The renderer which should draw multiple rectangles.
966 * \param rects A pointer to an array of destination rectangles.
967 * \param count The number of rectangles.
968 *
969 * \return 0 on success, or -1 on error
1344 * \param renderer The renderer which should draw multiple rectangles.
1345 * \param rects A pointer to an array of destination rectangles.
1346 * \param count The number of rectangles.
1347 * \return 0 on success, or -1 on error
970 1348 */ */
971 1349 extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
972 1350 const SDL_FRect * rects, const SDL_FRect * rects,
973 1351 int count); int count);
974 1352
975 1353 /** /**
976 * \brief Fill a rectangle on the current rendering target with the drawing color.
1354 * Fill a rectangle on the current rendering target with the drawing color at
1355 * subpixel precision.
977 1356 * *
978 * \param renderer The renderer which should fill a rectangle.
979 * \param rect A pointer to the destination rectangle, or NULL for the entire
980 * rendering target.
981 *
982 * \return 0 on success, or -1 on error
1357 * \param renderer The renderer which should fill a rectangle.
1358 * \param rect A pointer to the destination rectangle, or NULL for the entire
1359 * rendering target.
1360 * \return 0 on success, or -1 on error
983 1361 */ */
984 1362 extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer,
985 1363 const SDL_FRect * rect); const SDL_FRect * rect);
986 1364
987 1365 /** /**
988 * \brief Fill some number of rectangles on the current rendering target with the drawing color.
1366 * Fill some number of rectangles on the current rendering target with the
1367 * drawing color at subpixel precision.
989 1368 * *
990 * \param renderer The renderer which should fill multiple rectangles.
991 * \param rects A pointer to an array of destination rectangles.
992 * \param count The number of rectangles.
993 *
994 * \return 0 on success, or -1 on error
1369 * \param renderer The renderer which should fill multiple rectangles.
1370 * \param rects A pointer to an array of destination rectangles.
1371 * \param count The number of rectangles.
1372 * \return 0 on success, or -1 on error
995 1373 */ */
996 1374 extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer,
997 1375 const SDL_FRect * rects, const SDL_FRect * rects,
998 1376 int count); int count);
999 1377
1000 1378 /** /**
1001 * \brief Copy a portion of the texture to the current rendering target.
1379 * Copy a portion of the texture to the current rendering target at subpixel
1380 * precision.
1002 1381 * *
1003 * \param renderer The renderer which should copy parts of a texture.
1004 * \param texture The source texture.
1005 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1006 * texture.
1007 * \param dstrect A pointer to the destination rectangle, or NULL for the
1008 * entire rendering target.
1009 *
1010 * \return 0 on success, or -1 on error
1382 * \param renderer The renderer which should copy parts of a texture.
1383 * \param texture The source texture.
1384 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1385 * texture.
1386 * \param dstrect A pointer to the destination rectangle, or NULL for the
1387 * entire rendering target.
1388 * \return 0 on success, or -1 on error
1011 1389 */ */
1012 1390 extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1013 1391 SDL_Texture * texture, SDL_Texture * texture,
 
... ... extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1015 1393 const SDL_FRect * dstrect); const SDL_FRect * dstrect);
1016 1394
1017 1395 /** /**
1018 * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
1019 *
1020 * \param renderer The renderer which should copy parts of a texture.
1021 * \param texture The source texture.
1022 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1023 * texture.
1024 * \param dstrect A pointer to the destination rectangle, or NULL for the
1025 * entire rendering target.
1026 * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
1027 * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
1028 * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
1029 *
1030 * \return 0 on success, or -1 on error
1396 * Copy a portion of the source texture to the current rendering target, with
1397 * rotation and flipping, at subpixel precision.
1398 *
1399 * \param renderer The renderer which should copy parts of a texture.
1400 * \param texture The source texture.
1401 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1402 * texture.
1403 * \param dstrect A pointer to the destination rectangle, or NULL for the
1404 * entire rendering target.
1405 * \param angle An angle in degrees that indicates the rotation that will be
1406 * applied to dstrect, rotating it in a clockwise direction
1407 * \param center A pointer to a point indicating the point around which
1408 * dstrect will be rotated (if NULL, rotation will be done
1409 * around dstrect.w/2, dstrect.h/2).
1410 * \param flip An SDL_RendererFlip value stating which flipping actions should
1411 * be performed on the texture
1412 * \return 0 on success, or -1 on error
1031 1413 */ */
1032 1414 extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1033 1415 SDL_Texture * texture, SDL_Texture * texture,
 
... ... extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1038 1420 const SDL_RendererFlip flip); const SDL_RendererFlip flip);
1039 1421
1040 1422 /** /**
1041 * \brief Read pixels from the current rendering target.
1423 * Read pixels from the current rendering target to an array of pixels.
1042 1424 * *
1043 * \param renderer The renderer from which pixels should be read.
1044 * \param rect A pointer to the rectangle to read, or NULL for the entire
1045 * render target.
1046 * \param format The desired format of the pixel data, or 0 to use the format
1047 * of the rendering target
1048 * \param pixels A pointer to be filled in with the pixel data
1049 * \param pitch The pitch of the pixels parameter.
1425 * **WARNING**: This is a very slow operation, and should not be used
1426 * frequently.
1050 1427 * *
1051 * \return 0 on success, or -1 if pixel reading is not supported.
1428 * `pitch` specifies the number of bytes between rows in the destination
1429 * `pixels` data. This allows you to write to a subrectangle or have padded
1430 * rows in the destination. Generally, `pitch` should equal the number of
1431 * pixels per row in the `pixels` data times the number of bytes per pixel,
1432 * but it might contain additional padding (for example, 24bit RGB Windows
1433 * Bitmap data pads all rows to multiples of 4 bytes).
1052 1434 * *
1053 * \warning This is a very slow operation, and should not be used frequently.
1435 * \param renderer the rendering context
1436 * \param rect an SDL_Rect structure representing the area to read, or NULL
1437 * for the entire render target
1438 * \param format an SDL_PixelFormatEnum value of the desired format of the
1439 * pixel data, or 0 to use the format of the rendering target
1440 * \param pixels a pointer to the pixel data to copy into
1441 * \param pitch the pitch of the `pixels` parameter
1442 * \returns 0 on success or a negative error code on failure; call
1443 * SDL_GetError() for more information.
1054 1444 */ */
1055 1445 extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1056 1446 const SDL_Rect * rect, const SDL_Rect * rect,
 
... ... extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1058 1448 void *pixels, int pitch); void *pixels, int pitch);
1059 1449
1060 1450 /** /**
1061 * \brief Update the screen with rendering performed.
1451 * Update the screen with any rendering performed since the previous call.
1452 *
1453 * SDL's rendering functions operate on a backbuffer; that is, calling a
1454 * rendering function such as SDL_RenderDrawLine() does not directly put a
1455 * line on the screen, but rather updates the backbuffer. As such, you compose
1456 * your entire scene and *present* the composed backbuffer to the screen as a
1457 * complete picture.
1458 *
1459 * Therefore, when using SDL's rendering API, one does all drawing intended
1460 * for the frame, and then calls this function once per frame to present the
1461 * final drawing to the user.
1462 *
1463 * The backbuffer should be considered invalidated after each present; do not
1464 * assume that previous contents will exist between frames. You are strongly
1465 * encouraged to call SDL_RenderClear() to initialize the backbuffer before
1466 * starting each new frame's drawing, even if you plan to overwrite every
1467 * pixel.
1468 *
1469 * \param renderer the rendering context
1470 *
1471 * \sa SDL_RenderClear
1472 * \sa SDL_RenderDrawLine
1473 * \sa SDL_RenderDrawLines
1474 * \sa SDL_RenderDrawPoint
1475 * \sa SDL_RenderDrawPoints
1476 * \sa SDL_RenderDrawRect
1477 * \sa SDL_RenderDrawRects
1478 * \sa SDL_RenderFillRect
1479 * \sa SDL_RenderFillRects
1480 * \sa SDL_SetRenderDrawBlendMode
1481 * \sa SDL_SetRenderDrawColor
1062 1482 */ */
1063 1483 extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer); extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer);
1064 1484
1065 1485 /** /**
1066 * \brief Destroy the specified texture.
1486 * Destroy the specified texture.
1487 *
1488 * Passing NULL or an otherwise invalid texture will set the SDL error message
1489 * to "Invalid texture".
1067 1490 * *
1068 * \sa SDL_CreateTexture()
1069 * \sa SDL_CreateTextureFromSurface()
1491 * \param texture the texture to destroy
1492 *
1493 * \sa SDL_CreateTexture
1494 * \sa SDL_CreateTextureFromSurface
1070 1495 */ */
1071 1496 extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture); extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
1072 1497
1073 1498 /** /**
1074 * \brief Destroy the rendering context for a window and free associated
1075 * textures.
1499 * Destroy the rendering context for a window and free associated textures.
1500 *
1501 * \param renderer the rendering context
1076 1502 * *
1077 * \sa SDL_CreateRenderer()
1503 * \sa SDL_CreateRenderer
1078 1504 */ */
1079 1505 extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
1080 1506
1081 1507 /** /**
1082 * \brief Force the rendering context to flush any pending commands to the
1083 * underlying rendering API.
1508 * Force the rendering context to flush any pending commands to the underlying
1509 * rendering API.
1510 *
1511 * You do not need to (and in fact, shouldn't) call this function unless you
1512 * are planning to call into OpenGL/Direct3D/Metal/whatever directly in
1513 * addition to using an SDL_Renderer.
1084 1514 * *
1085 * You do not need to (and in fact, shouldn't) call this function unless
1086 * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
1087 * in addition to using an SDL_Renderer.
1515 * This is for a very-specific case: if you are using SDL's render API, you
1516 * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
1517 * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
1518 * calls in addition to SDL render API calls. If all of this applies, you
1519 * should call SDL_RenderFlush() between calls to SDL's render API and the
1520 * low-level API you're using in cooperation.
1088 1521 * *
1089 * This is for a very-specific case: if you are using SDL's render API,
1090 * you asked for a specific renderer backend (OpenGL, Direct3D, etc),
1091 * you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make
1092 * OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of
1093 * this applies, you should call SDL_RenderFlush() between calls to SDL's
1094 * render API and the low-level API you're using in cooperation.
1522 * In all other cases, you can ignore this function. This is only here to get
1523 * maximum performance out of a specific situation. In all other cases, SDL
1524 * will do the right thing, perhaps at a performance loss.
1095 1525 * *
1096 * In all other cases, you can ignore this function. This is only here to
1097 * get maximum performance out of a specific situation. In all other cases,
1098 * SDL will do the right thing, perhaps at a performance loss.
1526 * This function is first available in SDL 2.0.10, and is not needed in 2.0.9
1527 * and earlier, as earlier versions did not queue rendering commands at all,
1528 * instead flushing them to the OS immediately.
1099 1529 * *
1100 * This function is first available in SDL 2.0.10, and is not needed in
1101 * 2.0.9 and earlier, as earlier versions did not queue rendering commands
1102 * at all, instead flushing them to the OS immediately.
1530 * \param renderer the rendering context
1531 * \returns 0 on success or a negative error code on failure; call
1532 * SDL_GetError() for more information.
1533 *
1534 * \since This function is available since SDL 2.0.10.
1103 1535 */ */
1104 1536 extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
1105 1537
1106 1538
1107 1539 /** /**
1108 * \brief Bind the texture to the current OpenGL/ES/ES2 context for use with
1109 * OpenGL instructions.
1540 * Bind an OpenGL/ES/ES2 texture to the current context.
1541 *
1542 * This is for use with OpenGL instructions when rendering OpenGL primitives
1543 * directly.
1544 *
1545 * If not NULL, `texw` and `texh` will be filled with the width and height
1546 * values suitable for the provided texture. In most cases, both will be 1.0,
1547 * however, on systems that support the GL_ARB_texture_rectangle extension,
1548 * these values will actually be the pixel width and height used to create the
1549 * texture, so this factor needs to be taken into account when providing
1550 * texture coordinates to OpenGL.
1551 *
1552 * You need a renderer to create an SDL_Texture, therefore you can only use
1553 * this function with an implicit OpenGL context from SDL_CreateRenderer(),
1554 * not with your own OpenGL context. If you need control over your OpenGL
1555 * context, you need to write your own texture-loading methods.
1110 1556 * *
1111 * \param texture The SDL texture to bind
1112 * \param texw A pointer to a float that will be filled with the texture width
1113 * \param texh A pointer to a float that will be filled with the texture height
1557 * Also note that SDL may upload RGB textures as BGR (or vice-versa), and
1558 * re-order the color channels in the shaders phase, so the uploaded texture
1559 * may have swapped color channels.
1114 1560 * *
1115 * \return 0 on success, or -1 if the operation is not supported
1561 * \param texture the texture to bind to the current OpenGL/ES/ES2 context
1562 * \param texw a pointer to a float value which will be filled with the
1563 * texture width or NULL if you don't need that value
1564 * \param texh a pointer to a float value which will be filled with the
1565 * texture height or NULL if you don't need that value
1566 * \returns 0 on success, or -1 if the operation is not supported; call
1567 * SDL_GetError() for more information.
1568 *
1569 * \since This function is available since SDL 2.0.0.
1570 *
1571 * \sa SDL_GL_MakeCurrent
1572 * \sa SDL_GL_UnbindTexture
1116 1573 */ */
1117 1574 extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh); extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
1118 1575
1119 1576 /** /**
1120 * \brief Unbind a texture from the current OpenGL/ES/ES2 context.
1577 * Unbind an OpenGL/ES/ES2 texture from the current context.
1578 *
1579 * See SDL_GL_BindTexture() for examples on how to use these functions
1121 1580 * *
1122 * \param texture The SDL texture to unbind
1581 * \param texture the texture to unbind from the current OpenGL/ES/ES2 context
1582 * \returns 0 on success, or -1 if the operation is not supported
1123 1583 * *
1124 * \return 0 on success, or -1 if the operation is not supported
1584 * \sa SDL_GL_BindTexture
1585 * \sa SDL_GL_MakeCurrent
1125 1586 */ */
1126 1587 extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
1127 1588
1128 1589 /** /**
1129 * \brief Get the CAMetalLayer associated with the given Metal renderer
1590 * Get the CAMetalLayer associated with the given Metal renderer.
1130 1591 * *
1131 * \param renderer The renderer to query
1592 * This function returns `void *`, so SDL doesn't have to include Metal's
1593 * headers, but it can be safely cast to a `CAMetalLayer *`.
1132 1594 * *
1133 * \return CAMetalLayer* on success, or NULL if the renderer isn't a Metal renderer
1595 * \param renderer The renderer to query
1596 * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
1597 * Metal renderer
1134 1598 * *
1135 * \sa SDL_RenderGetMetalCommandEncoder()
1599 * \sa SDL_RenderGetMetalCommandEncoder
1136 1600 */ */
1137 1601 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
1138 1602
1139 1603 /** /**
1140 * \brief Get the Metal command encoder for the current frame
1604 * Get the Metal command encoder for the current frame
1141 1605 * *
1142 * \param renderer The renderer to query
1606 * This function returns `void *`, so SDL doesn't have to include Metal's
1607 * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
1143 1608 * *
1144 * \return id<MTLRenderCommandEncoder> on success, or NULL if the renderer isn't a Metal renderer
1609 * \param renderer The renderer to query
1610 * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
1611 * renderer isn't a Metal renderer.
1145 1612 * *
1146 * \sa SDL_RenderGetMetalLayer()
1613 * \sa SDL_RenderGetMetalLayer
1147 1614 */ */
1148 1615 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer); extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);
1149 1616
File include/SDL2/SDL_revision.h changed (mode: 100644) (index e0bcf43..2376375)
1 #define SDL_REVISION "hg-14525:e52d96ea04fc"
2 #define SDL_REVISION_NUMBER 14525
1 #define SDL_REVISION "https://github.com/libsdl-org/SDL.git@25f9ed87ff6947d9576fc9d79dee0784e638ac58"
2 #define SDL_REVISION_NUMBER 0
File include/SDL2/SDL_rwops.h changed (mode: 100644) (index 2e6225f..52b3a6c)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
45 45 #define SDL_RWOPS_JNIFILE 3U /**< Android asset */ #define SDL_RWOPS_JNIFILE 3U /**< Android asset */
46 46 #define SDL_RWOPS_MEMORY 4U /**< Memory stream */ #define SDL_RWOPS_MEMORY 4U /**< Memory stream */
47 47 #define SDL_RWOPS_MEMORY_RO 5U /**< Read-Only memory stream */ #define SDL_RWOPS_MEMORY_RO 5U /**< Read-Only memory stream */
48 #if defined(__VITA__)
49 #define SDL_RWOPS_VITAFILE 6U /**< Vita file */
50 #endif
48 51
49 52 /** /**
50 53 * This is the read/write operation structure -- very basic. * This is the read/write operation structure -- very basic.
 
... ... typedef struct SDL_RWops
110 113 size_t left; size_t left;
111 114 } buffer; } buffer;
112 115 } windowsio; } windowsio;
116 #elif defined(__VITA__)
117 struct
118 {
119 int h;
120 struct
121 {
122 void *data;
123 size_t size;
124 size_t left;
125 } buffer;
126 } vitaio;
113 127 #endif #endif
114 128
115 129 #ifdef HAVE_STDIO_H #ifdef HAVE_STDIO_H
 
... ... extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
168 182 #define RW_SEEK_END 2 /**< Seek relative to the end of data */ #define RW_SEEK_END 2 /**< Seek relative to the end of data */
169 183
170 184 /** /**
171 * Return the size of the file in this rwops, or -1 if unknown
185 * Use this macro to get the size of the data stream in an SDL_RWops.
186 *
187 * \param context the SDL_RWops to get the size of the data stream from
188 * \returns the size of the data stream in the SDL_RWops on success, -1 if
189 * unknown or a negative error code on failure; call SDL_GetError()
190 * for more information.
191 *
192 * \since This function is available since SDL 2.0.0.
172 193 */ */
173 194 extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
174 195
175 196 /** /**
176 * Seek to \c offset relative to \c whence, one of stdio's whence values:
177 * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
197 * Seek within an SDL_RWops data stream.
198 *
199 * This function seeks to byte `offset`, relative to `whence`.
200 *
201 * `whence` may be any of the following values:
202 *
203 * - `RW_SEEK_SET`: seek from the beginning of data
204 * - `RW_SEEK_CUR`: seek relative to current read point
205 * - `RW_SEEK_END`: seek relative to the end of data
206 *
207 * If this stream can not seek, it will return -1.
208 *
209 * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
210 * `seek` method appropriately, to simplify application development.
211 *
212 * \param context a pointer to an SDL_RWops structure
213 * \param offset an offset in bytes, relative to **whence** location; can be
214 * negative
215 * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
216 * \returns the final offset in the data stream after the seek or -1 on error.
178 217 * *
179 * \return the final offset in the data stream, or -1 on error.
218 * \sa SDL_RWclose
219 * \sa SDL_RWFromConstMem
220 * \sa SDL_RWFromFile
221 * \sa SDL_RWFromFP
222 * \sa SDL_RWFromMem
223 * \sa SDL_RWread
224 * \sa SDL_RWtell
225 * \sa SDL_RWwrite
180 226 */ */
181 227 extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
182 228 Sint64 offset, int whence); Sint64 offset, int whence);
183 229
184 230 /** /**
185 * Return the current offset in the data stream, or -1 on error.
231 * Determine the current read/write offset in an SDL_RWops data stream.
232 *
233 * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
234 * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
235 * application development.
236 *
237 * \param context a SDL_RWops data stream object from which to get the current
238 * offset
239 * \returns the current offset in the stream, or -1 if the information can not
240 * be determined.
241 *
242 * \sa SDL_RWclose
243 * \sa SDL_RWFromConstMem
244 * \sa SDL_RWFromFile
245 * \sa SDL_RWFromFP
246 * \sa SDL_RWFromMem
247 * \sa SDL_RWread
248 * \sa SDL_RWseek
249 * \sa SDL_RWwrite
186 250 */ */
187 251 extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context); extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
188 252
189 253 /** /**
190 * Read up to \c maxnum objects each of size \c size from the data
191 * stream to the area pointed at by \c ptr.
254 * Read from a data source.
255 *
256 * This function reads up to `maxnum` objects each of size `size` from the
257 * data source to the area pointed at by `ptr`. This function may read less
258 * objects than requested. It will return zero when there has been an error or
259 * the data stream is completely read.
260 *
261 * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
262 * `read` method appropriately, to simplify application development.
192 263 * *
193 * \return the number of objects read, or 0 at error or end of file.
264 * \param context a pointer to an SDL_RWops structure
265 * \param ptr a pointer to a buffer to read data into
266 * \param size the size of each object to read, in bytes
267 * \param maxnum the maximum number of objects to be read
268 * \returns the number of objects read, or 0 at error or end of file; call
269 * SDL_GetError() for more information.
270 *
271 * \sa SDL_RWclose
272 * \sa SDL_RWFromConstMem
273 * \sa SDL_RWFromFile
274 * \sa SDL_RWFromFP
275 * \sa SDL_RWFromMem
276 * \sa SDL_RWseek
277 * \sa SDL_RWwrite
194 278 */ */
195 279 extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
196 void *ptr, size_t size, size_t maxnum);
280 void *ptr, size_t size,
281 size_t maxnum);
197 282
198 283 /** /**
199 * Write exactly \c num objects each of size \c size from the area
200 * pointed at by \c ptr to data stream.
284 * Write to an SDL_RWops data stream.
285 *
286 * This function writes exactly `num` objects each of size `size` from the
287 * area pointed at by `ptr` to the stream. If this fails for any reason, it'll
288 * return less than `num` to demonstrate how far the write progressed. On
289 * success, it returns `num`.
290 *
291 * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
292 * `write` method appropriately, to simplify application development.
293 *
294 * \param context a pointer to an SDL_RWops structure
295 * \param ptr a pointer to a buffer containing data to write
296 * \param size the size of an object to write, in bytes
297 * \param num the number of objects to write
298 * \returns the number of objects written, which will be less than **num** on
299 * error; call SDL_GetError() for more information.
201 300 * *
202 * \return the number of objects written, or 0 at error or end of file.
301 * \sa SDL_RWclose
302 * \sa SDL_RWFromConstMem
303 * \sa SDL_RWFromFile
304 * \sa SDL_RWFromFP
305 * \sa SDL_RWFromMem
306 * \sa SDL_RWread
307 * \sa SDL_RWseek
203 308 */ */
204 309 extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
205 const void *ptr, size_t size, size_t num);
310 const void *ptr, size_t size,
311 size_t num);
206 312
207 313 /** /**
208 * Close and free an allocated SDL_RWops structure.
314 * Close and free an allocated SDL_RWops structure.
209 315 * *
210 * \return 0 if successful or -1 on write error when flushing data.
316 * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
317 * resources used by the stream and frees the SDL_RWops itself with
318 * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
319 * flush to its output (e.g. to disk).
320 *
321 * Note that if this fails to flush the stream to disk, this function reports
322 * an error, but the SDL_RWops is still invalid once this function returns.
323 *
324 * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close` method
325 * appropriately, to simplify application development.
326 *
327 * \param context SDL_RWops structure to close
328 * \returns 0 on success or a negative error code on failure; call
329 * SDL_GetError() for more information.
330 *
331 * \sa SDL_RWFromConstMem
332 * \sa SDL_RWFromFile
333 * \sa SDL_RWFromFP
334 * \sa SDL_RWFromMem
335 * \sa SDL_RWread
336 * \sa SDL_RWseek
337 * \sa SDL_RWwrite
211 338 */ */
212 339 extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context); extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
213 340
214 341 /** /**
215 * Load all the data from an SDL data stream.
342 * Load all the data from an SDL data stream.
216 343 * *
217 * The data is allocated with a zero byte at the end (null terminated)
344 * The data is allocated with a zero byte at the end (null terminated) for
345 * convenience. This extra byte is not included in the value reported via
346 * `datasize`.
218 347 * *
219 * If \c datasize is not NULL, it is filled with the size of the data read.
348 * The data should be freed with SDL_free().
220 349 * *
221 * If \c freesrc is non-zero, the stream will be closed after being read.
222 *
223 * The data should be freed with SDL_free().
224 *
225 * \return the data, or NULL if there was an error.
350 * \param src the SDL_RWops to read all available data from
351 * \param datasize if not NULL, will store the number of bytes read
352 * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
353 * \returns the data, or NULL if there was an error.
226 354 */ */
227 extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops * src, size_t *datasize,
228 int freesrc);
355 extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
356 size_t *datasize,
357 int freesrc);
229 358
230 359 /** /**
231 * Load an entire file.
232 *
233 * The data is allocated with a zero byte at the end (null terminated)
234 *
235 * If \c datasize is not NULL, it is filled with the size of the data read.
360 * Load all the data from a file path.
236 361 * *
237 * If \c freesrc is non-zero, the stream will be closed after being read.
362 * The data is allocated with a zero byte at the end (null terminated) for
363 * convenience. This extra byte is not included in the value reported via
364 * `datasize`.
238 365 * *
239 * The data should be freed with SDL_free().
366 * The data should be freed with SDL_free().
240 367 * *
241 * \return the data, or NULL if there was an error.
368 * \param file the path to read all available data from
369 * \param datasize if not NULL, will store the number of bytes read
370 * \returns the data, or NULL if there was an error.
242 371 */ */
243 372 extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
244 373
File include/SDL2/SDL_scancode.h changed (mode: 100644) (index b19197d..e54c1e0)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_sensor.h changed (mode: 100644) (index e623634..3bab8a4)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
130 130 * If you are using the sensor API or handling events from multiple threads * If you are using the sensor API or handling events from multiple threads
131 131 * you should use these locking functions to protect access to the sensors. * you should use these locking functions to protect access to the sensors.
132 132 * *
133 * In particular, you are guaranteed that the sensor list won't change, so
134 * the API functions that take a sensor index will be valid, and sensor
135 * events will not be delivered.
133 * In particular, you are guaranteed that the sensor list won't change, so the
134 * API functions that take a sensor index will be valid, and sensor events
135 * will not be delivered.
136 136 */ */
137 137 extern DECLSPEC void SDLCALL SDL_LockSensors(void); extern DECLSPEC void SDLCALL SDL_LockSensors(void);
138 138 extern DECLSPEC void SDLCALL SDL_UnlockSensors(void); extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
139 139
140 140 /** /**
141 * \brief Count the number of sensors attached to the system right now
141 * Count the number of sensors attached to the system right now.
142 *
143 * \returns the number of sensors detected.
142 144 */ */
143 145 extern DECLSPEC int SDLCALL SDL_NumSensors(void); extern DECLSPEC int SDLCALL SDL_NumSensors(void);
144 146
145 147 /** /**
146 * \brief Get the implementation dependent name of a sensor.
148 * Get the implementation dependent name of a sensor.
147 149 * *
148 * This can be called before any sensors are opened.
149 *
150 * \return The sensor name, or NULL if device_index is out of range.
150 * \param device_index The sensor to obtain name from
151 * \returns the sensor name, or NULL if `device_index` is out of range.
151 152 */ */
152 153 extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index); extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
153 154
154 155 /** /**
155 * \brief Get the type of a sensor.
156 *
157 * This can be called before any sensors are opened.
156 * Get the type of a sensor.
158 157 * *
159 * \return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.
158 * \param device_index The sensor to get the type from
159 * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
160 * out of range.
160 161 */ */
161 162 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index); extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
162 163
163 164 /** /**
164 * \brief Get the platform dependent type of a sensor.
165 * Get the platform dependent type of a sensor.
165 166 * *
166 * This can be called before any sensors are opened.
167 *
168 * \return The sensor platform dependent type, or -1 if device_index is out of range.
167 * \param device_index The sensor to check
168 * \returns the sensor platform dependent type, or -1 if `device_index` is out
169 * of range.
169 170 */ */
170 171 extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index); extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
171 172
172 173 /** /**
173 * \brief Get the instance ID of a sensor.
174 *
175 * This can be called before any sensors are opened.
174 * Get the instance ID of a sensor.
176 175 * *
177 * \return The sensor instance ID, or -1 if device_index is out of range.
176 * \param device_index The sensor to get instance id from
177 * \returns the sensor instance ID, or -1 if `device_index` is out of range.
178 178 */ */
179 179 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index); extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
180 180
181 181 /** /**
182 * \brief Open a sensor for use.
183 *
184 * The index passed as an argument refers to the N'th sensor on the system.
182 * Open a sensor for use.
185 183 * *
186 * \return A sensor identifier, or NULL if an error occurred.
184 * \param device_index The sensor to open
185 * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
187 186 */ */
188 187 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index); extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
189 188
190 189 /** /**
191 190 * Return the SDL_Sensor associated with an instance id. * Return the SDL_Sensor associated with an instance id.
191 *
192 * \param instance_id The sensor from instance id
193 * \returns an SDL_Sensor object.
192 194 */ */
193 195 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id); extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
194 196
195 197 /** /**
196 * \brief Get the implementation dependent name of a sensor.
198 * Get the implementation dependent name of a sensor
197 199 * *
198 * \return The sensor name, or NULL if the sensor is NULL.
200 * \param sensor The SDL_Sensor object
201 * \returns the sensor name, or NULL if `sensor` is NULL.
199 202 */ */
200 203 extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor); extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
201 204
202 205 /** /**
203 * \brief Get the type of a sensor.
204 *
205 * This can be called before any sensors are opened.
206 * Get the type of a sensor.
206 207 * *
207 * \return The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
208 * \param sensor The SDL_Sensor object to inspect
209 * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
210 * NULL.
208 211 */ */
209 212 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor); extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
210 213
211 214 /** /**
212 * \brief Get the platform dependent type of a sensor.
213 *
214 * This can be called before any sensors are opened.
215 * Get the platform dependent type of a sensor.
215 216 * *
216 * \return The sensor platform dependent type, or -1 if the sensor is NULL.
217 * \param sensor The SDL_Sensor object to inspect
218 * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
217 219 */ */
218 220 extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor); extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
219 221
220 222 /** /**
221 * \brief Get the instance ID of a sensor.
223 * Get the instance ID of a sensor.
222 224 * *
223 * This can be called before any sensors are opened.
224 *
225 * \return The sensor instance ID, or -1 if the sensor is NULL.
225 * \param sensor The SDL_Sensor object to inspect
226 * \returns the sensor instance ID, or -1 if `sensor` is NULL.
226 227 */ */
227 228 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor); extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
228 229
229 230 /** /**
230 * Get the current state of an opened sensor.
231 *
232 * The number of values and interpretation of the data is sensor dependent.
231 * Get the current state of an opened sensor.
233 232 * *
234 * \param sensor The sensor to query
235 * \param data A pointer filled with the current sensor state
236 * \param num_values The number of values to write to data
233 * The number of values and interpretation of the data is sensor dependent.
237 234 * *
238 * \return 0 or -1 if an error occurred.
235 * \param sensor The SDL_Sensor object to query
236 * \param data A pointer filled with the current sensor state
237 * \param num_values The number of values to write to data
238 * \returns 0 or -1 if an error occurred.
239 239 */ */
240 240 extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor * sensor, float *data, int num_values); extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor * sensor, float *data, int num_values);
241 241
242 242 /** /**
243 * Close a sensor previously opened with SDL_SensorOpen()
243 * Close a sensor previously opened with SDL_SensorOpen().
244 *
245 * \param sensor The SDL_Sensor object to close
244 246 */ */
245 247 extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor * sensor); extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor * sensor);
246 248
247 249 /** /**
248 * Update the current state of the open sensors.
250 * Update the current state of the open sensors.
249 251 * *
250 * This is called automatically by the event loop if sensor events are enabled.
252 * This is called automatically by the event loop if sensor events are
253 * enabled.
251 254 * *
252 * This needs to be called from the thread that initialized the sensor subsystem.
255 * This needs to be called from the thread that initialized the sensor
256 * subsystem.
253 257 */ */
254 258 extern DECLSPEC void SDLCALL SDL_SensorUpdate(void); extern DECLSPEC void SDLCALL SDL_SensorUpdate(void);
255 259
File include/SDL2/SDL_shape.h changed (mode: 100644) (index cbd9deb..8903e04)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
44 44 #define SDL_WINDOW_LACKS_SHAPE -3 #define SDL_WINDOW_LACKS_SHAPE -3
45 45
46 46 /** /**
47 * \brief Create a window that can be shaped with the specified position, dimensions, and flags.
47 * Create a window that can be shaped with the specified position, dimensions,
48 * and flags.
48 49 * *
49 * \param title The title of the window, in UTF-8 encoding.
50 * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
51 * ::SDL_WINDOWPOS_UNDEFINED.
52 * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
53 * ::SDL_WINDOWPOS_UNDEFINED.
54 * \param w The width of the window.
55 * \param h The height of the window.
56 * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following:
57 * ::SDL_WINDOW_OPENGL, ::SDL_WINDOW_INPUT_GRABBED,
58 * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_RESIZABLE,
59 * ::SDL_WINDOW_MAXIMIZED, ::SDL_WINDOW_MINIMIZED,
60 * ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
50 * \param title The title of the window, in UTF-8 encoding.
51 * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
52 * ::SDL_WINDOWPOS_UNDEFINED.
53 * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
54 * ::SDL_WINDOWPOS_UNDEFINED.
55 * \param w The width of the window.
56 * \param h The height of the window.
57 * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
58 * any of the following: ::SDL_WINDOW_OPENGL,
59 * ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN,
60 * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
61 * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set,
62 * and ::SDL_WINDOW_FULLSCREEN is always unset.
63 * \return the window created, or NULL if window creation failed.
61 64 * *
62 * \return The window created, or NULL if window creation failed.
63 *
64 * \sa SDL_DestroyWindow()
65 * \sa SDL_DestroyWindow
65 66 */ */
66 67 extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags); extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags);
67 68
68 69 /** /**
69 * \brief Return whether the given window is a shaped window.
70 * Return whether the given window is a shaped window.
70 71 * *
71 72 * \param window The window to query for being shaped. * \param window The window to query for being shaped.
72 *
73 * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
73 * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
74 * the window is unshaped or NULL.
74 75 * *
75 76 * \sa SDL_CreateShapedWindow * \sa SDL_CreateShapedWindow
76 77 */ */
 
... ... typedef struct SDL_WindowShapeMode {
106 107 } SDL_WindowShapeMode; } SDL_WindowShapeMode;
107 108
108 109 /** /**
109 * \brief Set the shape and parameters of a shaped window.
110 * Set the shape and parameters of a shaped window.
110 111 * *
111 112 * \param window The shaped window whose parameters should be set. * \param window The shaped window whose parameters should be set.
112 113 * \param shape A surface encoding the desired shape for the window. * \param shape A surface encoding the desired shape for the window.
113 114 * \param shape_mode The parameters to set for the shaped window. * \param shape_mode The parameters to set for the shaped window.
114 *
115 * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
116 * if the SDL_Window given does not reference a valid shaped window.
115 * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
116 * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
117 * not reference a valid shaped window.
117 118 * *
118 119 * \sa SDL_WindowShapeMode * \sa SDL_WindowShapeMode
119 * \sa SDL_GetShapedWindowMode.
120 * \sa SDL_GetShapedWindowMode
120 121 */ */
121 122 extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode); extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode);
122 123
123 124 /** /**
124 * \brief Get the shape parameters of a shaped window.
125 * Get the shape parameters of a shaped window.
125 126 * *
126 127 * \param window The shaped window whose parameters should be retrieved. * \param window The shaped window whose parameters should be retrieved.
127 * \param shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape.
128 *
129 * \return 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode
130 * data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if
131 * the SDL_Window given is a shapeable window currently lacking a shape.
128 * \param shape_mode An empty shape-mode structure to fill, or NULL to check
129 * whether the window has a shape.
130 * \return 0 if the window has a shape and, provided shape_mode was not NULL,
131 * shape_mode has been filled with the mode data,
132 * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
133 * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
134 * shapeable window currently lacking a shape.
132 135 * *
133 136 * \sa SDL_WindowShapeMode * \sa SDL_WindowShapeMode
134 137 * \sa SDL_SetWindowShape * \sa SDL_SetWindowShape
File include/SDL2/SDL_stdinc.h changed (mode: 100644) (index 91ccaa4..f64219d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef uint64_t Uint64;
223 223
224 224 /* @} *//* Basic data types */ /* @} *//* Basic data types */
225 225
226 /* Make sure we have macros for printing 64 bit values.
226 /* Make sure we have macros for printing width-based integers.
227 227 * <stdint.h> should define these but this is not true all platforms. * <stdint.h> should define these but this is not true all platforms.
228 228 * (for example win32) */ * (for example win32) */
229 229 #ifndef SDL_PRIs64 #ifndef SDL_PRIs64
 
... ... typedef uint64_t Uint64;
270 270 #define SDL_PRIX64 "llX" #define SDL_PRIX64 "llX"
271 271 #endif #endif
272 272 #endif #endif
273 #ifndef SDL_PRIs32
274 #ifdef PRId32
275 #define SDL_PRIs32 PRId32
276 #else
277 #define SDL_PRIs32 "d"
278 #endif
279 #endif
280 #ifndef SDL_PRIu32
281 #ifdef PRIu32
282 #define SDL_PRIu32 PRIu32
283 #else
284 #define SDL_PRIu32 "u"
285 #endif
286 #endif
287 #ifndef SDL_PRIx32
288 #ifdef PRIx32
289 #define SDL_PRIx32 PRIx32
290 #else
291 #define SDL_PRIx32 "x"
292 #endif
293 #endif
294 #ifndef SDL_PRIX32
295 #ifdef PRIX32
296 #define SDL_PRIX32 PRIX32
297 #else
298 #define SDL_PRIX32 "X"
299 #endif
300 #endif
273 301
274 302 /* Annotations to help code analysis tools */ /* Annotations to help code analysis tools */
275 303 #ifdef SDL_DISABLE_ANALYZE_MACROS #ifdef SDL_DISABLE_ANALYZE_MACROS
 
... ... SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
338 366
339 367 /** \cond */ /** \cond */
340 368 #ifndef DOXYGEN_SHOULD_IGNORE_THIS #ifndef DOXYGEN_SHOULD_IGNORE_THIS
341 #if !defined(__ANDROID__)
369 #if !defined(__ANDROID__) && !defined(__VITA__)
342 370 /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */ /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */
343 371 typedef enum typedef enum
344 372 { {
 
... ... typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
375 403 typedef void (SDLCALL *SDL_free_func)(void *mem); typedef void (SDLCALL *SDL_free_func)(void *mem);
376 404
377 405 /** /**
378 * \brief Get the current set of SDL memory functions
406 * Get the current set of SDL memory functions
379 407 */ */
380 408 extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func, extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
381 409 SDL_calloc_func *calloc_func, SDL_calloc_func *calloc_func,
 
... ... extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
383 411 SDL_free_func *free_func); SDL_free_func *free_func);
384 412
385 413 /** /**
386 * \brief Replace SDL's memory allocation functions with a custom set
387 *
388 * \note If you are replacing SDL's memory functions, you should call
389 * SDL_GetNumAllocations() and be very careful if it returns non-zero.
390 * That means that your free function will be called with memory
391 * allocated by the previous memory allocation functions.
414 * Replace SDL's memory allocation functions with a custom set
392 415 */ */
393 416 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
394 417 SDL_calloc_func calloc_func, SDL_calloc_func calloc_func,
 
... ... extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
396 419 SDL_free_func free_func); SDL_free_func free_func);
397 420
398 421 /** /**
399 * \brief Get the number of outstanding (unfreed) allocations
422 * Get the number of outstanding (unfreed) allocations
400 423 */ */
401 424 extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void); extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
402 425
 
... ... extern DECLSPEC int SDLCALL SDL_abs(int x);
412 435 #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) #define SDL_min(x, y) (((x) < (y)) ? (x) : (y))
413 436 #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) #define SDL_max(x, y) (((x) > (y)) ? (x) : (y))
414 437
438 extern DECLSPEC int SDLCALL SDL_isalpha(int x);
439 extern DECLSPEC int SDLCALL SDL_isalnum(int x);
440 extern DECLSPEC int SDLCALL SDL_isblank(int x);
441 extern DECLSPEC int SDLCALL SDL_iscntrl(int x);
415 442 extern DECLSPEC int SDLCALL SDL_isdigit(int x); extern DECLSPEC int SDLCALL SDL_isdigit(int x);
443 extern DECLSPEC int SDLCALL SDL_isxdigit(int x);
444 extern DECLSPEC int SDLCALL SDL_ispunct(int x);
416 445 extern DECLSPEC int SDLCALL SDL_isspace(int x); extern DECLSPEC int SDLCALL SDL_isspace(int x);
417 446 extern DECLSPEC int SDLCALL SDL_isupper(int x); extern DECLSPEC int SDLCALL SDL_isupper(int x);
418 447 extern DECLSPEC int SDLCALL SDL_islower(int x); extern DECLSPEC int SDLCALL SDL_islower(int x);
448 extern DECLSPEC int SDLCALL SDL_isprint(int x);
449 extern DECLSPEC int SDLCALL SDL_isgraph(int x);
419 450 extern DECLSPEC int SDLCALL SDL_toupper(int x); extern DECLSPEC int SDLCALL SDL_toupper(int x);
420 451 extern DECLSPEC int SDLCALL SDL_tolower(int x); extern DECLSPEC int SDLCALL SDL_tolower(int x);
421 452
 
... ... SDL_FORCE_INLINE void SDL_memset4(void *dst, Uint32 val, size_t dwords)
432 463 { {
433 464 #ifdef __APPLE__ #ifdef __APPLE__
434 465 memset_pattern4(dst, &val, dwords * 4); memset_pattern4(dst, &val, dwords * 4);
435 #elif defined(__GNUC__) && defined(i386)
466 #elif defined(__GNUC__) && defined(__i386__)
436 467 int u0, u1, u2; int u0, u1, u2;
437 468 __asm__ __volatile__ ( __asm__ __volatile__ (
438 469 "cld \n\t" "cld \n\t"
 
... ... SDL_FORCE_INLINE void SDL_memset4(void *dst, Uint32 val, size_t dwords)
445 476 size_t _n = (dwords + 3) / 4; size_t _n = (dwords + 3) / 4;
446 477 Uint32 *_p = SDL_static_cast(Uint32 *, dst); Uint32 *_p = SDL_static_cast(Uint32 *, dst);
447 478 Uint32 _val = (val); Uint32 _val = (val);
448 if (dwords == 0)
479 if (dwords == 0) {
449 480 return; return;
450 switch (dwords % 4)
451 {
481 }
482
483 /* !!! FIXME: there are better ways to do this, but this is just to clean this up for now. */
484 #ifdef __clang__
485 #pragma clang diagnostic push
486 #pragma clang diagnostic ignored "-Wimplicit-fallthrough"
487 #endif
488
489 switch (dwords % 4) {
452 490 case 0: do { *_p++ = _val; /* fallthrough */ case 0: do { *_p++ = _val; /* fallthrough */
453 491 case 3: *_p++ = _val; /* fallthrough */ case 3: *_p++ = _val; /* fallthrough */
454 492 case 2: *_p++ = _val; /* fallthrough */ case 2: *_p++ = _val; /* fallthrough */
455 493 case 1: *_p++ = _val; /* fallthrough */ case 1: *_p++ = _val; /* fallthrough */
456 494 } while ( --_n ); } while ( --_n );
457 495 } }
496
497 #ifdef __clang__
498 #pragma clang diagnostic pop
499 #endif
500
458 501 #endif #endif
459 502 } }
460 503
 
... ... extern DECLSPEC double SDLCALL SDL_log10(double x);
549 592 extern DECLSPEC float SDLCALL SDL_log10f(float x); extern DECLSPEC float SDLCALL SDL_log10f(float x);
550 593 extern DECLSPEC double SDLCALL SDL_pow(double x, double y); extern DECLSPEC double SDLCALL SDL_pow(double x, double y);
551 594 extern DECLSPEC float SDLCALL SDL_powf(float x, float y); extern DECLSPEC float SDLCALL SDL_powf(float x, float y);
595 extern DECLSPEC double SDLCALL SDL_round(double x);
596 extern DECLSPEC float SDLCALL SDL_roundf(float x);
597 extern DECLSPEC long SDLCALL SDL_lround(double x);
598 extern DECLSPEC long SDLCALL SDL_lroundf(float x);
552 599 extern DECLSPEC double SDLCALL SDL_scalbn(double x, int n); extern DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
553 600 extern DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); extern DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
554 601 extern DECLSPEC double SDLCALL SDL_sin(double x); extern DECLSPEC double SDLCALL SDL_sin(double x);
 
... ... extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
573 620 size_t * inbytesleft, char **outbuf, size_t * inbytesleft, char **outbuf,
574 621 size_t * outbytesleft); size_t * outbytesleft);
575 622 /** /**
576 * This function converts a string between encodings in one pass, returning a
577 * string that must be freed with SDL_free() or NULL on error.
623 * This function converts a string between encodings in one pass, returning a
624 * string that must be freed with SDL_free() or NULL on error.
578 625 */ */
579 626 extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode, extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
580 627 const char *fromcode, const char *fromcode,
File include/SDL2/SDL_surface.h changed (mode: 100644) (index d3f8c81..5325ed2)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef enum
112 112 } SDL_YUV_CONVERSION_MODE; } SDL_YUV_CONVERSION_MODE;
113 113
114 114 /** /**
115 * Allocate and free an RGB surface.
115 * Allocate a new RGB surface.
116 116 * *
117 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
118 * If the depth is greater than 8 bits, the pixel format is set using the
119 * flags '[RGB]mask'.
117 * If `depth` is 4 or 8 bits, an empty palette is allocated for the surface.
118 * If `depth` is greater than 8 bits, the pixel format is set using the
119 * [RGBA]mask parameters.
120 120 * *
121 * If the function runs out of memory, it will return NULL.
121 * The [RGBA]mask parameters are the bitmasks used to extract that color from
122 * a pixel. For instance, `Rmask` being 0xFF000000 means the red data is
123 * stored in the most significant byte. Using zeros for the RGB masks sets a
124 * default value, based on the depth. For example:
122 125 * *
123 * \param flags The \c flags are obsolete and should be set to 0.
124 * \param width The width in pixels of the surface to create.
125 * \param height The height in pixels of the surface to create.
126 * \param depth The depth in bits of the surface to create.
127 * \param Rmask The red mask of the surface to create.
128 * \param Gmask The green mask of the surface to create.
129 * \param Bmask The blue mask of the surface to create.
130 * \param Amask The alpha mask of the surface to create.
126 * ```c++
127 * SDL_CreateRGBSurface(0,w,h,32,0,0,0,0);
128 * ```
129 *
130 * However, using zero for the Amask results in an Amask of 0.
131 *
132 * By default surfaces with an alpha mask are set up for blending as with:
133 *
134 * ```c++
135 * SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND)
136 * ```
137 *
138 * You can change this by calling SDL_SetSurfaceBlendMode() and selecting a
139 * different `blendMode`.
140 *
141 * \param flags the flags are unused and should be set to 0
142 * \param width the width of the surface
143 * \param height the height of the surface
144 * \param depth the depth of the surface in bits
145 * \param Rmask the red mask for the pixels
146 * \param Gmask the green mask for the pixels
147 * \param Bmask the blue mask for the pixels
148 * \param Amask the alpha mask for the pixels
149 * \returns the new SDL_Surface structure that is created or NULL if it fails;
150 * call SDL_GetError() for more information.
151 *
152 * \sa SDL_CreateRGBSurfaceFrom
153 * \sa SDL_CreateRGBSurfaceWithFormat
154 * \sa SDL_FreeSurface
131 155 */ */
132 156 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
133 157 (Uint32 flags, int width, int height, int depth, (Uint32 flags, int width, int height, int depth,
134 158 Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
135 159
160
136 161 /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */ /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
162 /**
163 * Allocate a new RGB surface with a specific pixel format.
164 *
165 * This function operates mostly like SDL_CreateRGBSurface(), except instead
166 * of providing pixel color masks, you provide it with a predefined format
167 * from SDL_PixelFormatEnum.
168 *
169 * \param flags the flags are unused and should be set to 0
170 * \param width the width of the surface
171 * \param height the height of the surface
172 * \param depth the depth of the surface in bits
173 * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
174 * \returns the new SDL_Surface structure that is created or NULL if it fails;
175 * call SDL_GetError() for more information.
176 *
177 * \sa SDL_CreateRGBSurface
178 * \sa SDL_CreateRGBSurfaceFrom
179 * \sa SDL_FreeSurface
180 */
137 181 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
138 182 (Uint32 flags, int width, int height, int depth, Uint32 format); (Uint32 flags, int width, int height, int depth, Uint32 format);
139 183
184 /**
185 * Allocate a new RGB surface with existing pixel data.
186 *
187 * This function operates mostly like SDL_CreateRGBSurface(), except it does
188 * not allocate memory for the pixel data, instead the caller provides an
189 * existing buffer of data for the surface to use.
190 *
191 * No copy is made of the pixel data. Pixel data is not managed automatically;
192 * you must free the surface before you free the pixel data.
193 *
194 * \param pixels a pointer to existing pixel data
195 * \param width the width of the surface
196 * \param height the height of the surface
197 * \param depth the depth of the surface in bits
198 * \param pitch the pitch of the surface in bytes
199 * \param Rmask the red mask for the pixels
200 * \param Gmask the green mask for the pixels
201 * \param Bmask the blue mask for the pixels
202 * \param Amask the alpha mask for the pixels
203 * \returns the new SDL_Surface structure that is created or NULL if it fails;
204 * call SDL_GetError() for more information.
205 *
206 * \sa SDL_CreateRGBSurface
207 * \sa SDL_CreateRGBSurfaceWithFormat
208 * \sa SDL_FreeSurface
209 */
140 210 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
141 211 int width, int width,
142 212 int height, int height,
 
... ... extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
146 216 Uint32 Gmask, Uint32 Gmask,
147 217 Uint32 Bmask, Uint32 Bmask,
148 218 Uint32 Amask); Uint32 Amask);
219
220 /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
221 /**
222 * Allocate a new RGB surface with with a specific pixel format and existing
223 * pixel data.
224 *
225 * This function operates mostly like SDL_CreateRGBSurfaceFrom(), except
226 * instead of providing pixel color masks, you provide it with a predefined
227 * format from SDL_PixelFormatEnum.
228 *
229 * No copy is made of the pixel data. Pixel data is not managed automatically;
230 * you must free the surface before you free the pixel data.
231 *
232 * \param pixels a pointer to existing pixel data
233 * \param width the width of the surface
234 * \param height the height of the surface
235 * \param depth the depth of the surface in bits
236 * \param pitch the pitch of the surface in bytes
237 * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
238 * \returns the new SDL_Surface structure that is created or NULL if it fails;
239 * call SDL_GetError() for more information.
240 *
241 * \sa SDL_CreateRGBSurfaceFrom
242 * \sa SDL_CreateRGBSurfaceWithFormat
243 * \sa SDL_FreeSurface
244 */
149 245 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom
150 246 (void *pixels, int width, int height, int depth, int pitch, Uint32 format); (void *pixels, int width, int height, int depth, int pitch, Uint32 format);
247
248 /**
249 * Free an RGB surface.
250 *
251 * It is safe to pass NULL to this function.
252 *
253 * \param surface the SDL_Surface to free.
254 *
255 * \sa SDL_CreateRGBSurface
256 * \sa SDL_CreateRGBSurfaceFrom
257 * \sa SDL_LoadBMP
258 * \sa SDL_LoadBMP_RW
259 */
151 260 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
152 261
153 262 /** /**
154 * \brief Set the palette used by a surface.
263 * Set the palette used by a surface.
155 264 * *
156 * \return 0, or -1 if the surface format doesn't use a palette.
265 * A single palette can be shared with many surfaces.
157 266 * *
158 * \note A single palette can be shared with many surfaces.
267 * \param surface the SDL_Surface structure to update
268 * \param palette the SDL_Palette structure to use
269 * \returns 0 on success or a negative error code on failure; call
270 * SDL_GetError() for more information.
159 271 */ */
160 272 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
161 273 SDL_Palette * palette); SDL_Palette * palette);
162 274
163 275 /** /**
164 * \brief Sets up a surface for directly accessing the pixels.
165 *
166 * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
167 * to and read from \c surface->pixels, using the pixel format stored in
168 * \c surface->format. Once you are done accessing the surface, you should
169 * use SDL_UnlockSurface() to release it.
276 * Set up a surface for directly accessing the pixels.
170 277 * *
171 * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates
172 * to 0, then you can read and write to the surface at any time, and the
173 * pixel format of the surface will not change.
278 * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to
279 * and read from `surface->pixels`, using the pixel format stored in
280 * `surface->format`. Once you are done accessing the surface, you should use
281 * SDL_UnlockSurface() to release it.
174 282 * *
175 * No operating system or library calls should be made between lock/unlock
176 * pairs, as critical system locks may be held during this time.
283 * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to
284 * 0, then you can read and write to the surface at any time, and the pixel
285 * format of the surface will not change.
177 286 * *
178 * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
287 * \param surface the SDL_Surface structure to be locked
288 * \returns 0 on success or a negative error code on failure; call
289 * SDL_GetError() for more information.
179 290 * *
180 * \sa SDL_UnlockSurface()
291 * \sa SDL_MUSTLOCK
292 * \sa SDL_UnlockSurface
181 293 */ */
182 294 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface); extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
183 /** \sa SDL_LockSurface() */
295
296 /**
297 * Release a surface after directly accessing the pixels.
298 *
299 * \param surface the SDL_Surface structure to be unlocked
300 *
301 * \sa SDL_LockSurface
302 */
184 303 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
185 304
186 305 /** /**
187 * Load a surface from a seekable SDL data stream (memory or file).
306 * Load a BMP image from a seekable SDL data stream.
188 307 * *
189 * If \c freesrc is non-zero, the stream will be closed after being read.
308 * The new surface should be freed with SDL_FreeSurface().
190 309 * *
191 * The new surface should be freed with SDL_FreeSurface().
310 * \param src the data stream for the surface
311 * \param freesrc non-zero to close the stream after being read
312 * \returns a pointer to a new SDL_Surface structure or NULL if there was an
313 * error; call SDL_GetError() for more information.
192 314 * *
193 * \return the new surface, or NULL if there was an error.
315 * \sa SDL_FreeSurface
316 * \sa SDL_LoadBMP
317 * \sa SDL_SaveBMP_RW
194 318 */ */
195 319 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
196 320 int freesrc); int freesrc);
197 321
198 322 /** /**
199 * Load a surface from a file.
323 * Load a surface from a file.
200 324 * *
201 * Convenience macro.
325 * Convenience macro.
202 326 */ */
203 327 #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
204 328
205 329 /** /**
206 * Save a surface to a seekable SDL data stream (memory or file).
330 * Save a surface to a seekable SDL data stream in BMP format.
207 331 * *
208 * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
209 * BMP directly. Other RGB formats with 8-bit or higher get converted to a
210 * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
211 * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
212 * not supported.
332 * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
333 * BMP directly. Other RGB formats with 8-bit or higher get converted to a
334 * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
335 * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
336 * not supported.
213 337 * *
214 * If \c freedst is non-zero, the stream will be closed after being written.
338 * \param surface the SDL_Surface structure containing the image to be saved
339 * \param dst a data stream to save to
340 * \param freedst non-zero to close the stream after being written
341 * \returns 0 on success or a negative error code on failure; call
342 * SDL_GetError() for more information.
215 343 * *
216 * \return 0 if successful or -1 if there was an error.
344 * \sa SDL_LoadBMP_RW
345 * \sa SDL_SaveBMP
217 346 */ */
218 347 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
219 348 (SDL_Surface * surface, SDL_RWops * dst, int freedst); (SDL_Surface * surface, SDL_RWops * dst, int freedst);
 
... ... extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
227 356 SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1) SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
228 357
229 358 /** /**
230 * \brief Sets the RLE acceleration hint for a surface.
359 * Set the RLE acceleration hint for a surface.
231 360 * *
232 * \return 0 on success, or -1 if the surface is not valid
361 * If RLE is enabled, color key and alpha blending blits are much faster, but
362 * the surface must be locked before directly accessing the pixels.
233 363 * *
234 * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
235 * but the surface must be locked before directly accessing the pixels.
364 * \param surface the SDL_Surface structure to optimize
365 * \param flag 0 to disable, non-zero to enable RLE acceleration
366 * \returns 0 on success or a negative error code on failure; call
367 * SDL_GetError() for more information.
368 *
369 * \sa SDL_BlitSurface
370 * \sa SDL_LockSurface
371 * \sa SDL_UnlockSurface
236 372 */ */
237 373 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
238 374 int flag); int flag);
239 375
240 376 /** /**
241 * \brief Returns whether the surface is RLE enabled
377 * Returns whether the surface is RLE enabled
378 *
379 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
380 *
381 * \param surface the SDL_Surface structure to query
382 * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
242 383 * *
243 * \return SDL_TRUE if the surface is RLE enabled, or SDL_FALSE if the surface is NULL or not RLE enabled
384 * \sa SDL_SetSurfaceRLE
244 385 */ */
245 386 extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface); extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface);
246 387
247 388 /** /**
248 * \brief Sets the color key (transparent pixel) in a blittable surface.
389 * Set the color key (transparent pixel) in a surface.
249 390 * *
250 * \param surface The surface to update
251 * \param flag Non-zero to enable colorkey and 0 to disable colorkey
252 * \param key The transparent pixel in the native surface format
391 * The color key defines a pixel value that will be treated as transparent in
392 * a blit. For example, one can use this to specify that cyan pixels should be
393 * considered transparent, and therefore not rendered.
253 394 * *
254 * \return 0 on success, or -1 if the surface is not valid
395 * It is a pixel of the format used by the surface, as generated by
396 * SDL_MapRGB().
255 397 * *
256 * You can pass SDL_RLEACCEL to enable RLE accelerated blits.
398 * RLE acceleration can substantially speed up blitting of images with large
399 * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
400 *
401 * \param surface the SDL_Surface structure to update
402 * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
403 * \param key the transparent pixel
404 * \returns 0 on success or a negative error code on failure; call
405 * SDL_GetError() for more information.
406 *
407 * \sa SDL_BlitSurface
408 * \sa SDL_GetColorKey
257 409 */ */
258 410 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
259 411 int flag, Uint32 key); int flag, Uint32 key);
260 412
261 413 /** /**
262 * \brief Returns whether the surface has a color key
414 * Returns whether the surface has a color key
415 *
416 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
263 417 * *
264 * \return SDL_TRUE if the surface has a color key, or SDL_FALSE if the surface is NULL or has no color key
418 * \param surface the SDL_Surface structure to query
419 * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
420 *
421 * \sa SDL_SetColorKey
422 * \sa SDL_GetColorKey
265 423 */ */
266 424 extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface); extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface);
267 425
268 426 /** /**
269 * \brief Gets the color key (transparent pixel) in a blittable surface.
427 * Get the color key (transparent pixel) for a surface.
428 *
429 * The color key is a pixel of the format used by the surface, as generated by
430 * SDL_MapRGB().
270 431 * *
271 * \param surface The surface to update
272 * \param key A pointer filled in with the transparent pixel in the native
273 * surface format
432 * If the surface doesn't have color key enabled this function returns -1.
274 433 * *
275 * \return 0 on success, or -1 if the surface is not valid or colorkey is not
276 * enabled.
434 * \param surface the SDL_Surface structure to query
435 * \param key a pointer filled in with the transparent pixel
436 * \returns 0 on success or a negative error code on failure; call
437 * SDL_GetError() for more information.
438 *
439 * \sa SDL_BlitSurface
440 * \sa SDL_SetColorKey
277 441 */ */
278 442 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
279 443 Uint32 * key); Uint32 * key);
280 444
281 445 /** /**
282 * \brief Set an additional color value used in blit operations.
446 * Set an additional color value multiplied into blit operations.
447 *
448 * When this surface is blitted, during the blit operation each source color
449 * channel is modulated by the appropriate color value according to the
450 * following formula:
283 451 * *
284 * \param surface The surface to update.
285 * \param r The red color value multiplied into blit operations.
286 * \param g The green color value multiplied into blit operations.
287 * \param b The blue color value multiplied into blit operations.
452 * `srcC = srcC * (color / 255)`
288 453 * *
289 * \return 0 on success, or -1 if the surface is not valid.
454 * \param surface the SDL_Surface structure to update
455 * \param r the red color value multiplied into blit operations
456 * \param g the green color value multiplied into blit operations
457 * \param b the blue color value multiplied into blit operations
458 * \returns 0 on success or a negative error code on failure; call
459 * SDL_GetError() for more information.
290 460 * *
291 * \sa SDL_GetSurfaceColorMod()
461 * \sa SDL_GetSurfaceColorMod
462 * \sa SDL_SetSurfaceAlphaMod
292 463 */ */
293 464 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
294 465 Uint8 r, Uint8 g, Uint8 b); Uint8 r, Uint8 g, Uint8 b);
295 466
296 467
297 468 /** /**
298 * \brief Get the additional color value used in blit operations.
299 *
300 * \param surface The surface to query.
301 * \param r A pointer filled in with the current red color value.
302 * \param g A pointer filled in with the current green color value.
303 * \param b A pointer filled in with the current blue color value.
469 * Get the additional color value multiplied into blit operations.
304 470 * *
305 * \return 0 on success, or -1 if the surface is not valid.
471 * \param surface the SDL_Surface structure to query
472 * \param r a pointer filled in with the current red color value
473 * \param g a pointer filled in with the current green color value
474 * \param b a pointer filled in with the current blue color value
475 * \returns 0 on success or a negative error code on failure; call
476 * SDL_GetError() for more information.
306 477 * *
307 * \sa SDL_SetSurfaceColorMod()
478 * \sa SDL_GetSurfaceAlphaMod
479 * \sa SDL_SetSurfaceColorMod
308 480 */ */
309 481 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
310 482 Uint8 * r, Uint8 * g, Uint8 * r, Uint8 * g,
311 483 Uint8 * b); Uint8 * b);
312 484
313 485 /** /**
314 * \brief Set an additional alpha value used in blit operations.
486 * Set an additional alpha value used in blit operations.
315 487 * *
316 * \param surface The surface to update.
317 * \param alpha The alpha value multiplied into blit operations.
488 * When this surface is blitted, during the blit operation the source alpha
489 * value is modulated by this alpha value according to the following formula:
318 490 * *
319 * \return 0 on success, or -1 if the surface is not valid.
491 * `srcA = srcA * (alpha / 255)`
320 492 * *
321 * \sa SDL_GetSurfaceAlphaMod()
493 * \param surface the SDL_Surface structure to update
494 * \param alpha the alpha value multiplied into blit operations
495 * \returns 0 on success or a negative error code on failure; call
496 * SDL_GetError() for more information.
497 *
498 * \sa SDL_GetSurfaceAlphaMod
499 * \sa SDL_SetSurfaceColorMod
322 500 */ */
323 501 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
324 502 Uint8 alpha); Uint8 alpha);
325 503
326 504 /** /**
327 * \brief Get the additional alpha value used in blit operations.
328 *
329 * \param surface The surface to query.
330 * \param alpha A pointer filled in with the current alpha value.
505 * Get the additional alpha value used in blit operations.
331 506 * *
332 * \return 0 on success, or -1 if the surface is not valid.
507 * \param surface the SDL_Surface structure to query
508 * \param alpha a pointer filled in with the current alpha value
509 * \returns 0 on success or a negative error code on failure; call
510 * SDL_GetError() for more information.
333 511 * *
334 * \sa SDL_SetSurfaceAlphaMod()
512 * \sa SDL_GetSurfaceColorMod
513 * \sa SDL_SetSurfaceAlphaMod
335 514 */ */
336 515 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
337 516 Uint8 * alpha); Uint8 * alpha);
338 517
339 518 /** /**
340 * \brief Set the blend mode used for blit operations.
519 * Set the blend mode used for blit operations.
341 520 * *
342 * \param surface The surface to update.
343 * \param blendMode ::SDL_BlendMode to use for blit blending.
521 * To copy a surface to another surface (or texture) without blending with the
522 * existing data, the blendmode of the SOURCE surface should be set to
523 * `SDL_BLENDMODE_NONE`.
344 524 * *
345 * \return 0 on success, or -1 if the parameters are not valid.
525 * \param surface the SDL_Surface structure to update
526 * \param blendMode the SDL_BlendMode to use for blit blending
527 * \returns 0 on success or a negative error code on failure; call
528 * SDL_GetError() for more information.
346 529 * *
347 * \sa SDL_GetSurfaceBlendMode()
530 * \sa SDL_GetSurfaceBlendMode
348 531 */ */
349 532 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
350 533 SDL_BlendMode blendMode); SDL_BlendMode blendMode);
351 534
352 535 /** /**
353 * \brief Get the blend mode used for blit operations.
354 *
355 * \param surface The surface to query.
356 * \param blendMode A pointer filled in with the current blend mode.
536 * Get the blend mode used for blit operations.
357 537 * *
358 * \return 0 on success, or -1 if the surface is not valid.
538 * \param surface the SDL_Surface structure to query
539 * \param blendMode a pointer filled in with the current SDL_BlendMode
540 * \returns 0 on success or a negative error code on failure; call
541 * SDL_GetError() for more information.
359 542 * *
360 * \sa SDL_SetSurfaceBlendMode()
543 * \sa SDL_SetSurfaceBlendMode
361 544 */ */
362 545 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
363 546 SDL_BlendMode *blendMode); SDL_BlendMode *blendMode);
364 547
365 548 /** /**
366 * Sets the clipping rectangle for the destination surface in a blit.
549 * Set the clipping rectangle for a surface.
367 550 * *
368 * If the clip rectangle is NULL, clipping will be disabled.
551 * When `surface` is the destination of a blit, only the area within the clip
552 * rectangle is drawn into.
369 553 * *
370 * If the clip rectangle doesn't intersect the surface, the function will
371 * return SDL_FALSE and blits will be completely clipped. Otherwise the
372 * function returns SDL_TRUE and blits to the surface will be clipped to
373 * the intersection of the surface area and the clipping rectangle.
554 * Note that blits are automatically clipped to the edges of the source and
555 * destination surfaces.
374 556 * *
375 * Note that blits are automatically clipped to the edges of the source
376 * and destination surfaces.
557 * \param surface the SDL_Surface structure to be clipped
558 * \param rect the SDL_Rect structure representing the clipping rectangle, or
559 * NULL to disable clipping
560 * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
561 * SDL_FALSE and blits will be completely clipped.
562 *
563 * \sa SDL_BlitSurface
564 * \sa SDL_GetClipRect
377 565 */ */
378 566 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface, extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
379 567 const SDL_Rect * rect); const SDL_Rect * rect);
380 568
381 569 /** /**
382 * Gets the clipping rectangle for the destination surface in a blit.
570 * Get the clipping rectangle for a surface.
571 *
572 * When `surface` is the destination of a blit, only the area within the clip
573 * rectangle is drawn into.
574 *
575 * \param surface the SDL_Surface structure representing the surface to be
576 * clipped
577 * \param rect an SDL_Rect structure filled in with the clipping rectangle for
578 * the surface
383 579 * *
384 * \c rect must be a pointer to a valid rectangle which will be filled
385 * with the correct values.
580 * \sa SDL_BlitSurface
581 * \sa SDL_SetClipRect
386 582 */ */
387 583 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface, extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
388 584 SDL_Rect * rect); SDL_Rect * rect);
389 585
390 586 /* /*
391 * Creates a new surface identical to the existing surface
587 * Creates a new surface identical to the existing surface.
588 *
589 * The returned surface should be freed with SDL_FreeSurface().
590 *
591 * \param surface the surface to duplicate.
592 * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
593 * more information.
392 594 */ */
393 595 extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface); extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface);
394 596
395 597 /** /**
396 * Creates a new surface of the specified format, and then copies and maps
397 * the given surface to it so the blit of the converted surface will be as
398 * fast as possible. If this function fails, it returns NULL.
598 * Copy an existing surface to a new surface of the specified format.
599 *
600 * This function is used to optimize images for faster *repeat* blitting. This
601 * is accomplished by converting the original and storing the result as a new
602 * surface. The new, optimized surface can then be used as the source for
603 * future blits, making them faster.
399 604 * *
400 * The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
401 * semantics. You can also pass ::SDL_RLEACCEL in the flags parameter and
402 * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
403 * surface.
605 * \param src the existing SDL_Surface structure to convert
606 * \param fmt the SDL_PixelFormat structure that the new surface is optimized
607 * for
608 * \param flags the flags are unused and should be set to 0; this is a
609 * leftover from SDL 1.2's API
610 * \returns the new SDL_Surface structure that is created or NULL if it fails;
611 * call SDL_GetError() for more information.
612 *
613 * \sa SDL_AllocFormat
614 * \sa SDL_ConvertSurfaceFormat
615 * \sa SDL_CreateRGBSurface
404 616 */ */
405 617 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
406 618 (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags); (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
619
620 /**
621 * Copy an existing surface to a new surface of the specified format enum.
622 *
623 * This function operates just like SDL_ConvertSurface(), but accepts an
624 * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
625 * it might be easier to call but it doesn't have access to palette
626 * information for the destination surface, in case that would be important.
627 *
628 * \param src the existing SDL_Surface structure to convert
629 * \param pixel_format the SDL_PixelFormatEnum that the new surface is
630 * optimized for
631 * \param flags the flags are unused and should be set to 0; this is a
632 * leftover from SDL 1.2's API
633 * \returns the new SDL_Surface structure that is created or NULL if it fails;
634 * call SDL_GetError() for more information.
635 *
636 * \sa SDL_AllocFormat
637 * \sa SDL_ConvertSurfaceFormat
638 * \sa SDL_CreateRGBSurface
639 */
407 640 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
408 641 (SDL_Surface * src, Uint32 pixel_format, Uint32 flags); (SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
409 642
410 643 /** /**
411 * \brief Copy a block of pixels of one format to another format
644 * Copy a block of pixels of one format to another format.
412 645 * *
413 * \return 0 on success, or -1 if there was an error
646 * \param width the width of the block to copy, in pixels
647 * \param height the height of the block to copy, in pixels
648 * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
649 * \param src a pointer to the source pixels
650 * \param src_pitch the pitch of the block to copy, in bytes
651 * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
652 * \param dst a pointer to be filled in with new pixel data
653 * \param dst_pitch the pitch of the destination pixels, in bytes
654 * \returns 0 on success or a negative error code on failure; call
655 * SDL_GetError() for more information.
414 656 */ */
415 657 extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
416 658 Uint32 src_format, Uint32 src_format,
 
... ... extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
419 661 void * dst, int dst_pitch); void * dst, int dst_pitch);
420 662
421 663 /** /**
422 * Performs a fast fill of the given rectangle with \c color.
664 * Perform a fast fill of a rectangle with a specific color.
665 *
666 * `color` should be a pixel of the format used by the surface, and can be
667 * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
668 * alpha component then the destination is simply filled with that alpha
669 * information, no blending takes place.
423 670 * *
424 * If \c rect is NULL, the whole surface will be filled with \c color.
671 * If there is a clip rectangle set on the destination (set via
672 * SDL_SetClipRect()), then this function will fill based on the intersection
673 * of the clip rectangle and `rect`.
425 674 * *
426 * The color should be a pixel of the format used by the surface, and
427 * can be generated by the SDL_MapRGB() function.
675 * \param dst the SDL_Surface structure that is the drawing target
676 * \param rect the SDL_Rect structure representing the rectangle to fill, or
677 * NULL to fill the entire surface
678 * \param color the color to fill with
679 * \returns 0 on success or a negative error code on failure; call
680 * SDL_GetError() for more information.
428 681 * *
429 * \return 0 on success, or -1 on error.
682 * \sa SDL_FillRects
430 683 */ */
431 684 extern DECLSPEC int SDLCALL SDL_FillRect extern DECLSPEC int SDLCALL SDL_FillRect
432 685 (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color); (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
686
687 /**
688 * Perform a fast fill of a set of rectangles with a specific color.
689 *
690 * `color` should be a pixel of the format used by the surface, and can be
691 * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
692 * alpha component then the destination is simply filled with that alpha
693 * information, no blending takes place.
694 *
695 * If there is a clip rectangle set on the destination (set via
696 * SDL_SetClipRect()), then this function will fill based on the intersection
697 * of the clip rectangle and `rect`.
698 *
699 * \param dst the SDL_Surface structure that is the drawing target
700 * \param rects an array of SDL_Rects representing the rectangles to fill.
701 * \param count the number of rectangles in the array
702 * \param color the color to fill with
703 * \returns 0 on success or a negative error code on failure; call
704 * SDL_GetError() for more information.
705 *
706 * \sa SDL_FillRect
707 */
433 708 extern DECLSPEC int SDLCALL SDL_FillRects extern DECLSPEC int SDLCALL SDL_FillRects
434 709 (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color); (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
435 710
711 /* !!! FIXME: merge this documentation with the wiki */
436 712 /** /**
437 713 * Performs a fast blit from the source surface to the destination surface. * Performs a fast blit from the source surface to the destination surface.
438 714 * *
 
... ... extern DECLSPEC int SDLCALL SDL_FillRects
441 717 * surface (\c src or \c dst) is copied. The final blit rectangles are saved * surface (\c src or \c dst) is copied. The final blit rectangles are saved
442 718 * in \c srcrect and \c dstrect after all clipping is performed. * in \c srcrect and \c dstrect after all clipping is performed.
443 719 * *
444 * \return If the blit is successful, it returns 0, otherwise it returns -1.
720 * \returns 0 if the blit is successful, otherwise it returns -1.
445 721 * *
446 722 * The blit function should not be called on a locked surface. * The blit function should not be called on a locked surface.
447 723 * *
 
... ... extern DECLSPEC int SDLCALL SDL_FillRects
493 769 #define SDL_BlitSurface SDL_UpperBlit #define SDL_BlitSurface SDL_UpperBlit
494 770
495 771 /** /**
496 * This is the public blit function, SDL_BlitSurface(), and it performs
497 * rectangle validation and clipping before passing it to SDL_LowerBlit()
772 * Perform a fast blit from the source surface to the destination surface.
773 *
774 * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
775 * macro for this function with a less confusing name.
776 *
777 * \sa SDL_BlitSurface
498 778 */ */
499 779 extern DECLSPEC int SDLCALL SDL_UpperBlit extern DECLSPEC int SDLCALL SDL_UpperBlit
500 780 (SDL_Surface * src, const SDL_Rect * srcrect, (SDL_Surface * src, const SDL_Rect * srcrect,
501 781 SDL_Surface * dst, SDL_Rect * dstrect); SDL_Surface * dst, SDL_Rect * dstrect);
502 782
503 783 /** /**
504 * This is a semi-private blit function and it performs low-level surface
505 * blitting only.
784 * Perform low-level surface blitting only.
785 *
786 * This is a semi-private blit function and it performs low-level surface
787 * blitting, assuming the input rectangles have already been clipped.
788 *
789 * Unless you know what you're doing, you should be using SDL_BlitSurface()
790 * instead.
791 *
792 * \param src the SDL_Surface structure to be copied from
793 * \param srcrect the SDL_Rect structure representing the rectangle to be
794 * copied, or NULL to copy the entire surface
795 * \param dst the SDL_Surface structure that is the blit target
796 * \param dstrect the SDL_Rect structure representing the rectangle that is
797 * copied into
798 * \returns 0 on success or a negative error code on failure; call
799 * SDL_GetError() for more information.
800 *
801 * \sa SDL_BlitSurface
506 802 */ */
507 803 extern DECLSPEC int SDLCALL SDL_LowerBlit extern DECLSPEC int SDLCALL SDL_LowerBlit
508 804 (SDL_Surface * src, SDL_Rect * srcrect, (SDL_Surface * src, SDL_Rect * srcrect,
509 805 SDL_Surface * dst, SDL_Rect * dstrect); SDL_Surface * dst, SDL_Rect * dstrect);
510 806
807
808 /**
809 * Perform a fast, low quality, stretch blit between two surfaces of the
810 * same format.
811 *
812 * Please use SDL_BlitScaled() instead.
813 */
814 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
815 const SDL_Rect * srcrect,
816 SDL_Surface * dst,
817 const SDL_Rect * dstrect);
818
511 819 /** /**
512 * \brief Perform a fast, low quality, stretch blit between two surfaces of the
513 * same pixel format.
514 *
515 * \note This function uses a static buffer, and is not thread-safe.
820 * Perform bilinear scaling between two surfaces of the same format, 32BPP.
516 821 */ */
517 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
822 extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
518 823 const SDL_Rect * srcrect, const SDL_Rect * srcrect,
519 824 SDL_Surface * dst, SDL_Surface * dst,
520 825 const SDL_Rect * dstrect); const SDL_Rect * dstrect);
521 826
827
522 828 #define SDL_BlitScaled SDL_UpperBlitScaled #define SDL_BlitScaled SDL_UpperBlitScaled
523 829
524 830 /** /**
525 * This is the public scaled blit function, SDL_BlitScaled(), and it performs
526 * rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
831 * Perform a scaled surface copy to a destination surface.
832 *
833 * SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is
834 * merely a macro for this function with a less confusing name.
835 *
836 * \sa SDL_BlitScaled
527 837 */ */
528 838 extern DECLSPEC int SDLCALL SDL_UpperBlitScaled extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
529 839 (SDL_Surface * src, const SDL_Rect * srcrect, (SDL_Surface * src, const SDL_Rect * srcrect,
530 840 SDL_Surface * dst, SDL_Rect * dstrect); SDL_Surface * dst, SDL_Rect * dstrect);
531 841
532 842 /** /**
533 * This is a semi-private blit function and it performs low-level surface
534 * scaled blitting only.
843 * Perform low-level surface scaled blitting only.
844 *
845 * This is a semi-private function and it performs low-level surface blitting,
846 * assuming the input rectangles have already been clipped.
847 *
848 * \param src the SDL_Surface structure to be copied from
849 * \param srcrect the SDL_Rect structure representing the rectangle to be
850 * copied
851 * \param dst the SDL_Surface structure that is the blit target
852 * \param dstrect the SDL_Rect structure representing the rectangle that is
853 * copied into
854 * \returns 0 on success or a negative error code on failure; call
855 * SDL_GetError() for more information.
856 *
857 * \sa SDL_BlitScaled
535 858 */ */
536 859 extern DECLSPEC int SDLCALL SDL_LowerBlitScaled extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
537 860 (SDL_Surface * src, SDL_Rect * srcrect, (SDL_Surface * src, SDL_Rect * srcrect,
538 861 SDL_Surface * dst, SDL_Rect * dstrect); SDL_Surface * dst, SDL_Rect * dstrect);
539 862
540 863 /** /**
541 * \brief Set the YUV conversion mode
864 * Set the YUV conversion mode
542 865 */ */
543 866 extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode); extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
544 867
545 868 /** /**
546 * \brief Get the YUV conversion mode
869 * Get the YUV conversion mode
547 870 */ */
548 871 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void); extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
549 872
550 873 /** /**
551 * \brief Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
874 * Get the YUV conversion mode, returning the correct mode for the resolution
875 * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
552 876 */ */
553 877 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height); extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);
554 878
File include/SDL2/SDL_system.h changed (mode: 100644) (index d296ab1..5f12787)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
43 43 /* Platform specific functions for Windows */ /* Platform specific functions for Windows */
44 44 #ifdef __WIN32__ #ifdef __WIN32__
45 45
46 /**
47 \brief Set a function that is called for every windows message, before TranslateMessage()
48 */
49 46 typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam); typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
50 extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
51 47
52 48 /** /**
53 \brief Returns the D3D9 adapter index that matches the specified display index.
49 * Set a callback for every Windows message, run before TranslateMessage().
50 *
51 * \param callback The SDL_WindowsMessageHook function to call.
52 * \param userdata a pointer to pass to every iteration of `callback`
53 */
54 extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
54 55
55 This adapter index can be passed to IDirect3D9::CreateDevice and controls
56 on which monitor a full screen application will appear.
57 */
56 /**
57 * Get the D3D9 adapter index that matches the specified display index.
58 *
59 * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
60 * controls on which monitor a full screen application will appear.
61 *
62 * \param displayIndex the display index for which to get the D3D9 adapter
63 * index
64 * \returns the D3D9 adapter index on success or a negative error code on
65 * failure; call SDL_GetError() for more information.
66 *
67 * \since This function is available since SDL 2.0.1.
68 */
58 69 extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex ); extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
59 70
60 71 typedef struct IDirect3DDevice9 IDirect3DDevice9; typedef struct IDirect3DDevice9 IDirect3DDevice9;
61 /**
62 \brief Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer.
63 72
64 Once you are done using the device, you should release it to avoid a resource leak.
73 /**
74 * Get the D3D9 device associated with a renderer.
75 *
76 * Once you are done using the device, you should release it to avoid a
77 * resource leak.
78 *
79 * \param renderer the renderer from which to get the associated D3D device
80 * \returns the D3D9 device associated with given renderer or NULL if it is
81 * not a D3D9 renderer; call SDL_GetError() for more information.
82 *
83 * \since This function is available since SDL 2.0.1.
65 84 */ */
66 85 extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer); extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
67 86
87 typedef struct ID3D11Device ID3D11Device;
88
68 89 /** /**
69 \brief Returns the DXGI Adapter and Output indices for the specified display index.
90 * Get the D3D11 device associated with a renderer.
91 *
92 * Once you are done using the device, you should release it to avoid a
93 * resource leak.
94 *
95 * \param renderer the renderer from which to get the associated D3D11 device
96 * \returns the D3D11 device associated with given renderer or NULL if it is
97 * not a D3D11 renderer; call SDL_GetError() for more information.
98 */
99 extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer);
70 100
71 These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
72 required to create a DX10 or DX11 device and swap chain.
101 /**
102 * Get the DXGI Adapter and Output indices for the specified display index.
103 *
104 * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
105 * `EnumOutputs` respectively to get the objects required to create a DX10 or
106 * DX11 device and swap chain.
107 *
108 * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
109 * returns an SDL_bool.
110 *
111 * \param displayIndex the display index for which to get both indices
112 * \param adapterIndex a pointer to be filled in with the adapter index
113 * \param outputIndex a pointer to be filled in with the output index
114 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
115 * for more information.
116 *
117 * \since This function is available since SDL 2.0.2.
73 118 */ */
74 119 extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex ); extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
75 120
 
... ... extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *a
80 125 #ifdef __LINUX__ #ifdef __LINUX__
81 126
82 127 /** /**
83 \brief Sets the UNIX nice value for a thread, using setpriority() if possible, and RealtimeKit if available.
84
85 \return 0 on success, or -1 on error.
128 * Sets the UNIX nice value for a thread.
129 *
130 * This uses setpriority() if possible, and RealtimeKit if available.
131 *
132 * \param threadID the Unix thread ID to change priority of.
133 * \param priority The new, Unix-specific, priority value.
134 * \returns 0 on success, or -1 on error.
86 135 */ */
87 136 extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority); extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
88 137
 
... ... extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
104 153 #ifdef __ANDROID__ #ifdef __ANDROID__
105 154
106 155 /** /**
107 \brief Get the JNI environment for the current thread
108
109 This returns JNIEnv*, but the prototype is void* so we don't need jni.h
156 * Get the Android Java Native Interface Environment of the current thread.
157 *
158 * This is the JNIEnv one needs to access the Java virtual machine from native
159 * code, and is needed for many Android APIs to be usable from C.
160 *
161 * The prototype of the function in SDL's code actually declare a void* return
162 * type, even if the implementation returns a pointer to a JNIEnv. The
163 * rationale being that the SDL headers can avoid including jni.h.
164 *
165 * \returns a pointer to Java native interface object (JNIEnv) to which the
166 * current thread is attached, or 0 on error.
167 *
168 * \since This function is available since SDL 2.0.0.
169 *
170 * \sa SDL_AndroidGetActivity
110 171 */ */
111 172 extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void); extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
112 173
113 174 /** /**
114 \brief Get the SDL Activity object for the application
115
116 This returns jobject, but the prototype is void* so we don't need jni.h
117 The jobject returned by SDL_AndroidGetActivity is a local reference.
118 It is the caller's responsibility to properly release it
119 (using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
175 * Retrieve the Java instance of the Android activity class.
176 *
177 * The prototype of the function in SDL's code actually declares a void*
178 * return type, even if the implementation returns a jobject. The rationale
179 * being that the SDL headers can avoid including jni.h.
180 *
181 * The jobject returned by the function is a local reference and must be
182 * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
183 * DeleteLocalRef() functions of the Java native interface:
184 *
185 * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
186 *
187 * \returns the jobject representing the instance of the Activity class of the
188 * Android application, or NULL on error.
189 *
190 * \since This function is available since SDL 2.0.0.
191 *
192 * \sa SDL_AndroidGetJNIEnv
120 193 */ */
121 194 extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void); extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
122 195
123 196 /** /**
124 \brief Return API level of the current device
125
126 API level 30: Android 11
127 API level 29: Android 10
128 API level 28: Android 9
129 API level 27: Android 8.1
130 API level 26: Android 8.0
131 API level 25: Android 7.1
132 API level 24: Android 7.0
133 API level 23: Android 6.0
134 API level 22: Android 5.1
135 API level 21: Android 5.0
136 API level 20: Android 4.4W
137 API level 19: Android 4.4
138 API level 18: Android 4.3
139 API level 17: Android 4.2
140 API level 16: Android 4.1
141 API level 15: Android 4.0.3
142 API level 14: Android 4.0
143 API level 13: Android 3.2
144 API level 12: Android 3.1
145 API level 11: Android 3.0
146 API level 10: Android 2.3.3
197 * Query Android API level of the current device.
198 *
199 * - API level 30: Android 11
200 * - API level 29: Android 10
201 * - API level 28: Android 9
202 * - API level 27: Android 8.1
203 * - API level 26: Android 8.0
204 * - API level 25: Android 7.1
205 * - API level 24: Android 7.0
206 * - API level 23: Android 6.0
207 * - API level 22: Android 5.1
208 * - API level 21: Android 5.0
209 * - API level 20: Android 4.4W
210 * - API level 19: Android 4.4
211 * - API level 18: Android 4.3
212 * - API level 17: Android 4.2
213 * - API level 16: Android 4.1
214 * - API level 15: Android 4.0.3
215 * - API level 14: Android 4.0
216 * - API level 13: Android 3.2
217 * - API level 12: Android 3.1
218 * - API level 11: Android 3.0
219 * - API level 10: Android 2.3.3
220 *
221 * \returns the Android API level.
147 222 */ */
148 223 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
149 224
150 225 /** /**
151 \brief Return true if the application is running on Android TV
226 * Query if the application is running on Android TV.
227 *
228 * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
152 229 */ */
153 230 extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
154 231
155 232 /** /**
156 \brief Return true if the application is running on a Chromebook
233 * Query if the application is running on a Chromebook.
234 *
235 * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
157 236 */ */
158 237 extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
159 238
160 239 /** /**
161 \brief Return true is the application is running on a Samsung DeX docking station
240 * Query if the application is running on a Samsung DeX docking station.
241 *
242 * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
162 243 */ */
163 244 extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
164 245
165 246 /** /**
166 \brief Trigger the Android system back button behavior.
247 * Trigger the Android system back button behavior.
167 248 */ */
168 249 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
169 250
 
... ... extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
175 256 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
176 257
177 258 /** /**
178 \brief Get the path used for internal storage for this application.
179
180 This path is unique to your application and cannot be written to
181 by other applications.
259 * Get the path used for internal storage for this application.
260 *
261 * This path is unique to your application and cannot be written to by other
262 * applications.
263 *
264 * Your internal storage path is typically:
265 * `/data/data/your.app.package/files`.
266 *
267 * \returns the path used for internal storage or NULL on failure; call
268 * SDL_GetError() for more information.
269 *
270 * \since This function is available since SDL 2.0.0.
271 *
272 * \sa SDL_AndroidGetExternalStorageState
182 273 */ */
183 274 extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void); extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
184 275
185 276 /** /**
186 \brief Get the current state of external storage, a bitmask of these values:
187 SDL_ANDROID_EXTERNAL_STORAGE_READ
188 SDL_ANDROID_EXTERNAL_STORAGE_WRITE
189
190 If external storage is currently unavailable, this will return 0.
191 */
277 * Get the current state of external storage.
278 *
279 * The current state of external storage, a bitmask of these values:
280 * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
281 *
282 * If external storage is currently unavailable, this will return 0.
283 *
284 * \returns the current state of external storage on success or 0 on failure;
285 * call SDL_GetError() for more information.
286 *
287 * \since This function is available since SDL 2.0.0.
288 *
289 * \sa SDL_AndroidGetExternalStoragePath
290 */
192 291 extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void); extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
193 292
194 293 /** /**
195 \brief Get the path used for external storage for this application.
196
197 This path is unique to your application, but is public and can be
198 written to by other applications.
294 * Get the path used for external storage for this application.
295 *
296 * This path is unique to your application, but is public and can be written
297 * to by other applications.
298 *
299 * Your external storage path is typically:
300 * `/storage/sdcard0/Android/data/your.app.package/files`.
301 *
302 * \returns the path used for external storage for this application on success
303 * or NULL on failure; call SDL_GetError() for more information.
304 *
305 * \since This function is available since SDL 2.0.0.
306 *
307 * \sa SDL_AndroidGetExternalStorageState
199 308 */ */
200 309 extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void); extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
201 310
202 311 /** /**
203 \brief Request permissions at runtime.
204
205 This blocks the calling thread until the permission is granted or
206 denied. Returns SDL_TRUE if the permission was granted.
312 * Request permissions at runtime.
313 *
314 * This blocks the calling thread until the permission is granted or denied.
315 *
316 * \param permission The permission to request.
317 * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.
207 318 */ */
208 319 extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission); extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
209 320
321 /**
322 * Shows an Android toast notification.
323 *
324 * Toasts are a sort of lightweight notification that are unique to Android.
325 *
326 * https://developer.android.com/guide/topics/ui/notifiers/toasts
327 *
328 * Shows toast in UI thread.
329 *
330 * For the `gravity` parameter, choose a value from here, or -1 if you don't
331 * have a preference:
332 *
333 * https://developer.android.com/reference/android/view/Gravity
334 *
335 * \param message text message to be shown
336 * \param duration 0=short, 1=long
337 * \param gravity where the notification should appear on the screen.
338 * \param xoffset set this parameter only when gravity >=0
339 * \param yoffset set this parameter only when gravity >=0
340 * \returns 0 if success, -1 if any error occurs.
341 */
342 extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
343
210 344 #endif /* __ANDROID__ */ #endif /* __ANDROID__ */
211 345
212 346 /* Platform specific functions for WinRT */ /* Platform specific functions for WinRT */
 
... ... typedef enum
256 390
257 391
258 392 /** /**
259 * \brief Retrieves a WinRT defined path on the local file system
260 *
261 * \note Documentation on most app-specific path types on WinRT
262 * can be found on MSDN, at the URL:
263 * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
264 *
265 * \param pathType The type of path to retrieve.
266 * \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
267 * if the path is not available for any reason. Not all paths are
268 * available on all versions of Windows. This is especially true on
269 * Windows Phone. Check the documentation for the given
270 * SDL_WinRT_Path for more information on which path types are
271 * supported where.
393 * Retrieve a WinRT defined path on the local file system.
394 *
395 * Not all paths are available on all versions of Windows. This is especially
396 * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
397 * for more information on which path types are supported where.
398 *
399 * Documentation on most app-specific path types on WinRT can be found on
400 * MSDN, at the URL:
401 *
402 * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
403 *
404 * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
405 * \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if
406 * the path is not available for any reason; call SDL_GetError() for
407 * more information.
408 *
409 * \since This function is available since SDL 2.0.3.
410 *
411 * \sa SDL_WinRTGetFSPathUTF8
272 412 */ */
273 413 extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType); extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
274 414
275 415 /** /**
276 * \brief Retrieves a WinRT defined path on the local file system
277 *
278 * \note Documentation on most app-specific path types on WinRT
279 * can be found on MSDN, at the URL:
280 * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
281 *
282 * \param pathType The type of path to retrieve.
283 * \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
284 * if the path is not available for any reason. Not all paths are
285 * available on all versions of Windows. This is especially true on
286 * Windows Phone. Check the documentation for the given
287 * SDL_WinRT_Path for more information on which path types are
288 * supported where.
416 * Retrieve a WinRT defined path on the local file system.
417 *
418 * Not all paths are available on all versions of Windows. This is especially
419 * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
420 * for more information on which path types are supported where.
421 *
422 * Documentation on most app-specific path types on WinRT can be found on
423 * MSDN, at the URL:
424 *
425 * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
426 *
427 * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
428 * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
429 * the path is not available for any reason; call SDL_GetError() for
430 * more information.
431 *
432 * \since This function is available since SDL 2.0.3.
433 *
434 * \sa SDL_WinRTGetFSPathUNICODE
289 435 */ */
290 436 extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType); extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
291 437
292 438 /** /**
293 * \brief Detects the device family of WinRT plattform on runtime
439 * Detects the device family of WinRT plattform at runtime.
294 440 * *
295 * \return Device family
441 * \returns a value from the SDL_WinRT_DeviceFamily enum.
296 442 */ */
297 443 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily(); extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
298 444
299 445 #endif /* __WINRT__ */ #endif /* __WINRT__ */
300 446
301 447 /** /**
302 \brief Return true if the current device is a tablet.
448 * Query if the current device is a tablet.
449 *
450 * If SDL can't determine this, it will return SDL_FALSE.
451 *
452 * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
303 453 */ */
304 454 extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
305 455
File include/SDL2/SDL_syswm.h changed (mode: 100644) (index f0e9675..046a096)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef void *EGLSurface;
113 113 #endif #endif
114 114 #endif /* SDL_PROTOTYPES_ONLY */ #endif /* SDL_PROTOTYPES_ONLY */
115 115
116 #if defined(SDL_VIDEO_DRIVER_KMSDRM)
117 struct gbm_device;
118 #endif
119
116 120
117 121 #include "begin_code.h" #include "begin_code.h"
118 122 /* Set up for C function definitions, even when using C++ */ /* Set up for C function definitions, even when using C++ */
 
... ... typedef enum
138 142 SDL_SYSWM_ANDROID, SDL_SYSWM_ANDROID,
139 143 SDL_SYSWM_VIVANTE, SDL_SYSWM_VIVANTE,
140 144 SDL_SYSWM_OS2, SDL_SYSWM_OS2,
141 SDL_SYSWM_HAIKU
145 SDL_SYSWM_HAIKU,
146 SDL_SYSWM_KMSDRM
142 147 } SDL_SYSWM_TYPE; } SDL_SYSWM_TYPE;
143 148
144 149 /** /**
 
... ... struct SDL_SysWMinfo
251 256 #if defined(SDL_VIDEO_DRIVER_COCOA) #if defined(SDL_VIDEO_DRIVER_COCOA)
252 257 struct struct
253 258 { {
254 #if defined(__OBJC__) && defined(__has_feature) && __has_feature(objc_arc)
259 #if defined(__OBJC__) && defined(__has_feature)
260 #if __has_feature(objc_arc)
255 261 NSWindow __unsafe_unretained *window; /**< The Cocoa window */ NSWindow __unsafe_unretained *window; /**< The Cocoa window */
262 #else
263 NSWindow *window; /**< The Cocoa window */
264 #endif
256 265 #else #else
257 266 NSWindow *window; /**< The Cocoa window */ NSWindow *window; /**< The Cocoa window */
258 267 #endif #endif
 
... ... struct SDL_SysWMinfo
261 270 #if defined(SDL_VIDEO_DRIVER_UIKIT) #if defined(SDL_VIDEO_DRIVER_UIKIT)
262 271 struct struct
263 272 { {
264 #if defined(__OBJC__) && defined(__has_feature) && __has_feature(objc_arc)
273 #if defined(__OBJC__) && defined(__has_feature)
274 #if __has_feature(objc_arc)
265 275 UIWindow __unsafe_unretained *window; /**< The UIKit window */ UIWindow __unsafe_unretained *window; /**< The UIKit window */
276 #else
277 UIWindow *window; /**< The UIKit window */
278 #endif
266 279 #else #else
267 280 UIWindow *window; /**< The UIKit window */ UIWindow *window; /**< The UIKit window */
268 281 #endif #endif
 
... ... struct SDL_SysWMinfo
274 287 #if defined(SDL_VIDEO_DRIVER_WAYLAND) #if defined(SDL_VIDEO_DRIVER_WAYLAND)
275 288 struct struct
276 289 { {
277 struct wl_display *display; /**< Wayland display */
278 struct wl_surface *surface; /**< Wayland surface */
279 struct wl_shell_surface *shell_surface; /**< Wayland shell_surface (window manager handle) */
290 struct wl_display *display; /**< Wayland display */
291 struct wl_surface *surface; /**< Wayland surface */
292 void *shell_surface; /**< DEPRECATED Wayland shell_surface (window manager handle) */
293 struct wl_egl_window *egl_window; /**< Wayland EGL window (native window) */
294 struct xdg_surface *xdg_surface; /**< Wayland xdg surface (window manager handle) */
280 295 } wl; } wl;
281 296 #endif #endif
282 297 #if defined(SDL_VIDEO_DRIVER_MIR) /* no longer available, left for API/ABI compatibility. Remove in 2.1! */ #if defined(SDL_VIDEO_DRIVER_MIR) /* no longer available, left for API/ABI compatibility. Remove in 2.1! */
 
... ... struct SDL_SysWMinfo
311 326 } vivante; } vivante;
312 327 #endif #endif
313 328
329 #if defined(SDL_VIDEO_DRIVER_KMSDRM)
330 struct
331 {
332 int dev_index; /**< Device index (ex: the X in /dev/dri/cardX) */
333 int drm_fd; /**< DRM FD (unavailable on Vulkan windows) */
334 struct gbm_device *gbm_dev; /**< GBM device (unavailable on Vulkan windows) */
335 } kmsdrm;
336 #endif
337
314 338 /* Make sure this union is always 64 bytes (8 64-bit pointers). */ /* Make sure this union is always 64 bytes (8 64-bit pointers). */
315 339 /* Be careful not to overflow this if you add a new target! */ /* Be careful not to overflow this if you add a new target! */
316 340 Uint8 dummy[64]; Uint8 dummy[64];
 
... ... struct SDL_SysWMinfo
321 345
322 346 typedef struct SDL_SysWMinfo SDL_SysWMinfo; typedef struct SDL_SysWMinfo SDL_SysWMinfo;
323 347
324 /* Function prototypes */
348
325 349 /** /**
326 * \brief This function allows access to driver-dependent window information.
350 * Get driver-specific information about a window.
351 *
352 * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
327 353 * *
328 * \param window The window about which information is being requested
329 * \param info This structure must be initialized with the SDL version, and is
330 * then filled in with information about the given window.
354 * The caller must initialize the `info` structure's version by using
355 * `SDL_VERSION(&info.version)`, and then this function will fill in the rest
356 * of the structure with information about the given window.
331 357 * *
332 * \return SDL_TRUE if the function is implemented and the version member of
333 * the \c info struct is valid, SDL_FALSE otherwise.
358 * \param window the window about which information is being requested
359 * \param info an SDL_SysWMinfo structure filled in with window information
360 * \returns SDL_TRUE if the function is implemented and the `version` member
361 * of the `info` struct is valid, or SDL_FALSE if the information
362 * could not be retrieved; call SDL_GetError() for more information.
334 363 * *
335 * You typically use this function like this:
336 * \code
337 * SDL_SysWMinfo info;
338 * SDL_VERSION(&info.version);
339 * if ( SDL_GetWindowWMInfo(window, &info) ) { ... }
340 * \endcode
364 * \since This function is available since SDL 2.0.0.
341 365 */ */
342 366 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window, extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window,
343 367 SDL_SysWMinfo * info); SDL_SysWMinfo * info);
File include/SDL2/SDL_test.h changed (mode: 100644) (index 7095427..66fde83)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_assert.h changed (mode: 100644) (index 19b9095..d8e9d7d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
66 66 * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
67 67 * \param assertDescription Message to log with the assert describing it. * \param assertDescription Message to log with the assert describing it.
68 68 * *
69 * \returns Returns the assertCondition so it can be used to externally to break execution flow if desired.
69 * \returns the assertCondition so it can be used to externally to break execution flow if desired.
70 70 */ */
71 71 int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
72 72
File include/SDL2/SDL_test_common.h changed (mode: 100644) (index 3ad2030..97f036d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
37 37 #if defined(__PSP__) #if defined(__PSP__)
38 38 #define DEFAULT_WINDOW_WIDTH 480 #define DEFAULT_WINDOW_WIDTH 480
39 39 #define DEFAULT_WINDOW_HEIGHT 272 #define DEFAULT_WINDOW_HEIGHT 272
40 #elif defined(__VITA__)
41 #define DEFAULT_WINDOW_WIDTH 960
42 #define DEFAULT_WINDOW_HEIGHT 544
40 43 #else #else
41 44 #define DEFAULT_WINDOW_WIDTH 640 #define DEFAULT_WINDOW_WIDTH 640
42 45 #define DEFAULT_WINDOW_HEIGHT 480 #define DEFAULT_WINDOW_HEIGHT 480
 
... ... typedef struct
61 64 const char *window_title; const char *window_title;
62 65 const char *window_icon; const char *window_icon;
63 66 Uint32 window_flags; Uint32 window_flags;
67 SDL_bool flash_on_focus_loss;
64 68 int window_x; int window_x;
65 69 int window_y; int window_y;
66 70 int window_w; int window_w;
 
... ... extern "C" {
126 130 * \param argv Array of command line parameters * \param argv Array of command line parameters
127 131 * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO) * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
128 132 * *
129 * \returns Returns a newly allocated common state object.
133 * \returns a newly allocated common state object.
130 134 */ */
131 135 SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags); SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
132 136
 
... ... SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
136 140 * \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
137 141 * \param index The index of the argument to process in argv[]. * \param index The index of the argument to process in argv[].
138 142 * *
139 * \returns The number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
143 * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
140 144 */ */
141 145 int SDLTest_CommonArg(SDLTest_CommonState * state, int index); int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
142 146
 
... ... void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, cons
164 168 * those strings' memory is freed and can no longer be used. * those strings' memory is freed and can no longer be used.
165 169 * *
166 170 * \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
167 * \returns String with usage information
171 * \returns a string with usage information
168 172 */ */
169 173 const char *SDLTest_CommonUsage(SDLTest_CommonState * state); const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
170 174
 
... ... const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
173 177 * *
174 178 * \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
175 179 * *
176 * \returns True if initialization succeeded, false otherwise
180 * \returns SDL_TRUE if initialization succeeded, false otherwise
177 181 */ */
178 182 SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
179 183
 
... ... SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
184 188 * \param argc argc, as supplied to SDL_main * \param argc argc, as supplied to SDL_main
185 189 * \param argv argv, as supplied to SDL_main * \param argv argv, as supplied to SDL_main
186 190 * *
187 * \returns False if app should quit, true otherwise.
191 * \returns SDL_FALSE if app should quit, true otherwise.
188 192 */ */
189 193 SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv); SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv);
190 194
 
... ... void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *do
206 210 */ */
207 211 void SDLTest_CommonQuit(SDLTest_CommonState * state); void SDLTest_CommonQuit(SDLTest_CommonState * state);
208 212
213 /**
214 * \brief Draws various window information (position, size, etc.) to the renderer.
215 *
216 * \param renderer The renderer to draw to.
217 * \param window The window whose information should be displayed.
218 *
219 */
220 void SDLTest_CommonDrawWindowInfo(SDL_Renderer * renderer, SDL_Window * window);
209 221
210 222 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
211 223 #ifdef __cplusplus #ifdef __cplusplus
File include/SDL2/SDL_test_compare.h changed (mode: 100644) (index 38b22bb..ee42c9d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_crc32.h changed (mode: 100644) (index 611066a..f41e24e)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_font.h changed (mode: 100644) (index dc4ce6d..daa6670)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
48 48 * \param y The Y coordinate of the upper left corner of the character. * \param y The Y coordinate of the upper left corner of the character.
49 49 * \param c The character to draw. * \param c The character to draw.
50 50 * *
51 * \returns Returns 0 on success, -1 on failure.
51 * \returns 0 on success, -1 on failure.
52 52 */ */
53 53 int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c); int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
54 54
 
... ... int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
60 60 * \param y The Y coordinate of the upper left corner of the string. * \param y The Y coordinate of the upper left corner of the string.
61 61 * \param s The string to draw. * \param s The string to draw.
62 62 * *
63 * \returns Returns 0 on success, -1 on failure.
63 * \returns 0 on success, -1 on failure.
64 64 */ */
65 65 int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s); int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s);
66 66
File include/SDL2/SDL_test_fuzzer.h changed (mode: 100644) (index cb5a17a..84278bf)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... void SDLTest_FuzzerInit(Uint64 execKey);
66 66 /** /**
67 67 * Returns a random Uint8 * Returns a random Uint8
68 68 * *
69 * \returns Generated integer
69 * \returns a generated integer
70 70 */ */
71 71 Uint8 SDLTest_RandomUint8(void); Uint8 SDLTest_RandomUint8(void);
72 72
73 73 /** /**
74 74 * Returns a random Sint8 * Returns a random Sint8
75 75 * *
76 * \returns Generated signed integer
76 * \returns a generated signed integer
77 77 */ */
78 78 Sint8 SDLTest_RandomSint8(void); Sint8 SDLTest_RandomSint8(void);
79 79
 
... ... Sint8 SDLTest_RandomSint8(void);
81 81 /** /**
82 82 * Returns a random Uint16 * Returns a random Uint16
83 83 * *
84 * \returns Generated integer
84 * \returns a generated integer
85 85 */ */
86 86 Uint16 SDLTest_RandomUint16(void); Uint16 SDLTest_RandomUint16(void);
87 87
88 88 /** /**
89 89 * Returns a random Sint16 * Returns a random Sint16
90 90 * *
91 * \returns Generated signed integer
91 * \returns a generated signed integer
92 92 */ */
93 93 Sint16 SDLTest_RandomSint16(void); Sint16 SDLTest_RandomSint16(void);
94 94
 
... ... Sint16 SDLTest_RandomSint16(void);
96 96 /** /**
97 97 * Returns a random integer * Returns a random integer
98 98 * *
99 * \returns Generated integer
99 * \returns a generated integer
100 100 */ */
101 101 Sint32 SDLTest_RandomSint32(void); Sint32 SDLTest_RandomSint32(void);
102 102
 
... ... Sint32 SDLTest_RandomSint32(void);
104 104 /** /**
105 105 * Returns a random positive integer * Returns a random positive integer
106 106 * *
107 * \returns Generated integer
107 * \returns a generated integer
108 108 */ */
109 109 Uint32 SDLTest_RandomUint32(void); Uint32 SDLTest_RandomUint32(void);
110 110
111 111 /** /**
112 112 * Returns random Uint64. * Returns random Uint64.
113 113 * *
114 * \returns Generated integer
114 * \returns a generated integer
115 115 */ */
116 116 Uint64 SDLTest_RandomUint64(void); Uint64 SDLTest_RandomUint64(void);
117 117
 
... ... Uint64 SDLTest_RandomUint64(void);
119 119 /** /**
120 120 * Returns random Sint64. * Returns random Sint64.
121 121 * *
122 * \returns Generated signed integer
122 * \returns a generated signed integer
123 123 */ */
124 124 Sint64 SDLTest_RandomSint64(void); Sint64 SDLTest_RandomSint64(void);
125 125
126 126 /** /**
127 * \returns random float in range [0.0 - 1.0[
127 * \returns a random float in range [0.0 - 1.0]
128 128 */ */
129 129 float SDLTest_RandomUnitFloat(void); float SDLTest_RandomUnitFloat(void);
130 130
131 131 /** /**
132 * \returns random double in range [0.0 - 1.0[
132 * \returns a random double in range [0.0 - 1.0]
133 133 */ */
134 134 double SDLTest_RandomUnitDouble(void); double SDLTest_RandomUnitDouble(void);
135 135
136 136 /** /**
137 * \returns random float.
137 * \returns a random float.
138 138 * *
139 139 */ */
140 140 float SDLTest_RandomFloat(void); float SDLTest_RandomFloat(void);
141 141
142 142 /** /**
143 * \returns random double.
143 * \returns a random double.
144 144 * *
145 145 */ */
146 146 double SDLTest_RandomDouble(void); double SDLTest_RandomDouble(void);
 
... ... double SDLTest_RandomDouble(void);
162 162 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
163 163 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
164 164 * *
165 * \returns Random boundary value for the given range and domain or 0 with error set
165 * \returns a random boundary value for the given range and domain or 0 with error set
166 166 */ */
167 167 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain); Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
168 168
 
... ... Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo
183 183 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
184 184 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
185 185 * *
186 * \returns Random boundary value for the given range and domain or 0 with error set
186 * \returns a random boundary value for the given range and domain or 0 with error set
187 187 */ */
188 188 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain); Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
189 189
 
... ... Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL
204 204 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
205 205 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
206 206 * *
207 * \returns Random boundary value for the given range and domain or 0 with error set
207 * \returns a random boundary value for the given range and domain or 0 with error set
208 208 */ */
209 209 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain); Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
210 210
 
... ... Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL
225 225 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
226 226 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
227 227 * *
228 * \returns Random boundary value for the given range and domain or 0 with error set
228 * \returns a random boundary value for the given range and domain or 0 with error set
229 229 */ */
230 230 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain); Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
231 231
 
... ... Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL
246 246 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
247 247 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
248 248 * *
249 * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
249 * \returns a random boundary value for the given range and domain or SINT8_MIN with error set
250 250 */ */
251 251 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain); Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
252 252
 
... ... Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo
268 268 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
269 269 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
270 270 * *
271 * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
271 * \returns a random boundary value for the given range and domain or SINT16_MIN with error set
272 272 */ */
273 273 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain); Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
274 274
 
... ... Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL
289 289 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
290 290 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
291 291 * *
292 * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
292 * \returns a random boundary value for the given range and domain or SINT32_MIN with error set
293 293 */ */
294 294 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain); Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
295 295
 
... ... Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL
310 310 * \param boundary2 Upper boundary limit * \param boundary2 Upper boundary limit
311 311 * \param validDomain Should the generated boundary be valid (=within the bounds) or not? * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
312 312 * *
313 * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
313 * \returns a random boundary value for the given range and domain or SINT64_MIN with error set
314 314 */ */
315 315 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain); Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
316 316
 
... ... Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL
324 324 * \param min Minimum inclusive value of returned random number * \param min Minimum inclusive value of returned random number
325 325 * \param max Maximum inclusive value of returned random number * \param max Maximum inclusive value of returned random number
326 326 * *
327 * \returns Generated random integer in range
327 * \returns a generated random integer in range
328 328 */ */
329 329 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
330 330
 
... ... Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
336 336 * *
337 337 * Note: Returned string needs to be deallocated. * Note: Returned string needs to be deallocated.
338 338 * *
339 * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
339 * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated.
340 340 */ */
341 341 char * SDLTest_RandomAsciiString(void); char * SDLTest_RandomAsciiString(void);
342 342
 
... ... char * SDLTest_RandomAsciiString(void);
350 350 * *
351 351 * \param maxLength The maximum length of the generated string. * \param maxLength The maximum length of the generated string.
352 352 * *
353 * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
353 * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
354 354 */ */
355 355 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
356 356
 
... ... char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
364 364 * *
365 365 * \param size The length of the generated string * \param size The length of the generated string
366 366 * *
367 * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
367 * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated.
368 368 */ */
369 369 char * SDLTest_RandomAsciiStringOfSize(int size); char * SDLTest_RandomAsciiStringOfSize(int size);
370 370
371 371 /** /**
372 * Returns the invocation count for the fuzzer since last ...FuzzerInit.
372 * Get the invocation count for the fuzzer since last ...FuzzerInit.
373 *
374 * \returns the invocation count.
373 375 */ */
374 376 int SDLTest_GetFuzzerInvocationCount(void); int SDLTest_GetFuzzerInvocationCount(void);
375 377
File include/SDL2/SDL_test_harness.h changed (mode: 100644) (index 97d9812..106464c)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct SDLTest_TestSuiteReference {
105 105 * *
106 106 * \param length The length of the seed string to generate * \param length The length of the seed string to generate
107 107 * *
108 * \returns The generated seed string
108 * \returns the generated seed string
109 109 */ */
110 110 char *SDLTest_GenerateRunSeed(const int length); char *SDLTest_GenerateRunSeed(const int length);
111 111
 
... ... char *SDLTest_GenerateRunSeed(const int length);
118 118 * \param filter Filter specification. NULL disables. Case sensitive. * \param filter Filter specification. NULL disables. Case sensitive.
119 119 * \param testIterations Number of iterations to run each test case. * \param testIterations Number of iterations to run each test case.
120 120 * *
121 * \returns Test run result; 0 when all tests passed, 1 if any tests failed.
121 * \returns the test run result: 0 when all tests passed, 1 if any tests failed.
122 122 */ */
123 123 int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations); int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations);
124 124
File include/SDL2/SDL_test_images.h changed (mode: 100644) (index 1cc3ee2..a379cf1)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_log.h changed (mode: 100644) (index 6066f90..0caddca)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_md5.h changed (mode: 100644) (index b1c51d9..ca29757)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_memory.h changed (mode: 100644) (index df69f93..4a19c1d)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_test_random.h changed (mode: 100644) (index 9404e9d..8297f94)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
98 98 * *
99 99 * \param rndContext pointer to context structure * \param rndContext pointer to context structure
100 100 * *
101 * \returns A random number (32bit unsigned integer)
101 * \returns a random number (32bit unsigned integer)
102 102 * *
103 103 */ */
104 104 unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext); unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext);
File include/SDL2/SDL_thread.h changed (mode: 100644) (index 4016358..b344150)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
35 35 #include "SDL_atomic.h" #include "SDL_atomic.h"
36 36 #include "SDL_mutex.h" #include "SDL_mutex.h"
37 37
38 #if defined(__WIN32__)
39 #include <process.h> /* _beginthreadex() and _endthreadex() */
40 #endif
41 #if defined(__OS2__) /* for _beginthread() and _endthread() */
42 #ifndef __EMX__
43 #include <process.h>
44 #else
45 #include <stdlib.h>
46 #endif
47 #endif
48
38 49 #include "begin_code.h" #include "begin_code.h"
39 50 /* Set up for C function definitions, even when using C++ */ /* Set up for C function definitions, even when using C++ */
40 51 #ifdef __cplusplus #ifdef __cplusplus
 
... ... typedef enum {
69 80 } SDL_ThreadPriority; } SDL_ThreadPriority;
70 81
71 82 /** /**
72 * The function passed to SDL_CreateThread().
73 * It is passed a void* user context parameter and returns an int.
83 * The function passed to SDL_CreateThread().
84 *
85 * \param data what was passed as `data` to SDL_CreateThread()
86 * \returns a value that can be reported through SDL_WaitThread().
74 87 */ */
75 88 typedef int (SDLCALL * SDL_ThreadFunction) (void *data); typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
76 89
90
77 91 #if defined(__WIN32__) #if defined(__WIN32__)
78 92 /** /**
79 93 * \file SDL_thread.h * \file SDL_thread.h
 
... ... typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
96 110 * library! * library!
97 111 */ */
98 112 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
99 #include <process.h> /* _beginthreadex() and _endthreadex() */
100 113
101 114 typedef uintptr_t (__cdecl * pfnSDL_CurrentBeginThread) typedef uintptr_t (__cdecl * pfnSDL_CurrentBeginThread)
102 115 (void *, unsigned, unsigned (__stdcall *func)(void *), (void *, unsigned, unsigned (__stdcall *func)(void *),
 
... ... SDL_CreateThreadWithStackSize(int (SDLCALL * fn) (void *),
145 158 */ */
146 159 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
147 160
148 #ifndef __EMX__
149 #include <process.h>
150 #else
151 #include <stdlib.h>
152 #endif
153
154 161 typedef int (*pfnSDL_CurrentBeginThread)(void (*func)(void *), void *, unsigned, void * /*arg*/); typedef int (*pfnSDL_CurrentBeginThread)(void (*func)(void *), void *, unsigned, void * /*arg*/);
155 162 typedef void (*pfnSDL_CurrentEndThread)(void); typedef void (*pfnSDL_CurrentEndThread)(void);
156 163
 
... ... SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
183 190 #else #else
184 191
185 192 /** /**
186 * Create a thread with a default stack size.
193 * Create a new thread with a default stack size.
194 *
195 * This is equivalent to calling:
187 196 * *
188 * This is equivalent to calling:
189 * SDL_CreateThreadWithStackSize(fn, name, 0, data);
197 * ```c
198 * SDL_CreateThreadWithStackSize(fn, name, 0, data);
199 * ```
200 *
201 * \param fn the SDL_ThreadFunction function to call in the new thread
202 * \param name the name of the thread
203 * \param data a pointer that is passed to `fn`
204 * \returns an opaque pointer to the new thread object on success, NULL if the
205 * new thread could not be created; call SDL_GetError() for more
206 * information.
207 *
208 * \sa SDL_CreateThreadWithStackSize
209 * \sa SDL_WaitThread
190 210 */ */
191 211 extern DECLSPEC SDL_Thread *SDLCALL extern DECLSPEC SDL_Thread *SDLCALL
192 212 SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
193 213
194 214 /** /**
195 * Create a thread.
196 *
197 * Thread naming is a little complicated: Most systems have very small
198 * limits for the string length (Haiku has 32 bytes, Linux currently has 16,
199 * Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
200 * have to see what happens with your system's debugger. The name should be
201 * UTF-8 (but using the naming limits of C identifiers is a better bet).
202 * There are no requirements for thread naming conventions, so long as the
203 * string is null-terminated UTF-8, but these guidelines are helpful in
204 * choosing a name:
205 *
206 * http://stackoverflow.com/questions/149932/naming-conventions-for-threads
207 *
208 * If a system imposes requirements, SDL will try to munge the string for
209 * it (truncate, etc), but the original string contents will be available
210 * from SDL_GetThreadName().
211 *
212 * The size (in bytes) of the new stack can be specified. Zero means "use
213 * the system default" which might be wildly different between platforms
214 * (x86 Linux generally defaults to eight megabytes, an embedded device
215 * might be a few kilobytes instead).
216 *
217 * In SDL 2.1, stacksize will be folded into the original SDL_CreateThread
218 * function.
215 * Create a new thread with a specific stack size.
216 *
217 * SDL makes an attempt to report `name` to the system, so that debuggers can
218 * display it. Not all platforms support this.
219 *
220 * Thread naming is a little complicated: Most systems have very small limits
221 * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual
222 * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to
223 * see what happens with your system's debugger. The name should be UTF-8 (but
224 * using the naming limits of C identifiers is a better bet). There are no
225 * requirements for thread naming conventions, so long as the string is
226 * null-terminated UTF-8, but these guidelines are helpful in choosing a name:
227 *
228 * https://stackoverflow.com/questions/149932/naming-conventions-for-threads
229 *
230 * If a system imposes requirements, SDL will try to munge the string for it
231 * (truncate, etc), but the original string contents will be available from
232 * SDL_GetThreadName().
233 *
234 * The size (in bytes) of the new stack can be specified. Zero means "use the
235 * system default" which might be wildly different between platforms. x86
236 * Linux generally defaults to eight megabytes, an embedded device might be a
237 * few kilobytes instead. You generally need to specify a stack that is a
238 * multiple of the system's page size (in many cases, this is 4 kilobytes, but
239 * check your system documentation).
240 *
241 * In SDL 2.1, stack size will be folded into the original SDL_CreateThread
242 * function, but for backwards compatibility, this is currently a separate
243 * function.
244 *
245 * \param fn the SDL_ThreadFunction function to call in the new thread
246 * \param name the name of the thread
247 * \param stacksize the size, in bytes, to allocate for the new thread stack.
248 * \param data a pointer that is passed to `fn`
249 * \returns an opaque pointer to the new thread object on success, NULL if the
250 * new thread could not be created; call SDL_GetError() for more
251 * information.
252 *
253 * \sa SDL_WaitThread
219 254 */ */
220 255 extern DECLSPEC SDL_Thread *SDLCALL extern DECLSPEC SDL_Thread *SDLCALL
221 256 SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data); SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data);
 
... ... SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
223 258 #endif #endif
224 259
225 260 /** /**
226 * Get the thread name, as it was specified in SDL_CreateThread().
227 * This function returns a pointer to a UTF-8 string that names the
228 * specified thread, or NULL if it doesn't have a name. This is internal
229 * memory, not to be free()'d by the caller, and remains valid until the
230 * specified thread is cleaned up by SDL_WaitThread().
261 * Get the thread name as it was specified in SDL_CreateThread().
262 *
263 * This is internal memory, not to be freed by the caller, and remains valid
264 * until the specified thread is cleaned up by SDL_WaitThread().
265 *
266 * \param thread the thread to query
267 * \returns a pointer to a UTF-8 string that names the specified thread, or
268 * NULL if it doesn't have a name.
269 *
270 * \sa SDL_CreateThread
231 271 */ */
232 272 extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread); extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread);
233 273
234 274 /** /**
235 * Get the thread identifier for the current thread.
275 * Get the thread identifier for the current thread.
276 *
277 * This thread identifier is as reported by the underlying operating system.
278 * If SDL is running on a platform that does not support threads the return
279 * value will always be zero.
280 *
281 * This function also returns a valid thread ID when called from the main
282 * thread.
283 *
284 * \returns the ID of the current thread.
285 *
286 * \sa SDL_GetThreadID
236 287 */ */
237 288 extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
238 289
239 290 /** /**
240 * Get the thread identifier for the specified thread.
291 * Get the thread identifier for the specified thread.
241 292 * *
242 * Equivalent to SDL_ThreadID() if the specified thread is NULL.
293 * This thread identifier is as reported by the underlying operating system.
294 * If SDL is running on a platform that does not support threads the return
295 * value will always be zero.
296 *
297 * \param thread the thread to query
298 * \returns the ID of the specified thread, or the ID of the current thread if
299 * `thread` is NULL.
300 *
301 * \sa SDL_ThreadID
243 302 */ */
244 303 extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
245 304
246 305 /** /**
247 * Set the priority for the current thread
306 * Set the priority for the current thread.
307 *
308 * Note that some platforms will not let you alter the priority (or at least,
309 * promote the thread to a higher priority) at all, and some require you to be
310 * an administrator account. Be prepared for this to fail.
311 *
312 * \param priority the SDL_ThreadPriority to set
313 * \returns 0 on success or a negative error code on failure; call
314 * SDL_GetError() for more information.
248 315 */ */
249 316 extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
250 317
251 318 /** /**
252 * Wait for a thread to finish. Threads that haven't been detached will
253 * remain (as a "zombie") until this function cleans them up. Not doing so
254 * is a resource leak.
319 * Wait for a thread to finish.
255 320 * *
256 * Once a thread has been cleaned up through this function, the SDL_Thread
257 * that references it becomes invalid and should not be referenced again.
258 * As such, only one thread may call SDL_WaitThread() on another.
321 * Threads that haven't been detached will remain (as a "zombie") until this
322 * function cleans them up. Not doing so is a resource leak.
259 323 * *
260 * The return code for the thread function is placed in the area
261 * pointed to by \c status, if \c status is not NULL.
324 * Once a thread has been cleaned up through this function, the SDL_Thread
325 * that references it becomes invalid and should not be referenced again. As
326 * such, only one thread may call SDL_WaitThread() on another.
262 327 * *
263 * You may not wait on a thread that has been used in a call to
264 * SDL_DetachThread(). Use either that function or this one, but not
265 * both, or behavior is undefined.
328 * The return code for the thread function is placed in the area pointed to by
329 * `status`, if `status` is not NULL.
266 330 * *
267 * It is safe to pass NULL to this function; it is a no-op.
331 * You may not wait on a thread that has been used in a call to
332 * SDL_DetachThread(). Use either that function or this one, but not both, or
333 * behavior is undefined.
334 *
335 * It is safe to pass a NULL thread to this function; it is a no-op.
336 *
337 * Note that the thread pointer is freed by this function and is not valid
338 * afterward.
339 *
340 * \param thread the SDL_Thread pointer that was returned from the
341 * SDL_CreateThread() call that started this thread
342 * \param status pointer to an integer that will receive the value returned
343 * from the thread function by its 'return', or NULL to not
344 * receive such value back.
345 *
346 * \sa SDL_CreateThread
347 * \sa SDL_DetachThread
268 348 */ */
269 349 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
270 350
271 351 /** /**
272 * A thread may be "detached" to signify that it should not remain until
273 * another thread has called SDL_WaitThread() on it. Detaching a thread
274 * is useful for long-running threads that nothing needs to synchronize
275 * with or further manage. When a detached thread is done, it simply
276 * goes away.
277 *
278 * There is no way to recover the return code of a detached thread. If you
279 * need this, don't detach the thread and instead use SDL_WaitThread().
280 *
281 * Once a thread is detached, you should usually assume the SDL_Thread isn't
282 * safe to reference again, as it will become invalid immediately upon
283 * the detached thread's exit, instead of remaining until someone has called
284 * SDL_WaitThread() to finally clean it up. As such, don't detach the same
285 * thread more than once.
286 *
287 * If a thread has already exited when passed to SDL_DetachThread(), it will
288 * stop waiting for a call to SDL_WaitThread() and clean up immediately.
289 * It is not safe to detach a thread that might be used with SDL_WaitThread().
290 *
291 * You may not call SDL_WaitThread() on a thread that has been detached.
292 * Use either that function or this one, but not both, or behavior is
293 * undefined.
294 *
295 * It is safe to pass NULL to this function; it is a no-op.
352 * Let a thread clean up on exit without intervention.
353 *
354 * A thread may be "detached" to signify that it should not remain until
355 * another thread has called SDL_WaitThread() on it. Detaching a thread is
356 * useful for long-running threads that nothing needs to synchronize with or
357 * further manage. When a detached thread is done, it simply goes away.
358 *
359 * There is no way to recover the return code of a detached thread. If you
360 * need this, don't detach the thread and instead use SDL_WaitThread().
361 *
362 * Once a thread is detached, you should usually assume the SDL_Thread isn't
363 * safe to reference again, as it will become invalid immediately upon the
364 * detached thread's exit, instead of remaining until someone has called
365 * SDL_WaitThread() to finally clean it up. As such, don't detach the same
366 * thread more than once.
367 *
368 * If a thread has already exited when passed to SDL_DetachThread(), it will
369 * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is
370 * not safe to detach a thread that might be used with SDL_WaitThread().
371 *
372 * You may not call SDL_WaitThread() on a thread that has been detached. Use
373 * either that function or this one, but not both, or behavior is undefined.
374 *
375 * It is safe to pass NULL to this function; it is a no-op.
376 *
377 * \param thread the SDL_Thread pointer that was returned from the
378 * SDL_CreateThread() call that started this thread
379 *
380 * \since This function is available since SDL 2.0.2.
381 *
382 * \sa SDL_CreateThread
383 * \sa SDL_WaitThread
296 384 */ */
297 385 extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread); extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
298 386
299 387 /** /**
300 * \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
301 *
302 * \return The newly created thread local storage identifier, or 0 on error
303 *
304 * \code
305 * static SDL_SpinLock tls_lock;
306 * static SDL_TLSID thread_local_storage;
307 *
308 * void SetMyThreadData(void *value)
309 * {
310 * if (!thread_local_storage) {
311 * SDL_AtomicLock(&tls_lock);
312 * if (!thread_local_storage) {
313 * thread_local_storage = SDL_TLSCreate();
314 * }
315 * SDL_AtomicUnlock(&tls_lock);
316 * }
317 * SDL_TLSSet(thread_local_storage, value, 0);
318 * }
319 *
320 * void *GetMyThreadData(void)
321 * {
322 * return SDL_TLSGet(thread_local_storage);
323 * }
324 * \endcode
325 *
326 * \sa SDL_TLSGet()
327 * \sa SDL_TLSSet()
388 * Create a piece of thread-local storage.
389 *
390 * This creates an identifier that is globally visible to all threads but
391 * refers to data that is thread-specific.
392 *
393 * \returns the newly created thread local storage identifier or 0 on error.
394 *
395 * \since This function is available since SDL 2.0.0.
396 *
397 * \sa SDL_TLSGet
398 * \sa SDL_TLSSet
328 399 */ */
329 400 extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void);
330 401
331 402 /** /**
332 * \brief Get the value associated with a thread local storage ID for the current thread.
403 * Get the current thread's value associated with a thread local storage ID.
333 404 * *
334 * \param id The thread local storage ID
405 * \param id the thread local storage ID
406 * \returns the value associated with the ID for the current thread or NULL if
407 * no value has been set; call SDL_GetError() for more information.
335 408 * *
336 * \return The value associated with the ID for the current thread, or NULL if no value has been set.
409 * \since This function is available since SDL 2.0.0.
337 410 * *
338 * \sa SDL_TLSCreate()
339 * \sa SDL_TLSSet()
411 * \sa SDL_TLSCreate
412 * \sa SDL_TLSSet
340 413 */ */
341 414 extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
342 415
343 416 /** /**
344 * \brief Set the value associated with a thread local storage ID for the current thread.
417 * Set the current thread's value associated with a thread local storage ID.
418 *
419 * The function prototype for `destructor` is:
420 *
421 * ```c
422 * void destructor(void *value)
423 * ```
345 424 * *
346 * \param id The thread local storage ID
347 * \param value The value to associate with the ID for the current thread
348 * \param destructor A function called when the thread exits, to free the value.
425 * where its parameter `value` is what was passed as `value` to SDL_TLSSet().
349 426 * *
350 * \return 0 on success, -1 on error
427 * \param id the thread local storage ID
428 * \param value the value to associate with the ID for the current thread
429 * \param destructor a function called when the thread exits, to free the
430 * value
431 * \returns 0 on success or a negative error code on failure; call
432 * SDL_GetError() for more information.
351 433 * *
352 * \sa SDL_TLSCreate()
353 * \sa SDL_TLSGet()
434 * \since This function is available since SDL 2.0.0.
435 *
436 * \sa SDL_TLSCreate
437 * \sa SDL_TLSGet
354 438 */ */
355 439 extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*)); extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*));
356 440
441 /**
442 * Cleanup all TLS data for this thread.
443 */
444 extern DECLSPEC void SDLCALL SDL_TLSCleanup(void);
357 445
358 446 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
359 447 #ifdef __cplusplus #ifdef __cplusplus
File include/SDL2/SDL_timer.h changed (mode: 100644) (index aada717..04696dc)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
38 38 #endif #endif
39 39
40 40 /** /**
41 * \brief Get the number of milliseconds since the SDL library initialization.
41 * Get the number of milliseconds since SDL library initialization.
42 42 * *
43 * \note This value wraps if the program runs for more than ~49 days.
43 * This value wraps if the program runs for more than ~49 days.
44 *
45 * \returns an unsigned 32-bit value representing the number of milliseconds
46 * since the SDL library initialized.
47 *
48 * \sa SDL_TICKS_PASSED
44 49 */ */
45 50 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
46 51
47 52 /** /**
48 * \brief Compare SDL ticks values, and return true if A has passed B
53 * Compare SDL ticks values, and return true if `A` has passed `B`.
54 *
55 * For example, if you want to wait 100 ms, you could do this:
49 56 * *
50 * e.g. if you want to wait 100 ms, you could do this:
51 * Uint32 timeout = SDL_GetTicks() + 100;
52 * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
53 * ... do work until timeout has elapsed
54 * }
57 * ```c++
58 * Uint32 timeout = SDL_GetTicks() + 100;
59 * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
60 * // ... do work until timeout has elapsed
61 * }
62 * ```
55 63 */ */
56 64 #define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0) #define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0)
57 65
58 66 /** /**
59 * \brief Get the current value of the high resolution counter
67 * Get the current value of the high resolution counter.
68 *
69 * This function is typically used for profiling.
70 *
71 * The counter values are only meaningful relative to each other. Differences
72 * between values can be converted to times by using
73 * SDL_GetPerformanceFrequency().
74 *
75 * \returns the current counter value.
76 *
77 * \sa SDL_GetPerformanceFrequency
60 78 */ */
61 79 extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
62 80
63 81 /** /**
64 * \brief Get the count per second of the high resolution counter
82 * Get the count per second of the high resolution counter.
83 *
84 * \returns a platform-specific count per second.
85 *
86 * \since This function is available since SDL 2.0.0.
87 *
88 * \sa SDL_GetPerformanceCounter
65 89 */ */
66 90 extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
67 91
68 92 /** /**
69 * \brief Wait a specified number of milliseconds before returning.
93 * Wait a specified number of milliseconds before returning.
94 *
95 * This function waits a specified number of milliseconds before returning. It
96 * waits at least the specified time, but possibly longer due to OS
97 * scheduling.
98 *
99 * \param ms the number of milliseconds to delay
70 100 */ */
71 101 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
72 102
73 103 /** /**
74 * Function prototype for the timer callback function.
104 * Function prototype for the timer callback function.
75 105 * *
76 * The callback function is passed the current timer interval and returns
77 * the next timer interval. If the returned value is the same as the one
78 * passed in, the periodic alarm continues, otherwise a new alarm is
79 * scheduled. If the callback returns 0, the periodic alarm is cancelled.
106 * The callback function is passed the current timer interval and returns
107 * the next timer interval. If the returned value is the same as the one
108 * passed in, the periodic alarm continues, otherwise a new alarm is
109 * scheduled. If the callback returns 0, the periodic alarm is cancelled.
80 110 */ */
81 111 typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param); typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
82 112
 
... ... typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
86 116 typedef int SDL_TimerID; typedef int SDL_TimerID;
87 117
88 118 /** /**
89 * \brief Add a new timer to the pool of timers already running.
119 * Call a callback function at a future time.
120 *
121 * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init().
122 *
123 * The callback function is passed the current timer interval and the user
124 * supplied parameter from the SDL_AddTimer() call and should return the next
125 * timer interval. If the value returned from the callback is 0, the timer is
126 * canceled.
127 *
128 * The callback is run on a separate thread.
129 *
130 * Timers take into account the amount of time it took to execute the
131 * callback. For example, if the callback took 250 ms to execute and returned
132 * 1000 (ms), the timer would only wait another 750 ms before its next
133 * iteration.
134 *
135 * Timing may be inexact due to OS scheduling. Be sure to note the current
136 * time with SDL_GetTicks() or SDL_GetPerformanceCounter() in case your
137 * callback needs to adjust for variances.
138 *
139 * \param interval the timer delay, in milliseconds, passed to `callback`
140 * \param callback the SDL_TimerCallback function to call when the specified
141 * `interval` elapses
142 * \param param a pointer that is passed to `callback`
143 * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
144 * information.
90 145 * *
91 * \return A timer ID, or 0 when an error occurs.
146 * \sa SDL_RemoveTimer
92 147 */ */
93 148 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
94 149 SDL_TimerCallback callback, SDL_TimerCallback callback,
95 150 void *param); void *param);
96 151
97 152 /** /**
98 * \brief Remove a timer knowing its ID.
153 * Remove a timer created with SDL_AddTimer().
99 154 * *
100 * \return A boolean value indicating success or failure.
155 * \param id the ID of the timer to remove
156 * \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't
157 * found.
101 158 * *
102 * \warning It is not safe to remove a timer multiple times.
159 * \sa SDL_AddTimer
103 160 */ */
104 161 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);
105 162
File include/SDL2/SDL_touch.h changed (mode: 100644) (index fa5a37c..f370a67)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct SDL_Finger
64 64 #define SDL_MOUSE_TOUCHID ((Sint64)-1) #define SDL_MOUSE_TOUCHID ((Sint64)-1)
65 65
66 66
67 /* Function prototypes */
68
69 67 /** /**
70 * \brief Get the number of registered touch devices.
68 * Get the number of registered touch devices.
69 *
70 * On some platforms SDL first sees the touch device if it was actually used.
71 * Therefore SDL_GetNumTouchDevices() may return 0 although devices are
72 * available. After using all devices at least once the number will be
73 * correct.
74 *
75 * This was fixed for Android in SDL 2.0.1.
76 *
77 * \returns the number of registered touch devices.
78 *
79 * \since This function is available since SDL 2.0.0.
80 *
81 * \sa SDL_GetTouchDevice
71 82 */ */
72 83 extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void); extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void);
73 84
74 85 /** /**
75 * \brief Get the touch ID with the given index, or 0 if the index is invalid.
86 * Get the touch ID with the given index.
87 *
88 * \param index the touch device index
89 * \returns the touch ID with the given index on success or 0 if the index is
90 * invalid; call SDL_GetError() for more information.
91 *
92 * \since This function is available since SDL 2.0.0.
93 *
94 * \sa SDL_GetNumTouchDevices
76 95 */ */
77 96 extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index); extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
78 97
79 98 /** /**
80 * \brief Get the type of the given touch device.
99 * Get the type of the given touch device.
81 100 */ */
82 101 extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
83 102
84 103 /** /**
85 * \brief Get the number of active fingers for a given touch device.
104 * Get the number of active fingers for a given touch device.
105 *
106 * \param touchID the ID of a touch device
107 * \returns the number of active fingers for a given touch device on success
108 * or 0 on failure; call SDL_GetError() for more information.
109 *
110 * \since This function is available since SDL 2.0.0.
111 *
112 * \sa SDL_GetTouchFinger
86 113 */ */
87 114 extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID); extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID);
88 115
89 116 /** /**
90 * \brief Get the finger object of the given touch, with the given index.
117 * Get the finger object for specified touch device ID and finger index.
118 *
119 * The returned resource is owned by SDL and should not be deallocated.
120 *
121 * \param touchID the ID of the requested touch device
122 * \param index the index of the requested finger
123 * \returns a pointer to the SDL_Finger object or NULL if no object at the
124 * given ID and index could be found.
125 *
126 * \sa SDL_RecordGesture
91 127 */ */
92 128 extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index); extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index);
93 129
File include/SDL2/SDL_types.h changed (mode: 100644) (index b6bb571..4267f36)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/SDL_version.h changed (mode: 100644) (index 23b65f4..f4f8be2)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... extern "C" {
37 37 #endif #endif
38 38
39 39 /** /**
40 * \brief Information the version of SDL in use.
40 * Information about the version of SDL in use.
41 41 * *
42 * Represents the library's version as three levels: major revision
43 * (increments with massive changes, additions, and enhancements),
44 * minor revision (increments with backwards-compatible changes to the
45 * major revision), and patchlevel (increments with fixes to the minor
46 * revision).
42 * Represents the library's version as three levels: major revision
43 * (increments with massive changes, additions, and enhancements),
44 * minor revision (increments with backwards-compatible changes to the
45 * major revision), and patchlevel (increments with fixes to the minor
46 * revision).
47 47 * *
48 * \sa SDL_VERSION
49 * \sa SDL_GetVersion
48 * \sa SDL_VERSION
49 * \sa SDL_GetVersion
50 50 */ */
51 51 typedef struct SDL_version typedef struct SDL_version
52 52 { {
 
... ... typedef struct SDL_version
59 59 */ */
60 60 #define SDL_MAJOR_VERSION 2 #define SDL_MAJOR_VERSION 2
61 61 #define SDL_MINOR_VERSION 0 #define SDL_MINOR_VERSION 0
62 #define SDL_PATCHLEVEL 14
62 #define SDL_PATCHLEVEL 16
63 63
64 64 /** /**
65 * \brief Macro to determine SDL version program was compiled against.
65 * Macro to determine SDL version program was compiled against.
66 66 * *
67 * This macro fills in a SDL_version structure with the version of the
68 * library you compiled against. This is determined by what header the
69 * compiler uses. Note that if you dynamically linked the library, you might
70 * have a slightly newer or older version at runtime. That version can be
71 * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
72 * is not a macro.
67 * This macro fills in a SDL_version structure with the version of the
68 * library you compiled against. This is determined by what header the
69 * compiler uses. Note that if you dynamically linked the library, you might
70 * have a slightly newer or older version at runtime. That version can be
71 * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
72 * is not a macro.
73 73 * *
74 * \param x A pointer to a SDL_version struct to initialize.
74 * \param x A pointer to a SDL_version struct to initialize.
75 75 * *
76 * \sa SDL_version
77 * \sa SDL_GetVersion
76 * \sa SDL_version
77 * \sa SDL_GetVersion
78 78 */ */
79 79 #define SDL_VERSION(x) \ #define SDL_VERSION(x) \
80 80 { \ { \
 
... ... typedef struct SDL_version
107 107 (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z)) (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
108 108
109 109 /** /**
110 * \brief Get the version of SDL that is linked against your program.
110 * Get the version of SDL that is linked against your program.
111 111 * *
112 * If you are linking to SDL dynamically, then it is possible that the
113 * current version will be different than the version you compiled against.
114 * This function returns the current version, while SDL_VERSION() is a
115 * macro that tells you what version you compiled with.
112 * If you are linking to SDL dynamically, then it is possible that the current
113 * version will be different than the version you compiled against. This
114 * function returns the current version, while SDL_VERSION() is a macro that
115 * tells you what version you compiled with.
116 116 * *
117 * \code
118 * SDL_version compiled;
119 * SDL_version linked;
117 * This function may be called safely at any time, even before SDL_Init().
120 118 * *
121 * SDL_VERSION(&compiled);
122 * SDL_GetVersion(&linked);
123 * printf("We compiled against SDL version %d.%d.%d ...\n",
124 * compiled.major, compiled.minor, compiled.patch);
125 * printf("But we linked against SDL version %d.%d.%d.\n",
126 * linked.major, linked.minor, linked.patch);
127 * \endcode
119 * \param ver the SDL_version structure that contains the version information
128 120 * *
129 * This function may be called safely at any time, even before SDL_Init().
130 *
131 * \sa SDL_VERSION
121 * \sa SDL_GetRevision
132 122 */ */
133 123 extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver); extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
134 124
135 125 /** /**
136 * \brief Get the code revision of SDL that is linked against your program.
126 * Get the code revision of SDL that is linked against your program.
127 *
128 * This value is the revision of the code you are linked with and may be
129 * different from the code you are compiling with, which is found in the
130 * constant SDL_REVISION.
131 *
132 * The revision is arbitrary string (a hash value) uniquely identifying the
133 * exact revision of the SDL library in use, and is only useful in comparing
134 * against other revisions. It is NOT an incrementing number.
135 *
136 * If SDL wasn't built from a git repository with the appropriate tools, this
137 * will return an empty string.
138 *
139 * Prior to SDL 2.0.16, before development moved to GitHub, this returned a
140 * hash for a Mercurial repository.
141 *
142 * You shouldn't use this function for anything but logging it for debugging
143 * purposes. The string is not intended to be reliable in any way.
144 *
145 * \returns an arbitrary string, uniquely identifying the exact revision of
146 * the SDL library in use.
137 147 * *
138 * Returns an arbitrary string (a hash value) uniquely identifying the
139 * exact revision of the SDL library in use, and is only useful in comparing
140 * against other revisions. It is NOT an incrementing number.
148 * \sa SDL_GetVersion
141 149 */ */
142 150 extern DECLSPEC const char *SDLCALL SDL_GetRevision(void); extern DECLSPEC const char *SDLCALL SDL_GetRevision(void);
143 151
144 152 /** /**
145 * \brief Get the revision number of SDL that is linked against your program.
153 * Obsolete function, do not use.
146 154 * *
147 * Returns a number uniquely identifying the exact revision of the SDL
148 * library in use. It is an incrementing number based on commits to
149 * hg.libsdl.org.
155 * When SDL was hosted in a Mercurial repository, and was built carefully,
156 * this would return the revision number that the build was created from.
157 * This number was not reliable for several reasons, but more importantly,
158 * SDL is now hosted in a git repository, which does not offer numbers at
159 * all, only hashes. This function only ever returns zero now. Don't use it.
150 160 */ */
151 extern DECLSPEC int SDLCALL SDL_GetRevisionNumber(void);
161 extern SDL_DEPRECATED DECLSPEC int SDLCALL SDL_GetRevisionNumber(void);
152 162
153 163
154 164 /* Ends C function definitions when using C++ */ /* Ends C function definitions when using C++ */
File include/SDL2/SDL_video.h changed (mode: 100644) (index 54cbe0f..b6eb255)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
 
... ... typedef struct
65 65 * \sa SDL_CreateWindow() * \sa SDL_CreateWindow()
66 66 * \sa SDL_CreateWindowFrom() * \sa SDL_CreateWindowFrom()
67 67 * \sa SDL_DestroyWindow() * \sa SDL_DestroyWindow()
68 * \sa SDL_FlashWindow()
68 69 * \sa SDL_GetWindowData() * \sa SDL_GetWindowData()
69 70 * \sa SDL_GetWindowFlags() * \sa SDL_GetWindowFlags()
70 71 * \sa SDL_GetWindowGrab() * \sa SDL_GetWindowGrab()
72 * \sa SDL_GetWindowKeyboardGrab()
73 * \sa SDL_GetWindowMouseGrab()
71 74 * \sa SDL_GetWindowPosition() * \sa SDL_GetWindowPosition()
72 75 * \sa SDL_GetWindowSize() * \sa SDL_GetWindowSize()
73 76 * \sa SDL_GetWindowTitle() * \sa SDL_GetWindowTitle()
 
... ... typedef struct
79 82 * \sa SDL_SetWindowData() * \sa SDL_SetWindowData()
80 83 * \sa SDL_SetWindowFullscreen() * \sa SDL_SetWindowFullscreen()
81 84 * \sa SDL_SetWindowGrab() * \sa SDL_SetWindowGrab()
85 * \sa SDL_SetWindowKeyboardGrab()
86 * \sa SDL_SetWindowMouseGrab()
82 87 * \sa SDL_SetWindowIcon() * \sa SDL_SetWindowIcon()
83 88 * \sa SDL_SetWindowPosition() * \sa SDL_SetWindowPosition()
84 89 * \sa SDL_SetWindowSize() * \sa SDL_SetWindowSize()
 
... ... typedef enum
104 109 SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */ SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */
105 110 SDL_WINDOW_MINIMIZED = 0x00000040, /**< window is minimized */ SDL_WINDOW_MINIMIZED = 0x00000040, /**< window is minimized */
106 111 SDL_WINDOW_MAXIMIZED = 0x00000080, /**< window is maximized */ SDL_WINDOW_MAXIMIZED = 0x00000080, /**< window is maximized */
107 SDL_WINDOW_INPUT_GRABBED = 0x00000100, /**< window has grabbed input focus */
112 SDL_WINDOW_MOUSE_GRABBED = 0x00000100, /**< window has grabbed mouse input */
108 113 SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */ SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */
109 114 SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */ SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */
110 115 SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ), SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ),
 
... ... typedef enum
112 117 SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000, /**< window should be created in high-DPI mode if supported. SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000, /**< window should be created in high-DPI mode if supported.
113 118 On macOS NSHighResolutionCapable must be set true in the On macOS NSHighResolutionCapable must be set true in the
114 119 application's Info.plist for this to have any effect. */ application's Info.plist for this to have any effect. */
115 SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to INPUT_GRABBED) */
116 SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
117 SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */
118 SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window */
119 SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip */
120 SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu */
121 SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */
122 SDL_WINDOW_METAL = 0x20000000 /**< window usable for Metal view */
120 SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
121 SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
122 SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */
123 SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window */
124 SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip */
125 SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu */
126 SDL_WINDOW_KEYBOARD_GRABBED = 0x00100000, /**< window has grabbed keyboard input */
127 SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */
128 SDL_WINDOW_METAL = 0x20000000, /**< window usable for Metal view */
129
130 SDL_WINDOW_INPUT_GRABBED = SDL_WINDOW_MOUSE_GRABBED /**< equivalent to SDL_WINDOW_MOUSE_GRABBED for compatibility */
123 131 } SDL_WindowFlags; } SDL_WindowFlags;
124 132
125 133 /** /**
 
... ... typedef enum
180 188 SDL_DISPLAYEVENT_DISCONNECTED /**< Display has been removed from the system */ SDL_DISPLAYEVENT_DISCONNECTED /**< Display has been removed from the system */
181 189 } SDL_DisplayEventID; } SDL_DisplayEventID;
182 190
191 /**
192 * \brief Display orientation
193 */
183 194 typedef enum typedef enum
184 195 { {
185 196 SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */
 
... ... typedef enum
189 200 SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */ SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */
190 201 } SDL_DisplayOrientation; } SDL_DisplayOrientation;
191 202
203 /**
204 * \brief Window flash operation
205 */
206 typedef enum
207 {
208 SDL_FLASH_CANCEL, /**< Cancel any window flash state */
209 SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */
210 SDL_FLASH_UNTIL_FOCUSED, /**< Flash the window until it gets focus */
211 } SDL_FlashOperation;
212
192 213 /** /**
193 214 * \brief An opaque handle to an OpenGL context. * \brief An opaque handle to an OpenGL context.
194 215 */ */
 
... ... typedef enum
258 279 /* Function prototypes */ /* Function prototypes */
259 280
260 281 /** /**
261 * \brief Get the number of video drivers compiled into SDL
282 * Get the number of video drivers compiled into SDL.
262 283 * *
263 * \sa SDL_GetVideoDriver()
284 * \returns a number >= 1 on success or a negative error code on failure; call
285 * SDL_GetError() for more information.
286 *
287 * \sa SDL_GetVideoDriver
264 288 */ */
265 289 extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
266 290
267 291 /** /**
268 * \brief Get the name of a built in video driver.
292 * Get the name of a built in video driver.
293 *
294 * The video drivers are presented in the order in which they are normally
295 * checked during initialization.
269 296 * *
270 * \note The video drivers are presented in the order in which they are
271 * normally checked during initialization.
297 * \param index the index of a video driver
298 * \returns the name of the video driver with the given **index**.
272 299 * *
273 * \sa SDL_GetNumVideoDrivers()
300 * \sa SDL_GetNumVideoDrivers
274 301 */ */
275 302 extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
276 303
277 304 /** /**
278 * \brief Initialize the video subsystem, optionally specifying a video driver.
305 * Initialize the video subsystem, optionally specifying a video driver.
306 *
307 * This function initializes the video subsystem, setting up a connection to
308 * the window manager, etc, and determines the available display modes and
309 * pixel formats, but does not initialize a window or graphics mode.
279 310 * *
280 * \param driver_name Initialize a specific driver by name, or NULL for the
281 * default video driver.
311 * If you use this function and you haven't used the SDL_INIT_VIDEO flag with
312 * either SDL_Init() or SDL_InitSubSystem(), you should call SDL_VideoQuit()
313 * before calling SDL_Quit().
282 314 * *
283 * \return 0 on success, -1 on error
315 * It is safe to call this function multiple times. SDL_VideoInit() will call
316 * SDL_VideoQuit() itself if the video subsystem has already been initialized.
284 317 * *
285 * This function initializes the video subsystem; setting up a connection
286 * to the window manager, etc, and determines the available display modes
287 * and pixel formats, but does not initialize a window or graphics mode.
318 * You can use SDL_GetNumVideoDrivers() and SDL_GetVideoDriver() to find a
319 * specific `driver_name`.
288 320 * *
289 * \sa SDL_VideoQuit()
321 * \param driver_name the name of a video driver to initialize, or NULL for
322 * the default driver
323 * \returns 0 on success or a negative error code on failure; call
324 * SDL_GetError() for more information.
325 *
326 * \sa SDL_GetNumVideoDrivers
327 * \sa SDL_GetVideoDriver
328 * \sa SDL_InitSubSystem
329 * \sa SDL_VideoQuit
290 330 */ */
291 331 extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name); extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
292 332
293 333 /** /**
294 * \brief Shuts down the video subsystem.
334 * Shut down the video subsystem, if initialized with SDL_VideoInit().
295 335 * *
296 * This function closes all windows, and restores the original video mode.
336 * This function closes all windows, and restores the original video mode.
297 337 * *
298 * \sa SDL_VideoInit()
338 * \sa SDL_VideoInit
299 339 */ */
300 340 extern DECLSPEC void SDLCALL SDL_VideoQuit(void); extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
301 341
302 342 /** /**
303 * \brief Returns the name of the currently initialized video driver.
343 * Get the name of the currently initialized video driver.
344 *
345 * \returns the name of the current video driver or NULL if no driver has been
346 * initialized.
304 347 * *
305 * \return The name of the current video driver or NULL if no driver
306 * has been initialized
348 * \since This function is available since SDL 2.0.0.
307 349 * *
308 * \sa SDL_GetNumVideoDrivers()
309 * \sa SDL_GetVideoDriver()
350 * \sa SDL_GetNumVideoDrivers
351 * \sa SDL_GetVideoDriver
310 352 */ */
311 353 extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void); extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
312 354
313 355 /** /**
314 * \brief Returns the number of available video displays.
356 * Get the number of available video displays.
357 *
358 * \returns a number >= 1 or a negative error code on failure; call
359 * SDL_GetError() for more information.
315 360 * *
316 * \sa SDL_GetDisplayBounds()
361 * \since This function is available since SDL 2.0.0.
362 *
363 * \sa SDL_GetDisplayBounds
317 364 */ */
318 365 extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
319 366
320 367 /** /**
321 * \brief Get the name of a display in UTF-8 encoding
368 * Get the name of a display in UTF-8 encoding.
369 *
370 * \param displayIndex the index of display from which the name should be
371 * queried
372 * \returns the name of a display or NULL for an invalid display index or
373 * failure; call SDL_GetError() for more information.
322 374 * *
323 * \return The name of a display, or NULL for an invalid display index.
375 * \since This function is available since SDL 2.0.0.
324 376 * *
325 * \sa SDL_GetNumVideoDisplays()
377 * \sa SDL_GetNumVideoDisplays
326 378 */ */
327 379 extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
328 380
329 381 /** /**
330 * \brief Get the desktop area represented by a display, with the primary
331 * display located at 0,0
382 * Get the desktop area represented by a display.
332 383 * *
333 * \return 0 on success, or -1 if the index is out of range.
384 * The primary display (`displayIndex` zero) is always located at 0,0.
334 385 * *
335 * \sa SDL_GetNumVideoDisplays()
386 * \param displayIndex the index of the display to query
387 * \param rect the SDL_Rect structure filled in with the display bounds
388 * \returns 0 on success or a negative error code on failure; call
389 * SDL_GetError() for more information.
390 *
391 * \sa SDL_GetNumVideoDisplays
336 392 */ */
337 393 extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect); extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
338 394
339 395 /** /**
340 * \brief Get the usable desktop area represented by a display, with the
341 * primary display located at 0,0
396 * Get the usable desktop area represented by a display.
397 *
398 * The primary display (`displayIndex` zero) is always located at 0,0.
399 *
400 * This is the same area as SDL_GetDisplayBounds() reports, but with portions
401 * reserved by the system removed. For example, on Apple's macOS, this
402 * subtracts the area occupied by the menu bar and dock.
403 *
404 * Setting a window to be fullscreen generally bypasses these unusable areas,
405 * so these are good guidelines for the maximum space available to a
406 * non-fullscreen window.
407 *
408 * The parameter `rect` is ignored if it is NULL.
342 409 * *
343 * This is the same area as SDL_GetDisplayBounds() reports, but with portions
344 * reserved by the system removed. For example, on Mac OS X, this subtracts
345 * the area occupied by the menu bar and dock.
410 * This function also returns -1 if the parameter `displayIndex` is out of
411 * range.
346 412 * *
347 * Setting a window to be fullscreen generally bypasses these unusable areas,
348 * so these are good guidelines for the maximum space available to a
349 * non-fullscreen window.
413 * \param displayIndex the index of the display to query the usable bounds
414 * from
415 * \param rect the SDL_Rect structure filled in with the display bounds
416 * \returns 0 on success or a negative error code on failure; call
417 * SDL_GetError() for more information.
350 418 * *
351 * \return 0 on success, or -1 if the index is out of range.
419 * \since This function is available since SDL 2.0.5.
352 420 * *
353 * \sa SDL_GetDisplayBounds()
354 * \sa SDL_GetNumVideoDisplays()
421 * \sa SDL_GetDisplayBounds
422 * \sa SDL_GetNumVideoDisplays
355 423 */ */
356 424 extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect); extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect);
357 425
358 426 /** /**
359 * \brief Get the dots/pixels-per-inch for a display
427 * Get the dots/pixels-per-inch for a display.
360 428 * *
361 * \note Diagonal, horizontal and vertical DPI can all be optionally
362 * returned if the parameter is non-NULL.
429 * Diagonal, horizontal and vertical DPI can all be optionally returned if the
430 * appropriate parameter is non-NULL.
363 431 * *
364 * \return 0 on success, or -1 if no DPI information is available or the index is out of range.
432 * A failure of this function usually means that either no DPI information is
433 * available or the `displayIndex` is out of range.
365 434 * *
366 * \sa SDL_GetNumVideoDisplays()
435 * \param displayIndex the index of the display from which DPI information
436 * should be queried
437 * \param ddpi a pointer filled in with the diagonal DPI of the display; may
438 * be NULL
439 * \param hdpi a pointer filled in with the horizontal DPI of the display; may
440 * be NULL
441 * \param vdpi a pointer filled in with the vertical DPI of the display; may
442 * be NULL
443 * \returns 0 on success or a negative error code on failure; call
444 * SDL_GetError() for more information.
445 *
446 * \since This function is available since SDL 2.0.4.
447 *
448 * \sa SDL_GetNumVideoDisplays
367 449 */ */
368 450 extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi); extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi);
369 451
370 452 /** /**
371 * \brief Get the orientation of a display
453 * Get the orientation of a display.
372 454 * *
373 * \return The orientation of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available.
455 * \param displayIndex the index of the display to query
456 * \returns The SDL_DisplayOrientation enum value of the display, or
457 * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
374 458 * *
375 * \sa SDL_GetNumVideoDisplays()
459 * \sa SDL_GetNumVideoDisplays
376 460 */ */
377 461 extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex); extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
378 462
379 463 /** /**
380 * \brief Returns the number of available display modes.
464 * Get the number of available display modes.
381 465 * *
382 * \sa SDL_GetDisplayMode()
466 * The `displayIndex` needs to be in the range from 0 to
467 * SDL_GetNumVideoDisplays() - 1.
468 *
469 * \param displayIndex the index of the display to query
470 * \returns a number >= 1 on success or a negative error code on failure; call
471 * SDL_GetError() for more information.
472 *
473 * \since This function is available since SDL 2.0.0.
474 *
475 * \sa SDL_GetDisplayMode
476 * \sa SDL_GetNumVideoDisplays
383 477 */ */
384 478 extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
385 479
386 480 /** /**
387 * \brief Fill in information about a specific display mode.
481 * Get information about a specific display mode.
388 482 * *
389 * \note The display modes are sorted in this priority:
390 * \li bits per pixel -> more colors to fewer colors
391 * \li width -> largest to smallest
392 * \li height -> largest to smallest
393 * \li refresh rate -> highest to lowest
483 * The display modes are sorted in this priority:
394 484 * *
395 * \sa SDL_GetNumDisplayModes()
485 * - width -> largest to smallest
486 * - height -> largest to smallest
487 * - bits per pixel -> more colors to fewer colors
488 * - packed pixel layout -> largest to smallest
489 * - refresh rate -> highest to lowest
490 *
491 * \param displayIndex the index of the display to query
492 * \param modeIndex the index of the display mode to query
493 * \param mode an SDL_DisplayMode structure filled in with the mode at
494 * `modeIndex`
495 * \returns 0 on success or a negative error code on failure; call
496 * SDL_GetError() for more information.
497 *
498 * \sa SDL_GetNumDisplayModes
396 499 */ */
397 500 extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
398 501 SDL_DisplayMode * mode); SDL_DisplayMode * mode);
399 502
400 503 /** /**
401 * \brief Fill in information about the desktop display mode.
504 * Get information about the desktop's display mode.
505 *
506 * There's a difference between this function and SDL_GetCurrentDisplayMode()
507 * when SDL runs fullscreen and has changed the resolution. In that case this
508 * function will return the previous native display mode, and not the current
509 * display mode.
510 *
511 * \param displayIndex the index of the display to query
512 * \param mode an SDL_DisplayMode structure filled in with the current display
513 * mode
514 * \returns 0 on success or a negative error code on failure; call
515 * SDL_GetError() for more information.
516 *
517 * \sa SDL_GetCurrentDisplayMode
518 * \sa SDL_GetDisplayMode
519 * \sa SDL_SetWindowDisplayMode
402 520 */ */
403 521 extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode); extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode);
404 522
405 523 /** /**
406 * \brief Fill in information about the current display mode.
524 * Get information about the current display mode.
525 *
526 * There's a difference between this function and SDL_GetDesktopDisplayMode()
527 * when SDL runs fullscreen and has changed the resolution. In that case this
528 * function will return the current display mode, and not the previous native
529 * display mode.
530 *
531 * \param displayIndex the index of the display to query
532 * \param mode an SDL_DisplayMode structure filled in with the current display
533 * mode
534 * \returns 0 on success or a negative error code on failure; call
535 * SDL_GetError() for more information.
536 *
537 * \sa SDL_GetDesktopDisplayMode
538 * \sa SDL_GetDisplayMode
539 * \sa SDL_GetNumVideoDisplays
540 * \sa SDL_SetWindowDisplayMode
407 541 */ */
408 542 extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode); extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode);
409 543
410 544
411 545 /** /**
412 * \brief Get the closest match to the requested display mode.
413 *
414 * \param displayIndex The index of display from which mode should be queried.
415 * \param mode The desired display mode
416 * \param closest A pointer to a display mode to be filled in with the closest
417 * match of the available display modes.
546 * Get the closest match to the requested display mode.
418 547 * *
419 * \return The passed in value \c closest, or NULL if no matching video mode
420 * was available.
548 * The available display modes are scanned and `closest` is filled in with the
549 * closest mode matching the requested mode and returned. The mode format and
550 * refresh rate default to the desktop mode if they are set to 0. The modes
551 * are scanned with size being first priority, format being second priority,
552 * and finally checking the refresh rate. If all the available modes are too
553 * small, then NULL is returned.
421 554 * *
422 * The available display modes are scanned, and \c closest is filled in with the
423 * closest mode matching the requested mode and returned. The mode format and
424 * refresh_rate default to the desktop mode if they are 0. The modes are
425 * scanned with size being first priority, format being second priority, and
426 * finally checking the refresh_rate. If all the available modes are too
427 * small, then NULL is returned.
555 * \param displayIndex the index of the display to query
556 * \param mode an SDL_DisplayMode structure containing the desired display
557 * mode
558 * \param closest an SDL_DisplayMode structure filled in with the closest
559 * match of the available display modes
560 * \returns the passed in value `closest` or NULL if no matching video mode
561 * was available; call SDL_GetError() for more information.
428 562 * *
429 * \sa SDL_GetNumDisplayModes()
430 * \sa SDL_GetDisplayMode()
563 * \sa SDL_GetDisplayMode
564 * \sa SDL_GetNumDisplayModes
431 565 */ */
432 566 extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest); extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
433 567
434 568 /** /**
435 * \brief Get the display index associated with a window.
569 * Get the index of the display associated with a window.
570 *
571 * \param window the window to query
572 * \returns the index of the display containing the center of the window on
573 * success or a negative error code on failure; call SDL_GetError()
574 * for more information.
436 575 * *
437 * \return the display index of the display containing the center of the
438 * window, or -1 on error.
576 * \sa SDL_GetDisplayBounds
577 * \sa SDL_GetNumVideoDisplays
439 578 */ */
440 579 extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
441 580
442 581 /** /**
443 * \brief Set the display mode used when a fullscreen window is visible.
582 * Set the display mode to use when a window is visible at fullscreen.
444 583 * *
445 * By default the window's dimensions and the desktop format and refresh rate
446 * are used.
584 * This only affects the display mode used when the window is fullscreen. To
585 * change the window size when the window is not fullscreen, use
586 * SDL_SetWindowSize().
447 587 * *
448 * \param window The window for which the display mode should be set.
449 * \param mode The mode to use, or NULL for the default mode.
588 * \param window the window to affect
589 * \param mode the SDL_DisplayMode structure representing the mode to use, or
590 * NULL to use the window's dimensions and the desktop's format
591 * and refresh rate
592 * \returns 0 on success or a negative error code on failure; call
593 * SDL_GetError() for more information.
450 594 * *
451 * \return 0 on success, or -1 if setting the display mode failed.
452 *
453 * \sa SDL_GetWindowDisplayMode()
454 * \sa SDL_SetWindowFullscreen()
595 * \sa SDL_GetWindowDisplayMode
596 * \sa SDL_SetWindowFullscreen
455 597 */ */
456 598 extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
457 const SDL_DisplayMode
458 * mode);
599 const SDL_DisplayMode * mode);
459 600
460 601 /** /**
461 * \brief Fill in information about the display mode used when a fullscreen
462 * window is visible.
602 * Query the display mode to use when a window is visible at fullscreen.
463 603 * *
464 * \sa SDL_SetWindowDisplayMode()
465 * \sa SDL_SetWindowFullscreen()
604 * \param window the window to query
605 * \param mode an SDL_DisplayMode structure filled in with the fullscreen
606 * display mode
607 * \returns 0 on success or a negative error code on failure; call
608 * SDL_GetError() for more information.
609 *
610 * \sa SDL_SetWindowDisplayMode
611 * \sa SDL_SetWindowFullscreen
466 612 */ */
467 613 extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
468 614 SDL_DisplayMode * mode); SDL_DisplayMode * mode);
469 615
470 616 /** /**
471 * \brief Get the pixel format associated with the window.
617 * Get the pixel format associated with the window.
618 *
619 * \param window the window to query
620 * \returns the pixel format of the window on success or
621 * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
622 * information.
472 623 */ */
473 624 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window); extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
474 625
475 626 /** /**
476 * \brief Create a window with the specified position, dimensions, and flags.
477 *
478 * \param title The title of the window, in UTF-8 encoding.
479 * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
480 * ::SDL_WINDOWPOS_UNDEFINED.
481 * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
482 * ::SDL_WINDOWPOS_UNDEFINED.
483 * \param w The width of the window, in screen coordinates.
484 * \param h The height of the window, in screen coordinates.
485 * \param flags The flags for the window, a mask of any of the following:
486 * ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
487 * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS,
488 * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
489 * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_INPUT_GRABBED,
490 * ::SDL_WINDOW_ALLOW_HIGHDPI, ::SDL_WINDOW_VULKAN
491 * ::SDL_WINDOW_METAL.
492 *
493 * \return The created window, or NULL if window creation failed.
494 *
495 * If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size
496 * in pixels may differ from its size in screen coordinates on platforms with
497 * high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize() to query
498 * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize(),
499 * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to query the
500 * drawable size in pixels.
501 *
502 * If the window is created with any of the SDL_WINDOW_OPENGL or
503 * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
504 * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
505 * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
506 *
507 * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
508 * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
509 *
510 * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
511 * SDL_CreateWindow() will fail.
512 *
513 * \note On non-Apple devices, SDL requires you to either not link to the
514 * Vulkan loader or link to a dynamic library version. This limitation
515 * may be removed in a future version of SDL.
516 *
517 * \sa SDL_DestroyWindow()
518 * \sa SDL_GL_LoadLibrary()
519 * \sa SDL_Vulkan_LoadLibrary()
627 * Create a window with the specified position, dimensions, and flags.
628 *
629 * `flags` may be any of the following OR'd together:
630 *
631 * - `SDL_WINDOW_FULLSCREEN`: fullscreen window
632 * - `SDL_WINDOW_FULLSCREEN_DESKTOP`: fullscreen window at desktop resolution
633 * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
634 * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
635 * - `SDL_WINDOW_METAL`: window usable with a Metal instance
636 * - `SDL_WINDOW_HIDDEN`: window is not visible
637 * - `SDL_WINDOW_BORDERLESS`: no window decoration
638 * - `SDL_WINDOW_RESIZABLE`: window can be resized
639 * - `SDL_WINDOW_MINIMIZED`: window is minimized
640 * - `SDL_WINDOW_MAXIMIZED`: window is maximized
641 * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus
642 * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if
643 * supported (>= SDL 2.0.1)
644 *
645 * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is
646 * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be
647 * queried later using SDL_GetWindowFlags().
648 *
649 * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
650 * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
651 *
652 * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
653 * in pixels may differ from its size in screen coordinates on platforms with
654 * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
655 * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or
656 * SDL_GetRendererOutputSize() to query the drawable size in pixels.
657 *
658 * If the window is set fullscreen, the width and height parameters `w` and
659 * `h` will not be used. However, invalid size parameters (e.g. too large) may
660 * still fail. Window size is actually limited to 16384 x 16384 for all
661 * platforms at window creation.
662 *
663 * If the window is created with any of the SDL_WINDOW_OPENGL or
664 * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
665 * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
666 * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
667 *
668 * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
669 * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
670 *
671 * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
672 * SDL_CreateWindow() will fail.
673 *
674 * On non-Apple devices, SDL requires you to either not link to the Vulkan
675 * loader or link to a dynamic library version. This limitation may be removed
676 * in a future version of SDL.
677 *
678 * \param title the title of the window, in UTF-8 encoding
679 * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or
680 * `SDL_WINDOWPOS_UNDEFINED`
681 * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or
682 * `SDL_WINDOWPOS_UNDEFINED`
683 * \param w the width of the window, in screen coordinates
684 * \param h the height of the window, in screen coordinates
685 * \param flags 0, or one or more SDL_WindowFlags OR'd together
686 * \returns the window that was created or NULL on failure; call
687 * SDL_GetError() for more information.
688 *
689 * \since This function is available since SDL 2.0.0.
690 *
691 * \sa SDL_CreateWindowFrom
692 * \sa SDL_DestroyWindow
520 693 */ */
521 694 extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
522 695 int x, int y, int w, int x, int y, int w,
523 696 int h, Uint32 flags); int h, Uint32 flags);
524 697
525 698 /** /**
526 * \brief Create an SDL window from an existing native window.
699 * Create an SDL window from an existing native window.
527 700 * *
528 * \param data A pointer to driver-dependent window creation data
701 * In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows)
702 * the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured
703 * before using SDL_CreateWindowFrom().
529 704 * *
530 * \return The created window, or NULL if window creation failed.
705 * \param data a pointer to driver-dependent window creation data, typically
706 * your native window cast to a void*
707 * \returns the window that was created or NULL on failure; call
708 * SDL_GetError() for more information.
531 709 * *
532 * \sa SDL_DestroyWindow()
710 * \sa SDL_CreateWindow
711 * \sa SDL_DestroyWindow
533 712 */ */
534 713 extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
535 714
536 715 /** /**
537 * \brief Get the numeric ID of a window, for logging purposes.
716 * Get the numeric ID of a window.
717 *
718 * The numeric ID is what SDL_WindowEvent references, and is necessary to map
719 * these events to specific SDL_Window objects.
720 *
721 * \param window the window to query
722 * \returns the ID of the window on success or 0 on failure; call
723 * SDL_GetError() for more information.
724 *
725 * \since This function is available since SDL 2.0.0.
726 *
727 * \sa SDL_GetWindowFromID
538 728 */ */
539 729 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window); extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
540 730
541 731 /** /**
542 * \brief Get a window from a stored ID, or NULL if it doesn't exist.
732 * Get a window from a stored ID.
733 *
734 * The numeric ID is what SDL_WindowEvent references, and is necessary to map
735 * these events to specific SDL_Window objects.
736 *
737 * \param id the ID of the window
738 * \returns the window associated with `id` or NULL if it doesn't exist; call
739 * SDL_GetError() for more information.
740 *
741 * \sa SDL_GetWindowID
543 742 */ */
544 743 extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
545 744
546 745 /** /**
547 * \brief Get the window flags.
746 * Get the window flags.
747 *
748 * \param window the window to query
749 * \returns a mask of the SDL_WindowFlags associated with `window`
750 *
751 * \sa SDL_CreateWindow
752 * \sa SDL_HideWindow
753 * \sa SDL_MaximizeWindow
754 * \sa SDL_MinimizeWindow
755 * \sa SDL_SetWindowFullscreen
756 * \sa SDL_SetWindowGrab
757 * \sa SDL_ShowWindow
548 758 */ */
549 759 extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
550 760
551 761 /** /**
552 * \brief Set the title of a window, in UTF-8 format.
762 * Set the title of a window.
553 763 * *
554 * \sa SDL_GetWindowTitle()
764 * This string is expected to be in UTF-8 encoding.
765 *
766 * \param window the window to change
767 * \param title the desired window title in UTF-8 format
768 *
769 * \sa SDL_GetWindowTitle
555 770 */ */
556 771 extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
557 772 const char *title); const char *title);
558 773
559 774 /** /**
560 * \brief Get the title of a window, in UTF-8 format.
775 * Get the title of a window.
561 776 * *
562 * \sa SDL_SetWindowTitle()
777 * \param window the window to query
778 * \returns the title of the window in UTF-8 format or "" if there is no
779 * title.
780 *
781 * \sa SDL_SetWindowTitle
563 782 */ */
564 783 extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window); extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
565 784
566 785 /** /**
567 * \brief Set the icon for a window.
786 * Set the icon for a window.
568 787 * *
569 * \param window The window for which the icon should be set.
570 * \param icon The icon for the window.
788 * \param window the window to change
789 * \param icon an SDL_Surface structure containing the icon for the window
571 790 */ */
572 791 extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
573 792 SDL_Surface * icon); SDL_Surface * icon);
574 793
575 794 /** /**
576 * \brief Associate an arbitrary named pointer with a window.
577 *
578 * \param window The window to associate with the pointer.
579 * \param name The name of the pointer.
580 * \param userdata The associated pointer.
795 * Associate an arbitrary named pointer with a window.
581 796 * *
582 * \return The previous value associated with 'name'
797 * `name` is case-sensitive.
583 798 * *
584 * \note The name is case-sensitive.
799 * \param window the window to associate with the pointer
800 * \param name the name of the pointer
801 * \param userdata the associated pointer
802 * \returns the previous value associated with `name`.
585 803 * *
586 * \sa SDL_GetWindowData()
804 * \sa SDL_GetWindowData
587 805 */ */
588 806 extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window, extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
589 807 const char *name, const char *name,
590 808 void *userdata); void *userdata);
591 809
592 810 /** /**
593 * \brief Retrieve the data pointer associated with a window.
811 * Retrieve the data pointer associated with a window.
594 812 * *
595 * \param window The window to query.
596 * \param name The name of the pointer.
813 * \param window the window to query
814 * \param name the name of the pointer
815 * \returns the value associated with `name`.
597 816 * *
598 * \return The value associated with 'name'
599 *
600 * \sa SDL_SetWindowData()
817 * \sa SDL_SetWindowData
601 818 */ */
602 819 extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
603 820 const char *name); const char *name);
604 821
605 822 /** /**
606 * \brief Set the position of a window.
823 * Set the position of a window.
607 824 * *
608 * \param window The window to reposition.
609 * \param x The x coordinate of the window in screen coordinates, or
610 * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
611 * \param y The y coordinate of the window in screen coordinates, or
612 * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
825 * The window coordinate origin is the upper left of the display.
613 826 * *
614 * \note The window coordinate origin is the upper left of the display.
827 * \param window the window to reposition
828 * \param x the x coordinate of the window in screen coordinates, or
829 * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
830 * \param y the y coordinate of the window in screen coordinates, or
831 * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
615 832 * *
616 * \sa SDL_GetWindowPosition()
833 * \sa SDL_GetWindowPosition
617 834 */ */
618 835 extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
619 836 int x, int y); int x, int y);
620 837
621 838 /** /**
622 * \brief Get the position of a window.
839 * Get the position of a window.
623 840 * *
624 * \param window The window to query.
625 * \param x Pointer to variable for storing the x position, in screen
626 * coordinates. May be NULL.
627 * \param y Pointer to variable for storing the y position, in screen
628 * coordinates. May be NULL.
841 * If you do not need the value for one of the positions a NULL may be passed
842 * in the `x` or `y` parameter.
629 843 * *
630 * \sa SDL_SetWindowPosition()
844 * \param window the window to query
845 * \param x a pointer filled in with the x position of the window, in screen
846 * coordinates, may be NULL
847 * \param y a pointer filled in with the y position of the window, in screen
848 * coordinates, may be NULL
849 *
850 * \sa SDL_SetWindowPosition
631 851 */ */
632 852 extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
633 853 int *x, int *y); int *x, int *y);
634 854
635 855 /** /**
636 * \brief Set the size of a window's client area.
856 * Set the size of a window's client area.
637 857 * *
638 * \param window The window to resize.
639 * \param w The width of the window, in screen coordinates. Must be >0.
640 * \param h The height of the window, in screen coordinates. Must be >0.
858 * The window size in screen coordinates may differ from the size in pixels,
859 * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
860 * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or
861 * SDL_GetRendererOutputSize() to get the real client area size in pixels.
641 862 * *
642 * \note Fullscreen windows automatically match the size of the display mode,
643 * and you should use SDL_SetWindowDisplayMode() to change their size.
863 * Fullscreen windows automatically match the size of the display mode, and
864 * you should use SDL_SetWindowDisplayMode() to change their size.
644 865 * *
645 * The window size in screen coordinates may differ from the size in pixels, if
646 * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
647 * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
648 * SDL_GetRendererOutputSize() to get the real client area size in pixels.
866 * \param window the window to change
867 * \param w the width of the window in pixels, in screen coordinates, must be
868 * > 0
869 * \param h the height of the window in pixels, in screen coordinates, must be
870 * > 0
649 871 * *
650 * \sa SDL_GetWindowSize()
651 * \sa SDL_SetWindowDisplayMode()
872 * \sa SDL_GetWindowSize
873 * \sa SDL_SetWindowDisplayMode
652 874 */ */
653 875 extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
654 876 int h); int h);
655 877
656 878 /** /**
657 * \brief Get the size of a window's client area.
879 * Get the size of a window's client area.
658 880 * *
659 * \param window The window to query.
660 * \param w Pointer to variable for storing the width, in screen
661 * coordinates. May be NULL.
662 * \param h Pointer to variable for storing the height, in screen
663 * coordinates. May be NULL.
881 * NULL can safely be passed as the `w` or `h` parameter if the width or
882 * height value is not desired.
664 883 * *
665 * The window size in screen coordinates may differ from the size in pixels, if
666 * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
667 * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
668 * SDL_GetRendererOutputSize() to get the real client area size in pixels.
884 * The window size in screen coordinates may differ from the size in pixels,
885 * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
886 * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(),
887 * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the
888 * real client area size in pixels.
669 889 * *
670 * \sa SDL_SetWindowSize()
890 * \param window the window to query the width and height from
891 * \param w a pointer filled in with the width of the window, in screen
892 * coordinates, may be NULL
893 * \param h a pointer filled in with the height of the window, in screen
894 * coordinates, may be NULL
895 *
896 * \sa SDL_GL_GetDrawableSize
897 * \sa SDL_Vulkan_GetDrawableSize
898 * \sa SDL_SetWindowSize
671 899 */ */
672 900 extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
673 901 int *h); int *h);
674 902
675 903 /** /**
676 * \brief Get the size of a window's borders (decorations) around the client area.
904 * Get the size of a window's borders (decorations) around the client area.
905 *
906 * Note: If this function fails (returns -1), the size values will be
907 * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
908 * window in question was borderless.
677 909 * *
678 * \param window The window to query.
679 * \param top Pointer to variable for storing the size of the top border. NULL is permitted.
680 * \param left Pointer to variable for storing the size of the left border. NULL is permitted.
681 * \param bottom Pointer to variable for storing the size of the bottom border. NULL is permitted.
682 * \param right Pointer to variable for storing the size of the right border. NULL is permitted.
910 * Note: This function may fail on systems where the window has not yet been
911 * decorated by the display server (for example, immediately after calling
912 * SDL_CreateWindow). It is recommended that you wait at least until the
913 * window has been presented and composited, so that the window system has a
914 * chance to decorate the window and provide the border dimensions to SDL.
683 915 * *
684 * \return 0 on success, or -1 if getting this information is not supported.
916 * This function also returns -1 if getting the information is not supported.
685 917 * *
686 * \note if this function fails (returns -1), the size values will be
687 * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as
688 * if the window in question was borderless.
918 * \param window the window to query the size values of the border
919 * (decorations) from
920 * \param top pointer to variable for storing the size of the top border; NULL
921 * is permitted
922 * \param left pointer to variable for storing the size of the left border;
923 * NULL is permitted
924 * \param bottom pointer to variable for storing the size of the bottom
925 * border; NULL is permitted
926 * \param right pointer to variable for storing the size of the right border;
927 * NULL is permitted
928 * \returns 0 on success or a negative error code on failure; call
929 * SDL_GetError() for more information.
930 *
931 * \since This function is available since SDL 2.0.5.
932 *
933 * \sa SDL_GetWindowSize
689 934 */ */
690 935 extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window,
691 936 int *top, int *left, int *top, int *left,
692 937 int *bottom, int *right); int *bottom, int *right);
693 938
694 939 /** /**
695 * \brief Set the minimum size of a window's client area.
696 *
697 * \param window The window to set a new minimum size.
698 * \param min_w The minimum width of the window, must be >0
699 * \param min_h The minimum height of the window, must be >0
940 * Set the minimum size of a window's client area.
700 941 * *
701 * \note You can't change the minimum size of a fullscreen window, it
702 * automatically matches the size of the display mode.
942 * \param window the window to change
943 * \param min_w the minimum width of the window in pixels
944 * \param min_h the minimum height of the window in pixels
703 945 * *
704 * \sa SDL_GetWindowMinimumSize()
705 * \sa SDL_SetWindowMaximumSize()
946 * \sa SDL_GetWindowMinimumSize
947 * \sa SDL_SetWindowMaximumSize
706 948 */ */
707 949 extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window,
708 950 int min_w, int min_h); int min_w, int min_h);
709 951
710 952 /** /**
711 * \brief Get the minimum size of a window's client area.
953 * Get the minimum size of a window's client area.
712 954 * *
713 * \param window The window to query.
714 * \param w Pointer to variable for storing the minimum width, may be NULL
715 * \param h Pointer to variable for storing the minimum height, may be NULL
955 * \param window the window to query
956 * \param w a pointer filled in with the minimum width of the window, may be
957 * NULL
958 * \param h a pointer filled in with the minimum height of the window, may be
959 * NULL
716 960 * *
717 * \sa SDL_GetWindowMaximumSize()
718 * \sa SDL_SetWindowMinimumSize()
961 * \sa SDL_GetWindowMaximumSize
962 * \sa SDL_SetWindowMinimumSize
719 963 */ */
720 964 extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window,
721 965 int *w, int *h); int *w, int *h);
722 966
723 967 /** /**
724 * \brief Set the maximum size of a window's client area.
968 * Set the maximum size of a window's client area.
725 969 * *
726 * \param window The window to set a new maximum size.
727 * \param max_w The maximum width of the window, must be >0
728 * \param max_h The maximum height of the window, must be >0
970 * \param window the window to change
971 * \param max_w the maximum width of the window in pixels
972 * \param max_h the maximum height of the window in pixels
729 973 * *
730 * \note You can't change the maximum size of a fullscreen window, it
731 * automatically matches the size of the display mode.
732 *
733 * \sa SDL_GetWindowMaximumSize()
734 * \sa SDL_SetWindowMinimumSize()
974 * \sa SDL_GetWindowMaximumSize
975 * \sa SDL_SetWindowMinimumSize
735 976 */ */
736 977 extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window,
737 978 int max_w, int max_h); int max_w, int max_h);
738 979
739 980 /** /**
740 * \brief Get the maximum size of a window's client area.
981 * Get the maximum size of a window's client area.
741 982 * *
742 * \param window The window to query.
743 * \param w Pointer to variable for storing the maximum width, may be NULL
744 * \param h Pointer to variable for storing the maximum height, may be NULL
983 * \param window the window to query
984 * \param w a pointer filled in with the maximum width of the window, may be
985 * NULL
986 * \param h a pointer filled in with the maximum height of the window, may be
987 * NULL
745 988 * *
746 * \sa SDL_GetWindowMinimumSize()
747 * \sa SDL_SetWindowMaximumSize()
989 * \sa SDL_GetWindowMinimumSize
990 * \sa SDL_SetWindowMaximumSize
748 991 */ */
749 992 extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window,
750 993 int *w, int *h); int *w, int *h);
751 994
752 995 /** /**
753 * \brief Set the border state of a window.
996 * Set the border state of a window.
754 997 * *
755 * This will add or remove the window's SDL_WINDOW_BORDERLESS flag and
756 * add or remove the border from the actual window. This is a no-op if the
757 * window's border already matches the requested state.
998 * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add
999 * or remove the border from the actual window. This is a no-op if the
1000 * window's border already matches the requested state.
758 1001 * *
759 * \param window The window of which to change the border state.
760 * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
1002 * You can't change the border state of a fullscreen window.
761 1003 * *
762 * \note You can't change the border state of a fullscreen window.
1004 * \param window the window of which to change the border state
1005 * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border
763 1006 * *
764 * \sa SDL_GetWindowFlags()
1007 * \since This function is available since SDL 2.0.0.
1008 *
1009 * \sa SDL_GetWindowFlags
765 1010 */ */
766 1011 extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window,
767 1012 SDL_bool bordered); SDL_bool bordered);
768 1013
769 1014 /** /**
770 * \brief Set the user-resizable state of a window.
1015 * Set the user-resizable state of a window.
771 1016 * *
772 * This will add or remove the window's SDL_WINDOW_RESIZABLE flag and
773 * allow/disallow user resizing of the window. This is a no-op if the
774 * window's resizable state already matches the requested state.
1017 * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and
1018 * allow/disallow user resizing of the window. This is a no-op if the window's
1019 * resizable state already matches the requested state.
775 1020 * *
776 * \param window The window of which to change the resizable state.
777 * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow.
1021 * You can't change the resizable state of a fullscreen window.
778 1022 * *
779 * \note You can't change the resizable state of a fullscreen window.
1023 * \param window the window of which to change the resizable state
1024 * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow
780 1025 * *
781 * \sa SDL_GetWindowFlags()
1026 * \since This function is available since SDL 2.0.5.
1027 *
1028 * \sa SDL_GetWindowFlags
782 1029 */ */
783 1030 extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window,
784 1031 SDL_bool resizable); SDL_bool resizable);
785 1032
786 1033 /** /**
787 * \brief Show a window.
1034 * \brief Set the window to always be above the others.
788 1035 * *
789 * \sa SDL_HideWindow()
1036 * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP`
1037 * flag. This will bring the window to the front and keep the window above
1038 * the rest.
1039 *
1040 * \param window The window of which to change the always on top state.
1041 * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to disable.
1042 *
1043 * \sa SDL_SetWindowAlwaysOnTop
1044 */
1045
1046 extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window,
1047 SDL_bool on_top);
1048 /**
1049 * Show a window.
1050 *
1051 * \param window the window to show
1052 *
1053 * \sa SDL_HideWindow
1054 * \sa SDL_RaiseWindow
790 1055 */ */
791 1056 extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
792 1057
793 1058 /** /**
794 * \brief Hide a window.
1059 * Hide a window.
795 1060 * *
796 * \sa SDL_ShowWindow()
1061 * \param window the window to hide
1062 *
1063 * \sa SDL_ShowWindow
797 1064 */ */
798 1065 extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
799 1066
800 1067 /** /**
801 * \brief Raise a window above other windows and set the input focus.
1068 * Raise a window above other windows and set the input focus.
1069 *
1070 * \param window the window to raise
802 1071 */ */
803 1072 extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
804 1073
805 1074 /** /**
806 * \brief Make a window as large as possible.
1075 * Make a window as large as possible.
807 1076 * *
808 * \sa SDL_RestoreWindow()
1077 * \param window the window to maximize
1078 *
1079 * \sa SDL_MinimizeWindow
1080 * \sa SDL_RestoreWindow
809 1081 */ */
810 1082 extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
811 1083
812 1084 /** /**
813 * \brief Minimize a window to an iconic representation.
1085 * Minimize a window to an iconic representation.
814 1086 * *
815 * \sa SDL_RestoreWindow()
1087 * \param window the window to minimize
1088 *
1089 * \sa SDL_MaximizeWindow
1090 * \sa SDL_RestoreWindow
816 1091 */ */
817 1092 extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
818 1093
819 1094 /** /**
820 * \brief Restore the size and position of a minimized or maximized window.
1095 * Restore the size and position of a minimized or maximized window.
821 1096 * *
822 * \sa SDL_MaximizeWindow()
823 * \sa SDL_MinimizeWindow()
1097 * \param window the window to restore
1098 *
1099 * \sa SDL_MaximizeWindow
1100 * \sa SDL_MinimizeWindow
824 1101 */ */
825 1102 extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
826 1103
827 1104 /** /**
828 * \brief Set a window's fullscreen state.
1105 * Set a window's fullscreen state.
829 1106 * *
830 * \return 0 on success, or -1 if setting the display mode failed.
1107 * `flags` may be `SDL_WINDOW_FULLSCREEN`, for "real" fullscreen with a
1108 * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen
1109 * that takes the size of the desktop; and 0 for windowed mode.
831 1110 * *
832 * \sa SDL_SetWindowDisplayMode()
833 * \sa SDL_GetWindowDisplayMode()
1111 * \param window the window to change
1112 * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0
1113 * \returns 0 on success or a negative error code on failure; call
1114 * SDL_GetError() for more information.
1115 *
1116 * \since This function is available since SDL 2.0.0.
1117 *
1118 * \sa SDL_GetWindowDisplayMode
1119 * \sa SDL_SetWindowDisplayMode
834 1120 */ */
835 1121 extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
836 1122 Uint32 flags); Uint32 flags);
837 1123
838 1124 /** /**
839 * \brief Get the SDL surface associated with the window.
1125 * Get the SDL surface associated with the window.
1126 *
1127 * A new surface will be created with the optimal format for the window, if
1128 * necessary. This surface will be freed when the window is destroyed. Do not
1129 * free this surface.
840 1130 * *
841 * \return The window's framebuffer surface, or NULL on error.
1131 * This surface will be invalidated if the window is resized. After resizing a
1132 * window this function must be called again to return a valid surface.
842 1133 * *
843 * A new surface will be created with the optimal format for the window,
844 * if necessary. This surface will be freed when the window is destroyed.
1134 * You may not combine this with 3D or the rendering API on this window.
845 1135 * *
846 * \note You may not combine this with 3D or the rendering API on this window.
1136 * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.
847 1137 * *
848 * \sa SDL_UpdateWindowSurface()
849 * \sa SDL_UpdateWindowSurfaceRects()
1138 * \param window the window to query
1139 * \returns the surface associated with the window, or NULL on failure; call
1140 * SDL_GetError() for more information.
1141 *
1142 * \sa SDL_UpdateWindowSurface
1143 * \sa SDL_UpdateWindowSurfaceRects
850 1144 */ */
851 1145 extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window);
852 1146
853 1147 /** /**
854 * \brief Copy the window surface to the screen.
1148 * Copy the window surface to the screen.
1149 *
1150 * This is the function you use to reflect any changes to the surface on the
1151 * screen.
1152 *
1153 * This function is equivalent to the SDL 1.2 API SDL_Flip().
855 1154 * *
856 * \return 0 on success, or -1 on error.
1155 * \param window the window to update
1156 * \returns 0 on success or a negative error code on failure; call
1157 * SDL_GetError() for more information.
857 1158 * *
858 * \sa SDL_GetWindowSurface()
859 * \sa SDL_UpdateWindowSurfaceRects()
1159 * \sa SDL_GetWindowSurface
1160 * \sa SDL_UpdateWindowSurfaceRects
860 1161 */ */
861 1162 extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window); extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window);
862 1163
863 1164 /** /**
864 * \brief Copy a number of rectangles on the window surface to the screen.
1165 * Copy areas of the window surface to the screen.
865 1166 * *
866 * \return 0 on success, or -1 on error.
1167 * This is the function you use to reflect changes to portions of the surface
1168 * on the screen.
867 1169 * *
868 * \sa SDL_GetWindowSurface()
869 * \sa SDL_UpdateWindowSurface()
1170 * This function is equivalent to the SDL 1.2 API SDL_UpdateRects().
1171 *
1172 * \param window the window to update
1173 * \param rects an array of SDL_Rect structures representing areas of the
1174 * surface to copy
1175 * \param numrects the number of rectangles
1176 * \returns 0 on success or a negative error code on failure; call
1177 * SDL_GetError() for more information.
1178 *
1179 * \sa SDL_GetWindowSurface
1180 * \sa SDL_UpdateWindowSurface
870 1181 */ */
871 1182 extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
872 1183 const SDL_Rect * rects, const SDL_Rect * rects,
873 1184 int numrects); int numrects);
874 1185
875 1186 /** /**
876 * \brief Set a window's input grab mode.
1187 * Set a window's input grab mode.
877 1188 * *
878 * \param window The window for which the input grab mode should be set.
879 * \param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input.
1189 * When input is grabbed the mouse is confined to the window.
880 1190 * *
881 * If the caller enables a grab while another window is currently grabbed,
882 * the other window loses its grab in favor of the caller's window.
1191 * If the caller enables a grab while another window is currently grabbed, the
1192 * other window loses its grab in favor of the caller's window.
883 1193 * *
884 * \sa SDL_GetWindowGrab()
1194 * \param window the window for which the input grab mode should be set
1195 * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input
1196 *
1197 * \sa SDL_GetGrabbedWindow
1198 * \sa SDL_GetWindowGrab
885 1199 */ */
886 1200 extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
887 1201 SDL_bool grabbed); SDL_bool grabbed);
888 1202
889 1203 /** /**
890 * \brief Get a window's input grab mode.
1204 * Set a window's keyboard grab mode.
891 1205 * *
892 * \return This returns SDL_TRUE if input is grabbed, and SDL_FALSE otherwise.
1206 * If the caller enables a grab while another window is currently grabbed, the
1207 * other window loses its grab in favor of the caller's window.
893 1208 * *
894 * \sa SDL_SetWindowGrab()
1209 * \param window The window for which the keyboard grab mode should be set.
1210 * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
1211 *
1212 * \sa SDL_GetWindowKeyboardGrab
1213 * \sa SDL_SetWindowMouseGrab
1214 * \sa SDL_SetWindowGrab
1215 */
1216 extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
1217 SDL_bool grabbed);
1218
1219 /**
1220 * Set a window's mouse grab mode.
1221 *
1222 * \param window The window for which the mouse grab mode should be set.
1223 *
1224 * \sa SDL_GetWindowMouseGrab
1225 * \sa SDL_SetWindowKeyboardGrab
1226 * \sa SDL_SetWindowGrab
1227 */
1228 extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window,
1229 SDL_bool grabbed);
1230
1231 /**
1232 * Get a window's input grab mode.
1233 *
1234 * \param window the window to query
1235 * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
1236 *
1237 * \sa SDL_SetWindowGrab
895 1238 */ */
896 1239 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
897 1240
898 1241 /** /**
899 * \brief Get the window that currently has an input grab enabled.
1242 * Get a window's keyboard grab mode.
900 1243 * *
901 * \return This returns the window if input is grabbed, and NULL otherwise.
1244 * \param window the window to query
1245 * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
902 1246 * *
903 * \sa SDL_SetWindowGrab()
1247 * \sa SDL_SetWindowKeyboardGrab
1248 * \sa SDL_GetWindowGrab
1249 */
1250 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
1251
1252 /**
1253 * Get a window's mouse grab mode.
1254 *
1255 * \param window the window to query
1256 * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
1257 *
1258 * \sa SDL_SetWindowKeyboardGrab
1259 * \sa SDL_GetWindowGrab
1260 */
1261 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window);
1262
1263 /**
1264 * Get the window that currently has an input grab enabled.
1265 *
1266 * \returns the window if input is grabbed or NULL otherwise.
1267 *
1268 * \since This function is available since SDL 2.0.4.
1269 *
1270 * \sa SDL_GetWindowGrab
1271 * \sa SDL_SetWindowGrab
904 1272 */ */
905 1273 extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
906 1274
907 1275 /** /**
908 * \brief Set the brightness (gamma correction) for a window.
1276 * Set the brightness (gamma multiplier) for a given window's display.
1277 *
1278 * Despite the name and signature, this method sets the brightness of the
1279 * entire display, not an individual window. A window is considered to be
1280 * owned by the display that contains the window's center pixel. (The index of
1281 * this display can be retrieved using SDL_GetWindowDisplayIndex().) The
1282 * brightness set will not follow the window if it is moved to another
1283 * display.
909 1284 * *
910 * \return 0 on success, or -1 if setting the brightness isn't supported.
1285 * Many platforms will refuse to set the display brightness in modern times.
1286 * You are better off using a shader to adjust gamma during rendering, or
1287 * something similar.
911 1288 * *
912 * \sa SDL_GetWindowBrightness()
913 * \sa SDL_SetWindowGammaRamp()
1289 * \param window the window used to select the display whose brightness will
1290 * be changed
1291 * \param brightness the brightness (gamma multiplier) value to set where 0.0
1292 * is completely dark and 1.0 is normal brightness
1293 * \returns 0 on success or a negative error code on failure; call
1294 * SDL_GetError() for more information.
1295 *
1296 * \sa SDL_GetWindowBrightness
1297 * \sa SDL_SetWindowGammaRamp
914 1298 */ */
915 1299 extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness); extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness);
916 1300
917 1301 /** /**
918 * \brief Get the brightness (gamma correction) for a window.
1302 * Get the brightness (gamma multiplier) for a given window's display.
1303 *
1304 * Despite the name and signature, this method retrieves the brightness of the
1305 * entire display, not an individual window. A window is considered to be
1306 * owned by the display that contains the window's center pixel. (The index of
1307 * this display can be retrieved using SDL_GetWindowDisplayIndex().)
919 1308 * *
920 * \return The last brightness value passed to SDL_SetWindowBrightness()
1309 * \param window the window used to select the display whose brightness will
1310 * be queried
1311 * \returns the brightness for the display where 0.0 is completely dark and
1312 * 1.0 is normal brightness.
921 1313 * *
922 * \sa SDL_SetWindowBrightness()
1314 * \sa SDL_SetWindowBrightness
923 1315 */ */
924 1316 extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window);
925 1317
926 1318 /** /**
927 * \brief Set the opacity for a window
1319 * Set the opacity for a window.
1320 *
1321 * The parameter `opacity` will be clamped internally between 0.0f
1322 * (transparent) and 1.0f (opaque).
928 1323 * *
929 * \param window The window which will be made transparent or opaque
930 * \param opacity Opacity (0.0f - transparent, 1.0f - opaque) This will be
931 * clamped internally between 0.0f and 1.0f.
1324 * This function also returns -1 if setting the opacity isn't supported.
932 1325 * *
933 * \return 0 on success, or -1 if setting the opacity isn't supported.
1326 * \param window the window which will be made transparent or opaque
1327 * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque)
1328 * \returns 0 on success or a negative error code on failure; call
1329 * SDL_GetError() for more information.
934 1330 * *
935 * \sa SDL_GetWindowOpacity()
1331 * \since This function is available since SDL 2.0.5.
1332 *
1333 * \sa SDL_GetWindowOpacity
936 1334 */ */
937 1335 extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity); extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity);
938 1336
939 1337 /** /**
940 * \brief Get the opacity of a window.
1338 * Get the opacity of a window.
1339 *
1340 * If transparency isn't supported on this platform, opacity will be reported
1341 * as 1.0f without error.
1342 *
1343 * The parameter `opacity` is ignored if it is NULL.
941 1344 * *
942 * If transparency isn't supported on this platform, opacity will be reported
943 * as 1.0f without error.
1345 * This function also returns -1 if an invalid window was provided.
944 1346 * *
945 * \param window The window in question.
946 * \param out_opacity Opacity (0.0f - transparent, 1.0f - opaque)
1347 * \param window the window to get the current opacity value from
1348 * \param out_opacity the float filled in (0.0f - transparent, 1.0f - opaque)
1349 * \returns 0 on success or a negative error code on failure; call
1350 * SDL_GetError() for more information.
947 1351 * *
948 * \return 0 on success, or -1 on error (invalid window, etc).
1352 * \since This function is available since SDL 2.0.5.
949 1353 * *
950 * \sa SDL_SetWindowOpacity()
1354 * \sa SDL_SetWindowOpacity
951 1355 */ */
952 1356 extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity); extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity);
953 1357
954 1358 /** /**
955 * \brief Sets the window as a modal for another window (TODO: reconsider this function and/or its name)
1359 * Set the window as a modal for another window.
956 1360 * *
957 * \param modal_window The window that should be modal
958 * \param parent_window The parent window
1361 * \param modal_window the window that should be set modal
1362 * \param parent_window the parent window for the modal window
1363 * \returns 0 on success or a negative error code on failure; call
1364 * SDL_GetError() for more information.
959 1365 * *
960 * \return 0 on success, or -1 otherwise.
1366 * \since This function is available since SDL 2.0.5.
961 1367 */ */
962 1368 extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window); extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window);
963 1369
964 1370 /** /**
965 * \brief Explicitly sets input focus to the window.
1371 * Explicitly set input focus to the window.
966 1372 * *
967 * You almost certainly want SDL_RaiseWindow() instead of this function. Use
968 * this with caution, as you might give focus to a window that's completely
969 * obscured by other windows.
1373 * You almost certainly want SDL_RaiseWindow() instead of this function. Use
1374 * this with caution, as you might give focus to a window that is completely
1375 * obscured by other windows.
970 1376 * *
971 * \param window The window that should get the input focus
1377 * \param window the window that should get the input focus
1378 * \returns 0 on success or a negative error code on failure; call
1379 * SDL_GetError() for more information.
972 1380 * *
973 * \return 0 on success, or -1 otherwise.
974 * \sa SDL_RaiseWindow()
1381 * \since This function is available since SDL 2.0.5.
1382 *
1383 * \sa SDL_RaiseWindow
975 1384 */ */
976 1385 extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window);
977 1386
978 1387 /** /**
979 * \brief Set the gamma ramp for a window.
1388 * Set the gamma ramp for the display that owns a given window.
980 1389 * *
981 * \param window The window for which the gamma ramp should be set.
982 * \param red The translation table for the red channel, or NULL.
983 * \param green The translation table for the green channel, or NULL.
984 * \param blue The translation table for the blue channel, or NULL.
1390 * Set the gamma translation table for the red, green, and blue channels of
1391 * the video hardware. Each table is an array of 256 16-bit quantities,
1392 * representing a mapping between the input and output for that channel. The
1393 * input is the index into the array, and the output is the 16-bit gamma value
1394 * at that index, scaled to the output color precision.
985 1395 * *
986 * \return 0 on success, or -1 if gamma ramps are unsupported.
1396 * Despite the name and signature, this method sets the gamma ramp of the
1397 * entire display, not an individual window. A window is considered to be
1398 * owned by the display that contains the window's center pixel. (The index of
1399 * this display can be retrieved using SDL_GetWindowDisplayIndex().) The gamma
1400 * ramp set will not follow the window if it is moved to another display.
987 1401 * *
988 * Set the gamma translation table for the red, green, and blue channels
989 * of the video hardware. Each table is an array of 256 16-bit quantities,
990 * representing a mapping between the input and output for that channel.
991 * The input is the index into the array, and the output is the 16-bit
992 * gamma value at that index, scaled to the output color precision.
1402 * \param window the window used to select the display whose gamma ramp will
1403 * be changed
1404 * \param red a 256 element array of 16-bit quantities representing the
1405 * translation table for the red channel, or NULL
1406 * \param green a 256 element array of 16-bit quantities representing the
1407 * translation table for the green channel, or NULL
1408 * \param blue a 256 element array of 16-bit quantities representing the
1409 * translation table for the blue channel, or NULL
1410 * \returns 0 on success or a negative error code on failure; call
1411 * SDL_GetError() for more information.
993 1412 * *
994 * \sa SDL_GetWindowGammaRamp()
1413 * \sa SDL_GetWindowGammaRamp
995 1414 */ */
996 1415 extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
997 1416 const Uint16 * red, const Uint16 * red,
 
... ... extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
999 1418 const Uint16 * blue); const Uint16 * blue);
1000 1419
1001 1420 /** /**
1002 * \brief Get the gamma ramp for a window.
1421 * Get the gamma ramp for a given window's display.
1003 1422 * *
1004 * \param window The window from which the gamma ramp should be queried.
1005 * \param red A pointer to a 256 element array of 16-bit quantities to hold
1006 * the translation table for the red channel, or NULL.
1007 * \param green A pointer to a 256 element array of 16-bit quantities to hold
1008 * the translation table for the green channel, or NULL.
1009 * \param blue A pointer to a 256 element array of 16-bit quantities to hold
1010 * the translation table for the blue channel, or NULL.
1423 * Despite the name and signature, this method retrieves the gamma ramp of the
1424 * entire display, not an individual window. A window is considered to be
1425 * owned by the display that contains the window's center pixel. (The index of
1426 * this display can be retrieved using SDL_GetWindowDisplayIndex().)
1011 1427 * *
1012 * \return 0 on success, or -1 if gamma ramps are unsupported.
1428 * \param window the window used to select the display whose gamma ramp will
1429 * be queried
1430 * \param red a 256 element array of 16-bit quantities filled in with the
1431 * translation table for the red channel, or NULL
1432 * \param green a 256 element array of 16-bit quantities filled in with the
1433 * translation table for the green channel, or NULL
1434 * \param blue a 256 element array of 16-bit quantities filled in with the
1435 * translation table for the blue channel, or NULL
1436 * \returns 0 on success or a negative error code on failure; call
1437 * SDL_GetError() for more information.
1013 1438 * *
1014 * \sa SDL_SetWindowGammaRamp()
1439 * \sa SDL_SetWindowGammaRamp
1015 1440 */ */
1016 1441 extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
1017 1442 Uint16 * red, Uint16 * red,
 
... ... extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
1019 1444 Uint16 * blue); Uint16 * blue);
1020 1445
1021 1446 /** /**
1022 * \brief Possible return values from the SDL_HitTest callback.
1447 * Possible return values from the SDL_HitTest callback.
1023 1448 * *
1024 * \sa SDL_HitTest
1449 * \sa SDL_HitTest
1025 1450 */ */
1026 1451 typedef enum typedef enum
1027 1452 { {
 
... ... typedef enum
1038 1463 } SDL_HitTestResult; } SDL_HitTestResult;
1039 1464
1040 1465 /** /**
1041 * \brief Callback used for hit-testing.
1466 * Callback used for hit-testing.
1467 *
1468 * \param win the SDL_Window where hit-testing was set on
1469 * \param area an SDL_Point which should be hit-tested
1470 * \param data what was passed as `callback_data` to SDL_SetWindowHitTest()
1471 * \return an SDL_HitTestResult value.
1042 1472 * *
1043 * \sa SDL_SetWindowHitTest
1473 * \sa SDL_SetWindowHitTest
1044 1474 */ */
1045 1475 typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
1046 1476 const SDL_Point *area, const SDL_Point *area,
1047 1477 void *data); void *data);
1048 1478
1049 1479 /** /**
1050 * \brief Provide a callback that decides if a window region has special properties.
1480 * Provide a callback that decides if a window region has special properties.
1051 1481 * *
1052 * Normally windows are dragged and resized by decorations provided by the
1053 * system window manager (a title bar, borders, etc), but for some apps, it
1054 * makes sense to drag them from somewhere else inside the window itself; for
1055 * example, one might have a borderless window that wants to be draggable
1056 * from any part, or simulate its own title bar, etc.
1482 * Normally windows are dragged and resized by decorations provided by the
1483 * system window manager (a title bar, borders, etc), but for some apps, it
1484 * makes sense to drag them from somewhere else inside the window itself; for
1485 * example, one might have a borderless window that wants to be draggable from
1486 * any part, or simulate its own title bar, etc.
1057 1487 * *
1058 * This function lets the app provide a callback that designates pieces of
1059 * a given window as special. This callback is run during event processing
1060 * if we need to tell the OS to treat a region of the window specially; the
1061 * use of this callback is known as "hit testing."
1488 * This function lets the app provide a callback that designates pieces of a
1489 * given window as special. This callback is run during event processing if we
1490 * need to tell the OS to treat a region of the window specially; the use of
1491 * this callback is known as "hit testing."
1062 1492 * *
1063 * Mouse input may not be delivered to your application if it is within
1064 * a special area; the OS will often apply that input to moving the window or
1065 * resizing the window and not deliver it to the application.
1493 * Mouse input may not be delivered to your application if it is within a
1494 * special area; the OS will often apply that input to moving the window or
1495 * resizing the window and not deliver it to the application.
1066 1496 * *
1067 * Specifying NULL for a callback disables hit-testing. Hit-testing is
1068 * disabled by default.
1497 * Specifying NULL for a callback disables hit-testing. Hit-testing is
1498 * disabled by default.
1069 1499 * *
1070 * Platforms that don't support this functionality will return -1
1071 * unconditionally, even if you're attempting to disable hit-testing.
1500 * Platforms that don't support this functionality will return -1
1501 * unconditionally, even if you're attempting to disable hit-testing.
1072 1502 * *
1073 * Your callback may fire at any time, and its firing does not indicate any
1074 * specific behavior (for example, on Windows, this certainly might fire
1075 * when the OS is deciding whether to drag your window, but it fires for lots
1076 * of other reasons, too, some unrelated to anything you probably care about
1077 * _and when the mouse isn't actually at the location it is testing_).
1078 * Since this can fire at any time, you should try to keep your callback
1079 * efficient, devoid of allocations, etc.
1503 * Your callback may fire at any time, and its firing does not indicate any
1504 * specific behavior (for example, on Windows, this certainly might fire when
1505 * the OS is deciding whether to drag your window, but it fires for lots of
1506 * other reasons, too, some unrelated to anything you probably care about _and
1507 * when the mouse isn't actually at the location it is testing_). Since this
1508 * can fire at any time, you should try to keep your callback efficient,
1509 * devoid of allocations, etc.
1080 1510 * *
1081 * \param window The window to set hit-testing on.
1082 * \param callback The callback to call when doing a hit-test.
1083 * \param callback_data An app-defined void pointer passed to the callback.
1084 * \return 0 on success, -1 on error (including unsupported).
1511 * \param window the window to set hit-testing on
1512 * \param callback the function to call when doing a hit-test
1513 * \param callback_data an app-defined void pointer passed to **callback**
1514 * \returns 0 on success or -1 on error (including unsupported); call
1515 * SDL_GetError() for more information.
1516 *
1517 * \since This function is available since SDL 2.0.4.
1085 1518 */ */
1086 1519 extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
1087 1520 SDL_HitTest callback, SDL_HitTest callback,
1088 1521 void *callback_data); void *callback_data);
1089 1522
1090 1523 /** /**
1091 * \brief Destroy a window.
1524 * Request a window to demand attention from the user.
1525 *
1526 * \param window the window to be flashed
1527 * \param operation the flash operation
1528 * \returns 0 on success or a negative error code on failure; call
1529 * SDL_GetError() for more information.
1530 */
1531 extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperation operation);
1532
1533 /**
1534 * Destroy a window.
1535 *
1536 * If `window` is NULL, this function will return immediately after setting
1537 * the SDL error message to "Invalid window". See SDL_GetError().
1538 *
1539 * \param window the window to destroy
1540 *
1541 * \sa SDL_CreateWindow
1542 * \sa SDL_CreateWindowFrom
1092 1543 */ */
1093 1544 extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window);
1094 1545
1095 1546
1096 1547 /** /**
1097 * \brief Returns whether the screensaver is currently enabled (default off).
1548 * Check whether the screensaver is currently enabled.
1549 *
1550 * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2
1551 * the screensaver was enabled by default.
1552 *
1553 * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`.
1098 1554 * *
1099 * \sa SDL_EnableScreenSaver()
1100 * \sa SDL_DisableScreenSaver()
1555 * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is
1556 * disabled.
1557 *
1558 * \since This function is available since SDL 2.0.0.
1559 *
1560 * \sa SDL_DisableScreenSaver
1561 * \sa SDL_EnableScreenSaver
1101 1562 */ */
1102 1563 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void); extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
1103 1564
1104 1565 /** /**
1105 * \brief Allow the screen to be blanked by a screensaver
1566 * Allow the screen to be blanked by a screen saver.
1567 *
1568 * \since This function is available since SDL 2.0.0.
1106 1569 * *
1107 * \sa SDL_IsScreenSaverEnabled()
1108 * \sa SDL_DisableScreenSaver()
1570 * \sa SDL_DisableScreenSaver
1571 * \sa SDL_IsScreenSaverEnabled
1109 1572 */ */
1110 1573 extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void); extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
1111 1574
1112 1575 /** /**
1113 * \brief Prevent the screen from being blanked by a screensaver
1576 * Prevent the screen from being blanked by a screen saver.
1114 1577 * *
1115 * \sa SDL_IsScreenSaverEnabled()
1116 * \sa SDL_EnableScreenSaver()
1578 * If you disable the screensaver, it is automatically re-enabled when SDL
1579 * quits.
1580 *
1581 * \since This function is available since SDL 2.0.0.
1582 *
1583 * \sa SDL_EnableScreenSaver
1584 * \sa SDL_IsScreenSaverEnabled
1117 1585 */ */
1118 1586 extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void); extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
1119 1587
 
... ... extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
1124 1592 /* @{ */ /* @{ */
1125 1593
1126 1594 /** /**
1127 * \brief Dynamically load an OpenGL library.
1595 * Dynamically load an OpenGL library.
1128 1596 * *
1129 * \param path The platform dependent OpenGL library name, or NULL to open the
1130 * default OpenGL library.
1597 * This should be done after initializing the video driver, but before
1598 * creating any OpenGL windows. If no OpenGL library is loaded, the default
1599 * library will be loaded upon creation of the first OpenGL window.
1131 1600 * *
1132 * \return 0 on success, or -1 if the library couldn't be loaded.
1601 * If you do this, you need to retrieve all of the GL functions used in your
1602 * program from the dynamic library using SDL_GL_GetProcAddress().
1133 1603 * *
1134 * This should be done after initializing the video driver, but before
1135 * creating any OpenGL windows. If no OpenGL library is loaded, the default
1136 * library will be loaded upon creation of the first OpenGL window.
1604 * \param path the platform dependent OpenGL library name, or NULL to open the
1605 * default OpenGL library
1606 * \returns 0 on success or a negative error code on failure; call
1607 * SDL_GetError() for more information.
1137 1608 * *
1138 * \note If you do this, you need to retrieve all of the GL functions used in
1139 * your program from the dynamic library using SDL_GL_GetProcAddress().
1140 *
1141 * \sa SDL_GL_GetProcAddress()
1142 * \sa SDL_GL_UnloadLibrary()
1609 * \sa SDL_GL_GetProcAddress
1610 * \sa SDL_GL_UnloadLibrary
1143 1611 */ */
1144 1612 extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
1145 1613
1146 1614 /** /**
1147 * \brief Get the address of an OpenGL function.
1615 * Get an OpenGL function by name.
1616 *
1617 * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all
1618 * GL functions must be retrieved this way. Usually this is used to retrieve
1619 * function pointers to OpenGL extensions.
1620 *
1621 * There are some quirks to looking up OpenGL functions that require some
1622 * extra care from the application. If you code carefully, you can handle
1623 * these quirks without any platform-specific code, though:
1624 *
1625 * - On Windows, function pointers are specific to the current GL context;
1626 * this means you need to have created a GL context and made it current
1627 * before calling SDL_GL_GetProcAddress(). If you recreate your context or
1628 * create a second context, you should assume that any existing function
1629 * pointers aren't valid to use with it. This is (currently) a
1630 * Windows-specific limitation, and in practice lots of drivers don't suffer
1631 * this limitation, but it is still the way the wgl API is documented to
1632 * work and you should expect crashes if you don't respect it. Store a copy
1633 * of the function pointers that comes and goes with context lifespan.
1634 * - On X11, function pointers returned by this function are valid for any
1635 * context, and can even be looked up before a context is created at all.
1636 * This means that, for at least some common OpenGL implementations, if you
1637 * look up a function that doesn't exist, you'll get a non-NULL result that
1638 * is _NOT_ safe to call. You must always make sure the function is actually
1639 * available for a given GL context before calling it, by checking for the
1640 * existence of the appropriate extension with SDL_GL_ExtensionSupported(),
1641 * or verifying that the version of OpenGL you're using offers the function
1642 * as core functionality.
1643 * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
1644 * isn't supported, but you can't count on this behavior. Check for
1645 * extensions you use, and if you get a NULL anyway, act as if that
1646 * extension wasn't available. This is probably a bug in the driver, but you
1647 * can code defensively for this scenario anyhow.
1648 * - Just because you're on Linux/Unix, don't assume you'll be using X11.
1649 * Next-gen display servers are waiting to replace it, and may or may not
1650 * make the same promises about function pointers.
1651 * - OpenGL function pointers must be declared `APIENTRY` as in the example
1652 * code. This will ensure the proper calling convention is followed on
1653 * platforms where this matters (Win32) thereby avoiding stack corruption.
1654 *
1655 * \param proc the name of an OpenGL function
1656 * \returns a pointer to the named OpenGL function. The returned pointer
1657 * should be cast to the appropriate function signature.
1658 *
1659 * \sa SDL_GL_ExtensionSupported
1660 * \sa SDL_GL_LoadLibrary
1661 * \sa SDL_GL_UnloadLibrary
1148 1662 */ */
1149 1663 extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc); extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
1150 1664
1151 1665 /** /**
1152 * \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
1666 * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
1153 1667 * *
1154 * \sa SDL_GL_LoadLibrary()
1668 * \sa SDL_GL_LoadLibrary
1155 1669 */ */
1156 1670 extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
1157 1671
1158 1672 /** /**
1159 * \brief Return true if an OpenGL extension is supported for the current
1160 * context.
1673 * Check if an OpenGL extension is supported for the current context.
1674 *
1675 * This function operates on the current GL context; you must have created a
1676 * context and it must be current before calling this function. Do not assume
1677 * that all contexts you create will have the same set of extensions
1678 * available, or that recreating an existing context will offer the same
1679 * extensions again.
1680 *
1681 * While it's probably not a massive overhead, this function is not an O(1)
1682 * operation. Check the extensions you care about after creating the GL
1683 * context and save that information somewhere instead of calling the function
1684 * every time you need to know.
1685 *
1686 * \param extension the name of the extension to check
1687 * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise.
1688 *
1689 * \since This function is available since SDL 2.0.0.
1161 1690 */ */
1162 1691 extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
1163 1692 *extension); *extension);
1164 1693
1165 1694 /** /**
1166 * \brief Reset all previously set OpenGL context attributes to their default values
1695 * Reset all previously set OpenGL context attributes to their default values.
1696 *
1697 * \since This function is available since SDL 2.0.2.
1698 *
1699 * \sa SDL_GL_GetAttribute
1700 * \sa SDL_GL_SetAttribute
1167 1701 */ */
1168 1702 extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
1169 1703
1170 1704 /** /**
1171 * \brief Set an OpenGL window attribute before window creation.
1705 * Set an OpenGL window attribute before window creation.
1706 *
1707 * This function sets the OpenGL attribute `attr` to `value`. The requested
1708 * attributes should be set before creating an OpenGL window. You should use
1709 * SDL_GL_GetAttribute() to check the values after creating the OpenGL
1710 * context, since the values obtained can differ from the requested ones.
1172 1711 * *
1173 * \return 0 on success, or -1 if the attribute could not be set.
1712 * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
1713 * \param value the desired value for the attribute
1714 * \returns 0 on success or a negative error code on failure; call
1715 * SDL_GetError() for more information.
1716 *
1717 * \sa SDL_GL_GetAttribute
1718 * \sa SDL_GL_ResetAttributes
1174 1719 */ */
1175 1720 extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
1176 1721
1177 1722 /** /**
1178 * \brief Get the actual value for an attribute from the current context.
1723 * Get the actual value for an attribute from the current context.
1724 *
1725 * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to get
1726 * \param value a pointer filled in with the current value of `attr`
1727 * \returns 0 on success or a negative error code on failure; call
1728 * SDL_GetError() for more information.
1179 1729 * *
1180 * \return 0 on success, or -1 if the attribute could not be retrieved.
1181 * The integer at \c value will be modified in either case.
1730 * \sa SDL_GL_ResetAttributes
1731 * \sa SDL_GL_SetAttribute
1182 1732 */ */
1183 1733 extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
1184 1734
1185 1735 /** /**
1186 * \brief Create an OpenGL context for use with an OpenGL window, and make it
1187 * current.
1736 * Create an OpenGL context for an OpenGL window, and make it current.
1737 *
1738 * Windows users new to OpenGL should note that, for historical reasons, GL
1739 * functions added after OpenGL version 1.1 are not available by default.
1740 * Those functions must be loaded at run-time, either with an OpenGL
1741 * extension-handling library or with SDL_GL_GetProcAddress() and its related
1742 * functions.
1188 1743 * *
1189 * \sa SDL_GL_DeleteContext()
1744 * SDL_GLContext is an alias for `void *`. It's opaque to the application.
1745 *
1746 * \param window the window to associate with the context
1747 * \returns the OpenGL context associated with `window` or NULL on error; call
1748 * SDL_GetError() for more details.
1749 *
1750 * \sa SDL_GL_DeleteContext
1751 * \sa SDL_GL_MakeCurrent
1190 1752 */ */
1191 1753 extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window * extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *
1192 1754 window); window);
1193 1755
1194 1756 /** /**
1195 * \brief Set up an OpenGL context for rendering into an OpenGL window.
1757 * Set up an OpenGL context for rendering into an OpenGL window.
1758 *
1759 * The context must have been created with a compatible window.
1760 *
1761 * \param window the window to associate with the context
1762 * \param context the OpenGL context to associate with the window
1763 * \returns 0 on success or a negative error code on failure; call
1764 * SDL_GetError() for more information.
1196 1765 * *
1197 * \note The context must have been created with a compatible window.
1766 * \sa SDL_GL_CreateContext
1198 1767 */ */
1199 1768 extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window, extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window,
1200 1769 SDL_GLContext context); SDL_GLContext context);
1201 1770
1202 1771 /** /**
1203 * \brief Get the currently active OpenGL window.
1772 * Get the currently active OpenGL window.
1773 *
1774 * \returns the currently active OpenGL window on success or NULL on failure;
1775 * call SDL_GetError() for more information.
1776 *
1777 * \since This function is available since SDL 2.0.0.
1204 1778 */ */
1205 1779 extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void); extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void);
1206 1780
1207 1781 /** /**
1208 * \brief Get the currently active OpenGL context.
1782 * Get the currently active OpenGL context.
1783 *
1784 * \returns the currently active OpenGL context or NULL on failure; call
1785 * SDL_GetError() for more information.
1786 *
1787 * \since This function is available since SDL 2.0.0.
1788 *
1789 * \sa SDL_GL_MakeCurrent
1209 1790 */ */
1210 1791 extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
1211 1792
1212 1793 /** /**
1213 * \brief Get the size of a window's underlying drawable in pixels (for use
1214 * with glViewport).
1794 * Get the size of a window's underlying drawable in pixels.
1215 1795 * *
1216 * \param window Window from which the drawable size should be queried
1217 * \param w Pointer to variable for storing the width in pixels, may be NULL
1218 * \param h Pointer to variable for storing the height in pixels, may be NULL
1796 * This returns info useful for calling glViewport().
1219 1797 * *
1220 1798 * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
1221 * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
1222 * platform with high-DPI support (Apple calls this "Retina"), and not disabled
1223 * by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
1799 * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
1800 * platform with high-DPI support (Apple calls this "Retina"), and not
1801 * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
1224 1802 * *
1225 * \sa SDL_GetWindowSize()
1226 * \sa SDL_CreateWindow()
1803 * \param window the window from which the drawable size should be queried
1804 * \param w a pointer to variable for storing the width in pixels, may be NULL
1805 * \param h a pointer to variable for storing the height in pixels, may be
1806 * NULL
1807 *
1808 * \since This function is available since SDL 2.0.1.
1809 *
1810 * \sa SDL_CreateWindow
1811 * \sa SDL_GetWindowSize
1227 1812 */ */
1228 1813 extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
1229 1814 int *h); int *h);
1230 1815
1231 1816 /** /**
1232 * \brief Set the swap interval for the current OpenGL context.
1817 * Set the swap interval for the current OpenGL context.
1233 1818 * *
1234 * \param interval 0 for immediate updates, 1 for updates synchronized with the
1235 * vertical retrace. If the system supports it, you may
1236 * specify -1 to allow late swaps to happen immediately
1237 * instead of waiting for the next retrace.
1819 * Some systems allow specifying -1 for the interval, to enable adaptive
1820 * vsync. Adaptive vsync works the same as vsync, but if you've already missed
1821 * the vertical retrace for a given frame, it swaps buffers immediately, which
1822 * might be less jarring for the user during occasional framerate drops. If an
1823 * application requests adaptive vsync and the system does not support it,
1824 * this function will fail and return -1. In such a case, you should probably
1825 * retry the call with 1 for the interval.
1238 1826 * *
1239 * \return 0 on success, or -1 if setting the swap interval is not supported.
1827 * Adaptive vsync is implemented for some glX drivers with
1828 * GLX_EXT_swap_control_tear:
1240 1829 * *
1241 * \sa SDL_GL_GetSwapInterval()
1830 * https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt
1831 *
1832 * and for some Windows drivers with WGL_EXT_swap_control_tear:
1833 *
1834 * https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt
1835 *
1836 * Read more on the Khronos wiki:
1837 * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
1838 *
1839 * \param interval 0 for immediate updates, 1 for updates synchronized with
1840 * the vertical retrace, -1 for adaptive vsync
1841 * \returns 0 on success or -1 if setting the swap interval is not supported;
1842 * call SDL_GetError() for more information.
1843 *
1844 * \since This function is available since SDL 2.0.0.
1845 *
1846 * \sa SDL_GL_GetSwapInterval
1242 1847 */ */
1243 1848 extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
1244 1849
1245 1850 /** /**
1246 * \brief Get the swap interval for the current OpenGL context.
1851 * Get the swap interval for the current OpenGL context.
1247 1852 * *
1248 * \return 0 if there is no vertical retrace synchronization, 1 if the buffer
1853 * If the system can't determine the swap interval, or there isn't a valid
1854 * current context, this function will return 0 as a safe default.
1855 *
1856 * \returns 0 if there is no vertical retrace synchronization, 1 if the buffer
1249 1857 * swap is synchronized with the vertical retrace, and -1 if late * swap is synchronized with the vertical retrace, and -1 if late
1250 * swaps happen immediately instead of waiting for the next retrace.
1251 * If the system can't determine the swap interval, or there isn't a
1252 * valid current context, this will return 0 as a safe default.
1858 * swaps happen immediately instead of waiting for the next retrace;
1859 * call SDL_GetError() for more information.
1860 *
1861 * \since This function is available since SDL 2.0.0.
1253 1862 * *
1254 * \sa SDL_GL_SetSwapInterval()
1863 * \sa SDL_GL_SetSwapInterval
1255 1864 */ */
1256 1865 extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
1257 1866
1258 1867 /** /**
1259 * \brief Swap the OpenGL buffers for a window, if double-buffering is
1260 * supported.
1868 * Update a window with OpenGL rendering.
1869 *
1870 * This is used with double-buffered OpenGL contexts, which are the default.
1871 *
1872 * On macOS, make sure you bind 0 to the draw framebuffer before swapping the
1873 * window, otherwise nothing will happen. If you aren't using
1874 * glBindFramebuffer(), this is the default and you won't have to do anything
1875 * extra.
1876 *
1877 * \param window the window to change
1261 1878 */ */
1262 1879 extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window); extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
1263 1880
1264 1881 /** /**
1265 * \brief Delete an OpenGL context.
1882 * Delete an OpenGL context.
1883 *
1884 * \param context the OpenGL context to be deleted
1266 1885 * *
1267 * \sa SDL_GL_CreateContext()
1886 * \sa SDL_GL_CreateContext
1268 1887 */ */
1269 1888 extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context); extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
1270 1889
File include/SDL2/SDL_vulkan.h changed (mode: 100644) (index a3de1ce..006c5aa)
... ... typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
66 66 /* @{ */ /* @{ */
67 67
68 68 /** /**
69 * \brief Dynamically load a Vulkan loader library.
70 *
71 * \param [in] path The platform dependent Vulkan loader library name, or
72 * \c NULL.
73 *
74 * \return \c 0 on success, or \c -1 if the library couldn't be loaded.
75 *
76 * If \a path is NULL SDL will use the value of the environment variable
77 * \c SDL_VULKAN_LIBRARY, if set, otherwise it loads the default Vulkan
78 * loader library.
79 *
80 * This should be called after initializing the video driver, but before
81 * creating any Vulkan windows. If no Vulkan loader library is loaded, the
82 * default library will be loaded upon creation of the first Vulkan window.
83 *
84 * \note It is fairly common for Vulkan applications to link with \a libvulkan
85 * instead of explicitly loading it at run time. This will work with
86 * SDL provided the application links to a dynamic library and both it
87 * and SDL use the same search path.
88 *
89 * \note If you specify a non-NULL \c path, an application should retrieve all
90 * of the Vulkan functions it uses from the dynamic library using
91 * \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
92 * \c path points to the same vulkan loader library the application
93 * linked to.
94 *
95 * \note On Apple devices, if \a path is NULL, SDL will attempt to find
96 * the vkGetInstanceProcAddr address within all the mach-o images of
97 * the current process. This is because it is fairly common for Vulkan
98 * applications to link with libvulkan (and historically MoltenVK was
99 * provided as a static library). If it is not found then, on macOS, SDL
100 * will attempt to load \c vulkan.framework/vulkan, \c libvulkan.1.dylib,
101 * followed by \c libvulkan.dylib, in that order.
102 * On iOS SDL will attempt to load \c libvulkan.dylib only. Applications
103 * using a dynamic framework or .dylib must ensure it is included in its
104 * application bundle.
105 *
106 * \note On non-Apple devices, application linking with a static libvulkan is
107 * not supported. Either do not link to the Vulkan loader or link to a
108 * dynamic library version.
109 *
110 * \note This function will fail if there are no working Vulkan drivers
111 * installed.
112 *
113 * \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
114 * \sa SDL_Vulkan_UnloadLibrary()
69 * Dynamically load the Vulkan loader library.
70 *
71 * This should be called after initializing the video driver, but before
72 * creating any Vulkan windows. If no Vulkan loader library is loaded, the
73 * default library will be loaded upon creation of the first Vulkan window.
74 *
75 * It is fairly common for Vulkan applications to link with libvulkan instead
76 * of explicitly loading it at run time. This will work with SDL provided the
77 * application links to a dynamic library and both it and SDL use the same
78 * search path.
79 *
80 * If you specify a non-NULL `path`, an application should retrieve all of the
81 * Vulkan functions it uses from the dynamic library using
82 * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
83 * to the same vulkan loader library the application linked to.
84 *
85 * On Apple devices, if `path` is NULL, SDL will attempt to find the
86 * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
87 * process. This is because it is fairly common for Vulkan applications to
88 * link with libvulkan (and historically MoltenVK was provided as a static
89 * library). If it is not found, on macOS, SDL will attempt to load
90 * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
91 * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
92 * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
93 * dynamic framework or .dylib must ensure it is included in its application
94 * bundle.
95 *
96 * On non-Apple devices, application linking with a static libvulkan is not
97 * supported. Either do not link to the Vulkan loader or link to a dynamic
98 * library version.
99 *
100 * \param path The platform dependent Vulkan loader library name or NULL
101 * \returns 0 on success or -1 if the library couldn't be loaded; call
102 * SDL_GetError() for more information.
103 *
104 * \since This function is available in SDL 2.0.8
105 *
106 * \sa SDL_Vulkan_GetVkInstanceProcAddr
107 * \sa SDL_Vulkan_UnloadLibrary
115 108 */ */
116 109 extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
117 110
118 111 /** /**
119 * \brief Get the address of the \c vkGetInstanceProcAddr function.
112 * Get the address of the `vkGetInstanceProcAddr` function.
120 113 * *
121 * \note This should be called after either calling SDL_Vulkan_LoadLibrary
122 * or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
114 * This should be called after either calling SDL_Vulkan_LoadLibrary() or
115 * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
116 *
117 * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
123 118 */ */
124 119 extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
125 120
126 121 /** /**
127 * \brief Unload the Vulkan loader library previously loaded by
128 * \c SDL_Vulkan_LoadLibrary().
122 * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
123 *
124 * \since This function is available in SDL 2.0.8
129 125 * *
130 * \sa SDL_Vulkan_LoadLibrary()
126 * \sa SDL_Vulkan_LoadLibrary
131 127 */ */
132 128 extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
133 129
134 130 /** /**
135 * \brief Get the names of the Vulkan instance extensions needed to create
136 * a surface with \c SDL_Vulkan_CreateSurface().
137 *
138 * \param [in] \c NULL or window Window for which the required Vulkan instance
139 * extensions should be retrieved
140 * \param [in,out] pCount pointer to an \c unsigned related to the number of
141 * required Vulkan instance extensions
142 * \param [out] pNames \c NULL or a pointer to an array to be filled with the
143 * required Vulkan instance extensions
144 *
145 * \return \c SDL_TRUE on success, \c SDL_FALSE on error.
146 *
147 * If \a pNames is \c NULL, then the number of required Vulkan instance
148 * extensions is returned in pCount. Otherwise, \a pCount must point to a
149 * variable set to the number of elements in the \a pNames array, and on
150 * return the variable is overwritten with the number of names actually
151 * written to \a pNames. If \a pCount is less than the number of required
152 * extensions, at most \a pCount structures will be written. If \a pCount
153 * is smaller than the number of required extensions, \c SDL_FALSE will be
154 * returned instead of \c SDL_TRUE, to indicate that not all the required
155 * extensions were returned.
156 *
157 * \note If \c window is not NULL, it will be checked against its creation
158 * flags to ensure that the Vulkan flag is present. This parameter
159 * will be removed in a future major release.
160 *
161 * \note The returned list of extensions will contain \c VK_KHR_surface
162 * and zero or more platform specific extensions
163 *
164 * \note The extension names queried here must be enabled when calling
165 * VkCreateInstance, otherwise surface creation will fail.
166 *
167 * \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag
168 * or be \c NULL
169 *
170 * \code
171 * unsigned int count;
172 * // get count of required extensions
173 * if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
174 * handle_error();
175 *
176 * static const char *const additionalExtensions[] =
177 * {
178 * VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
179 * };
180 * size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
181 * size_t extensionCount = count + additionalExtensionsCount;
182 * const char **names = malloc(sizeof(const char *) * extensionCount);
183 * if(!names)
184 * handle_error();
185 *
186 * // get names of required extensions
187 * if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, names))
188 * handle_error();
189 *
190 * // copy additional extensions after required extensions
191 * for(size_t i = 0; i < additionalExtensionsCount; i++)
192 * names[i + count] = additionalExtensions[i];
193 *
194 * VkInstanceCreateInfo instanceCreateInfo = {};
195 * instanceCreateInfo.enabledExtensionCount = extensionCount;
196 * instanceCreateInfo.ppEnabledExtensionNames = names;
197 * // fill in rest of instanceCreateInfo
198 *
199 * VkInstance instance;
200 * // create the Vulkan instance
201 * VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
202 * free(names);
203 * \endcode
204 *
205 * \sa SDL_Vulkan_CreateSurface()
131 * Get the names of the Vulkan instance extensions needed to create a surface
132 * with SDL_Vulkan_CreateSurface.
133 *
134 * If `pNames` is NULL, then the number of required Vulkan instance extensions
135 * is returned in `pCount`. Otherwise, `pCount` must point to a variable set
136 * to the number of elements in the `pNames` array, and on return the variable
137 * is overwritten with the number of names actually written to `pNames`. If
138 * `pCount` is less than the number of required extensions, at most `pCount`
139 * structures will be written. If `pCount` is smaller than the number of
140 * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
141 * indicate that not all the required extensions were returned.
142 *
143 * The `window` parameter is currently needed to be valid as of SDL 2.0.8,
144 * however, this parameter will likely be removed in future releases
145 *
146 * \param window A window for which the required Vulkan instance extensions
147 * should be retrieved (will be deprecated in a future release)
148 * \param pCount A pointer to an unsigned int corresponding to the number of
149 * extensions to be returned
150 * \param pNames NULL or a pointer to an array to be filled with required
151 * Vulkan instance extensions
152 * \returns SDL_TRUE on success, SDL_FALSE on error.
153 *
154 * \since This function is available in SDL 2.0.8
155 *
156 * \sa SDL_Vulkan_CreateSurface
206 157 */ */
207 158 extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window, extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window,
208 159 unsigned int *pCount, unsigned int *pCount,
209 160 const char **pNames); const char **pNames);
210 161
211 162 /** /**
212 * \brief Create a Vulkan rendering surface for a window.
213 *
214 * \param [in] window SDL_Window to which to attach the rendering surface.
215 * \param [in] instance handle to the Vulkan instance to use.
216 * \param [out] surface pointer to a VkSurfaceKHR handle to receive the
217 * handle of the newly created surface.
218 *
219 * \return \c SDL_TRUE on success, \c SDL_FALSE on error.
163 * Create a Vulkan rendering surface for a window.
220 164 * *
221 * \code
222 * VkInstance instance;
223 * SDL_Window *window;
165 * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
166 * `instance` must have been created with extensions returned by
167 * SDL_Vulkan_GetInstanceExtensions() enabled.
224 168 * *
225 * // create instance and window
169 * \param window The window to which to attach the Vulkan surface
170 * \param instance The Vulkan instance handle
171 * \param surface A pointer to a VkSurfaceKHR handle to output the newly
172 * created surface
173 * \returns SDL_TRUE on success, SDL_FALSE on error.
226 174 * *
227 * // create the Vulkan surface
228 * VkSurfaceKHR surface;
229 * if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
230 * handle_error();
231 * \endcode
175 * \since This function is available in SDL 2.0.8
232 176 * *
233 * \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
234 *
235 * \note \a instance should have been created with the extensions returned
236 * by \c SDL_Vulkan_CreateSurface() enabled.
237 *
238 * \sa SDL_Vulkan_GetInstanceExtensions()
177 * \sa SDL_Vulkan_GetInstanceExtensions
178 * \sa SDL_Vulkan_GetDrawableSize
239 179 */ */
240 180 extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
241 181 VkInstance instance, VkInstance instance,
242 182 VkSurfaceKHR* surface); VkSurfaceKHR* surface);
243 183
244 184 /** /**
245 * \brief Get the size of a window's underlying drawable in pixels (for use
246 * with setting viewport, scissor & etc).
247 *
248 * \param window SDL_Window from which the drawable size should be queried
249 * \param w Pointer to variable for storing the width in pixels,
250 * may be NULL
251 * \param h Pointer to variable for storing the height in pixels,
252 * may be NULL
185 * Get the size of the window's underlying drawable dimensions in pixels.
253 186 * *
254 187 * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
255 * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
256 * platform with high-DPI support (Apple calls this "Retina"), and not disabled
257 * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
188 * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
189 * platform with high-DPI support (Apple calls this "Retina"), and not
190 * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
191 *
192 * \param window an SDL_Window for which the size is to be queried
193 * \param w Pointer to the variable to write the width to or NULL
194 * \param h Pointer to the variable to write the height to or NULL
258 195 * *
259 * \note On macOS high-DPI support must be enabled for an application by
260 * setting NSHighResolutionCapable to true in its Info.plist.
196 * \since This function is available in SDL 2.0.8
261 197 * *
262 * \sa SDL_GetWindowSize()
263 * \sa SDL_CreateWindow()
198 * \sa SDL_GetWindowSize
199 * \sa SDL_CreateWindow
200 * \sa SDL_Vulkan_CreateSurface
264 201 */ */
265 202 extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window, extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
266 203 int *w, int *h); int *w, int *h);
File include/SDL2/begin_code.h changed (mode: 100644) (index 1ca40cc..37bf975)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
File include/SDL2/close_code.h changed (mode: 100644) (index 6aa411b..c65a216)
1 1 /* /*
2 2 Simple DirectMedia Layer Simple DirectMedia Layer
3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
4 4
5 5 This software is provided 'as-is', without any express or implied This software is provided 'as-is', without any express or implied
6 6 warranty. In no event will the authors be held liable for any damages warranty. In no event will the authors be held liable for any damages
Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/mse/ConfectionerEngine

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/mse/ConfectionerEngine

Clone this repository using git:
git clone git://git.rocketgit.com/user/mse/ConfectionerEngine

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main