···17## The wiki and headers share the same text.
1819There is a massive Perl script (`build-scripts/wikiheaders.pl`, hereafter
20-refered to as "wikiheaders") that can read both the wiki and the public
21headers, and move changes in one across to the other.
2223If you prefer to use the wiki, go ahead and edit there. If you prefer to use
···17## The wiki and headers share the same text.
1819There is a massive Perl script (`build-scripts/wikiheaders.pl`, hereafter
20+referred to as "wikiheaders") that can read both the wiki and the public
21headers, and move changes in one across to the other.
2223If you prefer to use the wiki, go ahead and edit there. If you prefer to use
+1-1
docs/README-emscripten.md
···110getting started.
111112There's a lot of little details that are beyond the scope of this
113-document, but that's the biggest intial set of hurdles to porting
114your app to the web.
115116
···110getting started.
111112There's a lot of little details that are beyond the scope of this
113+document, but that's the biggest initial set of hurdles to porting
114your app to the web.
115116
+1-1
docs/README-gdk.md
···151* For Xbox Series consoles, use the Gaming.Xbox.Scarlett.x64 target
152* The Xbox One target sets the `SDL_PLATFORM_XBOXONE` define and the Xbox Series target sets the `SDL_PLATFORM_XBOXSERIES` define
153* You don't need to link against the Xbox.Services Thunks lib nor include that dll in your package (it doesn't exist for Xbox)
154-* The shader blobs for Xbox are created in a pre-build step for the Xbox targets, rather than included in the source (due to NDA and version compatability reasons)
155* To create a package, use:
156 `makepkg pack /f PackageLayout.xml /lt /d . /pd Package`
157* To install the package, use:
···151* For Xbox Series consoles, use the Gaming.Xbox.Scarlett.x64 target
152* The Xbox One target sets the `SDL_PLATFORM_XBOXONE` define and the Xbox Series target sets the `SDL_PLATFORM_XBOXSERIES` define
153* You don't need to link against the Xbox.Services Thunks lib nor include that dll in your package (it doesn't exist for Xbox)
154+* The shader blobs for Xbox are created in a pre-build step for the Xbox targets, rather than included in the source (due to NDA and version compatibility reasons)
155* To create a package, use:
156 `makepkg pack /f PackageLayout.xml /lt /d . /pd Package`
157* To install the package, use:
+2-2
docs/README-migration.md
···7071SDL3 will not implicitly initialize the audio subsystem on your behalf if you open a device without doing so. Please explicitly call SDL_Init(SDL_INIT_AUDIO) at some point.
7273-SDL2 refered to audio devices that record sound as "capture" devices, and ones that play sound to speakers as "output" devices. In SDL3, we've changed this terminology to be "recording" devices and "playback" devices, which we hope is more clear.
7475SDL3's audio subsystem offers an enormous amount of power over SDL2, but if you just want a simple migration of your existing code, you can ignore most of it. The simplest migration path from SDL2 looks something like this:
76···1918* SDL_RestoreWindow() (SDL_EVENT_WINDOW_RESTORED)
1919* SDL_SetWindowFullscreen() (SDL_EVENT_WINDOW_ENTER_FULLSCREEN / SDL_EVENT_WINDOW_LEAVE_FULLSCREEN)
19201921-If it is required that operations be applied immediately after one of the preceeding calls, the `SDL_SyncWindow()` function
1922will attempt to wait until all pending window operations have completed. The `SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS` hint
1923can also be set to automatically synchronize after all calls to an asynchronous window operation, mimicking the behavior
1924of SDL 2. Be aware that synchronizing can potentially block for long periods of time, as it may have to wait for window
···7071SDL3 will not implicitly initialize the audio subsystem on your behalf if you open a device without doing so. Please explicitly call SDL_Init(SDL_INIT_AUDIO) at some point.
7273+SDL2 referred to audio devices that record sound as "capture" devices, and ones that play sound to speakers as "output" devices. In SDL3, we've changed this terminology to be "recording" devices and "playback" devices, which we hope is more clear.
7475SDL3's audio subsystem offers an enormous amount of power over SDL2, but if you just want a simple migration of your existing code, you can ignore most of it. The simplest migration path from SDL2 looks something like this:
76···1918* SDL_RestoreWindow() (SDL_EVENT_WINDOW_RESTORED)
1919* SDL_SetWindowFullscreen() (SDL_EVENT_WINDOW_ENTER_FULLSCREEN / SDL_EVENT_WINDOW_LEAVE_FULLSCREEN)
19201921+If it is required that operations be applied immediately after one of the preceding calls, the `SDL_SyncWindow()` function
1922will attempt to wait until all pending window operations have completed. The `SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS` hint
1923can also be set to automatically synchronize after all calls to an asynchronous window operation, mimicking the behavior
1924of SDL 2. Be aware that synchronizing can potentially block for long periods of time, as it may have to wait for window
+1-1
docs/README-ps2.md
···31```
32For a release binary is recommendable to reset the IOP always.
3334-Remember to do a clean compilation everytime you enable or disable the `SDL_PS2_SKIP_IOP_RESET` otherwise the change won't be reflected.
3536## Getting PS2 Dev
37[Installing PS2 Dev](https://github.com/ps2dev/ps2dev)
···31```
32For a release binary is recommendable to reset the IOP always.
3334+Remember to do a clean compilation every time you enable or disable the `SDL_PS2_SKIP_IOP_RESET` otherwise the change won't be reflected.
3536## Getting PS2 Dev
37[Installing PS2 Dev](https://github.com/ps2dev/ps2dev)
+1-1
include/SDL3/SDL_camera.h
···249 * Get the position of the camera in relation to the system.
250 *
251 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
252- * often make a distiction between cameras on the front of the device (that
253 * points towards the user, for taking "selfies") and cameras on the back (for
254 * filming in the direction the user is facing).
255 *
···249 * Get the position of the camera in relation to the system.
250 *
251 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
252+ * often make a distinction between cameras on the front of the device (that
253 * points towards the user, for taking "selfies") and cameras on the back (for
254 * filming in the direction the user is facing).
255 *
+7-7
include/SDL3/SDL_dialog.h
···68 *
69 * If `filelist` is:
70 *
71- * - NULL, an error occured. Details can be obtained with SDL_GetError().
72 * - A pointer to NULL, the user either didn't choose any file or canceled the
73 * dialog.
74 * - A pointer to non-`NULL`, the user chose one or more files. The argument
···105 *
106 * The callback will be invoked with a null-terminated list of files the user
107 * chose. The list will be empty if the user canceled the dialog, and it will
108- * be NULL if an error occured.
109 *
110 * Note that the callback may be called from a different thread than the one
111 * the function was invoked on.
···122 * error occurs. The first argument is a null-terminated list
123 * of C strings, representing the paths chosen by the user.
124 * The list will be empty if the user canceled the dialog, and
125- * it will be NULL if an error occured. If an error occured,
126 * it can be fetched with SDL_GetError(). The second argument
127 * is the userdata pointer passed to the function. The third
128 * argument is the index of the filter selected by the user,
···163 *
164 * The callback will be invoked with a null-terminated list of files the user
165 * chose. The list will be empty if the user canceled the dialog, and it will
166- * be NULL if an error occured.
167 *
168 * Note that the callback may be called from a different thread than the one
169 * the function was invoked on.
···179 * error occurs. The first argument is a null-terminated list
180 * of C strings, representing the paths chosen by the user.
181 * The list will be empty if the user canceled the dialog, and
182- * it will be NULL if an error occured. If an error occured,
183 * it can be fetched with SDL_GetError(). The second argument
184 * is the userdata pointer passed to the function. The third
185 * argument is the index of the filter selected by the user,
···217 *
218 * The callback will be invoked with a null-terminated list of files the user
219 * chose. The list will be empty if the user canceled the dialog, and it will
220- * be NULL if an error occured.
221 *
222 * Note that the callback may be called from a different thread than the one
223 * the function was invoked on.
···234 * error occurs. The first argument is a null-terminated list
235 * of C strings, representing the paths chosen by the user.
236 * The list will be empty if the user canceled the dialog, and
237- * it will be NULL if an error occured. If an error occured,
238 * it can be fetched with SDL_GetError(). The second argument
239 * is the userdata pointer passed to the function. The third
240 * argument is always -1 for SDL_ShowOpenFolderDialog.
···68 *
69 * If `filelist` is:
70 *
71+ * - NULL, an error occurred. Details can be obtained with SDL_GetError().
72 * - A pointer to NULL, the user either didn't choose any file or canceled the
73 * dialog.
74 * - A pointer to non-`NULL`, the user chose one or more files. The argument
···105 *
106 * The callback will be invoked with a null-terminated list of files the user
107 * chose. The list will be empty if the user canceled the dialog, and it will
108+ * be NULL if an error occurred.
109 *
110 * Note that the callback may be called from a different thread than the one
111 * the function was invoked on.
···122 * error occurs. The first argument is a null-terminated list
123 * of C strings, representing the paths chosen by the user.
124 * The list will be empty if the user canceled the dialog, and
125+ * it will be NULL if an error occurred. If an error occurred,
126 * it can be fetched with SDL_GetError(). The second argument
127 * is the userdata pointer passed to the function. The third
128 * argument is the index of the filter selected by the user,
···163 *
164 * The callback will be invoked with a null-terminated list of files the user
165 * chose. The list will be empty if the user canceled the dialog, and it will
166+ * be NULL if an error occurred.
167 *
168 * Note that the callback may be called from a different thread than the one
169 * the function was invoked on.
···179 * error occurs. The first argument is a null-terminated list
180 * of C strings, representing the paths chosen by the user.
181 * The list will be empty if the user canceled the dialog, and
182+ * it will be NULL if an error occurred. If an error occurred,
183 * it can be fetched with SDL_GetError(). The second argument
184 * is the userdata pointer passed to the function. The third
185 * argument is the index of the filter selected by the user,
···217 *
218 * The callback will be invoked with a null-terminated list of files the user
219 * chose. The list will be empty if the user canceled the dialog, and it will
220+ * be NULL if an error occurred.
221 *
222 * Note that the callback may be called from a different thread than the one
223 * the function was invoked on.
···234 * error occurs. The first argument is a null-terminated list
235 * of C strings, representing the paths chosen by the user.
236 * The list will be empty if the user canceled the dialog, and
237+ * it will be NULL if an error occurred. If an error occurred,
238 * it can be fetched with SDL_GetError(). The second argument
239 * is the userdata pointer passed to the function. The third
240 * argument is always -1 for SDL_ShowOpenFolderDialog.
+3-3
include/SDL3/SDL_hints.h
···327 * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might
328 * require of the app), they can specify it.
329 *
330- * SDL will try to accomodate this value, but there is no promise you'll get
331 * the buffer size requested. Many platforms won't honor this request at all,
332 * or might adjust it.
333 *
···1050#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED"
10511052/**
1053- * A variable containing a list of devices that should not be considerd
1054 * joysticks.
1055 *
1056 * The format of the string is a comma separated list of USB VID/PID pairs in
···2590 *
2591 * The variable can be set to the following values:
2592 *
2593- * - "0": Use the prefered OS device. (default)
2594 * - "1": Select a low power device.
2595 *
2596 * This hint should be set before creating a renderer.
···327 * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might
328 * require of the app), they can specify it.
329 *
330+ * SDL will try to accommodate this value, but there is no promise you'll get
331 * the buffer size requested. Many platforms won't honor this request at all,
332 * or might adjust it.
333 *
···1050#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED"
10511052/**
1053+ * A variable containing a list of devices that should not be considered
1054 * joysticks.
1055 *
1056 * The format of the string is a comma separated list of USB VID/PID pairs in
···2590 *
2591 * The variable can be set to the following values:
2592 *
2593+ * - "0": Use the preferred OS device. (default)
2594 * - "1": Select a low power device.
2595 *
2596 * This hint should be set before creating a renderer.
+1-1
include/SDL3/SDL_keycode.h
···314#define SDL_KMOD_NUM 0x1000u /**< the Num Lock key (may be located on an extended keypad) is down. */
315#define SDL_KMOD_CAPS 0x2000u /**< the Caps Lock key is down. */
316#define SDL_KMOD_MODE 0x4000u /**< the !AltGr key is down. */
317-#define SDL_KMOD_SCROLL 0x8000u /**< the Scoll Lock key is down. */
318#define SDL_KMOD_CTRL (SDL_KMOD_LCTRL | SDL_KMOD_RCTRL) /**< Any Ctrl key is down. */
319#define SDL_KMOD_SHIFT (SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT) /**< Any Shift key is down. */
320#define SDL_KMOD_ALT (SDL_KMOD_LALT | SDL_KMOD_RALT) /**< Any Alt key is down. */
···314#define SDL_KMOD_NUM 0x1000u /**< the Num Lock key (may be located on an extended keypad) is down. */
315#define SDL_KMOD_CAPS 0x2000u /**< the Caps Lock key is down. */
316#define SDL_KMOD_MODE 0x4000u /**< the !AltGr key is down. */
317+#define SDL_KMOD_SCROLL 0x8000u /**< the Scroll Lock key is down. */
318#define SDL_KMOD_CTRL (SDL_KMOD_LCTRL | SDL_KMOD_RCTRL) /**< Any Ctrl key is down. */
319#define SDL_KMOD_SHIFT (SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT) /**< Any Shift key is down. */
320#define SDL_KMOD_ALT (SDL_KMOD_LALT | SDL_KMOD_RALT) /**< Any Alt key is down. */
+1-1
src/audio/SDL_audiocvt.c
···49 *
50 * These are listed in the order they are laid out in
51 * memory, so "FL+FR" means "the front left speaker is
52- * layed out in memory first, then the front right, then
53 * it repeats for the next audio frame".
54 *
55 * 1 channel (mono) layout: FRONT
···49 *
50 * These are listed in the order they are laid out in
51 * memory, so "FL+FR" means "the front left speaker is
52+ * laid out in memory first, then the front right, then
53 * it repeats for the next audio frame".
54 *
55 * 1 channel (mono) layout: FRONT
···362 }
363364 // we currently ignore stream_flags format changes, but my _hope_ is that IMFSourceReader is handling this and
365- // will continue to give us the explictly-specified format we requested when opening the device, though, and
366 // we don't have to manually deal with it.
367368 if (sample != NULL) {
···362 }
363364 // we currently ignore stream_flags format changes, but my _hope_ is that IMFSourceReader is handling this and
365+ // will continue to give us the explicitly-specified format we requested when opening the device, though, and
366 // we don't have to manually deal with it.
367368 if (sample != NULL) {
+1-1
src/hidapi/linux/hid.c
···291 * Skips all nested Collection, i.e. iterates until the end of current level Collection.
292 *
293 * The return value is non-0 when an end of current Collection is found,
294- * 0 when error is occured (broken Descriptor, end of a Collection is found before its begin,
295 * or no Collection is found at all).
296 */
297static int hid_iterate_over_collection(const __u8 *report_descriptor, __u32 size, unsigned int *pos, int *data_len, int *key_size)
···291 * Skips all nested Collection, i.e. iterates until the end of current level Collection.
292 *
293 * The return value is non-0 when an end of current Collection is found,
294+ * 0 when error is occurred (broken Descriptor, end of a Collection is found before its begin,
295 * or no Collection is found at all).
296 */
297static int hid_iterate_over_collection(const __u8 *report_descriptor, __u32 size, unsigned int *pos, int *data_len, int *key_size)
+1-1
src/hidapi/netbsd/hid.c
···234 * Skips all nested Collection, i.e. iterates until the end of current level Collection.
235 *
236 * The return value is non-0 when an end of current Collection is found,
237- * 0 when error is occured (broken Descriptor, end of a Collection is found before its begin,
238 * or no Collection is found at all).
239 */
240static int hid_iterate_over_collection(const uint8_t *report_descriptor, uint32_t size, unsigned int *pos, int *data_len, int *key_size)
···234 * Skips all nested Collection, i.e. iterates until the end of current level Collection.
235 *
236 * The return value is non-0 when an end of current Collection is found,
237+ * 0 when error is occurred (broken Descriptor, end of a Collection is found before its begin,
238 * or no Collection is found at all).
239 */
240static int hid_iterate_over_collection(const uint8_t *report_descriptor, uint32_t size, unsigned int *pos, int *data_len, int *key_size)
+1-1
src/joystick/hidapi/steam/controller_structs.h
···158// message types within ValveInReport_t or the header itself. Hopefully this should
159// be super rare and instead you should just add new message payloads to the union,
160// or just add fields to the end of existing payload structs which is expected to be
161-// safe in all code consuming these as they should just consume/copy upto the prior size
162// they were aware of when processing.
163#define k_ValveInReportMsgVersion 0x01
164
···158// message types within ValveInReport_t or the header itself. Hopefully this should
159// be super rare and instead you should just add new message payloads to the union,
160// or just add fields to the end of existing payload structs which is expected to be
161+// safe in all code consuming these as they should just consume/copy up to the prior size
162// they were aware of when processing.
163#define k_ValveInReportMsgVersion 0x01
164
+3-3
src/stdlib/SDL_malloc.c
···42764277void dlfree(void* mem) {
4278 /*
4279- Consolidate freed chunks with preceeding or succeeding bordering
4280 free chunks, if they exist, and then place in a bin. Intermixed
4281 with special cases for top, dv, mmapped chunks, and usage errors.
4282 */
···5113 Wolfram Gloger (Gloger@lrz.uni-muenchen.de).
5114 * Use last_remainder in more cases.
5115 * Pack bins using idea from colin@nyx10.cs.du.edu
5116- * Use ordered bins instead of best-fit threshhold
5117 * Eliminate block-local decls to simplify tracing and debugging.
5118 * Support another case of realloc via move into top
5119- * Fix error occuring when initial sbrk_base not word-aligned.
5120 * Rely on page size for units instead of SBRK_UNIT to
5121 avoid surprises about sbrk alignment conventions.
5122 * Add mallinfo, mallopt. Thanks to Raymond Nijssen
···42764277void dlfree(void* mem) {
4278 /*
4279+ Consolidate freed chunks with preceding or succeeding bordering
4280 free chunks, if they exist, and then place in a bin. Intermixed
4281 with special cases for top, dv, mmapped chunks, and usage errors.
4282 */
···5113 Wolfram Gloger (Gloger@lrz.uni-muenchen.de).
5114 * Use last_remainder in more cases.
5115 * Pack bins using idea from colin@nyx10.cs.du.edu
5116+ * Use ordered bins instead of best-fit threshold
5117 * Eliminate block-local decls to simplify tracing and debugging.
5118 * Support another case of realloc via move into top
5119+ * Fix error occurring when initial sbrk_base not word-aligned.
5120 * Rely on page size for units instead of SBRK_UNIT to
5121 avoid surprises about sbrk alignment conventions.
5122 * Add mallinfo, mallopt. Thanks to Raymond Nijssen
+1-1
src/video/SDL_video.c
···3428 const int ret = _this->SetWindowModalFor(_this, modal_window, parent_window);
34293430 /* The existing parent might be needed when changing the modal status,
3431- * so don't change the heirarchy until after setting the new modal state.
3432 */
3433 if (!ret) {
3434 SDL_SetWindowParent(modal_window, !ret ? parent_window : NULL);
···3428 const int ret = _this->SetWindowModalFor(_this, modal_window, parent_window);
34293430 /* The existing parent might be needed when changing the modal status,
3431+ * so don't change the hierarchy until after setting the new modal state.
3432 */
3433 if (!ret) {
3434 SDL_SetWindowParent(modal_window, !ret ? parent_window : NULL);
+1-1
test/testautomation.c
···49 &timeTestSuite,
50 &timerTestSuite,
51 &videoTestSuite,
52- &subsystemsTestSuite, /* run last, not interfere with other test enviroment */
53 NULL
54};
55
···49 &timeTestSuite,
50 &timerTestSuite,
51 &videoTestSuite,
52+ &subsystemsTestSuite, /* run last, not interfere with other test environment */
53 NULL
54};
55