Add "Common mistakes" documentation chapter

docs/html/index.html

@@ -134,6 +134,7 @@ Table of contents</h1>
 </ul>
 </li>
 <li><a class="el" href="usage_patterns.html">Recommended usage patterns</a><ul>
+<li><a class="el" href="usage_patterns.html#usage_patterns_common_mistakes">Common mistakes</a></li>
 <li><a class="el" href="usage_patterns.html#usage_patterns_simple">Simple patterns</a></li>
 <li><a class="el" href="usage_patterns.html#usage_patterns_advanced">Advanced patterns</a></li>
 </ul>

docs/html/usage_patterns.html

@@ -70,6 +70,12 @@ $(function() {
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>See also slides from talk: <a href="https://www.gdcvault.com/play/1025458/Advanced-Graphics-Techniques-Tutorial-New">Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018</a></p>
+<h1><a class="anchor" id="usage_patterns_common_mistakes"></a>
+Common mistakes</h1>
+<p><b>Use of CPU_TO_GPU instead of CPU_ONLY memory</b></p>
+<p><a class="el" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305cca9066b52c5a7079bb74a69aaf8b92ff67">VMA_MEMORY_USAGE_CPU_TO_GPU</a> is recommended only for resources that will be mapped and written by the CPU, as well as read directly by the GPU - like some buffers or textures updated every frame (dynamic). If you create a staging copy of a resource to be written by CPU and then used as a source of transfer to another resource placed in the GPU memory, that staging resource should be created with <a class="el" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">VMA_MEMORY_USAGE_CPU_ONLY</a>. Please read the descriptions of these enums carefully for details.</p>
+<p><b>Unnecessary use of custom pools</b></p>
+<p><a class="el" href="custom_memory_pools.html">Custom memory pools</a> may be useful for special purposes - when you want to keep certain type of resources separate e.g. to reserve minimum amount of memory for them, limit maximum amount of memory they can occupy, or make some of them push out the other through the mechanism of <a class="el" href="lost_allocations.html">Lost allocations</a>. For most resources this is not needed and so it is not recommended to create <a class="el" href="struct_vma_pool.html" title="Represents custom memory pool.">VmaPool</a> objects and allocations out of them. Allocating from the default pool is sufficient.</p>
 <h1><a class="anchor" id="usage_patterns_simple"></a>
 Simple patterns</h1>
 <h2><a class="anchor" id="usage_patterns_simple_render_targets"></a>

src/vk_mem_alloc.h

@@ -80,6 +80,7 @@ Documentation of all members: vk_mem_alloc.h
     - [Corruption detection](@ref debugging_memory_usage_corruption_detection)
   - \subpage record_and_replay
 - \subpage usage_patterns
+  - [Common mistakes](@ref usage_patterns_common_mistakes)
   - [Simple patterns](@ref usage_patterns_simple)
   - [Advanced patterns](@ref usage_patterns_advanced)
 - \subpage configuration
@@ -1339,6 +1340,27 @@ See also slides from talk:
 [Sawicki, Adam. Advanced Graphics Techniques Tutorial: Memory management in Vulkan and DX12. Game Developers Conference, 2018](https://www.gdcvault.com/play/1025458/Advanced-Graphics-Techniques-Tutorial-New)
 
 
+\section usage_patterns_common_mistakes Common mistakes
+
+<b>Use of CPU_TO_GPU instead of CPU_ONLY memory</b>
+
+#VMA_MEMORY_USAGE_CPU_TO_GPU is recommended only for resources that will be
+mapped and written by the CPU, as well as read directly by the GPU - like some
+buffers or textures updated every frame (dynamic). If you create a staging copy
+of a resource to be written by CPU and then used as a source of transfer to
+another resource placed in the GPU memory, that staging resource should be
+created with #VMA_MEMORY_USAGE_CPU_ONLY. Please read the descriptions of these
+enums carefully for details.
+
+<b>Unnecessary use of custom pools</b>
+
+\ref custom_memory_pools may be useful for special purposes - when you want to
+keep certain type of resources separate e.g. to reserve minimum amount of memory
+for them, limit maximum amount of memory they can occupy, or make some of them
+push out the other through the mechanism of \ref lost_allocations. For most
+resources this is not needed and so it is not recommended to create #VmaPool
+objects and allocations out of them. Allocating from the default pool is sufficient.
+
 \section usage_patterns_simple Simple patterns
 
 \subsection usage_patterns_simple_render_targets Render targets