Sync SDL3 wiki -> header

[ci skip]
This commit is contained in:
SDL Wiki Bot 2024-12-16 06:13:48 +00:00
parent 79316ca36e
commit 3fa0537565
10 changed files with 54 additions and 53 deletions

View file

@ -31,22 +31,22 @@
* *
* Several platforms will alert the user if an app tries to access a camera, * Several platforms will alert the user if an app tries to access a camera,
* and some will present a UI asking the user if your application should be * and some will present a UI asking the user if your application should be
* allowed to obtain images at all, which they can deny. A successfully * allowed to obtain images at all, which they can deny. A successfully opened
* opened camera will not provide images until permission is granted. * camera will not provide images until permission is granted. Applications,
* Applications, after opening a camera device, can see if they were granted * after opening a camera device, can see if they were granted access by
* access by either polling with the SDL_GetCameraPermissionState() function, * either polling with the SDL_GetCameraPermissionState() function, or waiting
* or waiting for an SDL_EVENT_CAMERA_DEVICE_APPROVED or * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED
* SDL_EVENT_CAMERA_DEVICE_DENIED event. Platforms that don't have any * event. Platforms that don't have any user approval process will report
* user approval process will report approval immediately. * approval immediately.
* *
* Note that SDL cameras only provide video as individual frames; they will * Note that SDL cameras only provide video as individual frames; they will
* not provide full-motion video encoded in a movie file format, although an * not provide full-motion video encoded in a movie file format, although an
* app is free to encode the acquired frames into any format it likes. It * app is free to encode the acquired frames into any format it likes. It also
* also does not provide audio from the camera hardware through this API; * does not provide audio from the camera hardware through this API; not only
* not only do many webcams not have microphones at all, many people--from * do many webcams not have microphones at all, many people--from streamers to
* streamers to people on Zoom calls--will want to use a separate microphone * people on Zoom calls--will want to use a separate microphone regardless of
* regardless of the camera. In any case, recorded audio will be available * the camera. In any case, recorded audio will be available through SDL's
* through SDL's audio API no matter what hardware provides the microphone. * audio API no matter what hardware provides the microphone.
* *
* ## Camera gotchas * ## Camera gotchas
* *

View file

@ -29,19 +29,18 @@
* *
* ## Basic use (text) * ## Basic use (text)
* *
* Obtaining and publishing simple text to the system clipboard is as easy * Obtaining and publishing simple text to the system clipboard is as easy as
* as calling SDL_GetClipboardText() and SDL_SetClipboardText(), * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively.
* respectively. These deal with C strings in UTF-8 encoding. Data * These deal with C strings in UTF-8 encoding. Data transmission and encoding
* transmission and encoding conversion is completely managed by SDL. * conversion is completely managed by SDL.
* *
* ## Clipboard callbacks (data other than text) * ## Clipboard callbacks (data other than text)
* *
* Things get more complicated when the clipboard contains something other * Things get more complicated when the clipboard contains something other
* than text. Not only can the system clipboard contain data of any type, * than text. Not only can the system clipboard contain data of any type, in
* in some cases it can contain the same data in different formats! For * some cases it can contain the same data in different formats! For example,
* example, an image painting app might let the user copy a graphic to the * an image painting app might let the user copy a graphic to the clipboard,
* clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to * and offers it in .BMP, .JPG, or .PNG format for other apps to consume.
* consume.
* *
* Obtaining clipboard data ("pasting") like this is a matter of calling * Obtaining clipboard data ("pasting") like this is a matter of calling
* SDL_GetClipboardData() and telling it the mimetype of the data you want. * SDL_GetClipboardData() and telling it the mimetype of the data you want.
@ -56,9 +55,9 @@
* rather the mimetypes it is willing to provide and a callback function. * rather the mimetypes it is willing to provide and a callback function.
* During the callback, the app will generate the data. This allows massive * During the callback, the app will generate the data. This allows massive
* data sets to be provided to the clipboard, without any data being copied * data sets to be provided to the clipboard, without any data being copied
* before it is explicitly requested. More specifically, it allows an app * before it is explicitly requested. More specifically, it allows an app to
* to offer data in multiple formats without providing a copy of all of * offer data in multiple formats without providing a copy of all of them
* them upfront. If the app has an image that it could provide in PNG or JPG * upfront. If the app has an image that it could provide in PNG or JPG
* format, it doesn't have to encode it to either of those unless and until * format, it doesn't have to encode it to either of those unless and until
* something tries to paste it. * something tries to paste it.
* *
@ -67,11 +66,11 @@
* The X11 and Wayland video targets have a concept of the "primary selection" * The X11 and Wayland video targets have a concept of the "primary selection"
* in addition to the usual clipboard. This is generally highlighted (but not * in addition to the usual clipboard. This is generally highlighted (but not
* explicitly copied) text from various apps. SDL offers APIs for this through * explicitly copied) text from various apps. SDL offers APIs for this through
* SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers
* SDL offers these APIs on platforms without this concept, too, but only so * these APIs on platforms without this concept, too, but only so far that it
* far that it will keep a copy of a string that the app sets for later * will keep a copy of a string that the app sets for later retrieval; the
* retrieval; the operating system will not ever attempt to change the * operating system will not ever attempt to change the string externally if
* string externally if it doesn't support a primary selection. * it doesn't support a primary selection.
*/ */
#ifndef SDL_clipboard_h_ #ifndef SDL_clipboard_h_

View file

@ -33,7 +33,8 @@
* CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are
* available on all platforms, even if they don't make sense (an ARM processor * available on all platforms, even if they don't make sense (an ARM processor
* will never have SSE and an x86 processor will never have NEON, for example, * will never have SSE and an x86 processor will never have NEON, for example,
* but these functions still exist and will simply return false in these cases). * but these functions still exist and will simply return false in these
* cases).
*/ */
#ifndef SDL_cpuinfo_h_ #ifndef SDL_cpuinfo_h_

View file

@ -28,13 +28,14 @@
* SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's
* native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE,
* SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the
* latter case, the functionality is provided by macros that become no-ops * latter case, the functionality is provided by macros that become no-ops if
* if a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
* does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC
* processor (bigendian), the macros behavior is reversed. * processor (bigendian), the macros behavior is reversed.
* *
* The swap routines are inline functions, and attempt to use compiler * The swap routines are inline functions, and attempt to use compiler
* intrinsics, inline assembly, and other magic to make byteswapping efficient. * intrinsics, inline assembly, and other magic to make byteswapping
* efficient.
*/ */
#ifndef SDL_endian_h_ #ifndef SDL_endian_h_

View file

@ -25,9 +25,9 @@
* Event queue management. * Event queue management.
* *
* It's extremely common--often required--that an app deal with SDL's event * It's extremely common--often required--that an app deal with SDL's event
* queue. Almost all useful information about interactions with the real * queue. Almost all useful information about interactions with the real world
* world flow through here: the user interacting with the computer and app, * flow through here: the user interacting with the computer and app, hardware
* hardware coming and going, the system changing in some way, etc. * coming and going, the system changing in some way, etc.
* *
* An app generally takes a moment, perhaps at the start of a new frame, to * An app generally takes a moment, perhaps at the start of a new frame, to
* examine any events that have occured since the last time and process or * examine any events that have occured since the last time and process or
@ -43,10 +43,10 @@
* beneficial for certain types of programs on low-power hardware. One may * beneficial for certain types of programs on low-power hardware. One may
* also call SDL_AddEventWatch() to set a callback when new events arrive. * also call SDL_AddEventWatch() to set a callback when new events arrive.
* *
* The app is free to generate their own events, too: SDL_PushEvent allows * The app is free to generate their own events, too: SDL_PushEvent allows the
* the app to put events onto the queue for later retrieval; * app to put events onto the queue for later retrieval; SDL_RegisterEvents
* SDL_RegisterEvents can guarantee that these events have a type that isn't * can guarantee that these events have a type that isn't in use by other
* in use by other parts of the system. * parts of the system.
*/ */
#ifndef SDL_events_h_ #ifndef SDL_events_h_

View file

@ -25,8 +25,8 @@
* SDL joystick support. * SDL joystick support.
* *
* This is the lower-level joystick handling. If you want the simpler option, * This is the lower-level joystick handling. If you want the simpler option,
* where what each button does is well-defined, you should use the gamepad * where what each button does is well-defined, you should use the gamepad API
* API instead. * instead.
* *
* The term "instance_id" is the current instantiation of a joystick device in * The term "instance_id" is the current instantiation of a joystick device in
* the system, if the joystick is removed and then re-inserted then it will * the system, if the joystick is removed and then re-inserted then it will

View file

@ -24,8 +24,8 @@
* *
* Defines constants which identify keyboard keys and modifiers. * Defines constants which identify keyboard keys and modifiers.
* *
* Please refer to the Best Keyboard Practices document for * Please refer to the Best Keyboard Practices document for details on what
* details on what this information means and how best to use it. * this information means and how best to use it.
* *
* https://wiki.libsdl.org/SDL3/BestKeyboardPractices * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/ */

View file

@ -49,8 +49,8 @@
* - Once a library is unloaded, all pointers into it obtained through * - Once a library is unloaded, all pointers into it obtained through
* SDL_LoadFunction() become invalid, even if the library is later reloaded. * SDL_LoadFunction() become invalid, even if the library is later reloaded.
* Don't unload a library if you plan to use these pointers in the future. * Don't unload a library if you plan to use these pointers in the future.
* Notably: beware of giving one of these pointers to atexit(), since it * Notably: beware of giving one of these pointers to atexit(), since it may
* may call that pointer after the library unloads. * call that pointer after the library unloads.
*/ */
#ifndef SDL_loadso_h_ #ifndef SDL_loadso_h_

View file

@ -35,12 +35,12 @@
* *
* SDL will take care of platform specific details on how it gets called. * SDL will take care of platform specific details on how it gets called.
* *
* This is also where an app can be configured to use the main callbacks, * This is also where an app can be configured to use the main callbacks, via
* via the SDL_MAIN_USE_CALLBACKS macro. * the SDL_MAIN_USE_CALLBACKS macro.
* *
* This is a "single-header library," which is to say that including this * This is a "single-header library," which is to say that including this
* header inserts code into your program, and you should only include it * header inserts code into your program, and you should only include it once
* once in most cases. SDL.h does not include this header automatically. * in most cases. SDL.h does not include this header automatically.
* *
* For more information, see: * For more information, see:
* *

View file

@ -24,8 +24,8 @@
* *
* Defines keyboard scancodes. * Defines keyboard scancodes.
* *
* Please refer to the Best Keyboard Practices document for * Please refer to the Best Keyboard Practices document for details on what
* details on what this information means and how best to use it. * this information means and how best to use it.
* *
* https://wiki.libsdl.org/SDL3/BestKeyboardPractices * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/ */