From 7647f16ae107d286e0a93eabdece818018fbe8fb Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Thu, 26 Dec 2024 18:03:51 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_gpu.h | 71 +++++++++++++++++++++---------------------
1 file changed, 36 insertions(+), 35 deletions(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 68b5c96b2788b..f023eddaeb543 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -162,17 +162,17 @@
*
* **Question: Why is my shader not working?**
*
- * Answer: A common oversight when using shaders is not properly laying out the
- * shader resources/registers correctly. The GPU API is very strict with how it
- * wants resources to be laid out and it's difficult for the API to
+ * Answer: A common oversight when using shaders is not properly laying out
+ * the shader resources/registers correctly. The GPU API is very strict with
+ * how it wants resources to be laid out and it's difficult for the API to
* automatically validate shaders to see if they have a compatible layout. See
* the documentation for SDL_CreateGPUShader() and
* SDL_CreateGPUComputePipeline() for information on the expected layout.
*
- * Another common issue is not setting the correct number of samplers, textures,
- * and buffers in SDL_GPUShaderCreateInfo. If possible use shader reflection to
- * extract the required information from the shader automatically instead of
- * manually filling in the struct's values.
+ * Another common issue is not setting the correct number of samplers,
+ * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader
+ * reflection to extract the required information from the shader
+ * automatically instead of manually filling in the struct's values.
*
* ## System Requirements
*
@@ -211,54 +211,55 @@
* keeps its value throughout the command buffer until you call the relevant
* Push function on that slot again.
*
- * For example, you could write your vertex shaders to read a camera matrix from
- * uniform binding slot 0, push the camera matrix at the start of the command
- * buffer, and that data will be used for every subsequent draw call.
+ * For example, you could write your vertex shaders to read a camera matrix
+ * from uniform binding slot 0, push the camera matrix at the start of the
+ * command buffer, and that data will be used for every subsequent draw call.
*
* It is valid to push uniform data during a render or compute pass.
*
- * Uniforms are best for pushing small amounts of data. If you are pushing more
- * than a matrix or two per call you should consider using a storage buffer
- * instead.
+ * Uniforms are best for pushing small amounts of data. If you are pushing
+ * more than a matrix or two per call you should consider using a storage
+ * buffer instead.
*
* ## A Note On Cycling
*
- * When using a command buffer, operations do not occur immediately - they occur
- * some time after the command buffer is submitted.
+ * When using a command buffer, operations do not occur immediately - they
+ * occur some time after the command buffer is submitted.
*
* When a resource is used in a pending or active command buffer, it is
- * considered to be "bound". When a resource is no longer used in any pending or
- * active command buffers, it is considered to be "unbound".
+ * considered to be "bound". When a resource is no longer used in any pending
+ * or active command buffers, it is considered to be "unbound".
*
- * If data resources are bound, it is unspecified when that data will be unbound
- * unless you acquire a fence when submitting the command buffer and wait on it.
- * However, this doesn't mean you need to track resource usage manually.
+ * If data resources are bound, it is unspecified when that data will be
+ * unbound unless you acquire a fence when submitting the command buffer and
+ * wait on it. However, this doesn't mean you need to track resource usage
+ * manually.
*
* All of the functions and structs that involve writing to a resource have a
* "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all
* effectively function as ring buffers on internal resources. When cycle is
* true, if the resource is bound, the cycle rotates to the next unbound
- * internal resource, or if none are available, a new one is created. This means
- * you don't have to worry about complex state tracking and synchronization as
- * long as cycling is correctly employed.
+ * internal resource, or if none are available, a new one is created. This
+ * means you don't have to worry about complex state tracking and
+ * synchronization as long as cycling is correctly employed.
*
* For example: you can call SDL_MapGPUTransferBuffer(), write texture data,
* SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next
* time you write texture data to the transfer buffer, if you set the cycle
- * param to true, you don't have to worry about overwriting any data that is not
- * yet uploaded.
+ * param to true, you don't have to worry about overwriting any data that is
+ * not yet uploaded.
*
* Another example: If you are using a texture in a render pass every frame,
- * this can cause a data dependency between frames. If you set cycle to true in
- * the SDL_GPUColorTargetInfo struct, you can prevent this data dependency.
+ * this can cause a data dependency between frames. If you set cycle to true
+ * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency.
*
- * Cycling will never undefine already bound data. When cycling, all data in the
- * resource is considered to be undefined for subsequent commands until that
- * data is written again. You must take care not to read undefined data.
+ * Cycling will never undefine already bound data. When cycling, all data in
+ * the resource is considered to be undefined for subsequent commands until
+ * that data is written again. You must take care not to read undefined data.
*
- * Note that when cycling a texture, the entire texture will be cycled, even if
- * only part of the texture is used in the call, so you must consider the entire
- * texture to contain undefined data after cycling.
+ * Note that when cycling a texture, the entire texture will be cycled, even
+ * if only part of the texture is used in the call, so you must consider the
+ * entire texture to contain undefined data after cycling.
*
* You must also take care not to overwrite a section of data that has been
* referenced in a command without cycling first. It is OK to overwrite
@@ -1214,8 +1215,8 @@ typedef enum SDL_GPUPresentMode
*
* - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding.
* - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are
- * stored in memory in sRGB encoding but accessed in shaders in "linear sRGB"
- * encoding which is sRGB but with a linear transfer function.
+ * stored in memory in sRGB encoding but accessed in shaders in "linear
+ * sRGB" encoding which is sRGB but with a linear transfer function.
* - HDR_EXTENDED_LINEAR: R16G16B16A16_SFLOAT swapchain. Pixel values are in
* extended linear sRGB encoding and permits values outside of the [0, 1]
* range.