From 1c8c0144811c7d8a3aab96497d2170d37c1a0771 Mon Sep 17 00:00:00 2001 From: Evan Hemsley <2342303+thatcosmonaut@users.noreply.github.com> Date: Wed, 4 Sep 2024 18:24:11 -0700 Subject: [PATCH] GPU: Document opaque handles and enums (#10700) --- include/SDL3/SDL_gpu.h | 633 +++++++++++++++++++++++++++++++++-------- 1 file changed, 520 insertions(+), 113 deletions(-) diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h index 06478b036b..080d6275d0 100644 --- a/include/SDL3/SDL_gpu.h +++ b/include/SDL3/SDL_gpu.h @@ -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.