Merge pull request #811 from billhollings/master
Document recommendation to use 3 swapchain images, particularly with full-screen rendering.
diff --git a/Docs/MoltenVK_Runtime_UserGuide.md b/Docs/MoltenVK_Runtime_UserGuide.md
index 999b42e..055deca 100644
--- a/Docs/MoltenVK_Runtime_UserGuide.md
+++ b/Docs/MoltenVK_Runtime_UserGuide.md
@@ -30,6 +30,7 @@
- [Troubleshooting Shader Conversion](#spv_vs_msl)
- [Performance Considerations](#performance)
- [Shader Loading Time](#shader_load_time)
+ - [Swapchains](#swapchains)
- [Xcode Configuration](#xcode_config)
- [Metal System Trace Tool](#trace_tool)
- [Known **MoltenVK** Limitations](#limitations)
@@ -498,6 +499,24 @@
cache contents as described in the previous paragraphs.
+<a name="swapchains"></a>
+### Swapchains
+
+*Metal* supports a very small number (3) of concurrent swapchain images. In addition, *Metal* can
+sometimes hold onto these images during surface presentation.
+
+**MoltenVK** supports using either 2 or 3 swapchain images. For best performance, it is recommended
+that you use 3 swapchain images (triple-buffering), to ensure that at least one swapchain image will
+be available when you need to render to it.
+
+Using 3 swapchain images is particularly important when rendering to a full-screen surface, because
+in that situation, *Metal* uses its *Direct to Display* feature, and avoids compositing the swapchain
+image onto a separate composition surface before displaying it. Although *Direct to Display* can improve
+performance throughput, it also means that *Metal* may hold onto each swapchain image a little longer
+than when using an internal compositor, which increases the risk that a swapchain image will not be a
+vailable when you request it, resulting in frame delays and visual stuttering.
+
+
<a name="xcode_config"></a>
### Xcode Configuration
diff --git a/Docs/Whats_New.md b/Docs/Whats_New.md
index 0871d7e..3bce2c8 100644
--- a/Docs/Whats_New.md
+++ b/Docs/Whats_New.md
@@ -23,6 +23,7 @@
- Fix buffer offset in `vkCmdPushDescriptorSet()` for non-dedicated buffer memory.
- Fix Metal validation error on push constant sizing differences between C and MSL structs.
- Track performance of `CAMetalLayer nextDrawable` call.
+- Document recommendation to use 3 swapchain images, particularly with full-screen rendering.
- Update `VK_MVK_MOLTENVK_SPEC_VERSION` to `24`.
