From cba5ccb9cf318e820a2f3a91b0b95ae881fba205 Mon Sep 17 00:00:00 2001
From: cosmonaut <[EMAIL REDACTED]>
Date: Thu, 5 Sep 2024 09:57:26 -0700
Subject: [PATCH] GPU: Fix documentation formatting
---
include/SDL3/SDL_gpu.h | 208 +++++++++++++++++++++++++++--------------
1 file changed, 139 insertions(+), 69 deletions(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 674ead366d260..dcf393b18fb39 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -307,28 +307,71 @@ typedef enum SDL_GPUIndexElementSize
* a format is supported before using it. However, there are a few guaranteed
* formats.
*
- * 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 - 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 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
+ * - 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
- * supported: - 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
+ * supported:
+ *
+ * - 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
* D24/D32 is supported before creating a depth-stencil texture!
@@ -664,7 +707,7 @@ typedef enum SDL_GPUCullMode
typedef enum SDL_GPUFrontFace
{
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;
/**
@@ -820,13 +863,14 @@ typedef enum SDL_GPUSamplerAddressMode
* 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. 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.
* Disallows tearing at the cost of visual latency. When using this present
* 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
- * 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
* image is replaced by the new image. Similar to VSYNC, but with reduced
* 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
* SDR.
*
- * SDR: 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. HDR_EXTENDED_LINEAR:
+ * - SDR: 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.
+ * - HDR_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.
*
* \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.
*
- * Shader resource bindings must be authored to follow a particular order. For
- * SPIR-V shaders, use the following resource sets: 0: Read-only storage
- * textures, followed by read-only storage buffers 1: Write-only storage
- * textures, followed by write-only storage buffers 2: Uniform buffers
+ * Shader resource bindings must be authored to follow a particular order depending on the shader format.
+ *
+ * For SPIR-V shaders, use the following resource sets:
+ *
+ * - 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:
+ *
+ * - t registers: Read-only storage textures, followed by read-only storage buffers
+ * - u registers: Write-only storage textures, followed by write-only storage buffers
+ * - b registers: Uniform buffers
*
- * For DXBC Shader Model 5_0 shaders, use the following register order: For t
- * registers: Read-only storage textures, followed by read-only storage
- * buffers For u registers: Write-only storage textures, followed by
- * write-only storage buffers For b registers: Uniform buffers
+ * For DXIL shaders, use the following register order:
*
- * 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
+ * - (t[n], space0): Read-only storage textures, followed by read-only storage buffers
+ * - (u[n], space1): Write-only storage textures, followed by write-only storage buffers
+ * - (b[n], space2): Uniform buffers
*
- * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers,
- * followed by write-only storage buffers, followed by write-only storage
- * buffers For [[texture]]: Read-only storage textures, followed by write-only
- * storage textures
+ * 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 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.
*
- * Shader resource bindings must be authored to follow a particular order
- * depending on the shader format.
- *
- * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0:
- * Sampled textures, followed by storage textures, followed by storage buffers
- * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by
- * storage textures, followed by storage buffers 3: Uniform buffers
- *
- * For DXBC Shader Model 5_0 shaders, use the following register order: For t
- * registers: Sampled textures, followed by storage textures, followed by
- * storage buffers For s registers: Samplers with indices corresponding to the
- * sampled textures For b registers: Uniform buffers
- *
- * For DXIL shaders, use the following register order: For vertex shaders:
- * (t[n], space0): Sampled textures, followed by storage textures, followed by
- * storage buffers (s[n], space0): Samplers with indices corresponding to the
- * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n],
- * space2): Sampled textures, followed by storage textures, followed by
- * storage buffers (s[n], space2): Samplers with indices corresponding to the
- * sampled textures (b[n], space3): Uniform buffers
- *
- * For MSL/metallib, use the following order: For [[texture]]: Sampled
- * textures, followed by storage textures For [[sampler]]: Samplers with
- * indices corresponding to the sampled textures For [[buffer]]: Uniform
- * buffers, followed by storage buffers. Vertex buffer 0 is bound at
+ * Shader resource bindings must be authored to follow a particular order depending on the shader format.
+ *
+ * For SPIR-V shaders, use the following resource sets:
+ *
+ * For vertex shaders:
+ *
+ * - 0: Sampled textures, followed by storage textures, followed by storage buffers
+ * - 1: Uniform buffers
+ *
+ * For fragment shaders:
+ *
+ * - 2: Sampled textures, followed by storage textures, followed by storage buffers
+ * - 3: Uniform buffers
+ *
+ * For DXBC Shader Model 5_0 shaders, use the following register order:
+ *
+ * - 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
* manually authoring vertex buffer indices, use the [[stage_in]] attribute
* which will automatically use the vertex input information from the