Sync SDL3 wiki -> header

include/SDL3/SDL_gpu.h

@@ -24,16 +24,16 @@
 /**
  * # CategoryGPU
  *
- * The GPU API offers a cross-platform way for apps to talk to modern
+ * The GPU API offers a cross-platform way for apps to talk to modern graphics
- * graphics hardware. It offers both 3D graphics and "compute" support,
+ * hardware. It offers both 3D graphics and "compute" support, in the style of
- * in the style of Metal, Vulkan, and Direct3D 12.
+ * Metal, Vulkan, and Direct3D 12.
  *
  * A basic workflow might be something like this:
  *
- * The app creates a GPU device with SDL_GPUCreateDevice(), and assigns it
+ * The app creates a GPU device with SDL_GPUCreateDevice(), and assigns it to
- * to a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking
+ * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you
- * you can render offscreen entirely, perhaps for image processing, and not
+ * can render offscreen entirely, perhaps for image processing, and not use a
- * use a window at all.
+ * window at all.
  *
  * Next the app prepares static data (things that are created once and used
  * over and over). For example:
@@ -48,25 +48,26 @@
  *
  * To render, the app creates one or more command buffers, with
  * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering
- * instructions that will be submitted to the GPU in batch. Complex scenes
+ * instructions that will be submitted to the GPU in batch. Complex scenes can
- * can use multiple command buffers, maybe configured across multiple threads
+ * use multiple command buffers, maybe configured across multiple threads in
- * in parallel, as long as they are submitted in the correct order, but many
+ * parallel, as long as they are submitted in the correct order, but many apps
- * apps will just need one command buffer per frame.
+ * will just need one command buffer per frame.
  *
  * Rendering can happen to a texture (what other APIs call a "render target")
- * or it can happen to the swapchain texture (which is just a special texture that
+ * or it can happen to the swapchain texture (which is just a special texture
- * represents a window's contents). The app can use SDL_AcquireGPUSwapchainTexture()
+ * that represents a window's contents). The app can use
- * to render to the window.
+ * SDL_AcquireGPUSwapchainTexture() to render to the window.
  *
  * Rendering actually happens in a Render Pass, which is encoded into a
- * command buffer. One can encode multiple render passes (or alternate
+ * command buffer. One can encode multiple render passes (or alternate between
- * between render and compute passes) in a single command buffer, but many
+ * render and compute passes) in a single command buffer, but many apps might
- * apps might simply need a single render pass in a single command buffer.
+ * simply need a single render pass in a single command buffer. Render Passes
- * Render Passes can render to up to four color textures and one depth texture simultaneously.
+ * can render to up to four color textures and one depth texture
- * If the set of textures being rendered to needs to change, the Render Pass must be ended and a new one must be begun.
+ * simultaneously. If the set of textures being rendered to needs to change,
+ * the Render Pass must be ended and a new one must be begun.
  *
- * The app calls SDL_BeginGPURenderPass().
+ * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for
- * Then it sets states it needs for each draw:
+ * each draw:
  *
  * - SDL_BindGPUGraphicsPipeline
  * - SDL_SetGPUViewport
@@ -82,24 +83,27 @@
  * - etc
  *
  * After all the drawing commands for a pass are complete, the app should call
- * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is reset.
+ * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is
+ * reset.
  *
- * The app can begin new Render Passes and make new draws in the same command buffer
+ * The app can begin new Render Passes and make new draws in the same command
- * until the entire scene is rendered.
+ * buffer until the entire scene is rendered.
  *
- * Once all of the render commands for the scene are complete,
+ * Once all of the render commands for the scene are complete, the app calls
- * the app calls SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing.
+ * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing.
  *
- * If the app needs to read back data from texture or buffers, the API
+ * If the app needs to read back data from texture or buffers, the API has an
- * has an efficient way of doing this, provided that the app is willing to tolerate some latency.
+ * efficient way of doing this, provided that the app is willing to tolerate
- * When the app uses SDL_DownloadFromGPUTexture() or SDL_DownloadFromGPUBuffer(), submitting the command buffer with
+ * some latency. When the app uses SDL_DownloadFromGPUTexture() or
- * SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that the app
+ * SDL_DownloadFromGPUBuffer(), submitting the command buffer with
- * can poll or wait on in a thread. Once the fence indicates that the command buffer is done processing,
+ * SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that the
- * it is safe to read the downloaded data. Make sure to call SDL_ReleaseGPUFence() when done with the fence.
+ * app can poll or wait on in a thread. Once the fence indicates that the
+ * command buffer is done processing, it is safe to read the downloaded data.
+ * Make sure to call SDL_ReleaseGPUFence() when done with the fence.
  *
  * The API also has "compute" support. The app calls SDL_GPUBeginComputePass()
- * with compute-writeable textures and/or buffers, which can be written to in a compute shader.
+ * with compute-writeable textures and/or buffers, which can be written to in
- * Then it sets states it needs for the compute dispatches:
+ * a compute shader. Then it sets states it needs for the compute dispatches:
  *
  * - SDL_BindGPUComputePipeline
  * - SDL_BindGPUComputeStorageBuffers
@@ -111,31 +115,38 @@
  *
  * For advanced users, this opens up powerful GPU-driven workflows.
  *
- * Graphics and compute pipelines require the use of shaders, which as mentioned above are small programs
+ * Graphics and compute pipelines require the use of shaders, which as
- * executed on the GPU. Each backend (Vulkan, Metal, D3D12) requires a different shader format.
+ * mentioned above are small programs executed on the GPU. Each backend
- * When the app creates the GPU device, the app lets the device know which shader formats the app can provide.
+ * (Vulkan, Metal, D3D12) requires a different shader format. When the app
- * It will then select the appropriate backend depending on the available shader formats and the backends available on the platform.
+ * creates the GPU device, the app lets the device know which shader formats
- * When creating shaders, the app must provide the correct shader for the selected backend.
+ * the app can provide. It will then select the appropriate backend depending
- * If you would like to learn more about why the API works this way, there is a
+ * on the available shader formats and the backends available on the platform.
- * detailed [blog post](https://moonside.games/posts/layers-all-the-way-down/)
+ * When creating shaders, the app must provide the correct shader for the
+ * selected backend. If you would like to learn more about why the API works
+ * this way, there is a detailed
+ * [blog post](https://moonside.games/posts/layers-all-the-way-down/)
  * explaining this situation.
  *
- * It is optimal for apps to pre-compile the shader formats they might use, but for ease of use
+ * It is optimal for apps to pre-compile the shader formats they might use,
- * SDL provides a satellite single-header library for performing runtime shader cross-compilation:
+ * but for ease of use SDL provides a satellite single-header library for
+ * performing runtime shader cross-compilation:
  * https://github.com/libsdl-org/SDL_gpu_shadercross
  *
  * This is an extremely quick overview that leaves out several important
  * details. Already, though, one can see that GPU programming can be quite
  * complex! If you just need simple 2D graphics, the
- * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) is much easier to use but still
+ * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender)
- * hardware-accelerated. That said, even for 2D applications the performance benefits
+ * is much easier to use but still hardware-accelerated. That said, even for
- * and expressiveness of the GPU API are significant.
+ * 2D applications the performance benefits and expressiveness of the GPU API
+ * are significant.
  *
- * The GPU API targets a feature set with a wide range of hardware support and ease of portability.
+ * The GPU API targets a feature set with a wide range of hardware support and
- * It is designed so that the app won't have to branch itself by querying feature support.
+ * ease of portability. It is designed so that the app won't have to branch
- * If you need cutting-edge features with limited hardware support, this API is probably not for you.
+ * itself by querying feature support. If you need cutting-edge features with
+ * limited hardware support, this API is probably not for you.
  *
- * Examples demonstrating proper usage of this API can be found here: https://github.com/TheSpydog/SDL_gpu_examples
+ * Examples demonstrating proper usage of this API can be found here:
+ * https://github.com/TheSpydog/SDL_gpu_examples
  */
 
 #ifndef SDL_gpu_h_