From 99ad53ec3f9746d425e7609b75102e89c0e53d27 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Tue, 31 Dec 2024 19:44:29 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_gpu.h | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 257efbc586d99..305b1165ba2a1 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -149,6 +149,29 @@
* [here](https://github.com/TheSpydog/SDL_gpu_examples)
* .
*
+ * ## Performance considerations
+ *
+ * Here are some basic tips for maximizing your rendering performance.
+ *
+ * - Beginning a new render pass is relatively expensive. Use as few render
+ * passes as you can.
+ * - Minimize the amount of state changes. For example, binding a pipeline is
+ * relatively cheap, but doing it hundreds of times when you don't need to
+ * will slow the performance significantly.
+ * - Perform your data uploads as early as possible in the frame.
+ * - Don't churn resources. Creating and releasing resources is expensive.
+ * It's better to create what you need up front and cache it.
+ * - Don't use uniform buffers for large amounts of data (more than a matrix
+ * or so). Use a storage buffer instead.
+ * - Use cycling correctly. There is a detailed explanation of cycling further
+ * below.
+ * - Use culling techniques to minimize pixel writes. The less writing the GPU
+ * has to do the better. Culling can be a very advanced topic but even
+ * simple culling techniques can boost performance significantly.
+ *
+ * In general try to remember the golden rule of performance: doing things is
+ * more expensive than not doing things. Don't Touch The Driver!
+ *
* ## FAQ
*
* **Question: When are you adding more advanced features, like ray tracing or
@@ -174,6 +197,16 @@
* reflection to extract the required information from the shader
* automatically instead of manually filling in the struct's values.
*
+ * **Question: My application isn't performing very well. Is this the GPU
+ * API's fault?**
+ *
+ * Answer: No. Long answer: The GPU API is a relatively thin layer over the
+ * underlying graphics API. While it's possible that we have done something
+ * inefficiently, it's very unlikely especially if you are relatively
+ * inexperienced with GPU rendering. Please see the performance tips above and
+ * make sure you are following them. Additionally, tools like RenderDoc can be
+ * very helpful for diagnosing incorrect behavior and performance issues.
+ *
* ## System Requirements
*
* **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain