SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_video.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
Go to the source code of this file.
Typedefs | |
typedef struct SDL_GPUDevice | SDL_GPUDevice |
typedef struct SDL_GPUBuffer | SDL_GPUBuffer |
typedef struct SDL_GPUTransferBuffer | SDL_GPUTransferBuffer |
typedef struct SDL_GPUTexture | SDL_GPUTexture |
typedef struct SDL_GPUSampler | SDL_GPUSampler |
typedef struct SDL_GPUShader | SDL_GPUShader |
typedef struct SDL_GPUComputePipeline | SDL_GPUComputePipeline |
typedef struct SDL_GPUGraphicsPipeline | SDL_GPUGraphicsPipeline |
typedef struct SDL_GPUCommandBuffer | SDL_GPUCommandBuffer |
typedef struct SDL_GPURenderPass | SDL_GPURenderPass |
typedef struct SDL_GPUComputePass | SDL_GPUComputePass |
typedef struct SDL_GPUCopyPass | SDL_GPUCopyPass |
typedef struct SDL_GPUFence | SDL_GPUFence |
typedef Uint32 | SDL_GPUTextureUsageFlags |
typedef Uint32 | SDL_GPUBufferUsageFlags |
typedef Uint32 | SDL_GPUShaderFormat |
typedef Uint8 | SDL_GPUColorComponentFlags |
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) |
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) |
#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) |
#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) |
#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) |
#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) |
#define SDL_GPU_COLORCOMPONENT_A (1u << 3) |
#define SDL_GPU_COLORCOMPONENT_B (1u << 2) |
#define SDL_GPU_COLORCOMPONENT_G (1u << 1) |
#define SDL_GPU_COLORCOMPONENT_R (1u << 0) |
#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) |
#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) |
#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) |
#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) |
#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) |
#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) |
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) |
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) |
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) |
#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) |
#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) |
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" |
#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" |
#define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" |
#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" |
#define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" |
#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOL "SDL.gpu.device.create.shaders.private" |
#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" |
typedef struct SDL_GPUBuffer SDL_GPUBuffer |
typedef Uint32 SDL_GPUBufferUsageFlags |
typedef Uint8 SDL_GPUColorComponentFlags |
typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer |
typedef struct SDL_GPUComputePass SDL_GPUComputePass |
typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline |
typedef struct SDL_GPUCopyPass SDL_GPUCopyPass |
typedef struct SDL_GPUDevice SDL_GPUDevice |
typedef struct SDL_GPUFence SDL_GPUFence |
typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline |
typedef struct SDL_GPURenderPass SDL_GPURenderPass |
typedef struct SDL_GPUSampler SDL_GPUSampler |
typedef struct SDL_GPUShader SDL_GPUShader |
typedef Uint32 SDL_GPUShaderFormat |
typedef struct SDL_GPUTexture SDL_GPUTexture |
typedef Uint32 SDL_GPUTextureUsageFlags |
typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer |
enum SDL_GPUBlendFactor |
Definition at line 411 of file SDL_gpu.h.
enum SDL_GPUBlendOp |
Enumerator | |
---|---|
SDL_GPU_BLENDOP_ADD | |
SDL_GPU_BLENDOP_SUBTRACT | |
SDL_GPU_BLENDOP_REVERSE_SUBTRACT | |
SDL_GPU_BLENDOP_MIN | |
SDL_GPU_BLENDOP_MAX |
enum SDL_GPUCompareOp |
Definition at line 378 of file SDL_gpu.h.
enum SDL_GPUCubeMapFace |
Enumerator | |
---|---|
SDL_GPU_CUBEMAPFACE_POSITIVEX | |
SDL_GPU_CUBEMAPFACE_NEGATIVEX | |
SDL_GPU_CUBEMAPFACE_POSITIVEY | |
SDL_GPU_CUBEMAPFACE_NEGATIVEY | |
SDL_GPU_CUBEMAPFACE_POSITIVEZ | |
SDL_GPU_CUBEMAPFACE_NEGATIVEZ |
Definition at line 256 of file SDL_gpu.h.
enum SDL_GPUCullMode |
Enumerator | |
---|---|
SDL_GPU_CULLMODE_NONE | |
SDL_GPU_CULLMODE_FRONT | |
SDL_GPU_CULLMODE_BACK |
Definition at line 365 of file SDL_gpu.h.
enum SDL_GPUDriver |
Enumerator | |
---|---|
SDL_GPU_DRIVER_INVALID | |
SDL_GPU_DRIVER_PRIVATE | |
SDL_GPU_DRIVER_VULKAN | |
SDL_GPU_DRIVER_D3D11 | |
SDL_GPU_DRIVER_D3D12 | |
SDL_GPU_DRIVER_METAL |
Definition at line 495 of file SDL_gpu.h.
enum SDL_GPUFillMode |
Enumerator | |
---|---|
SDL_GPU_FILLMODE_FILL | |
SDL_GPU_FILLMODE_LINE |
Definition at line 359 of file SDL_gpu.h.
enum SDL_GPUFilter |
Enumerator | |
---|---|
SDL_GPU_FILTER_NEAREST | |
SDL_GPU_FILTER_LINEAR |
Definition at line 435 of file SDL_gpu.h.
enum SDL_GPUFrontFace |
Enumerator | |
---|---|
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE | |
SDL_GPU_FRONTFACE_CLOCKWISE |
Definition at line 372 of file SDL_gpu.h.
enum SDL_GPULoadOp |
Enumerator | |
---|---|
SDL_GPU_LOADOP_LOAD | |
SDL_GPU_LOADOP_CLEAR | |
SDL_GPU_LOADOP_DONT_CARE |
Definition at line 70 of file SDL_gpu.h.
enum SDL_GPUPresentMode |
Enumerator | |
---|---|
SDL_GPU_PRESENTMODE_VSYNC | |
SDL_GPU_PRESENTMODE_IMMEDIATE | |
SDL_GPU_PRESENTMODE_MAILBOX |
Definition at line 470 of file SDL_gpu.h.
enum SDL_GPUPrimitiveType |
Enumerator | |
---|---|
SDL_GPU_PRIMITIVETYPE_POINTLIST | |
SDL_GPU_PRIMITIVETYPE_LINELIST | |
SDL_GPU_PRIMITIVETYPE_LINESTRIP | |
SDL_GPU_PRIMITIVETYPE_TRIANGLELIST | |
SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP |
Definition at line 61 of file SDL_gpu.h.
enum SDL_GPUSampleCount |
Enumerator | |
---|---|
SDL_GPU_SAMPLECOUNT_1 | |
SDL_GPU_SAMPLECOUNT_2 | |
SDL_GPU_SAMPLECOUNT_4 | |
SDL_GPU_SAMPLECOUNT_8 |
Definition at line 248 of file SDL_gpu.h.
Enumerator | |
---|---|
SDL_GPU_SAMPLERADDRESSMODE_REPEAT | |
SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT | |
SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE |
Definition at line 447 of file SDL_gpu.h.
Enumerator | |
---|---|
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST | |
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR |
Definition at line 441 of file SDL_gpu.h.
enum SDL_GPUShaderStage |
Enumerator | |
---|---|
SDL_GPU_SHADERSTAGE_VERTEX | |
SDL_GPU_SHADERSTAGE_FRAGMENT |
Definition at line 281 of file SDL_gpu.h.
enum SDL_GPUStencilOp |
Definition at line 390 of file SDL_gpu.h.
enum SDL_GPUStoreOp |
Enumerator | |
---|---|
SDL_GPU_STOREOP_STORE | |
SDL_GPU_STOREOP_DONT_CARE |
Definition at line 77 of file SDL_gpu.h.
Enumerator | |
---|---|
SDL_GPU_SWAPCHAINCOMPOSITION_SDR | |
SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR | |
SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR | |
SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 |
Definition at line 487 of file SDL_gpu.h.
enum SDL_GPUTextureFormat |
Definition at line 157 of file SDL_gpu.h.
enum SDL_GPUTextureType |
Enumerator | |
---|---|
SDL_GPU_TEXTURETYPE_2D | |
SDL_GPU_TEXTURETYPE_2D_ARRAY | |
SDL_GPU_TEXTURETYPE_3D | |
SDL_GPU_TEXTURETYPE_CUBE |
Definition at line 240 of file SDL_gpu.h.
Definition at line 296 of file SDL_gpu.h.
Enumerator | |
---|---|
SDL_GPU_VERTEXINPUTRATE_VERTEX | |
SDL_GPU_VERTEXINPUTRATE_INSTANCE |
Definition at line 353 of file SDL_gpu.h.
|
extern |
Acquire a command buffer.
This command buffer is managed by the implementation and should not be freed by the user. The command buffer may only be used on the thread it was acquired on. The command buffer should be submitted on the thread it was acquired on.
device | a GPU context. |
|
extern |
Acquire a texture to use in presentation.
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it. May return NULL under certain conditions. This is not necessarily an error. This texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.
commandBuffer | a command buffer. |
window | a window that has been claimed. |
pWidth | a pointer filled in with the swapchain width. |
pHeight | a pointer filled in with the swapchain height. |
|
extern |
Begins a compute pass on a command buffer.
A compute pass is defined by a set of texture subresources and buffers that will be written to by compute pipelines. These textures and buffers must have been created with the COMPUTE_STORAGE_WRITE bit. All operations related to compute pipelines must take place inside of a compute pass. You must not begin another compute pass, or a render pass or copy pass before ending the compute pass.
A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be read from during the compute pass. Doing so will result in undefined behavior. If your compute work requires reading the output from a previous dispatch, you MUST end the current compute pass and begin a new one before you can safely access the data.
commandBuffer | a command buffer. |
storageTextureBindings | an array of writeable storage texture binding structs. |
storageTextureBindingCount | the number of storage textures to bind from the array. |
storageBufferBindings | an array of writeable storage buffer binding structs. |
storageBufferBindingCount | the number of storage buffers to bind from the array. |
|
extern |
Begins a copy pass on a command buffer.
All operations related to copying to or from buffers or textures take place inside a copy pass. You must not begin another copy pass, or a render pass or compute pass before ending the copy pass.
commandBuffer | a command buffer. |
|
extern |
Begins a render pass on a command buffer.
A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.
commandBuffer | a command buffer. |
colorAttachmentInfos | an array of texture subresources with corresponding clear values and load/store ops. |
colorAttachmentCount | the number of color attachments in the colorAttachmentInfos array. |
depthStencilAttachmentInfo | a texture subresource with corresponding clear value and load/store ops, may be NULL. |
|
extern |
Binds a compute pipeline on a command buffer for use in compute dispatch.
computePass | a compute pass handle. |
computePipeline | a compute pipeline to bind. |
|
extern |
Binds storage buffers as readonly for use on the compute pipeline.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ.
computePass | a compute pass handle. |
firstSlot | the compute storage buffer slot to begin binding from. |
storageBuffers | an array of storage buffer binding structs. |
bindingCount | the number of storage buffers to bind from the array. |
|
extern |
Binds storage textures as readonly for use on the compute pipeline.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ.
computePass | a compute pass handle. |
firstSlot | the compute storage texture slot to begin binding from. |
storageTextures | an array of storage textures. |
bindingCount | the number of storage textures to bind from the array. |
|
extern |
Binds texture-sampler pairs for use on the fragment shader.
The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
renderPass | a render pass handle. |
firstSlot | the fragment sampler slot to begin binding from. |
textureSamplerBindings | an array of texture-sampler binding structs. |
bindingCount | the number of texture-sampler pairs to bind from the array. |
|
extern |
Binds storage buffers for use on the fragment shader.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
renderPass | a render pass handle. |
firstSlot | the fragment storage buffer slot to begin binding from. |
storageBuffers | an array of storage buffers. |
bindingCount | the number of storage buffers to bind from the array. |
|
extern |
Binds storage textures for use on the fragment shader.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
renderPass | a render pass handle. |
firstSlot | the fragment storage texture slot to begin binding from. |
storageTextures | an array of storage textures. |
bindingCount | the number of storage textures to bind from the array. |
|
extern |
Binds a graphics pipeline on a render pass to be used in rendering.
A graphics pipeline must be bound before making any draw calls.
renderPass | a render pass handle. |
graphicsPipeline | the graphics pipeline to bind. |
|
extern |
Binds an index buffer on a command buffer for use with subsequent draw calls.
renderPass | a render pass handle. |
pBinding | a pointer to a struct containing an index buffer and offset. |
indexElementSize | whether the index values in the buffer are 16- or 32-bit. |
|
extern |
Binds vertex buffers on a command buffer for use with subsequent draw calls.
renderPass | a render pass handle. |
firstBinding | the starting bind point for the vertex buffers. |
pBindings | an array of SDL_GPUBufferBinding structs containing vertex buffers and offset values. |
bindingCount | the number of bindings in the pBindings array. |
|
extern |
Binds texture-sampler pairs for use on the vertex shader.
The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER.
renderPass | a render pass handle. |
firstSlot | the vertex sampler slot to begin binding from. |
textureSamplerBindings | an array of texture-sampler binding structs. |
bindingCount | the number of texture-sampler pairs to bind from the array. |
|
extern |
Binds storage buffers for use on the vertex shader.
These buffers must have been created with SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ.
renderPass | a render pass handle. |
firstSlot | the vertex storage buffer slot to begin binding from. |
storageBuffers | an array of buffers. |
bindingCount | the number of buffers to bind from the array. |
|
extern |
Binds storage textures for use on the vertex shader.
These textures must have been created with SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ.
renderPass | a render pass handle. |
firstSlot | the vertex storage texture slot to begin binding from. |
storageTextures | an array of storage textures. |
bindingCount | the number of storage texture to bind from the array. |
|
extern |
Blits from a source texture region to a destination texture region.
This function must not be called inside of any pass.
commandBuffer | a command buffer. |
source | the texture region to copy from. |
destination | the texture region to copy to. |
flipMode | the flip mode for the source texture region. |
filterMode | the filter mode that will be used when blitting. |
cycle | if SDL_TRUE, cycles the destination texture if the destination texture is bound, otherwise overwrites the data. |
|
extern |
Claims a window, creating a swapchain structure for it.
This must be called before SDL_AcquireGPUSwapchainTexture is called using the window.
The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain parameters, you must call SetSwapchainParameters after claiming the window.
device | a GPU context. |
window | an SDL_Window. |
|
extern |
Performs a buffer-to-buffer copy.
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
copyPass | a copy pass handle. |
source | the buffer and offset to copy from. |
destination | the buffer and offset to copy to. |
size | the length of the buffer to copy. |
cycle | if SDL_TRUE, cycles the destination buffer if it is bound, otherwise overwrites the data. |
|
extern |
Performs a texture-to-texture copy.
This copy occurs on the GPU timeline. You may assume the copy has finished in subsequent commands.
copyPass | a copy pass handle. |
source | a source texture region. |
destination | a destination texture region. |
w | the width of the region to copy. |
h | the height of the region to copy. |
d | the depth of the region to copy. |
cycle | if SDL_TRUE, cycles the destination texture if the destination texture is bound, otherwise overwrites the data. |
|
extern |
Creates a buffer object to be used in graphics or compute workflows.
The contents of this buffer are undefined until data is written to the buffer.
Note that certain combinations of usage flags are invalid. For example, a buffer cannot have both the VERTEX and INDEX flags.
device | a GPU Context. |
bufferCreateInfo | a struct describing the state of the buffer to create. |
|
extern |
Creates a pipeline object to be used in a compute workflow.
Shader resource bindings must be authored to follow a particular order. For SPIR-V shaders, use the following resource sets: 0: Read-only storage textures, followed by read-only storage buffers 1: Write-only storage textures, followed by write-only storage buffers 2: Uniform buffers
For DXBC Shader Model 5_0 shaders, use the following register order: For t registers: Read-only storage textures, followed by read-only storage buffers For u registers: Write-only storage textures, followed by write-only storage buffers For b registers: Uniform buffers
For DXIL shaders, use the following register order: (t[n], space0): Read-only storage textures, followed by read-only storage buffers (u[n], space1): Write-only storage textures, followed by write-only storage buffers (b[n], space2): Uniform buffers
For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, followed by write-only storage buffers, followed by write-only storage buffers For [[texture]]: Read-only storage textures, followed by write-only storage textures
device | a GPU Context. |
computePipelineCreateInfo | a struct describing the state of the requested compute pipeline. |
|
extern |
Creates a GPU context.
formatFlags | a bitflag indicating which shader formats the app is able to provide. |
debugMode | enable debug mode properties and validations. |
name | the preferred GPU driver, or NULL to let SDL pick the optimal driver. |
|
extern |
Creates a GPU context.
These are the supported properties:
SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL
: enable debug mode properties and validations, defaults to SDL_TRUE.SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL
: enable to prefer energy efficiency over maximum GPU performance, defaults to SDL_FALSE.SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING
: the name of the GPU driver to use, if a specific one is desired.These are the current shader format properties:
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOL
: The app is able to provide shaders for an NDA platform.SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL
: The app is able to provide SPIR-V shaders if applicable.: The app is able to provide DXBC shaders if applicable
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL: The app is able to provide DXIL shaders if applicable. -
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL: The app is able to provide MSL shaders if applicable. -
SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to provide Metal shader libraries if applicable.With the D3D12 renderer:
SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING
: the prefix to use for all vertex semantics, default is "TEXCOORD".props | the properties to use. |
|
extern |
Creates a pipeline object to be used in a graphics workflow.
device | a GPU Context. |
pipelineCreateInfo | a struct describing the state of the desired graphics pipeline. |
|
extern |
Creates a sampler object to be used when binding textures in a graphics workflow.
device | a GPU Context. |
samplerCreateInfo | a struct describing the state of the desired sampler. |
|
extern |
Creates a shader to be used when creating a graphics pipeline.
Shader resource bindings must be authored to follow a particular order depending on the shader format.
For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: Sampled textures, followed by storage textures, followed by storage buffers 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by storage textures, followed by storage buffers 3: Uniform buffers
For DXBC Shader Model 5_0 shaders, use the following register order: For t registers: Sampled textures, followed by storage textures, followed by storage buffers For s registers: Samplers with indices corresponding to the sampled textures For b registers: Uniform buffers
For DXIL shaders, use the following register order: For vertex shaders: (t[n], space0): Sampled textures, followed by storage textures, followed by storage buffers (s[n], space0): Samplers with indices corresponding to the sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], space2): Sampled textures, followed by storage textures, followed by storage buffers (s[n], space2): Samplers with indices corresponding to the sampled textures (b[n], space3): Uniform buffers
For MSL/metallib, use the following order: For [[texture]]: Sampled textures, followed by storage textures For [[sampler]]: Samplers with indices corresponding to the sampled textures For [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 is bound at [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than manually authoring vertex buffer indices, use the [[stage_in]] attribute which will automatically use the vertex input information from the SDL_GPUPipeline.
device | a GPU Context. |
shaderCreateInfo | a struct describing the state of the desired shader. |
|
extern |
Creates a texture object to be used in graphics or compute workflows.
The contents of this texture are undefined until data is written to the texture.
Note that certain combinations of usage flags are invalid. For example, a texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags.
If you request a sample count higher than the hardware supports, the implementation will automatically fall back to the highest available sample count.
device | a GPU Context. |
textureCreateInfo | a struct describing the state of the texture to create. |
|
extern |
Creates a transfer buffer to be used when uploading to or downloading from graphics resources.
device | a GPU Context. |
transferBufferCreateInfo | a struct describing the state of the transfer buffer to create. |
|
extern |
Destroys a GPU context previously returned by SDL_CreateGPUDevice.
device | a GPU Context to destroy. |
|
extern |
Dispatches compute work.
You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
computePass | a compute pass handle. |
groupCountX | number of local workgroups to dispatch in the X dimension. |
groupCountY | number of local workgroups to dispatch in the Y dimension. |
groupCountZ | number of local workgroups to dispatch in the Z dimension. |
|
extern |
Dispatches compute work with parameters set from a buffer.
The buffer layout should match the layout of SDL_GPUIndirectDispatchCommand. You must not call this function before binding a compute pipeline.
A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and the dispatches write to the same resource region as each other, there is no guarantee of which order the writes will occur. If the write order matters, you MUST end the compute pass and begin another one.
computePass | a compute pass handle. |
buffer | a buffer containing dispatch parameters. |
offsetInBytes | the offset to start reading from the dispatch buffer. |
|
extern |
Copies data from a buffer to a transfer buffer on the GPU timeline.
This data is not guaranteed to be copied until the command buffer fence is signaled.
copyPass | a copy pass handle. |
source | the source buffer with offset and size. |
destination | the destination transfer buffer with offset. |
|
extern |
Copies data from a texture to a transfer buffer on the GPU timeline.
This data is not guaranteed to be copied until the command buffer fence is signaled.
copyPass | a copy pass handle. |
source | the source texture region. |
destination | the destination transfer buffer with image layout information. |
|
extern |
Draws data using bound graphics state with an index buffer and instancing enabled.
You must not call this function before binding a graphics pipeline.
Note that the firstVertex
and firstInstance
parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If your shader depends on these variables, the correlating draw call parameter MUST be 0.
renderPass | a render pass handle. |
indexCount | the number of vertices to draw per instance. |
instanceCount | the number of instances to draw. |
firstIndex | the starting index within the index buffer. |
vertexOffset | value added to vertex index before indexing into the vertex buffer. |
firstInstance | the ID of the first instance to draw. |
|
extern |
Draws data using bound graphics state with an index buffer enabled and with draw parameters set from a buffer.
The buffer layout should match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
renderPass | a render pass handle. |
buffer | a buffer containing draw parameters. |
offsetInBytes | the offset to start reading from the draw buffer. |
drawCount | the number of draw parameter sets that should be read from the draw buffer. |
stride | the byte stride between sets of draw parameters. |
|
extern |
Draws data using bound graphics state.
You must not call this function before binding a graphics pipeline.
Note that the firstVertex
and firstInstance
parameters are NOT compatible with built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If your shader depends on these variables, the correlating draw call parameter MUST be 0.
renderPass | a render pass handle. |
vertexCount | the number of vertices to draw. |
instanceCount | the number of instances that will be drawn. |
firstVertex | the index of the first vertex to draw. |
firstInstance | the ID of the first instance to draw. |
|
extern |
Draws data using bound graphics state and with draw parameters set from a buffer.
The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. You must not call this function before binding a graphics pipeline.
renderPass | a render pass handle. |
buffer | a buffer containing draw parameters. |
offsetInBytes | the offset to start reading from the draw buffer. |
drawCount | the number of draw parameter sets that should be read from the draw buffer. |
stride | the byte stride between sets of draw parameters. |
|
extern |
Ends the current compute pass.
All bound compute state on the command buffer is unset. The compute pass handle is now invalid.
computePass | a compute pass handle. |
|
extern |
Ends the current copy pass.
copyPass | a copy pass handle. |
|
extern |
Ends the given render pass.
All bound graphics state on the render pass command buffer is unset. The render pass handle is now invalid.
renderPass | a render pass handle. |
|
extern |
Generates mipmaps for the given texture.
This function must not be called inside of any pass.
commandBuffer | a commandBuffer. |
texture | a texture with more than 1 mip level. |
|
extern |
Returns the backend used to create this GPU context.
device | a GPU context to query. |
|
extern |
Obtains the texture format of the swapchain for the given window.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
|
extern |
Obtains the texel block size for a texture format.
textureFormat | the texture format you want to know the texel size of. |
|
extern |
Determines whether a texture format is supported for a given type and usage.
device | a GPU context. |
format | the texture format to check. |
type | the type of texture (2D, 3D, Cube). |
usage | a bitmask of all usage scenarios to check. |
|
extern |
Determines if a sample count for a texture format is supported.
device | a GPU context. |
format | the texture format to check. |
sampleCount | the sample count to check. |
|
extern |
Inserts an arbitrary string label into the command buffer callstream.
Useful for debugging.
commandBuffer | a command buffer. |
text | a UTF-8 string constant to insert as the label. |
|
extern |
Maps a transfer buffer into application address space.
You must unmap the transfer buffer before encoding upload commands.
device | a GPU context. |
transferBuffer | a transfer buffer. |
cycle | if SDL_TRUE, cycles the transfer buffer if it is bound. |
|
extern |
Ends the most-recently pushed debug group.
commandBuffer | a command buffer. |
|
extern |
Pushes data to a uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
commandBuffer | a command buffer. |
slotIndex | the uniform slot to push data to. |
data | client data to write. |
dataLengthInBytes | the length of the data to write. |
|
extern |
Begins a debug group with an arbitary name.
Used for denoting groups of calls when viewing the command buffer callstream in a graphics debugging tool.
Each call to SDL_PushGPUDebugGroup must have a corresponding call to SDL_PopGPUDebugGroup.
On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass will create a group that is scoped to the native pass rather than the command buffer. For best results, if you push a debug group during a pass, always pop it in the same pass.
commandBuffer | a command buffer. |
name | a UTF-8 string constant that names the group. |
|
extern |
Pushes data to a fragment uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
commandBuffer | a command buffer. |
slotIndex | the fragment uniform slot to push data to. |
data | client data to write. |
dataLengthInBytes | the length of the data to write. |
|
extern |
Pushes data to a vertex uniform slot on the command buffer.
Subsequent draw calls will use this uniform data.
commandBuffer | a command buffer. |
slotIndex | the vertex uniform slot to push data to. |
data | client data to write. |
dataLengthInBytes | the length of the data to write. |
|
extern |
Checks the status of a fence.
device | a GPU context. |
fence | a fence. |
|
extern |
Frees the given buffer as soon as it is safe to do so.
You must not reference the buffer after calling this function.
device | a GPU context. |
buffer | a buffer to be destroyed. |
|
extern |
Frees the given compute pipeline as soon as it is safe to do so.
You must not reference the compute pipeline after calling this function.
device | a GPU context. |
computePipeline | a compute pipeline to be destroyed. |
|
extern |
Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence.
device | a GPU context. |
fence | a fence. |
|
extern |
Frees the given graphics pipeline as soon as it is safe to do so.
You must not reference the graphics pipeline after calling this function.
device | a GPU context. |
graphicsPipeline | a graphics pipeline to be destroyed. |
|
extern |
Frees the given sampler as soon as it is safe to do so.
You must not reference the texture after calling this function.
device | a GPU context. |
sampler | a sampler to be destroyed. |
|
extern |
Frees the given shader as soon as it is safe to do so.
You must not reference the shader after calling this function.
device | a GPU context. |
shader | a shader to be destroyed. |
|
extern |
Frees the given texture as soon as it is safe to do so.
You must not reference the texture after calling this function.
device | a GPU context. |
texture | a texture to be destroyed. |
|
extern |
Frees the given transfer buffer as soon as it is safe to do so.
You must not reference the transfer buffer after calling this function.
device | a GPU context. |
transferBuffer | a transfer buffer to be destroyed. |
|
extern |
Unclaims a window, destroying its swapchain structure.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
|
extern |
Sets an arbitrary string constant to label a buffer.
Useful for debugging.
device | a GPU Context. |
buffer | a buffer to attach the name to. |
text | a UTF-8 string constant to mark as the name of the buffer. |
|
extern |
Sets the current scissor state on a command buffer.
renderPass | a render pass handle. |
scissor | the scissor area to set. |
|
extern |
Changes the swapchain parameters for the given claimed window.
This function will fail if the requested present mode or swapchain composition are unsupported by the device. Check if the parameters are supported via SDL_WindowSupportsGPUPresentMode / SDL_WindowSupportsGPUSwapchainComposition prior to calling this function.
SDL_GPU_PRESENTMODE_VSYNC and SDL_GPU_SWAPCHAINCOMPOSITION_SDR are always supported.
device | a GPU context. |
window | an SDL_Window that has been claimed. |
swapchainComposition | the desired composition of the swapchain. |
presentMode | the desired present mode for the swapchain. |
|
extern |
Sets an arbitrary string constant to label a texture.
Useful for debugging.
device | a GPU Context. |
texture | a texture to attach the name to. |
text | a UTF-8 string constant to mark as the name of the texture. |
|
extern |
Sets the current viewport state on a command buffer.
renderPass | a render pass handle. |
viewport | the viewport to set. |
|
extern |
Submits a command buffer so its commands can be processed on the GPU.
It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
commandBuffer | a command buffer. |
|
extern |
Submits a command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer.
You must release this fence when it is no longer needed or it will cause a leak. It is invalid to use the command buffer after this is called.
This must be called from the thread the command buffer was acquired on.
All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.
commandBuffer | a command buffer. |
|
extern |
Unmaps a previously mapped transfer buffer.
device | a GPU context. |
transferBuffer | a previously mapped transfer buffer. |
|
extern |
Uploads data from a transfer buffer to a buffer.
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
copyPass | a copy pass handle. |
source | the source transfer buffer with offset. |
destination | the destination buffer with offset and size. |
cycle | if SDL_TRUE, cycles the buffer if it is bound, otherwise overwrites the data. |
|
extern |
Uploads data from a transfer buffer to a texture.
The upload occurs on the GPU timeline. You may assume that the upload has finished in subsequent commands.
You must align the data in the transfer buffer to a multiple of the texel size of the texture format.
copyPass | a copy pass handle. |
source | the source transfer buffer with image layout information. |
destination | the destination texture region. |
cycle | if SDL_TRUE, cycles the texture if the texture is bound, otherwise overwrites the data. |
|
extern |
Blocks the thread until the given fences are signaled.
device | a GPU context. |
waitAll | if 0, wait for any fence to be signaled, if 1, wait for all fences to be signaled. |
pFences | an array of fences to wait on. |
fenceCount | the number of fences in the pFences array. |
|
extern |
Blocks the thread until the GPU is completely idle.
device | a GPU context. |
|
extern |
Determines whether a presentation mode is supported by the window.
The window must be claimed before calling this function.
device | a GPU context. |
window | an SDL_Window. |
presentMode | the presentation mode to check. |
|
extern |
Determines whether a swapchain composition is supported by the window.
The window must be claimed before calling this function.
device | a GPU context. |
window | an SDL_Window. |
swapchainComposition | the swapchain composition to check. |