mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-05 19:08:12 +00:00
Code Issues 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 */
/**
* An opaque handle representing the SDL_GPU context.
*
* \since This struct is available since SDL 3.0.0
*/
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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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
{
SDL_GPU_PRIMITIVETYPE_POINTLIST,
SDL_GPU_PRIMITIVETYPE_LINELIST,
SDL_GPU_PRIMITIVETYPE_LINESTRIP,
SDL_GPU_PRIMITIVETYPE_TRIANGLELIST,
SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP
SDL_GPU_PRIMITIVETYPE_POINTLIST, /**< A series of separate points. */
SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */
SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */
SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */
SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP /**< A series of connected triangles. */
} 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
{
SDL_GPU_LOADOP_LOAD,
SDL_GPU_LOADOP_CLEAR,
SDL_GPU_LOADOP_DONT_CARE
SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */
SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */
SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */
} 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
{
SDL_GPU_STOREOP_STORE,
SDL_GPU_STOREOP_DONT_CARE
SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */
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;
/**
* 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
{
SDL_GPU_INDEXELEMENTSIZE_16BIT,
SDL_GPU_INDEXELEMENTSIZE_32BIT
SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */
SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */
} 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
* 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
* 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
{
@@ -228,31 +440,67 @@ typedef enum SDL_GPUTextureFormat
SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT
} 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;
#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_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_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_SAMPLER (1u << 0) /**< Texture supports sampling. */
#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_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_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
{
SDL_GPU_TEXTURETYPE_2D,
SDL_GPU_TEXTURETYPE_2D_ARRAY,
SDL_GPU_TEXTURETYPE_3D,
SDL_GPU_TEXTURETYPE_CUBE
SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */
SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */
SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */
SDL_GPU_TEXTURETYPE_CUBE /**< The texture is a cube image. */
} 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
{
SDL_GPU_SAMPLECOUNT_1,
SDL_GPU_SAMPLECOUNT_2,
SDL_GPU_SAMPLECOUNT_4,
SDL_GPU_SAMPLECOUNT_8
SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */
SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */
SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */
SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */
} 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
{
SDL_GPU_CUBEMAPFACE_POSITIVEX,
@@ -263,36 +511,78 @@ typedef enum SDL_GPUCubeMapFace
SDL_GPU_CUBEMAPFACE_NEGATIVEZ
} 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;
#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_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_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_VERTEX (1u << 0) /**< Buffer is a vertex 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_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_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
{
SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD,
SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD
} 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
{
SDL_GPU_SHADERSTAGE_VERTEX,
SDL_GPU_SHADERSTAGE_FRAGMENT
} 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;
#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_DXBC (1u << 2) /**< DXBC SM5_0 shaders for D3D11 */
#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_METALLIB (1u << 5) /**< precompiled metallib shaders for Metal */
#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_DXBC (1u << 2) /**< DXBC SM5_0 shaders for D3D11. */
#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_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
{
/* 32-bit Signed Integers */
@@ -350,81 +640,151 @@ typedef enum SDL_GPUVertexElementFormat
SDL_GPU_VERTEXELEMENTFORMAT_HALF4
} 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
{
SDL_GPU_VERTEXINPUTRATE_VERTEX = 0,
SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1
SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, /**< Attribute addressing is a function of the vertex index. */
SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 /**< Attribute addressing is a function of the instance index. */
} 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
{
SDL_GPU_FILLMODE_FILL,
SDL_GPU_FILLMODE_LINE
SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */
SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */
} 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
{
SDL_GPU_CULLMODE_NONE,
SDL_GPU_CULLMODE_FRONT,
SDL_GPU_CULLMODE_BACK
SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */
SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */
SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */
} 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
{
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE,
SDL_GPU_FRONTFACE_CLOCKWISE
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */
SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise winding vertex winding will be considered front-facing. */
} 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
{
SDL_GPU_COMPAREOP_NEVER,
SDL_GPU_COMPAREOP_LESS,
SDL_GPU_COMPAREOP_EQUAL,
SDL_GPU_COMPAREOP_LESS_OR_EQUAL,
SDL_GPU_COMPAREOP_GREATER,
SDL_GPU_COMPAREOP_NOT_EQUAL,
SDL_GPU_COMPAREOP_GREATER_OR_EQUAL,
SDL_GPU_COMPAREOP_ALWAYS
SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */
SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */
SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */
SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */
SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */
SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */
SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */
SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */
} 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
{
SDL_GPU_STENCILOP_KEEP,
SDL_GPU_STENCILOP_ZERO,
SDL_GPU_STENCILOP_REPLACE,
SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP,
SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP,
SDL_GPU_STENCILOP_INVERT,
SDL_GPU_STENCILOP_INCREMENT_AND_WRAP,
SDL_GPU_STENCILOP_DECREMENT_AND_WRAP
SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */
SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */
SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */
SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */
SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */
SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */
SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */
SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */
} 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
{
SDL_GPU_BLENDOP_ADD,
SDL_GPU_BLENDOP_SUBTRACT,
SDL_GPU_BLENDOP_REVERSE_SUBTRACT,
SDL_GPU_BLENDOP_MIN,
SDL_GPU_BLENDOP_MAX
SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */
SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */
SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */
SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */
SDL_GPU_BLENDOP_MAX /**< max(source, destination) */
} 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
{
SDL_GPU_BLENDFACTOR_ZERO,
SDL_GPU_BLENDFACTOR_ONE,
SDL_GPU_BLENDFACTOR_SRC_COLOR,
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR,
SDL_GPU_BLENDFACTOR_DST_COLOR,
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR,
SDL_GPU_BLENDFACTOR_SRC_ALPHA,
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA,
SDL_GPU_BLENDFACTOR_DST_ALPHA,
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA,
SDL_GPU_BLENDFACTOR_CONSTANT_COLOR,
SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR,
SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE
SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */
SDL_GPU_BLENDFACTOR_ONE, /**< 1 */
SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */
SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */
SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */
SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */
SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */
SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */
SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */
SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */
SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */
} 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;
#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_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
{
SDL_GPU_FILTER_NEAREST,
SDL_GPU_FILTER_LINEAR
SDL_GPU_FILTER_NEAREST, /**< Point filtering. */
SDL_GPU_FILTER_LINEAR /**< Linear filtering. */
} 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
{
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST,
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR
SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */
SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */
} 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
{
SDL_GPU_SAMPLERADDRESSMODE_REPEAT,
SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT,
SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE
SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */
SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */
SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */
} 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:
* 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.
* Disallows tearing at the cost of visual latency.
* 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.
* Similar to VSYNC, but with reduced visual latency.
* 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
{
@@ -474,15 +870,29 @@ typedef enum SDL_GPUPresentMode
SDL_GPU_PRESENTMODE_MAILBOX
} 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:
* 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:
* 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:
* 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:
* 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
{
@@ -492,6 +902,13 @@ typedef enum SDL_GPUSwapchainComposition
SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048
} 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
{
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.
*
* \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
*/
extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer(
@@ -1430,22 +1853,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline(
SDL_GPUDevice *device,
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.
*
@@ -2339,7 +2746,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode(
*
* 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.
* parameters, you must call SDL_SetGPUSwapchainParameters after claiming the window.
*
* \param device a GPU context.
* \param window an SDL_Window.