gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

GPU: Document opaque handles and enums (#10700)

Browse Source
This commit is contained in:
Evan Hemsley
2024-09-04 18:24:11 -07:00
committed by GitHub
parent 20d0a1a3d1
commit 1c8c014481
1 changed files with 520 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

633
include/SDL3/SDL_gpu.h
View File

@@ -44,49 +44,256 @@ extern "C" {
/* Type Declarations */ /* Type Declarations */
/**
* An opaque handle representing the SDL_GPU context.
*
* \since This struct is available since SDL 3.0.0
*/
typedef struct SDL_GPUDevice SDL_GPUDevice; typedef struct SDL_GPUDevice SDL_GPUDevice;
/**
* An opaque handle representing a buffer.
*
* Used for vertices, indices, indirect draw commands, and general compute data.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUBuffer
* \sa SDL_SetGPUBufferName
* \sa SDL_UploadToGPUBuffer
* \sa SDL_DownloadFromGPUBuffer
* \sa SDL_CopyGPUBufferToBuffer
* \sa SDL_BindGPUVertexBuffers
* \sa SDL_BindGPUIndexBuffer
* \sa SDL_BindGPUVertexStorageBuffers
* \sa SDL_BindGPUFragmentStorageBuffers
* \sa SDL_DrawGPUPrimitivesIndirect
* \sa SDL_DrawGPUIndexedPrimitivesIndirect
* \sa SDL_BindGPUComputeStorageBuffers
* \sa SDL_DispatchGPUComputeIndirect
* \sa SDL_ReleaseGPUBuffer
*/
typedef struct SDL_GPUBuffer SDL_GPUBuffer; typedef struct SDL_GPUBuffer SDL_GPUBuffer;
/**
* An opaque handle representing a transfer buffer.
*
* Used for transferring data to and from the device.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTransferBuffer
* \sa SDL_MapGPUTransferBuffer
* \sa SDL_UnmapGPUTransferBuffer
* \sa SDL_UploadToGPUBuffer
* \sa SDL_UploadToGPUTexture
* \sa SDL_DownloadFromGPUBuffer
* \sa SDL_DownloadFromGPUTexture
* \sa SDL_ReleaseGPUTransferBuffer
*/
typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer;
/**
* An opaque handle representing a texture.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTexture
* \sa SDL_SetGPUTextureName
* \sa SDL_UploadToGPUTexture
* \sa SDL_DownloadFromGPUTexture
* \sa SDL_CopyGPUTextureToTexture
* \sa SDL_BindGPUVertexSamplers
* \sa SDL_BindGPUVertexStorageTextures
* \sa SDL_BindGPUFragmentSamplers
* \sa SDL_BindGPUFragmentStorageTextures
* \sa SDL_BindGPUComputeStorageTextures
* \sa SDL_GenerateMipmapsForGPUTexture
* \sa SDL_BlitGPUTexture
* \sa SDL_ReleaseGPUTexture
*/
typedef struct SDL_GPUTexture SDL_GPUTexture; typedef struct SDL_GPUTexture SDL_GPUTexture;
/**
* An opaque handle representing a sampler.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUSampler
* \sa SDL_BindGPUVertexSamplers
* \sa SDL_BindGPUFragmentSamplers
* \sa SDL_ReleaseGPUSampler
*/
typedef struct SDL_GPUSampler SDL_GPUSampler; typedef struct SDL_GPUSampler SDL_GPUSampler;
/**
* An opaque handle representing a compiled shader object.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUShader
* \sa SDL_CreateGPUGraphicsPipeline
* \sa SDL_ReleaseGPUShader
*/
typedef struct SDL_GPUShader SDL_GPUShader; typedef struct SDL_GPUShader SDL_GPUShader;
/**
* An opaque handle representing a compute pipeline.
*
* Used during compute passes.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUComputePipeline
* \sa SDL_BindGPUComputePipeline
* \sa SDL_ReleaseGPUComputePipeline
*/
typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline;
/**
* An opaque handle representing a graphics pipeline.
*
* Used during render passes.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
* \sa SDL_BindGPUGraphicsPipeline
* \sa SDL_ReleaseGPUGraphicsPipeline
*/
typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline;
/**
* An opaque handle representing a command buffer.
*
* Most state is managed via command buffers.
* When setting state using a command buffer, that state is local to the command buffer.
*
* Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is called.
* Once the command buffer is submitted, it is no longer valid to use it.
*
* Command buffers are executed in submission order. If you submit command buffer A and then command buffer B
* all commands in A will begin executing before any command in B begins executing.
*
* In multi-threading scenarios, you should acquire and submit a command buffer on the same thread.
* As long as you satisfy this requirement, all functionality related to command buffers is thread-safe.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_AcquireGPUCommandBuffer
* \sa SDL_SubmitGPUCommandBuffer
* \sa SDL_SubmitGPUCommandBufferAndAcquireFence
*/
typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer;
/**
* An opaque handle representing a render pass.
*
* This handle is transient and should not be held or referenced after SDL_EndGPURenderPass is called.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_BeginGPURenderPass
* \sa SDL_EndGPURenderPass
*/
typedef struct SDL_GPURenderPass SDL_GPURenderPass; typedef struct SDL_GPURenderPass SDL_GPURenderPass;
/**
* An opaque handle representing a compute pass.
*
* This handle is transient and should not be held or referenced after SDL_EndGPUComputePass is called.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_BeginGPUComputePass
* \sa SDL_EndGPUComputePass
*/
typedef struct SDL_GPUComputePass SDL_GPUComputePass; typedef struct SDL_GPUComputePass SDL_GPUComputePass;
/**
* An opaque handle representing a copy pass.
*
* This handle is transient and should not be held or referenced after SDL_EndGPUCopyPass is called.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_BeginGPUCopyPass
* \sa SDL_EndGPUCopyPass
*/
typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; typedef struct SDL_GPUCopyPass SDL_GPUCopyPass;
/**
* An opaque handle representing a fence.
*
* \since This struct is available since SDL 3.0.0
*
* \sa SDL_SubmitGPUCommandBufferAndAcquireFence
* \sa SDL_QueryGPUFence
* \sa SDL_WaitForGPUFences
* \sa SDL_ReleaseGPUFence
*/
typedef struct SDL_GPUFence SDL_GPUFence; typedef struct SDL_GPUFence SDL_GPUFence;
/**
* Specifies the primitive topology of a graphics pipeline.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUPrimitiveType typedef enum SDL_GPUPrimitiveType
{ {
SDL_GPU_PRIMITIVETYPE_POINTLIST, SDL_GPU_PRIMITIVETYPE_POINTLIST, /**< A series of separate points. */
SDL_GPU_PRIMITIVETYPE_LINELIST, SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */
SDL_GPU_PRIMITIVETYPE_LINESTRIP, SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */
SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */
SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP /**< A series of connected triangles. */
} SDL_GPUPrimitiveType; } SDL_GPUPrimitiveType;
/**
* Specifies how the contents of a texture attached to a render pass are treated at the beginning of the render pass.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_BeginGPURenderPass
*/
typedef enum SDL_GPULoadOp typedef enum SDL_GPULoadOp
{ {
SDL_GPU_LOADOP_LOAD, SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */
SDL_GPU_LOADOP_CLEAR, SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */
SDL_GPU_LOADOP_DONT_CARE SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */
} SDL_GPULoadOp; } SDL_GPULoadOp;
/**
* Specifies how the contents of a texture attached to a render pass are treated at the end of the render pass.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_BeginGPURenderPass
*/
typedef enum SDL_GPUStoreOp typedef enum SDL_GPUStoreOp
{ {
SDL_GPU_STOREOP_STORE, SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */
SDL_GPU_STOREOP_DONT_CARE SDL_GPU_STOREOP_DONT_CARE /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */
} SDL_GPUStoreOp; } SDL_GPUStoreOp;
/**
* Specifies the size of elements in an index buffer.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUIndexElementSize typedef enum SDL_GPUIndexElementSize
{ {
SDL_GPU_INDEXELEMENTSIZE_16BIT, SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */
SDL_GPU_INDEXELEMENTSIZE_32BIT SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */
} SDL_GPUIndexElementSize; } SDL_GPUIndexElementSize;
/* Texture format support varies depending on driver, hardware, and usage flags. /**
* Specifies the pixel format of a texture.
*
* Texture format support varies depending on driver, hardware, and usage flags.
* In general, you should use SDL_GPUTextureSupportsFormat to query if a format * In general, you should use SDL_GPUTextureSupportsFormat to query if a format
* is supported before using it. However, there are a few guaranteed formats. * is supported before using it. However, there are a few guaranteed formats.
* *
@@ -153,6 +360,11 @@ typedef enum SDL_GPUIndexElementSize
* *
* Unless D16_UNORM is sufficient for your purposes, always check which * Unless D16_UNORM is sufficient for your purposes, always check which
* of D24/D32 is supported before creating a depth-stencil texture! * of D24/D32 is supported before creating a depth-stencil texture!
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTexture
* \sa SDL_GPUTextureSupportsFormat
*/ */
typedef enum SDL_GPUTextureFormat typedef enum SDL_GPUTextureFormat
{ {
@@ -228,31 +440,67 @@ typedef enum SDL_GPUTextureFormat
SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT
} SDL_GPUTextureFormat; } SDL_GPUTextureFormat;
/**
* Specifies how a texture is intended to be used by the client.
*
* A texture must have at least one usage flag.
* Note that some usage flag combinations are invalid.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTexture
*/
typedef Uint32 SDL_GPUTextureUsageFlags; typedef Uint32 SDL_GPUTextureUsageFlags;
#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< texture supports sampling */ #define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */
#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< texture is a color render target */ #define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */
#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< texture is a depth stencil target */ #define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */
#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< texture supports storage reads in graphics stages */ #define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< texture supports storage reads in the compute stage */ #define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */
#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< texture supports storage writes in the compute stage */ #define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */
/**
* Specifies the type of a texture.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTexture
*/
typedef enum SDL_GPUTextureType typedef enum SDL_GPUTextureType
{ {
SDL_GPU_TEXTURETYPE_2D, SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */
SDL_GPU_TEXTURETYPE_2D_ARRAY, SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */
SDL_GPU_TEXTURETYPE_3D, SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */
SDL_GPU_TEXTURETYPE_CUBE SDL_GPU_TEXTURETYPE_CUBE /**< The texture is a cube image. */
} SDL_GPUTextureType; } SDL_GPUTextureType;
/**
* Specifies the sample count of a texture.
*
* Used in multisampling.
* Note that this value only applies when the texture is used as a render pass attachment.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTexture
* \sa SDL_GPUTextureSupportsSampleCount
*/
typedef enum SDL_GPUSampleCount typedef enum SDL_GPUSampleCount
{ {
SDL_GPU_SAMPLECOUNT_1, SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */
SDL_GPU_SAMPLECOUNT_2, SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */
SDL_GPU_SAMPLECOUNT_4, SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */
SDL_GPU_SAMPLECOUNT_8 SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */
} SDL_GPUSampleCount; } SDL_GPUSampleCount;
/**
* Specifies the face of a cube map.
*
* Can be passed in as the layer field in texture-related structs.
*
* \since This enum is available since SDL 3.0.0
*/
typedef enum SDL_GPUCubeMapFace typedef enum SDL_GPUCubeMapFace
{ {
SDL_GPU_CUBEMAPFACE_POSITIVEX, SDL_GPU_CUBEMAPFACE_POSITIVEX,
@@ -263,36 +511,78 @@ typedef enum SDL_GPUCubeMapFace
SDL_GPU_CUBEMAPFACE_NEGATIVEZ SDL_GPU_CUBEMAPFACE_NEGATIVEZ
} SDL_GPUCubeMapFace; } SDL_GPUCubeMapFace;
/**
* Specifies how a buffer is intended to be used by the client.
*
* A buffer must have at least one usage flag.
* Note that some usage flag combinations are invalid.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUBuffer
*/
typedef Uint32 SDL_GPUBufferUsageFlags; typedef Uint32 SDL_GPUBufferUsageFlags;
#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< buffer is a vertex buffer */ #define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */
#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< buffer is an index buffer */ #define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */
#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< buffer is an indirect buffer */ #define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */
#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< buffer supports storage reads in graphics stages */ #define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< buffer supports storage reads in the compute stage */ #define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */
#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< buffer supports storage writes in the compute stage */ #define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */
/**
* Specifies how a transfer buffer is intended to be used by the client.
*
* Note that mapping and copying FROM an upload transfer buffer or TO a download transfer buffer is undefined behavior.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUTransferBuffer
*/
typedef enum SDL_GPUTransferBufferUsage typedef enum SDL_GPUTransferBufferUsage
{ {
SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD,
SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD
} SDL_GPUTransferBufferUsage; } SDL_GPUTransferBufferUsage;
/**
* Specifies which stage a shader program corresponds to.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUShader
*/
typedef enum SDL_GPUShaderStage typedef enum SDL_GPUShaderStage
{ {
SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_VERTEX,
SDL_GPU_SHADERSTAGE_FRAGMENT SDL_GPU_SHADERSTAGE_FRAGMENT
} SDL_GPUShaderStage; } SDL_GPUShaderStage;
/**
* Specifies the format of shader code.
*
* Each format corresponds to a specific backend that accepts it.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUShader
*/
typedef Uint32 SDL_GPUShaderFormat; typedef Uint32 SDL_GPUShaderFormat;
#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< shaders for NDA'd platforms */ #define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */
#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan */ #define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */
#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_0 shaders for D3D11 */ #define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_0 shaders for D3D11. */
#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL shaders for D3D12 */ #define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL shaders for D3D12. */
#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal */ #define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */
#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< precompiled metallib shaders for Metal */ #define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */
/**
* Specifies the format of a vertex attribute.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUVertexElementFormat typedef enum SDL_GPUVertexElementFormat
{ {
/* 32-bit Signed Integers */ /* 32-bit Signed Integers */
@@ -350,81 +640,151 @@ typedef enum SDL_GPUVertexElementFormat
SDL_GPU_VERTEXELEMENTFORMAT_HALF4 SDL_GPU_VERTEXELEMENTFORMAT_HALF4
} SDL_GPUVertexElementFormat; } SDL_GPUVertexElementFormat;
/**
* Specifies the rate at which vertex attributes are pulled from buffers.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUVertexInputRate typedef enum SDL_GPUVertexInputRate
{ {
SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, /**< Attribute addressing is a function of the vertex index. */
SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 /**< Attribute addressing is a function of the instance index. */
} SDL_GPUVertexInputRate; } SDL_GPUVertexInputRate;
/**
* Specifies the fill mode of the graphics pipeline.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUFillMode typedef enum SDL_GPUFillMode
{ {
SDL_GPU_FILLMODE_FILL, SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */
SDL_GPU_FILLMODE_LINE SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */
} SDL_GPUFillMode; } SDL_GPUFillMode;
/**
* Specifies the facing direction in which triangle faces will be culled.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUCullMode typedef enum SDL_GPUCullMode
{ {
SDL_GPU_CULLMODE_NONE, SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */
SDL_GPU_CULLMODE_FRONT, SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */
SDL_GPU_CULLMODE_BACK SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */
} SDL_GPUCullMode; } SDL_GPUCullMode;
/**
* Specifies the vertex winding that will cause a triangle to be determined to be front-facing.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUFrontFace typedef enum SDL_GPUFrontFace
{ {
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */
SDL_GPU_FRONTFACE_CLOCKWISE SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise winding vertex winding will be considered front-facing. */
} SDL_GPUFrontFace; } SDL_GPUFrontFace;
/**
* Specifies a comparison operator for depth, stencil and sampler operations.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUCompareOp typedef enum SDL_GPUCompareOp
{ {
SDL_GPU_COMPAREOP_NEVER, SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */
SDL_GPU_COMPAREOP_LESS, SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */
SDL_GPU_COMPAREOP_EQUAL, SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */
SDL_GPU_COMPAREOP_LESS_OR_EQUAL, SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */
SDL_GPU_COMPAREOP_GREATER, SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */
SDL_GPU_COMPAREOP_NOT_EQUAL, SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */
SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */
SDL_GPU_COMPAREOP_ALWAYS SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */
} SDL_GPUCompareOp; } SDL_GPUCompareOp;
/**
* Specifies what happens to a stored stencil value if stencil tests fail or pass.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUStencilOp typedef enum SDL_GPUStencilOp
{ {
SDL_GPU_STENCILOP_KEEP, SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */
SDL_GPU_STENCILOP_ZERO, SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */
SDL_GPU_STENCILOP_REPLACE, SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */
SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */
SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */
SDL_GPU_STENCILOP_INVERT, SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */
SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */
SDL_GPU_STENCILOP_DECREMENT_AND_WRAP SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */
} SDL_GPUStencilOp; } SDL_GPUStencilOp;
/**
* Specifies the operator to be used when pixels in a render pass texture attachment are blended with existing pixels in the texture.
*
* The source color is the value written by the fragment shader.
* The destination color is the value currently existing in the texture.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUBlendOp typedef enum SDL_GPUBlendOp
{ {
SDL_GPU_BLENDOP_ADD, SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */
SDL_GPU_BLENDOP_SUBTRACT, SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */
SDL_GPU_BLENDOP_REVERSE_SUBTRACT, SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */
SDL_GPU_BLENDOP_MIN, SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */
SDL_GPU_BLENDOP_MAX SDL_GPU_BLENDOP_MAX /**< max(source, destination) */
} SDL_GPUBlendOp; } SDL_GPUBlendOp;
/**
* Specifies a blending factor to be used when pixels in a render pass texture attachment
* are blended with existing pixels in the texture.
*
* The source color is the value written by the fragment shader.
* The destination color is the value currently existing in the texture.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef enum SDL_GPUBlendFactor typedef enum SDL_GPUBlendFactor
{ {
SDL_GPU_BLENDFACTOR_ZERO, SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */
SDL_GPU_BLENDFACTOR_ONE, SDL_GPU_BLENDFACTOR_ONE, /**< 1 */
SDL_GPU_BLENDFACTOR_SRC_COLOR, SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */
SDL_GPU_BLENDFACTOR_DST_COLOR, SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */
SDL_GPU_BLENDFACTOR_SRC_ALPHA, SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */
SDL_GPU_BLENDFACTOR_DST_ALPHA, SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */
SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */
SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */
SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */
} SDL_GPUBlendFactor; } SDL_GPUBlendFactor;
/**
* Specifies which color components are written in a graphics pipeline.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUGraphicsPipeline
*/
typedef Uint8 SDL_GPUColorComponentFlags; typedef Uint8 SDL_GPUColorComponentFlags;
#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ #define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */
@@ -432,28 +792,58 @@ typedef Uint8 SDL_GPUColorComponentFlags;
#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ #define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */
#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ #define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */
/**
* Specifies a filter operation used by a sampler.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUSampler
*/
typedef enum SDL_GPUFilter typedef enum SDL_GPUFilter
{ {
SDL_GPU_FILTER_NEAREST, SDL_GPU_FILTER_NEAREST, /**< Point filtering. */
SDL_GPU_FILTER_LINEAR SDL_GPU_FILTER_LINEAR /**< Linear filtering. */
} SDL_GPUFilter; } SDL_GPUFilter;
/**
* Specifies a mipmap mode used by a sampler.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUSampler
*/
typedef enum SDL_GPUSamplerMipmapMode typedef enum SDL_GPUSamplerMipmapMode
{ {
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */
} SDL_GPUSamplerMipmapMode; } SDL_GPUSamplerMipmapMode;
/**
* Specifies behavior of texture sampling when the coordinates exceed the 0-1 range.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_CreateGPUSampler
*/
typedef enum SDL_GPUSamplerAddressMode typedef enum SDL_GPUSamplerAddressMode
{ {
SDL_GPU_SAMPLERADDRESSMODE_REPEAT, SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */
SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */
SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */
} SDL_GPUSamplerAddressMode; } SDL_GPUSamplerAddressMode;
/* /**
* Specifies the timing that will be used to present swapchain textures to the OS.
*
* Note that this value affects the behavior of SDL_AcquireGPUSwapchainTexture.
* VSYNC mode will always be supported.
* IMMEDIATE and MAILBOX modes may not be supported on certain systems.
*
* It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming the window
* if you wish to change the present mode to IMMEDIATE or MAILBOX.
*
* VSYNC: * VSYNC:
* Waits for vblank before presenting. * Waits for vblank before presenting. No tearing is possible.
* If there is a pending image to present, the new image is enqueued for presentation. * If there is a pending image to present, the new image is enqueued for presentation.
* Disallows tearing at the cost of visual latency. * Disallows tearing at the cost of visual latency.
* When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight.
@@ -466,6 +856,12 @@ typedef enum SDL_GPUSamplerAddressMode
* If there is a pending image to present, the pending image is replaced by the new image. * If there is a pending image to present, the pending image is replaced by the new image.
* Similar to VSYNC, but with reduced visual latency. * Similar to VSYNC, but with reduced visual latency.
* When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_SetGPUSwapchainParameters
* \sa SDL_WindowSupportsGPUPresentMode
* \sa SDL_AcquireGPUSwapchainTexture
*/ */
typedef enum SDL_GPUPresentMode typedef enum SDL_GPUPresentMode
{ {
@@ -474,15 +870,29 @@ typedef enum SDL_GPUPresentMode
SDL_GPU_PRESENTMODE_MAILBOX SDL_GPU_PRESENTMODE_MAILBOX
} SDL_GPUPresentMode; } SDL_GPUPresentMode;
/* /**
* Specifies the texture format and colorspace of the swapchain textures.
*
* SDR will always be supported.
* Other compositions may not be supported on certain systems.
*
* It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after claiming the window
* if you wish to change the swapchain composition from SDR.
*
* SDR: * SDR:
* B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding.
* SDR_LINEAR: * SDR_LINEAR:
* B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding.
* HDR_EXTENDED_LINEAR: * HDR_EXTENDED_LINEAR:
* R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding.
* HDR10_ST2048: * HDR10_ST2048:
* A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding.
*
* \since This enum is available since SDL 3.0.0
*
* \sa SDL_SetGPUSwapchainParameters
* \sa SDL_WindowSupportsGPUSwapchainComposition
* \sa SDL_AcquireGPUSwapchainTexture
*/ */
typedef enum SDL_GPUSwapchainComposition typedef enum SDL_GPUSwapchainComposition
{ {
@@ -492,6 +902,13 @@ typedef enum SDL_GPUSwapchainComposition
SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048
} SDL_GPUSwapchainComposition; } SDL_GPUSwapchainComposition;
/**
* Specifies a backend API supported by SDL_GPU.
*
* Only one of these will be in use at a time.
*
* \since This enum is available since SDL 3.0.0
*/
typedef enum SDL_GPUDriver typedef enum SDL_GPUDriver
{ {
SDL_GPU_DRIVER_INVALID = -1, SDL_GPU_DRIVER_INVALID = -1,
@@ -1212,12 +1629,18 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture(
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_SetGPUBufferName
* \sa SDL_UploadToGPUBuffer * \sa SDL_UploadToGPUBuffer
* \sa SDL_DownloadFromGPUBuffer
* \sa SDL_CopyGPUBufferToBuffer
* \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUVertexBuffers
* \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUIndexBuffer
* \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUVertexStorageBuffers
* \sa SDL_BindGPUFragmentStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers
* \sa SDL_DrawGPUPrimitivesIndirect
* \sa SDL_DrawGPUIndexedPrimitivesIndirect
* \sa SDL_BindGPUComputeStorageBuffers * \sa SDL_BindGPUComputeStorageBuffers
* \sa SDL_DispatchGPUComputeIndirect
* \sa SDL_ReleaseGPUBuffer * \sa SDL_ReleaseGPUBuffer
*/ */
extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer(
@@ -1430,22 +1853,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline(
SDL_GPUDevice *device, SDL_GPUDevice *device,
SDL_GPUGraphicsPipeline *graphicsPipeline); SDL_GPUGraphicsPipeline *graphicsPipeline);
/*
* COMMAND BUFFERS
*
* Render state is managed via command buffers.
* When setting render state, that state is always local to the command buffer.
*
* Commands only begin execution on the GPU once Submit is called.
* Once the command buffer is submitted, it is no longer valid to use it.
*
* Command buffers are executed in submission order. If you submit command buffer A and then command buffer B
* all commands in A will begin executing before any command in B begins executing.
*
* In multi-threading scenarios, you should acquire and submit a command buffer on the same thread.
* As long as you satisfy this requirement, all functionality related to command buffers is thread-safe.
*/
/** /**
* Acquire a command buffer. * Acquire a command buffer.
* *
@@ -2339,7 +2746,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode(
* *
* The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and
* SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain
* parameters, you must call SetSwapchainParameters after claiming the window. * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the window.
* *
* \param device a GPU context. * \param device a GPU context.
* \param window an SDL_Window. * \param window an SDL_Window.