mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

GPU: Fix documentation formatting

Browse Source
This commit is contained in:
cosmonaut 2024-09-05 09:57:26 -07:00
parent 42a0df91bf
commit cba5ccb9cf
1 changed files with 133 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
include/SDL3/SDL_gpu.h
View File

@ -307,28 +307,71 @@ typedef enum SDL_GPUIndexElementSize
* a format is supported before using it. However, there are a few guaranteed * a format is supported before using it. However, there are a few guaranteed
* formats. * formats.
* *
* For SAMPLER usage, the following formats are universally supported: - * For SAMPLER usage, the following formats are universally supported:
* R8G8B8A8_UNORM - B8G8R8A8_UNORM - R8_UNORM - R8_SNORM - R8G8_UNORM -
* R8G8_SNORM - R8G8B8A8_SNORM - R16_FLOAT - R16G16_FLOAT - R16G16B16A16_FLOAT
* - R32_FLOAT - R32G32_FLOAT - R32G32B32A32_FLOAT - R11G11B10_UFLOAT -
* R8G8B8A8_UNORM_SRGB - B8G8R8A8_UNORM_SRGB - D16_UNORM
* *
* For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM
* R8G8B8A8_UNORM - B8G8R8A8_UNORM - R8_UNORM - R16_FLOAT - R16G16_FLOAT - * - B8G8R8A8_UNORM
* R16G16B16A16_FLOAT - R32_FLOAT - R32G32_FLOAT - R32G32B32A32_FLOAT - * - R8_UNORM
* R8_UINT - R8G8_UINT - R8G8B8A8_UINT - R16_UINT - R16G16_UINT - * - R8_SNORM
* R16G16B16A16_UINT - R8_INT - R8G8_INT - R8G8B8A8_INT - R16_INT - R16G16_INT * - R8G8_UNORM
* - R16G16B16A16_INT - R8G8B8A8_UNORM_SRGB - B8G8R8A8_UNORM_SRGB * - R8G8_SNORM
* - R8G8B8A8_SNORM
* - R16_FLOAT
* - R16G16_FLOAT
* - R16G16B16A16_FLOAT
* - R32_FLOAT
* - R32G32_FLOAT
* - R32G32B32A32_FLOAT
* - R11G11B10_UFLOAT
* - R8G8B8A8_UNORM_SRGB
* - B8G8R8A8_UNORM_SRGB
* - D16_UNORM
* *
* For STORAGE usages, the following formats are universally supported: - * For COLOR_TARGET usage, the following formats are universally supported:
* R8G8B8A8_UNORM - R8G8B8A8_SNORM - R16G16B16A16_FLOAT - R32_FLOAT - *
* R32G32_FLOAT - R32G32B32A32_FLOAT - R8G8B8A8_UINT - R16G16B16A16_UINT - * - R8G8B8A8_UNORM
* R8G8B8A8_INT - R16G16B16A16_INT * - B8G8R8A8_UNORM
* - R8_UNORM
* - R16_FLOAT
* - R16G16_FLOAT
* - R16G16B16A16_FLOAT
* - R32_FLOAT
* - R32G32_FLOAT
* - R32G32B32A32_FLOAT
* - R8_UINT
* - R8G8_UINT
* - R8G8B8A8_UINT
* - R16_UINT
* - R16G16_UINT
* - R16G16B16A16_UINT
* - R8_INT
* - R8G8_INT
* - R8G8B8A8_INT
* - R16_INT
* - R16G16_INT
* - R16G16B16A16_INT
* - R8G8B8A8_UNORM_SRGB
* - B8G8R8A8_UNORM_SRGB
*
* For STORAGE usages, the following formats are universally supported:
*
* - R8G8B8A8_UNORM
* - R8G8B8A8_SNORM
* - R16G16B16A16_FLOAT
* - R32_FLOAT
* - R32G32_FLOAT
* - R32G32B32A32_FLOAT
* - R8G8B8A8_UINT
* - R16G16B16A16_UINT
* - R8G8B8A8_INT
* - R16G16B16A16_INT
* *
* For DEPTH_STENCIL_TARGET usage, the following formats are universally * For DEPTH_STENCIL_TARGET usage, the following formats are universally
* supported: - D16_UNORM - Either (but not necessarily both!) D24_UNORM or * supported:
* D32_SFLOAT - Either (but not necessarily both!) D24_UNORM_S8_UINT or *
* D32_SFLOAT_S8_UINT * - D16_UNORM
* - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT
* - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT
* *
* Unless D16_UNORM is sufficient for your purposes, always check which of * Unless D16_UNORM is sufficient for your purposes, always check which of
* D24/D32 is supported before creating a depth-stencil texture! * D24/D32 is supported before creating a depth-stencil texture!
@ -664,7 +707,7 @@ typedef enum SDL_GPUCullMode
typedef enum SDL_GPUFrontFace typedef enum SDL_GPUFrontFace
{ {
SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ 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_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */
} SDL_GPUFrontFace; } SDL_GPUFrontFace;
/** /**
@ -820,13 +863,14 @@ typedef enum SDL_GPUSamplerAddressMode
* It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming
* the window if you wish to change the present mode to IMMEDIATE or MAILBOX. * the window if you wish to change the present mode to IMMEDIATE or MAILBOX.
* *
* VSYNC: Waits for vblank before presenting. No tearing is possible. If there * - VSYNC: Waits for vblank before presenting. No tearing is possible. If there
* is a pending image to present, the new image is enqueued for presentation. * 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 * Disallows tearing at the cost of visual latency. When using this present
* mode, AcquireSwapchainTexture will block if too many frames are in flight. * mode, AcquireSwapchainTexture will block if too many frames are in flight.
* IMMEDIATE: Immediately presents. Lowest latency option, but tearing may * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may
* occur. When using this mode, AcquireSwapchainTexture will return NULL if * occur. When using this mode, AcquireSwapchainTexture will return NULL if
* too many frames are in flight. MAILBOX: Waits for vblank before presenting. * too many frames are in flight.
* - MAILBOX: Waits for vblank before presenting.
* No tearing is possible. If there is a pending image to present, the pending * No tearing is possible. If there is a pending image to present, the pending
* image is replaced by the new image. Similar to VSYNC, but with reduced * image is replaced by the new image. Similar to VSYNC, but with reduced
* visual latency. When using this mode, AcquireSwapchainTexture will return * visual latency. When using this mode, AcquireSwapchainTexture will return
@ -855,11 +899,14 @@ typedef enum SDL_GPUPresentMode
* claiming the window if you wish to change the swapchain composition from * 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 * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB
* encoding. SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel * encoding.
* values are in nonlinear sRGB encoding. HDR_EXTENDED_LINEAR: * - SDR_LINEAR: 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 * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear
* encoding. HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values * encoding.
* - HDR10_ST2048: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values
* are in PQ ST2048 encoding. * are in PQ ST2048 encoding.
* *
* \since This enum is available since SDL 3.0.0 * \since This enum is available since SDL 3.0.0
@ -1462,25 +1509,30 @@ extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device
/** /**
* Creates a pipeline object to be used in a compute workflow. * Creates a pipeline object to be used in a compute workflow.
* *
* Shader resource bindings must be authored to follow a particular order. For * Shader resource bindings must be authored to follow a particular order depending on the shader format.
* SPIR-V shaders, use the following resource sets: 0: Read-only storage
* textures, followed by read-only storage buffers 1: Write-only storage
* textures, followed by write-only storage buffers 2: Uniform buffers
* *
* For DXBC Shader Model 5_0 shaders, use the following register order: For t * For SPIR-V shaders, use the following resource sets:
* registers: Read-only storage textures, followed by read-only storage
* buffers For u registers: Write-only storage textures, followed by
* write-only storage buffers For b registers: Uniform buffers
* *
* For DXIL shaders, use the following register order: (t[n], space0): * - 0: Read-only storage textures, followed by read-only storage buffers
* Read-only storage textures, followed by read-only storage buffers (u[n], * - 1: Write-only storage textures, followed by write-only storage buffers
* space1): Write-only storage textures, followed by write-only storage * - 2: Uniform buffers
* buffers (b[n], space2): Uniform buffers
* *
* For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, * For DXBC Shader Model 5_0 shaders, use the following register order:
* followed by write-only storage buffers, followed by write-only storage *
* buffers For [[texture]]: Read-only storage textures, followed by write-only * - t registers: Read-only storage textures, followed by read-only storage buffers
* storage textures * - u registers: Write-only storage textures, followed by write-only storage buffers
* - b registers: Uniform buffers
*
* For DXIL shaders, use the following register order:
*
* - (t[n], space0): Read-only storage textures, followed by read-only storage buffers
* - (u[n], space1): Write-only storage textures, followed by write-only storage buffers
* - (b[n], space2): Uniform buffers
*
* For MSL/metallib, use the following order:
*
* - [[buffer]]: Uniform buffers, followed by write-only storage buffers, followed by write-only storage buffers
* - [[texture]]: Read-only storage textures, followed by write-only storage textures
* *
* \param device a GPU Context. * \param device a GPU Context.
* \param computePipelineCreateInfo a struct describing the state of the * \param computePipelineCreateInfo a struct describing the state of the
@ -1536,31 +1588,49 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler(
/** /**
* Creates a shader to be used when creating a graphics pipeline. * Creates a shader to be used when creating a graphics pipeline.
* *
* Shader resource bindings must be authored to follow a particular order * Shader resource bindings must be authored to follow a particular order depending on the shader format.
* depending on the shader format.
* *
* For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: * For SPIR-V shaders, use the following resource sets:
* Sampled textures, followed by storage textures, followed by storage buffers
* 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by
* storage textures, followed by storage buffers 3: Uniform buffers
* *
* For DXBC Shader Model 5_0 shaders, use the following register order: For t * For vertex shaders:
* registers: Sampled textures, followed by storage textures, followed by
* storage buffers For s registers: Samplers with indices corresponding to the
* sampled textures For b registers: Uniform buffers
* *
* For DXIL shaders, use the following register order: For vertex shaders: * - 0: Sampled textures, followed by storage textures, followed by storage buffers
* (t[n], space0): Sampled textures, followed by storage textures, followed by * - 1: Uniform buffers
* storage buffers (s[n], space0): Samplers with indices corresponding to the
* sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n],
* space2): Sampled textures, followed by storage textures, followed by
* storage buffers (s[n], space2): Samplers with indices corresponding to the
* sampled textures (b[n], space3): Uniform buffers
* *
* For MSL/metallib, use the following order: For [[texture]]: Sampled * For fragment shaders:
* textures, followed by storage textures For [[sampler]]: Samplers with *
* indices corresponding to the sampled textures For [[buffer]]: Uniform * - 2: Sampled textures, followed by storage textures, followed by storage buffers
* buffers, followed by storage buffers. Vertex buffer 0 is bound at * - 3: Uniform buffers
*
* For DXBC Shader Model 5_0 shaders, use the following register order:
*
* - t registers: Sampled textures, followed by storage textures, followed by storage buffers
* - s registers: Samplers with indices corresponding to the sampled textures
* - b registers: Uniform buffers
*
* For DXIL shaders, use the following register order:
*
* For vertex shaders:
*
* - (t[n], space0): Sampled textures, followed by storage textures, followed by
* storage buffers
* - (s[n], space0): Samplers with indices corresponding to the
* sampled textures
* - (b[n], space1): Uniform buffers
*
* For pixel shaders:
*
* - (t[n], space2): Sampled textures, followed by storage textures, followed by
* storage buffers
* - (s[n], space2): Samplers with indices corresponding to the
* sampled textures
* - (b[n], space3): Uniform buffers
*
* For MSL/metallib, use the following order:
*
* - [[texture]]: Sampled textures, followed by storage textures
* - [[sampler]]: Samplers with indices corresponding to the sampled textures
* - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 is bound at
* [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than
* manually authoring vertex buffer indices, use the [[stage_in]] attribute * manually authoring vertex buffer indices, use the [[stage_in]] attribute
* which will automatically use the vertex input information from the * which will automatically use the vertex input information from the