Merge commit 'b22c6238d5eb65ced42808ec326aae75d0d5c9ed' into back-to-imgui

This commit is contained in:
irisz64
2025-06-26 22:23:47 +02:00
317 changed files with 18074 additions and 2718 deletions

View File

@@ -132,7 +132,7 @@ extern "C" {
#define SDL_TriggerBreakpoint() __debugbreak()
#elif defined(_MSC_VER) && defined(_M_IX86)
#define SDL_TriggerBreakpoint() { _asm { int 0x03 } }
#elif defined(ANDROID)
#elif defined(ANDROID) || defined(__SYMBIAN32__)
#include <assert.h>
#define SDL_TriggerBreakpoint() assert(0)
#elif SDL_HAS_BUILTIN(__builtin_debugtrap)

View File

@@ -1021,7 +1021,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
/**
* Query an audio stream for its currently-bound device.
*
* This reports the audio device that an audio stream is currently bound to.
* This reports the logical audio device that an audio stream is currently
* bound to.
*
* If not bound, or invalid, this returns zero, which is not a valid device
* ID.
@@ -1063,6 +1064,17 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au
/**
* Get the properties associated with an audio stream.
*
* The application can hang any data it wants here, but the following
* properties are understood by SDL:
*
* - `SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN`: if true (the default), the
* stream be automatically cleaned up when the audio subsystem quits. If set
* to false, the streams will persist beyond that. This property is ignored
* for streams created through SDL_OpenAudioDeviceStream(), and will always
* be cleaned up. Streams that are not cleaned up will still be unbound from
* devices when the audio subsystem quits. This property was added in SDL
* 3.4.0.
*
* \param stream the SDL_AudioStream to query.
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
@@ -1073,6 +1085,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au
*/
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);
#define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN "SDL.audiostream.auto_cleanup"
/**
* Query the current format of an audio stream.
*
@@ -1149,14 +1164,14 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
*
* The frequency ratio is used to adjust the rate at which input data is
* consumed. Changing this effectively modifies the speed and pitch of the
* audio. A value greater than 1.0 will play the audio faster, and at a higher
* pitch. A value less than 1.0 will play the audio slower, and at a lower
* pitch.
* audio. A value greater than 1.0f will play the audio faster, and at a
* higher pitch. A value less than 1.0f will play the audio slower, and at a
* lower pitch. 1.0f means play at normal speed.
*
* This is applied during SDL_GetAudioStreamData, and can be continuously
* changed to create various effects.
*
* \param stream the stream the frequency ratio is being changed.
* \param stream the stream on which the frequency ratio is being changed.
* \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100.
* \returns true on success or false on failure; call SDL_GetError() for more
@@ -1332,7 +1347,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStre
* Channel maps are optional; most things do not need them, instead passing
* data in the [order that SDL expects](CategoryAudio#channel-layouts).
*
* The output channel map reorders data that leaving a stream via
* The output channel map reorders data that is leaving a stream via
* SDL_GetAudioStreamData.
*
* Each item in the array represents an input channel, and its value is the
@@ -1414,6 +1429,136 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStr
*/
extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
/**
* A callback that fires for completed SDL_PutAudioStreamDataNoCopy() data.
*
* When using SDL_PutAudioStreamDataNoCopy() to provide data to an
* SDL_AudioStream, it's not safe to dispose of the data until the stream has
* completely consumed it. Often times it's difficult to know exactly when
* this has happened.
*
* This callback fires once when the stream no longer needs the buffer,
* allowing the app to easily free or reuse it.
*
* \param userdata an opaque pointer provided by the app for their personal
* use.
* \param buf the pointer provided to SDL_PutAudioStreamDataNoCopy().
* \param buflen the size of buffer, in bytes, provided to
* SDL_PutAudioStreamDataNoCopy().
*
* \threadsafety This callbacks may run from any thread, so if you need to
* protect shared data, you should use SDL_LockAudioStream to
* serialize access; this lock will be held before your callback
* is called, so your callback does not need to manage the lock
* explicitly.
*
* \since This datatype is available since SDL 3.4.0.
*
* \sa SDL_SetAudioStreamGetCallback
* \sa SDL_SetAudioStreamPutCallback
*/
typedef void (SDLCALL *SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen);
/**
* Add external data to an audio stream without copying it.
*
* Unlike SDL_PutAudioStreamData(), this function does not make a copy of the
* provided data, instead storing the provided pointer. This means that the
* put operation does not need to allocate and copy the data, but the original
* data must remain available until the stream is done with it, either by
* being read from the stream in its entirety, or a call to
* SDL_ClearAudioStream() or SDL_DestroyAudioStream().
*
* The data must match the format/channels/samplerate specified in the latest
* call to SDL_SetAudioStreamFormat, or the format specified when creating the
* stream if it hasn't been changed.
*
* An optional callback may be provided, which is called when the stream no
* longer needs the data. Once this callback fires, the stream will not access
* the data again. This callback will fire for any reason the data is no
* longer needed, including clearing or destroying the stream.
*
* Note that there is still an allocation to store tracking information, so
* this function is more efficient for larger blocks of data. If you're
* planning to put a few samples at a time, it will be more efficient to use
* SDL_PutAudioStreamData(), which allocates and buffers in blocks.
*
* \param stream the stream the audio data is being added to.
* \param buf a pointer to the audio data to add.
* \param len the number of bytes to add to the stream.
* \param callback the callback function to call when the data is no longer
* needed by the stream. May be NULL.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
* extra locking.
*
* \since This function is available since SDL 3.4.0.
*
* \sa SDL_ClearAudioStream
* \sa SDL_FlushAudioStream
* \sa SDL_GetAudioStreamData
* \sa SDL_GetAudioStreamQueued
*/
extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata);
/**
* Add data to the stream with each channel in a separate array.
*
* This data must match the format/channels/samplerate specified in the latest
* call to SDL_SetAudioStreamFormat, or the format specified when creating the
* stream if it hasn't been changed.
*
* The data will be interleaved and queued. Note that SDL_AudioStream only
* operates on interleaved data, so this is simply a convenience function for
* easily queueing data from sources that provide separate arrays. There is no
* equivalent function to retrieve planar data.
*
* The arrays in `channel_buffers` are ordered as they are to be interleaved;
* the first array will be the first sample in the interleaved data. Any
* individual array may be NULL; in this case, silence will be interleaved for
* that channel.
*
* `num_channels` specifies how many arrays are in `channel_buffers`. This can
* be used as a safety to prevent overflow, in case the stream format has
* changed elsewhere. If more channels are specified than the current input
* spec, they are ignored. If less channels are specified, the missing arrays
* are treated as if they are NULL (silence is written to those channels). If
* the count is -1, SDL will assume the array count matches the current input
* spec.
*
* Note that `num_samples` is the number of _samples per array_. This can also
* be thought of as the number of _sample frames_ to be queued. A value of 1
* with stereo arrays will queue two samples to the stream. This is different
* than SDL_PutAudioStreamData, which wants the size of a single array in
* bytes.
*
* \param stream the stream the audio data is being added to.
* \param channel_buffers a pointer to an array of arrays, one array per
* channel.
* \param num_channels the number of arrays in `channel_buffers` or -1.
* \param num_samples the number of _samples_ per array to write to the
* stream.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
* extra locking.
*
* \since This function is available since SDL 3.4.0.
*
* \sa SDL_ClearAudioStream
* \sa SDL_FlushAudioStream
* \sa SDL_GetAudioStreamData
* \sa SDL_GetAudioStreamQueued
*/
extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples);
/**
* Get converted/resampled data from the stream.
*
@@ -1583,8 +1728,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *str
* previously been paused. Once unpaused, any bound audio streams will begin
* to progress again, and audio can be generated.
*
* Remember, SDL_OpenAudioDeviceStream opens device in a paused state, so this
* function call is required for audio playback to begin on such device.
* SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this
* function call is required for audio playback to begin on such devices.
*
* \param stream the audio stream associated with the audio device to resume.
* \returns true on success or false on failure; call SDL_GetError() for more
@@ -1841,7 +1986,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
* Also unlike other functions, the audio device begins paused. This is to map
* more closely to SDL2-style behavior, since there is no extra step here to
* bind a stream to begin audio flowing. The audio device should be resumed
* with `SDL_ResumeAudioStreamDevice(stream);`
* with SDL_ResumeAudioStreamDevice().
*
* This function works with both playback and recording devices.
*
@@ -1887,6 +2032,85 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
*/
extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
/**
* A callback that fires around an audio device's processing work.
*
* This callback fires when a logical audio device is about to start accessing
* its bound audio streams, and fires again when it has finished accessing
* them. It covers the range of one "iteration" of the audio device.
*
* It can be useful to use this callback to update state that must apply to
* all bound audio streams atomically: to make sure state changes don't happen
* while half of the streams are already processed for the latest audio
* buffer.
*
* This callback should run as quickly as possible and not block for any
* significant time, as this callback delays submission of data to the audio
* device, which can cause audio playback problems. This callback delays all
* audio processing across a single physical audio device: all its logical
* devices and all bound audio streams. Use it carefully.
*
* \param userdata a pointer provided by the app through
* SDL_SetAudioPostmixCallback, for its own use.
* \param devid the audio device this callback is running for.
* \param start true if this is the start of the iteration, false if the end.
*
* \threadsafety This will run from a background thread owned by SDL. The
* application is responsible for locking resources the callback
* touches that need to be protected.
*
* \since This datatype is available since SDL 3.4.0.
*
* \sa SDL_SetAudioIterationCallbacks
*/
typedef void (SDLCALL *SDL_AudioIterationCallback)(void *userdata, SDL_AudioDeviceID devid, bool start);
/**
* Set callbacks that fire around a new iteration of audio device processing.
*
* Two callbacks are provided here: one that runs when a device is about to
* process its bound audio streams, and another that runs when the device has
* finished processing them.
*
* These callbacks can run at any time, and from any thread; if you need to
* serialize access to your app's data, you should provide and use a mutex or
* other synchronization device.
*
* Generally these callbacks are used to apply state that applies to multiple
* bound audio streams, with a guarantee that the audio device's thread isn't
* halfway through processing them. Generally a finer-grained lock through
* SDL_LockAudioStream() is more appropriate.
*
* The callbacks are extremely time-sensitive; the callback should do the
* least amount of work possible and return as quickly as it can. The longer
* the callback runs, the higher the risk of audio dropouts or other problems.
*
* This function will block until the audio device is in between iterations,
* so any existing callback that might be running will finish before this
* function sets the new callback and returns.
*
* Physical devices do not accept these callbacks, only logical devices
* created through SDL_OpenAudioDevice() can be.
*
* Setting a NULL callback function disables any previously-set callback.
* Either callback may be NULL, and the same callback is permitted to be used
* for both.
*
* \param devid the ID of an opened audio device.
* \param start a callback function to be called at the start of an iteration.
* Can be NULL.
* \param end a callback function to be called at the end of an iteration. Can
* be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.4.0.
*/
extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioIterationCallbacks(SDL_AudioDeviceID devid, SDL_AudioIterationCallback start, SDL_AudioIterationCallback end, void *userdata);
/**
* A callback that fires when data is about to be fed to an audio device.
*

View File

@@ -261,9 +261,9 @@
*
* On compilers without restrict support, this is defined to nothing.
*
* \since This macro is available since SDL 3.2.0.
* \since This macro is available since SDL 3.4.0.
*/
#define SDL_RESTRICT __restrict__
#define SDL_RESTRICT __restrict
/**
* Check if the compiler supports a given builtin functionality.
@@ -281,9 +281,61 @@
*/
#define SDL_HAS_BUILTIN(x) __has_builtin(x)
/**
* A macro to specify data alignment.
*
* This informs the compiler that a given datatype or variable must be aligned
* to a specific byte count.
*
* For example:
*
* ```c
* // make sure this is struct is aligned to 16 bytes for SIMD access.
* typedef struct {
* float x, y, z, w;
* } SDL_ALIGNED(16) MySIMDAlignedData;
*
* // make sure this one field in a struct is aligned to 16 bytes for SIMD access.
* typedef struct {
* SomeStuff stuff;
* float position[4] SDL_ALIGNED(16);
* SomeOtherStuff other_stuff;
* } MyStruct;
*
* // make sure this variable is aligned to 32 bytes.
* int SDL_ALIGNED(32) myval = 0;
* ```
*
* Alignment is only guaranteed for things the compiler places: local
* variables on the stack and global/static variables. To dynamically allocate
* something that respects this alignment, use SDL_aligned_alloc() or some
* other mechanism.
*
* On compilers without alignment support, this macro is defined to an invalid
* symbol, to make it clear that the current compiler is likely to generate
* incorrect code when it sees this macro.
*
* \param x the byte count to align to, so the data's address will be a
* multiple of this value.
*
* \since This macro is available since SDL 3.4.0.
*/
#define SDL_ALIGNED(x) __attribute__((aligned(x)))
/* end of wiki documentation section. */
#endif
/* `restrict` is from C99, but __restrict works with both Visual Studio and GCC. */
#ifndef SDL_RESTRICT
# if defined(restrict) || ((defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)))
# define SDL_RESTRICT restrict
# elif defined(_MSC_VER) || defined(__GNUC__) || defined(__clang__)
# define SDL_RESTRICT __restrict
# else
# define SDL_RESTRICT
# endif
#endif
#ifndef SDL_HAS_BUILTIN
#ifdef __has_builtin
#define SDL_HAS_BUILTIN(x) __has_builtin(x)
@@ -389,7 +441,7 @@
#endif /* SDL_FORCE_INLINE not defined */
#ifndef SDL_NORETURN
#ifdef __GNUC__
#if defined(__GNUC__)
#define SDL_NORETURN __attribute__((noreturn))
#elif defined(_MSC_VER)
#define SDL_NORETURN __declspec(noreturn)
@@ -484,3 +536,18 @@
#define SDL_ALLOC_SIZE2(p1, p2)
#endif
#endif /* SDL_ALLOC_SIZE2 not defined */
#ifndef SDL_ALIGNED
#if defined(__clang__) || defined(__GNUC__)
#define SDL_ALIGNED(x) __attribute__((aligned(x)))
#elif defined(_MSC_VER)
#define SDL_ALIGNED(x) __declspec(align(x))
#elif defined(__cplusplus) && (__cplusplus >= 201103L)
#define SDL_ALIGNED(x) alignas(x)
#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L)
#define SDL_ALIGNED(x) _Alignas(x)
#else
#define SDL_ALIGNED(x) PLEASE_DEFINE_SDL_ALIGNED
#endif
#endif /* SDL_ALIGNED not defined */

View File

@@ -135,7 +135,8 @@ typedef enum SDL_EventType
/* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */
SDL_EVENT_WINDOW_SHOWN = 0x202, /**< Window has been shown */
SDL_EVENT_WINDOW_HIDDEN, /**< Window has been hidden */
SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event */
SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event.
data1 is 1 for live-resize expose events, 0 otherwise. */
SDL_EVENT_WINDOW_MOVED, /**< Window has been moved to data1, data2 */
SDL_EVENT_WINDOW_RESIZED, /**< Window has been resized to data1xdata2 */
SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED,/**< The pixel size of the window has changed to data1xdata2 */
@@ -492,6 +493,8 @@ typedef struct SDL_MouseWheelEvent
SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
float mouse_x; /**< X coordinate, relative to window */
float mouse_y; /**< Y coordinate, relative to window */
Sint32 integer_x; /**< The amount scrolled horizontally, accumulated to whole scroll "ticks" (added in 3.2.12) */
Sint32 integer_y; /**< The amount scrolled vertically, accumulated to whole scroll "ticks" (added in 3.2.12) */
} SDL_MouseWheelEvent;
/**
@@ -779,7 +782,7 @@ typedef struct SDL_TouchFingerEvent
} SDL_TouchFingerEvent;
/**
* Pressure-sensitive pen proximity event structure (event.pmotion.*)
* Pressure-sensitive pen proximity event structure (event.pproximity.*)
*
* When a pen becomes visible to the system (it is close enough to a tablet,
* etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's
@@ -1565,6 +1568,38 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
*/
extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromEvent(const SDL_Event *event);
/**
* Generate a human-readable description of an event.
*
* This will fill `buf` with a null-terminated string that might look
* something like this:
*
* ```
* SDL_EVENT_MOUSE_MOTION (timestamp=1140256324 windowid=2 which=0 state=0 x=492.99 y=139.09 xrel=52 yrel=6)
* ```
*
* The exact format of the string is not guaranteed; it is intended for
* logging purposes, to be read by a human, and not parsed by a computer.
*
* The returned value follows the same rules as SDL_snprintf(): `buf` will
* always be NULL-terminated (unless `buflen` is zero), and will be truncated
* if `buflen` is too small. The return code is the number of bytes needed for
* the complete string, not counting the NULL-terminator, whether the string
* was truncated or not. Unlike SDL_snprintf(), though, this function never
* returns -1.
*
* \param event an event to describe. May be NULL.
* \param buf the buffer to fill with the description string. May be NULL.
* \param buflen the maximum bytes that can be written to `buf`.
* \returns number of bytes needed for the full string, not counting the
* null-terminator byte.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.4.0.
*/
extern SDL_DECLSPEC int SDLCALL SDL_GetEventDescription(const SDL_Event *event, char *buf, int buflen);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

View File

@@ -444,10 +444,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo
* Enumerate a directory tree, filtered by pattern, and return a list.
*
* Files are filtered out if they don't match the string in `pattern`, which
* may contain wildcard characters '\*' (match everything) and '?' (match one
* may contain wildcard characters `*` (match everything) and `?` (match one
* character). If pattern is NULL, no filtering is done and all results are
* returned. Subdirectories are permitted, and are specified with a path
* separator of '/'. Wildcard characters '\*' and '?' never match a path
* separator of `/`. Wildcard characters `*` and `?` never match a path
* separator.
*
* `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching

View File

@@ -118,6 +118,7 @@ typedef enum SDL_GamepadType
SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR,
SDL_GAMEPAD_TYPE_GAMECUBE,
SDL_GAMEPAD_TYPE_COUNT
} SDL_GamepadType;
@@ -127,8 +128,9 @@ typedef enum SDL_GamepadType
* For controllers that use a diamond pattern for the face buttons, the
* south/east/west/north buttons below correspond to the locations in the
* diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo
* Switch controllers, this would be B/A/Y/X, for PlayStation controllers this
* would be Cross/Circle/Square/Triangle.
* Switch controllers, this would be B/A/Y/X, for GameCube controllers this
* would be A/X/B/Y, for PlayStation controllers this would be
* Cross/Circle/Square/Triangle.
*
* For controllers that don't use a diamond pattern for the face buttons, the
* south/east/west/north buttons indicate the buttons labeled A, B, C, D, or

View File

@@ -206,14 +206,20 @@
* underlying graphics API. While it's possible that we have done something
* inefficiently, it's very unlikely especially if you are relatively
* inexperienced with GPU rendering. Please see the performance tips above and
* make sure you are following them. Additionally, tools like RenderDoc can be
* very helpful for diagnosing incorrect behavior and performance issues.
* make sure you are following them. Additionally, tools like
* [RenderDoc](https://renderdoc.org/)
* can be very helpful for diagnosing incorrect behavior and performance
* issues.
*
* ## System Requirements
*
* **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain
* Android devices. Requires Vulkan 1.0 with the following extensions and
* device features:
* ### Vulkan
*
* SDL driver name: "vulkan" (for use in SDL_CreateGPUDevice() and
* SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING)
*
* Supported on Windows, Linux, Nintendo Switch, and certain Android devices.
* Requires Vulkan 1.0 with the following extensions and device features:
*
* - `VK_KHR_swapchain`
* - `VK_KHR_maintenance1`
@@ -224,12 +230,19 @@
* - `drawIndirectFirstInstance`
* - `sampleRateShading`
*
* **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox
* Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level
* 11_1.
* ### D3D12
*
* **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware
* requirements vary by operating system:
* SDL driver name: "direct3d12"
*
* Supported on Windows 10 or newer, Xbox One (GDK), and Xbox Series X|S
* (GDK). Requires a GPU that supports DirectX 12 Feature Level 11_1.
*
* ### Metal
*
* SDL driver name: "metal"
*
* Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware requirements vary by
* operating system:
*
* - macOS requires an Apple Silicon or
* [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc)
@@ -237,6 +250,26 @@
* - iOS/tvOS requires an A9 GPU or newer
* - iOS Simulator and tvOS Simulator are unsupported
*
* ## Coordinate System
*
* The GPU API uses a left-handed coordinate system, following the convention
* of D3D12 and Metal. Specifically:
*
* - **Normalized Device Coordinates:** The lower-left corner has an x,y
* coordinate of `(-1.0, -1.0)`. The upper-right corner is `(1.0, 1.0)`. Z
* values range from `[0.0, 1.0]` where 0 is the near plane.
* - **Viewport Coordinates:** The top-left corner has an x,y coordinate of
* `(0, 0)` and extends to the bottom-right corner at `(viewportWidth,
* viewportHeight)`. +Y is down.
* - **Texture Coordinates:** The top-left corner has an x,y coordinate of
* `(0, 0)` and extends to the bottom-right corner at `(1.0, 1.0)`. +Y is
* down.
*
* If the backend driver differs from this convention (e.g. Vulkan, which has
* an NDC that assumes +Y is down), SDL will automatically convert the
* coordinate system behind the scenes, so you don't need to perform any
* coordinate flipping logic in your shaders.
*
* ## Uniform Data
*
* Uniforms are for passing data to shaders. The uniform data will be constant
@@ -302,6 +335,39 @@
* unreferenced data in a bound resource without cycling, but overwriting a
* section of data that has already been referenced will produce unexpected
* results.
*
* ## Debugging
*
* At some point of your GPU journey, you will probably encounter issues that
* are not traceable with regular debugger - for example, your code compiles
* but you get an empty screen, or your shader fails in runtime.
*
* For debugging such cases, there are tools that allow visually inspecting
* the whole GPU frame, every drawcall, every bound resource, memory buffers,
* etc. They are the following, per platform:
*
* * For Windows/Linux, use
* [RenderDoc](https://renderdoc.org/)
* * For MacOS (Metal), use Xcode built-in debugger (Open XCode, go to Debug >
* Debug Executable..., select your application, set "GPU Frame Capture" to
* "Metal" in scheme "Options" window, run your app, and click the small
* Metal icon on the bottom to capture a frame)
*
* Aside from that, you may want to enable additional debug layers to receive
* more detailed error messages, based on your GPU backend:
*
* * For D3D12, the debug layer is an optional feature that can be installed
* via "Windows Settings -> System -> Optional features" and adding the
* "Graphics Tools" optional feature.
* * For Vulkan, you will need to install Vulkan SDK on Windows, and on Linux,
* you usually have some sort of `vulkan-validation-layers` system package
* that should be installed.
* * For Metal, it should be enough just to run the application from XCode to
* receive detailed errors or warnings in the output.
*
* Don't hesitate to use tools as RenderDoc when encountering runtime issues
* or unexpected output on screen, quick GPU frame inspection can usually help
* you fix the majority of such problems.
*/
#ifndef SDL_gpu_h_
@@ -1312,10 +1378,15 @@ typedef struct SDL_GPUViewport
* texture.
*
* If either of `pixels_per_row` or `rows_per_layer` is zero, then width and
* height of passed SDL_GPUTextureRegion to SDL_UploadToGPUTexture
* height of passed SDL_GPUTextureRegion to SDL_UploadToGPUTexture or
* SDL_DownloadFromGPUTexture are used as default values respectively and data
* is considered to be tightly packed.
*
* / SDL_DownloadFromGPUTexture are used as default values respectively and
* data is considered to be tightly packed.
* **WARNING**: Direct3D 12 requires texture data row pitch to be 256 byte
* aligned, and offsets to be aligned to 512 bytes. If they are not, SDL will
* make a temporary copy of the data that is properly aligned, but this adds
* overhead to the transfer process. Apps can avoid this by aligning their
* data appropriately, or using a different GPU backend than Direct3D 12.
*
* \since This struct is available since SDL 3.2.0.
*
@@ -1398,7 +1469,7 @@ typedef struct SDL_GPUTextureRegion
*/
typedef struct SDL_GPUBlitRegion
{
SDL_GPUTexture *texture; /**< The texture. */
SDL_GPUTexture *texture; /**< The texture. */
Uint32 mip_level; /**< The mip level index of the region. */
Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */
Uint32 x; /**< The left offset of the region. */
@@ -1527,8 +1598,8 @@ typedef struct SDL_GPUSamplerCreateInfo
SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */
float min_lod; /**< Clamps the minimum of the computed LOD value. */
float max_lod; /**< Clamps the maximum of the computed LOD value. */
bool enable_anisotropy; /**< true to enable anisotropic filtering. */
bool enable_compare; /**< true to enable comparison against a reference value during lookups. */
bool enable_anisotropy; /**< true to enable anisotropic filtering. */
bool enable_compare; /**< true to enable comparison against a reference value during lookups. */
Uint8 padding1;
Uint8 padding2;
@@ -1620,6 +1691,9 @@ typedef struct SDL_GPUStencilOpState
* \since This struct is available since SDL 3.2.0.
*
* \sa SDL_GPUColorTargetDescription
* \sa SDL_GPUBlendFactor
* \sa SDL_GPUBlendOp
* \sa SDL_GPUColorComponentFlags
*/
typedef struct SDL_GPUColorTargetBlendState
{
@@ -1630,8 +1704,8 @@ typedef struct SDL_GPUColorTargetBlendState
SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */
SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */
SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */
bool enable_blend; /**< Whether blending is enabled for the color target. */
bool enable_color_write_mask; /**< Whether the color write mask is enabled. */
bool enable_blend; /**< Whether blending is enabled for the color target. */
bool enable_color_write_mask; /**< Whether the color write mask is enabled. */
Uint8 padding1;
Uint8 padding2;
} SDL_GPUColorTargetBlendState;
@@ -1643,6 +1717,8 @@ typedef struct SDL_GPUColorTargetBlendState
* \since This struct is available since SDL 3.2.0.
*
* \sa SDL_CreateGPUShader
* \sa SDL_GPUShaderFormat
* \sa SDL_GPUShaderStage
*/
typedef struct SDL_GPUShaderCreateInfo
{
@@ -1748,8 +1824,8 @@ typedef struct SDL_GPURasterizerState
float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */
float depth_bias_clamp; /**< The maximum depth bias of a fragment. */
float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */
bool enable_depth_bias; /**< true to bias fragment depth values. */
bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */
bool enable_depth_bias; /**< true to bias fragment depth values. */
bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */
Uint8 padding1;
Uint8 padding2;
} SDL_GPURasterizerState;
@@ -1766,7 +1842,7 @@ typedef struct SDL_GPUMultisampleState
{
SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */
Uint32 sample_mask; /**< Reserved for future use. Must be set to 0. */
bool enable_mask; /**< Reserved for future use. Must be set to false. */
bool enable_mask; /**< Reserved for future use. Must be set to false. */
bool enable_alpha_to_coverage; /**< true enables the alpha-to-coverage feature. */
Uint8 padding2;
Uint8 padding3;
@@ -1787,9 +1863,9 @@ typedef struct SDL_GPUDepthStencilState
SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */
Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */
Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */
bool enable_depth_test; /**< true enables the depth test. */
bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */
bool enable_stencil_test; /**< true enables the stencil test. */
bool enable_depth_test; /**< true enables the depth test. */
bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */
bool enable_stencil_test; /**< true enables the stencil test. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
@@ -1824,7 +1900,7 @@ typedef struct SDL_GPUGraphicsPipelineTargetInfo
const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */
Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */
SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */
bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */
bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
@@ -1931,8 +2007,8 @@ typedef struct SDL_GPUColorTargetInfo
SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */
Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */
Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */
bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */
bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */
bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */
bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */
Uint8 padding1;
Uint8 padding2;
} SDL_GPUColorTargetInfo;
@@ -1989,7 +2065,7 @@ typedef struct SDL_GPUDepthStencilTargetInfo
SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */
SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */
SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */
bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */
bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */
Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */
Uint8 padding1;
Uint8 padding2;
@@ -2009,7 +2085,7 @@ typedef struct SDL_GPUBlitInfo {
SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */
SDL_FlipMode flip_mode; /**< The flip mode for the source region. */
SDL_GPUFilter filter; /**< The filter mode used when blitting. */
bool cycle; /**< true cycles the destination texture if it is already bound. */
bool cycle; /**< true cycles the destination texture if it is already bound. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
@@ -2118,6 +2194,13 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties(
/**
* Creates a GPU context.
*
* The GPU driver name can be one of the following:
*
* - "vulkan": [Vulkan](CategoryGPU#vulkan)
* - "direct3d12": [D3D12](CategoryGPU#d3d12)
* - "metal": [Metal](CategoryGPU#metal)
* - NULL: let SDL pick the optimal driver
*
* \param format_flags a bitflag indicating which shader formats the app is
* able to provide.
* \param debug_mode enable debug mode properties and validations.
@@ -2128,6 +2211,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties(
*
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateGPUDeviceWithProperties
* \sa SDL_GetGPUShaderFormats
* \sa SDL_GetGPUDeviceDriver
* \sa SDL_DestroyGPUDevice
@@ -2172,6 +2256,25 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
* - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to
* use for all vertex semantics, default is "TEXCOORD".
*
* With the Vulkan renderer:
*
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN`: Enable
* device feature shaderClipDistance. If disabled, clip distances are not
* supported in shader code: gl_ClipDistance[] built-ins of GLSL,
* SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of
* Metal. Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN`: Enable device
* feature depthClamp. If disabled, there is no depth clamp support and
* enable_depth_clip in SDL_GPURasterizerState must always be set to true.
* Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN`: Enable
* device feature drawIndirectFirstInstance. If disabled, the argument
* first_instance of SDL_GPUIndirectDrawCommand must be set to zero.
* Defaults to true.
* - `SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN`: Enable
* device feature samplerAnisotropy. If disabled, enable_anisotropy of
* SDL_GPUSamplerCreateInfo must be set to false. Defaults to true.
*
* \param props the properties to use.
* \returns a GPU context on success or NULL on failure; call SDL_GetError()
* for more information.
@@ -2186,17 +2289,21 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDevice(
extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
SDL_PropertiesID props);
#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode"
#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower"
#define SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose"
#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib"
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic"
#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode"
#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower"
#define SDL_PROP_GPU_DEVICE_CREATE_VERBOSE_BOOLEAN "SDL.gpu.device.create.verbose"
#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl"
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib"
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SHADERCLIPDISTANCE_BOOLEAN "SDL.gpu.device.create.vulkan.shaderclipdistance"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DEPTHCLAMP_BOOLEAN "SDL.gpu.device.create.vulkan.depthclamp"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_DRAWINDIRECTFIRST_BOOLEAN "SDL.gpu.device.create.vulkan.drawindirectfirstinstance"
#define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_SAMPLERANISOTROPY_BOOLEAN "SDL.gpu.device.create.vulkan.sampleranisotropy"
/**
* Destroys a GPU context previously returned by SDL_CreateGPUDevice.
@@ -2587,9 +2694,9 @@ extern SDL_DECLSPEC SDL_GPUShader * SDLCALL SDL_CreateGPUShader(
* - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
* the texture to a depth of this value. Defaults to zero.
* - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12
* - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER`: (Direct3D 12
* only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
* clear the texture to a stencil of this value. Defaults to zero.
* clear the texture to a stencil of this Uint8 value. Defaults to zero.
* - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed
* in debugging tools.
*
@@ -2615,13 +2722,13 @@ extern SDL_DECLSPEC SDL_GPUTexture * SDLCALL SDL_CreateGPUTexture(
SDL_GPUDevice *device,
const SDL_GPUTextureCreateInfo *createinfo);
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil"
#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth"
#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_NUMBER "SDL.gpu.texture.create.d3d12.clear.stencil"
#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name"
/**
* Creates a buffer object to be used in graphics or compute workflows.
@@ -2942,6 +3049,9 @@ extern SDL_DECLSPEC SDL_GPUCommandBuffer * SDLCALL SDL_AcquireGPUCommandBuffer(
* terms this means you must ensure that vec3 and vec4 fields are 16-byte
* aligned.
*
* For detailed information about accessing uniform data from a shader, please
* refer to SDL_CreateGPUShader.
*
* \param command_buffer a command buffer.
* \param slot_index the vertex uniform slot to push data to.
* \param data client data to write.
@@ -3895,7 +4005,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice(
* supported via SDL_WindowSupportsGPUPresentMode /
* SDL_WindowSupportsGPUSwapchainComposition prior to calling this function.
*
* SDL_GPU_PRESENTMODE_VSYNC and SDL_GPU_SWAPCHAINCOMPOSITION_SDR are always
* SDL_GPU_PRESENTMODE_VSYNC with SDL_GPU_SWAPCHAINCOMPOSITION_SDR is always
* supported.
*
* \param device a GPU context.
@@ -3969,7 +4079,9 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma
* buffer used to acquire it.
*
* This function will fill the swapchain texture handle with NULL if too many
* frames are in flight. This is not an error.
* frames are in flight. This is not an error. This NULL pointer should not be
* passed back into SDL. Instead, it should be considered as an indication to
* wait until the swapchain is available.
*
* If you use this function, it is possible to create a situation where many
* command buffers are allocated while the rendering context waits for the GPU

View File

@@ -70,7 +70,7 @@
* {
* SDL_Haptic *haptic;
* SDL_HapticEffect effect;
* int effect_id;
* SDL_HapticEffectID effect_id;
*
* // Open the device
* haptic = SDL_OpenHapticFromJoystick(joystick);
@@ -149,6 +149,19 @@ extern "C" {
*/
typedef struct SDL_Haptic SDL_Haptic;
/*
* Misc defines.
*/
/**
* Used to play a device an infinite number of times.
*
* \since This macro is available since SDL 3.2.0.
*
* \sa SDL_RunHapticEffect
*/
#define SDL_HAPTIC_INFINITY 4294967295U
/**
* \name Haptic features
@@ -162,6 +175,11 @@ typedef struct SDL_Haptic SDL_Haptic;
*/
/* @{ */
/**
* Type of haptic effect.
*/
typedef Uint16 SDL_HapticEffectType;
/**
* Constant effect supported.
*
@@ -383,6 +401,11 @@ typedef struct SDL_Haptic SDL_Haptic;
*/
/* @{ */
/**
* Type of coordinates used for haptic direction.
*/
typedef Uint8 SDL_HapticDirectionType;
/**
* Uses polar coordinates for the direction.
*
@@ -426,18 +449,15 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @} *//* Haptic features */
/*
* Misc defines.
*/
/**
* Used to play a device an infinite number of times.
* ID for haptic effects.
*
* \since This macro is available since SDL 3.2.0.
* This is -1 if the ID is invalid.
*
* \sa SDL_RunHapticEffect
* \sa SDL_CreateHapticEffect
*/
#define SDL_HAPTIC_INFINITY 4294967295U
typedef int SDL_HapticEffectID;
/**
@@ -545,8 +565,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*/
typedef struct SDL_HapticDirection
{
Uint8 type; /**< The type of encoding. */
Sint32 dir[3]; /**< The encoded direction. */
SDL_HapticDirectionType type; /**< The type of encoding. */
Sint32 dir[3]; /**< The encoded direction. */
} SDL_HapticDirection;
@@ -566,7 +586,7 @@ typedef struct SDL_HapticDirection
typedef struct SDL_HapticConstant
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_CONSTANT */
SDL_HapticEffectType type; /**< SDL_HAPTIC_CONSTANT */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@@ -652,9 +672,9 @@ typedef struct SDL_HapticConstant
typedef struct SDL_HapticPeriodic
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE
SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
SDL_HAPTIC_SAWTOOTHDOWN */
SDL_HapticEffectType type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE
SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
SDL_HAPTIC_SAWTOOTHDOWN */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@@ -708,8 +728,8 @@ typedef struct SDL_HapticPeriodic
typedef struct SDL_HapticCondition
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
SDL_HapticEffectType type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@@ -747,7 +767,7 @@ typedef struct SDL_HapticCondition
typedef struct SDL_HapticRamp
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_RAMP */
SDL_HapticEffectType type; /**< SDL_HAPTIC_RAMP */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@@ -786,7 +806,7 @@ typedef struct SDL_HapticRamp
typedef struct SDL_HapticLeftRight
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */
SDL_HapticEffectType type; /**< SDL_HAPTIC_LEFTRIGHT */
/* Replay */
Uint32 length; /**< Duration of the effect in milliseconds. */
@@ -816,7 +836,7 @@ typedef struct SDL_HapticLeftRight
typedef struct SDL_HapticCustom
{
/* Header */
Uint16 type; /**< SDL_HAPTIC_CUSTOM */
SDL_HapticEffectType type; /**< SDL_HAPTIC_CUSTOM */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@@ -915,7 +935,7 @@ typedef struct SDL_HapticCustom
typedef union SDL_HapticEffect
{
/* Common for all force feedback effects */
Uint16 type; /**< Effect type. */
SDL_HapticEffectType type; /**< Effect type. */
SDL_HapticConstant constant; /**< Constant effect. */
SDL_HapticPeriodic periodic; /**< Periodic effect. */
SDL_HapticCondition condition; /**< Condition effect. */
@@ -1193,7 +1213,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, c
* \sa SDL_RunHapticEffect
* \sa SDL_UpdateHapticEffect
*/
extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const SDL_HapticEffect *effect);
extern SDL_DECLSPEC SDL_HapticEffectID SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const SDL_HapticEffect *effect);
/**
* Update the properties of an effect.
@@ -1215,7 +1235,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const
* \sa SDL_CreateHapticEffect
* \sa SDL_RunHapticEffect
*/
extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data);
extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, SDL_HapticEffectID effect, const SDL_HapticEffect *data);
/**
* Run the haptic effect on its associated haptic device.
@@ -1239,7 +1259,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int
* \sa SDL_StopHapticEffect
* \sa SDL_StopHapticEffects
*/
extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations);
extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, SDL_HapticEffectID effect, Uint32 iterations);
/**
* Stop the haptic effect on its associated haptic device.
@@ -1254,7 +1274,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int eff
* \sa SDL_RunHapticEffect
* \sa SDL_StopHapticEffects
*/
extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect);
extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, SDL_HapticEffectID effect);
/**
* Destroy a haptic effect on the device.
@@ -1269,7 +1289,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int ef
*
* \sa SDL_CreateHapticEffect
*/
extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int effect);
extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, SDL_HapticEffectID effect);
/**
* Get the status of the current effect on the specified haptic device.
@@ -1285,7 +1305,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int
*
* \sa SDL_GetHapticFeatures
*/
extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect);
extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, SDL_HapticEffectID effect);
/**
* Set the global gain of the specified haptic device.

View File

@@ -1072,8 +1072,8 @@ extern "C" {
*
* By default, SDL will try all available GPU backends in a reasonable order
* until it finds one that can work, but this hint allows the app or user to
* force a specific target, such as "direct3d11" if, say, your hardware
* supports D3D12 but want to try using D3D11 instead.
* force a specific target, such as "direct3d12" if, say, your hardware
* supports Vulkan but you want to try using D3D12 instead.
*
* This hint should be set before any GPU functions are called.
*
@@ -1746,6 +1746,18 @@ extern "C" {
*/
#define SDL_HINT_JOYSTICK_HIDAPI_8BITDO "SDL_JOYSTICK_HIDAPI_8BITDO"
/**
* A variable controlling whether the HIDAPI driver for Flydigi controllers
* should be used.
*
* This variable can be set to the following values:
*
* "0" - HIDAPI driver is not used. "1" - HIDAPI driver is used.
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_FLYDIGI "SDL_JOYSTICK_HIDAPI_FLYDIGI"
/**
* A variable controlling whether the HIDAPI driver for Nintendo Switch
* controllers should be used.
@@ -1949,6 +1961,41 @@ extern "C" {
*/
#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED"
/**
* A variable controlling whether the new HIDAPI driver for wired Xbox One
* (GIP) controllers should be used.
*
* The variable can be set to the following values:
*
* - "0": HIDAPI driver is not used.
* - "1": HIDAPI driver is used.
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE.
*
* This hint should be set before initializing joysticks and gamepads.
*
* \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_GIP "SDL_JOYSTICK_HIDAPI_GIP"
/**
* A variable controlling whether the new HIDAPI driver for wired Xbox One
* (GIP) controllers should reset the controller if it can't get the metadata
* from the controller.
*
* The variable can be set to the following values:
*
* - "0": Assume this is a generic controller.
* - "1": Reset the controller to get metadata.
*
* By default the controller is not reset.
*
* This hint should be set before initializing joysticks and gamepads.
*
* \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_GIP_RESET_FOR_METADATA "SDL_JOYSTICK_HIDAPI_GIP_RESET_FOR_METADATA"
/**
* A variable controlling whether IOKit should be used for controller
* handling.
@@ -2049,8 +2096,8 @@ extern "C" {
*
* The variable can be set to the following values:
*
* - "0": RAWINPUT drivers are not used.
* - "1": RAWINPUT drivers are used. (default)
* - "0": RAWINPUT drivers are not used. (default)
* - "1": RAWINPUT drivers are used.
*
* This hint should be set before SDL is initialized.
*

View File

@@ -79,7 +79,7 @@ typedef Uint32 SDL_InitFlags;
#define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */
#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */
#define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */
#define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS` */
#define SDL_INIT_HAPTIC 0x00001000u
#define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */
#define SDL_INIT_EVENTS 0x00004000u
@@ -101,7 +101,7 @@ typedef Uint32 SDL_InitFlags;
* to run.
*
* See
* [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3)
* [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README-main-functions#main-callbacks-in-sdl3)
* for complete details.
*
* \since This enum is available since SDL 3.2.0.

View File

@@ -823,7 +823,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value);
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -846,7 +846,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -869,7 +869,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -892,7 +892,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -915,7 +915,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -938,7 +938,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -961,7 +961,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -984,7 +984,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -1007,7 +1007,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -1030,7 +1030,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -1053,7 +1053,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.
@@ -1076,7 +1076,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
* \returns true on successful read or false on failure; call SDL_GetError()
* for more information.
*
* \threadsafety This function is not thread safe.

View File

@@ -206,6 +206,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
* SDL_LOG_PRIORITY_WARN and higher have a prefix showing their priority, e.g.
* "WARNING: ".
*
* This function makes a copy of its string argument, **prefix**, so it is not
* necessary to keep the value of **prefix** alive after the call returns.
*
* \param priority the SDL_LogPriority to modify.
* \param prefix the prefix to use for that log priority, or NULL to use no
* prefix.

View File

@@ -47,7 +47,7 @@
*
* For more information, see:
*
* https://wiki.libsdl.org/SDL3/README/main-functions
* https://wiki.libsdl.org/SDL3/README-main-functions
*/
#ifndef SDL_main_h_
@@ -68,7 +68,7 @@
* proper entry point for the platform, and all the other magic details
* needed, like manually calling SDL_SetMainReady.
*
* Please see [README/main-functions](README/main-functions), (or
* Please see [README-main-functions](README-main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
@@ -85,7 +85,7 @@
* SDL_AppQuit. The app should not provide a `main` function in this case, and
* doing so will likely cause the build to fail.
*
* Please see [README/main-functions](README/main-functions), (or
* Please see [README-main-functions](README-main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
@@ -512,7 +512,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
* SDL_MAIN_USE_CALLBACKS.
*
* Program startup is a surprisingly complex topic. Please see
* [README/main-functions](README/main-functions), (or
* [README-main-functions](README-main-functions), (or
* docs/README-main-functions.md in the source tree) for a more detailed
* explanation.
*
@@ -618,8 +618,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[]
* \param name the window class name, in UTF-8 encoding. If NULL, SDL
* currently uses "SDL_app" but this isn't guaranteed.
* \param style the value to use in WNDCLASSEX::style. If `name` is NULL, SDL
* currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` regardless of
* what is specified here.
* currently uses `(CS_BYTEALIGNCLIENT \| CS_OWNDC)` regardless
* of what is specified here.
* \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL
* will use `GetModuleHandle(NULL)` instead.
* \returns true on success or false on failure; call SDL_GetError() for more

View File

@@ -147,6 +147,19 @@ typedef enum SDL_MouseWheelDirection
*/
typedef Uint32 SDL_MouseButtonFlags;
#define SDL_BUTTON_LEFT 1
#define SDL_BUTTON_MIDDLE 2
#define SDL_BUTTON_RIGHT 3
#define SDL_BUTTON_X1 4
#define SDL_BUTTON_X2 5
#define SDL_BUTTON_MASK(X) (1u << ((X)-1))
#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT)
#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE)
#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)
#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1)
#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2)
/**
* A callback used to transform mouse motion delta from raw values.
*
@@ -174,7 +187,7 @@ typedef Uint32 SDL_MouseButtonFlags;
* with proper synchronization practices when adding other side
* effects beyond mutation of the x and y values.
*
* \since This datatype is available since SDL 3.2.6.
* \since This datatype is available since SDL 3.4.0.
*
* \sa SDL_SetRelativeMouseTransform
*/
@@ -186,20 +199,6 @@ typedef void (SDLCALL *SDL_MouseMotionTransformCallback)(
float *x, float *y
);
#define SDL_BUTTON_LEFT 1
#define SDL_BUTTON_MIDDLE 2
#define SDL_BUTTON_RIGHT 3
#define SDL_BUTTON_X1 4
#define SDL_BUTTON_X2 5
#define SDL_BUTTON_MASK(X) (1u << ((X)-1))
#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT)
#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE)
#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)
#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1)
#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2)
/* Function prototypes */
/**
@@ -579,15 +578,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 *data,
/**
* Create a color cursor.
*
* If this function is passed a surface with alternate representations, the
* surface will be interpreted as the content to be used for 100% display
* scale, and the alternate representations will be used for high DPI
* situations. For example, if the original surface is 32x32, then on a 2x
* macOS display or 200% display scale on Windows, a 64x64 version of the
* image will be used, if available. If a matching version of the image isn't
* available, the closest larger size image will be downscaled to the
* appropriate size and be used instead, if available. Otherwise, the closest
* smaller image will be upscaled and be used instead.
* If this function is passed a surface with alternate representations added
* with SDL_AddSurfaceAlternateImage(), the surface will be interpreted as the
* content to be used for 100% display scale, and the alternate
* representations will be used for high DPI situations. For example, if the
* original surface is 32x32, then on a 2x macOS display or 200% display scale
* on Windows, a 64x64 version of the image will be used, if available. If a
* matching version of the image isn't available, the closest larger size
* image will be downscaled to the appropriate size and be used instead, if
* available. Otherwise, the closest smaller image will be upscaled and be
* used instead.
*
* \param surface an SDL_Surface structure representing the cursor image.
* \param hot_x the x position of the cursor hot spot.
@@ -599,6 +599,7 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 *data,
*
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_AddSurfaceAlternateImage
* \sa SDL_CreateCursor
* \sa SDL_CreateSystemCursor
* \sa SDL_DestroyCursor

View File

@@ -517,7 +517,7 @@ typedef enum SDL_PackedLayout
* ABGR32, define a platform-independent encoding into bytes in the order
* specified. For example, in RGB24 data, each pixel is encoded in 3 bytes
* (red, green, blue) in that order, and in ABGR32 data, each pixel is
* encoded in 4 bytes alpha, blue, green, red) in that order. Use these
* encoded in 4 bytes (alpha, blue, green, red) in that order. Use these
* names if the property of a format that is important to you is the order
* of the bytes in memory or on disk.
* - Names with a bit count per component, such as ARGB8888 and XRGB1555, are

View File

@@ -317,7 +317,7 @@
#define SDL_PLATFORM_CYGWIN 1
#endif
#if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN)
#if (defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN)) && !defined(__NGAGE__)
/**
* A preprocessor macro that is only defined if compiling for Windows.
@@ -473,4 +473,15 @@
#define SDL_PLATFORM_3DS 1
#endif
#ifdef __NGAGE__
/**
* A preprocessor macro that is only defined if compiling for the Nokia
* N-Gage.
*
* \since This macro is available since SDL 3.4.0.
*/
#define SDL_PLATFORM_NGAGE 1
#endif
#endif /* SDL_platform_defines_h_ */

View File

@@ -195,6 +195,12 @@ typedef enum SDL_ProcessIO
* run in the background. In this case the default input and output is
* `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not
* available, and will always be 0.
* - `SDL_PROP_PROCESS_CREATE_CMDLINE_STRING`: a string containing the program
* to run and any parameters. This string is passed directly to
* `CreateProcess` on Windows, and does nothing on other platforms. This
* property is only important if you want to start programs that does
* non-standard command-line processing, and in most cases using
* `SDL_PROP_PROCESS_CREATE_ARGS_POINTER` is sufficient.
*
* On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and
* SIGCHLD should not be ignored or handled because those would prevent SDL
@@ -231,6 +237,7 @@ extern SDL_DECLSPEC SDL_Process * SDLCALL SDL_CreateProcessWithProperties(SDL_Pr
#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source"
#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout"
#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background"
#define SDL_PROP_PROCESS_CREATE_CMDLINE_STRING "SDL.process.create.cmdline"
/**
* Get the properties associated with a process.

View File

@@ -110,7 +110,7 @@ typedef enum SDL_TextureAddressMode
SDL_TEXTURE_ADDRESS_INVALID = -1,
SDL_TEXTURE_ADDRESS_AUTO, /**< Wrapping is enabled if texture coordinates are outside [0, 1], this is the default */
SDL_TEXTURE_ADDRESS_CLAMP, /**< Texture coordinates are clamped to the [0, 1] range */
SDL_TEXTURE_ADDRESS_WRAP, /**< The texture is repeated (tiled) */
SDL_TEXTURE_ADDRESS_WRAP /**< The texture is repeated (tiled) */
} SDL_TextureAddressMode;
/**
@@ -1666,8 +1666,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, S
* Return whether an explicit rectangle was set as the viewport.
*
* This is useful if you're saving and restoring the viewport and want to know
* whether you should restore a specific rectangle or NULL. Note that the
* viewport is always reset when changing rendering targets.
* whether you should restore a specific rectangle or NULL.
*
* Each render target has its own viewport. This function checks the viewport
* for the current render target.

View File

@@ -4656,7 +4656,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
*
* Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
*
* Range: `-Pi/2 <= y <= Pi/2`
* Range: `-Pi <= y <= Pi`
*
* This function operates on double-precision floating point values, use
* SDL_atan2f for single-precision floats.
@@ -4692,7 +4692,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
*
* Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
*
* Range: `-Pi/2 <= y <= Pi/2`
* Range: `-Pi <= y <= Pi`
*
* This function operates on single-precision floating point values, use
* SDL_atan2 for double-precision floats.
@@ -5974,8 +5974,12 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size);
size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
#endif
#ifndef _WIN32
/* strdup is not ANSI but POSIX, and its prototype might be hidden... */
/* not for windows: might conflict with string.h where strdup may have
* dllimport attribute: https://github.com/libsdl-org/SDL/issues/12948 */
char *strdup(const char *str);
#endif
/* Starting LLVM 16, the analyser errors out if these functions do not have
their prototype defined (clang-diagnostic-implicit-function-declaration) */

View File

@@ -334,6 +334,10 @@ typedef struct SDL_Storage SDL_Storage;
/**
* Opens up a read-only container for the application's filesystem.
*
* By default, SDL_OpenTitleStorage uses the generic storage implementation.
* When the path override is not provided, the generic implementation will use
* the output of SDL_GetBasePath as the base path.
*
* \param override a path to override the backend's default title root.
* \param props a property list that may contain backend-specific information.
* \returns a title storage container on success or NULL on failure; call

View File

@@ -32,7 +32,8 @@
* There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not
* provide loaders for various other file formats, but there are several
* excellent external libraries that do, including its own satellite library,
* SDL_image:
* [SDL_image](https://wiki.libsdl.org/SDL3_image)
* :
*
* https://github.com/libsdl-org/SDL_image
*/
@@ -1136,9 +1137,6 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SD
* If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
* `dst`) is copied while ensuring clipping to `dst->clip_rect`.
*
* The final blit rectangles are saved in `srcrect` and `dstrect` after all
* clipping is performed.
*
* The blit function should not be called on a locked surface.
*
* The blit semantics for surfaces with and without blending and colorkey are
@@ -1283,10 +1281,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src
*
* \param src the SDL_Surface structure to be copied from.
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied, may not be NULL.
* copied, or NULL to copy the entire surface.
* \param dst the SDL_Surface structure that is the blit target.
* \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface, may not be NULL.
* the destination surface, or NULL to fill the entire
* destination surface.
* \param scaleMode the SDL_ScaleMode to be used.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.

View File

@@ -247,14 +247,14 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
*
* For more information see:
*
* https://wiki.libsdl.org/SDL3/README/ios
* https://wiki.libsdl.org/SDL3/README-ios
*
* Note that if you use the "main callbacks" instead of a standard C `main`
* function, you don't have to use this API, as SDL will manage this for you.
*
* Details on main callbacks are here:
*
* https://wiki.libsdl.org/SDL3/README/main-functions
* https://wiki.libsdl.org/SDL3/README-main-functions
*
* \param window the window for which the animation callback should be set.
* \param interval the number of frames after which **callback** will be

View File

@@ -148,13 +148,14 @@ extern "C" {
extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void);
/**
* Get the code revision of SDL that is linked against your program.
* Get the code revision of the SDL library that is linked against your
* program.
*
* This value is the revision of the code you are linked with and may be
* This value is the revision of the code you are linking against and may be
* different from the code you are compiling with, which is found in the
* constant SDL_REVISION.
*
* The revision is arbitrary string (a hash value) uniquely identifying the
* The revision is an arbitrary string (a hash value) uniquely identifying the
* exact revision of the SDL library in use, and is only useful in comparing
* against other revisions. It is NOT an incrementing number.
*

View File

@@ -1188,6 +1188,16 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int
* Popup windows implicitly do not have a border/decorations and do not appear
* on the taskbar/dock or in lists of windows such as alt-tab menus.
*
* By default, popup window positions will automatically be constrained to
* keep the entire window within display bounds. This can be overridden with
* the `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN` property.
*
* By default, popup menus will automatically grab keyboard focus from the
* parent when shown. This behavior can be overridden by setting the
* `SDL_WINDOW_NOT_FOCUSABLE` flag, setting the
* `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN` property to false, or toggling
* it after creation via the `SDL_SetWindowFocusable()` function.
*
* If a parent window is hidden or destroyed, any child popup windows will be
* recursively hidden or destroyed as well. Child popup windows not explicitly
* hidden will be restored when the parent is shown.
@@ -1228,6 +1238,10 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
* be always on top
* - `SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN`: true if the window has no
* window decoration
* - `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN`: true if the "tooltip"
* and "menu" window types should be automatically constrained to be
* entirely within display bounds (default), false if no constraints on the
* position are desired.
* - `SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN`: true if the
* window will be used with an externally managed graphics context.
* - `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN`: true if the window should
@@ -1289,7 +1303,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
* - `SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN` - true if
* the application wants to use the Wayland surface for a custom role and
* does not want it attached to an XDG toplevel window. See
* [README/wayland](README/wayland) for more information on using custom
* [README-wayland](README-wayland) for more information on using custom
* surfaces.
* - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the
* application wants an associated `wl_egl_window` object to be created and
@@ -1297,7 +1311,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
* property or `SDL_WINDOW_OPENGL` flag set.
* - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface
* associated with the window, if you want to wrap an existing window. See
* [README/wayland](README/wayland) for more information.
* [README-wayland](README-wayland) for more information.
*
* These are additional supported properties on Windows:
*
@@ -1356,6 +1370,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop
#define SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "SDL.window.create.always_on_top"
#define SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN "SDL.window.create.borderless"
#define SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN "SDL.window.create.constrain_popup"
#define SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN "SDL.window.create.focusable"
#define SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN "SDL.window.create.external_graphics_context"
#define SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER "SDL.window.create.flags"
@@ -1501,8 +1516,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window)
*
* On OpenVR:
*
* - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the
* associated overlay window.
* - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER`: the OpenVR Overlay Handle ID
* for the associated overlay window.
*
* On Vivante:
*
@@ -1587,7 +1602,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window
#define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev"
#define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window"
#define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag"
#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id"
#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER "SDL.window.openvr.overlay_id"
#define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display"
#define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window"
#define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface"
@@ -1665,15 +1680,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
/**
* Set the icon for a window.
*
* If this function is passed a surface with alternate representations, the
* surface will be interpreted as the content to be used for 100% display
* scale, and the alternate representations will be used for high DPI
* situations. For example, if the original surface is 32x32, then on a 2x
* macOS display or 200% display scale on Windows, a 64x64 version of the
* image will be used, if available. If a matching version of the image isn't
* available, the closest larger size image will be downscaled to the
* appropriate size and be used instead, if available. Otherwise, the closest
* smaller image will be upscaled and be used instead.
* If this function is passed a surface with alternate representations added
* using SDL_AddSurfaceAlternateImage(), the surface will be interpreted as
* the content to be used for 100% display scale, and the alternate
* representations will be used for high DPI situations. For example, if the
* original surface is 32x32, then on a 2x macOS display or 200% display scale
* on Windows, a 64x64 version of the image will be used, if available. If a
* matching version of the image isn't available, the closest larger size
* image will be downscaled to the appropriate size and be used instead, if
* available. Otherwise, the closest smaller image will be upscaled and be
* used instead.
*
* \param window the window to change.
* \param icon an SDL_Surface structure containing the icon for the window.
@@ -1683,6 +1699,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
* \threadsafety This function should only be called on the main thread.
*
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_AddSurfaceAlternateImage
*/
extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon);
@@ -1876,7 +1894,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_R
extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect);
/**
* Get the size of a window's client area.
* Get the aspect ratio of a window's client area.
*
* \param window the window to query the width and height from.
* \param min_aspect a pointer filled in with the minimum aspect ratio of the

View File

@@ -51,14 +51,14 @@
extern "C" {
#endif
/* Avoid including vulkan.h, don't define VkInstance if it's already included */
#ifdef VULKAN_H_
/* Avoid including vulkan_core.h, don't define VkInstance if it's already included */
#ifdef VULKAN_CORE_H_
#define NO_SDL_VULKAN_TYPEDEFS
#endif
#ifndef NO_SDL_VULKAN_TYPEDEFS
#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__)) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) || (defined(__riscv) && __riscv_xlen == 64)
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
#else
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;

View File

@@ -33,6 +33,10 @@
#cmakedefine SDL_PLATFORM_PRIVATE 1
#ifdef SDL_PLATFORM_PRIVATE
#include "SDL_begin_config_private.h"
#endif
#cmakedefine HAVE_GCC_ATOMICS 1
#cmakedefine HAVE_GCC_SYNC_LOCK_TEST_AND_SET 1
@@ -277,6 +281,7 @@
#cmakedefine SDL_AUDIO_DRIVER_PSP 1
#cmakedefine SDL_AUDIO_DRIVER_PS2 1
#cmakedefine SDL_AUDIO_DRIVER_N3DS 1
#cmakedefine SDL_AUDIO_DRIVER_NGAGE 1
#cmakedefine SDL_AUDIO_DRIVER_QNX 1
#cmakedefine SDL_AUDIO_DRIVER_PRIVATE 1
@@ -365,6 +370,9 @@
#cmakedefine SDL_TIME_PSP 1
#cmakedefine SDL_TIME_PS2 1
#cmakedefine SDL_TIME_N3DS 1
#cmakedefine SDL_TIME_NGAGE 1
#cmakedefine SDL_TIME_PRIVATE 1
/* Enable various timer systems */
#cmakedefine SDL_TIMER_HAIKU 1
@@ -387,6 +395,7 @@
#cmakedefine SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC @SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC@
#cmakedefine SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC_GBM @SDL_VIDEO_DRIVER_KMSDRM_DYNAMIC_GBM@
#cmakedefine SDL_VIDEO_DRIVER_N3DS 1
#cmakedefine SDL_VIDEO_DRIVER_NGAGE 1
#cmakedefine SDL_VIDEO_DRIVER_OFFSCREEN 1
#cmakedefine SDL_VIDEO_DRIVER_PS2 1
#cmakedefine SDL_VIDEO_DRIVER_PSP 1
@@ -438,6 +447,7 @@
#cmakedefine SDL_VIDEO_RENDER_VULKAN 1
#cmakedefine SDL_VIDEO_RENDER_OGL 1
#cmakedefine SDL_VIDEO_RENDER_OGL_ES2 1
#cmakedefine SDL_VIDEO_RENDER_NGAGE 1
#cmakedefine SDL_VIDEO_RENDER_PS2 1
#cmakedefine SDL_VIDEO_RENDER_PSP 1
#cmakedefine SDL_VIDEO_RENDER_VITA_GXM 1
@@ -467,6 +477,8 @@
#cmakedefine SDL_GPU_VULKAN 1
#cmakedefine SDL_GPU_METAL 1
#cmakedefine SDL_GPU_PRIVATE 1
/* Enable system power support */
#cmakedefine SDL_POWER_ANDROID 1
#cmakedefine SDL_POWER_LINUX 1
@@ -501,6 +513,8 @@
/* Enable system storage support */
#cmakedefine SDL_STORAGE_STEAM @SDL_STORAGE_STEAM@
#cmakedefine SDL_STORAGE_PRIVATE 1
/* Enable system FSops support */
#cmakedefine SDL_FSOPS_POSIX 1
#cmakedefine SDL_FSOPS_WINDOWS 1
@@ -544,6 +558,11 @@
#cmakedefine SDL_VIDEO_VITA_PVR 1
#cmakedefine SDL_VIDEO_VITA_PVR_OGL 1
/* xkbcommon version info */
#define SDL_XKBCOMMON_VERSION_MAJOR @SDL_XKBCOMMON_VERSION_MAJOR@
#define SDL_XKBCOMMON_VERSION_MINOR @SDL_XKBCOMMON_VERSION_MINOR@
#define SDL_XKBCOMMON_VERSION_PATCH @SDL_XKBCOMMON_VERSION_PATCH@
/* Libdecor version info */
#define SDL_LIBDECOR_VERSION_MAJOR @SDL_LIBDECOR_VERSION_MAJOR@
#define SDL_LIBDECOR_VERSION_MINOR @SDL_LIBDECOR_VERSION_MINOR@