From 15b963fd4790436b38dec9c2be31a8d286f0443e Mon Sep 17 00:00:00 2001
From: baldurk <baldurk@baldurk.org>
Date: Sun, 6 Mar 2016 15:09:45 +0100
Subject: [PATCH] Add documentation for unstripped-path-specifying code

---
 docs/FAQ.aml         | 23 +++++++++++++++++++++++
 docs/TipsNTricks.aml | 23 +++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/docs/FAQ.aml b/docs/FAQ.aml
index a683e222a..5ab54b627 100644
--- a/docs/FAQ.aml
+++ b/docs/FAQ.aml
@@ -412,5 +412,28 @@
         </para>
       </content>
     </section>
+    <section address="FAQ17">
+      <title>My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?</title>
+      <content>
+        <para>
+          If you get textures that are just named 'texture0' and 'texture1' or constant/uniform buffers named
+          'cbuffer2' then this indicates that you have stripped optional reflection/debug information out of
+          your shaders.
+        </para>
+        <para>
+          This optional information is generated by the compiler, but is not required for API correctness
+          so some codebases will strip the information out after processing it offline, and so it will not
+          be available for RenderDoc to fetch.
+        </para>
+        <para>
+          The simplest solution is just to avoid stripping the data when using RenderDoc, but that isn't
+          always possible. Instead RenderDoc allows you to use API-specific methods to specify where the
+          unstripped data can be found. This means you can save the unstripped shader to a debug location
+          and then either store this location with the shader, or specify it at runtime. On replay
+          RenderDoc will expect the data to be available at that location and it will load it up instead.
+        </para>
+        <para>For details on this method, check out <link xlink:href="e2878f27-34d3-458a-9077-d0fb32c16829" />.</para>
+      </content>
+    </section>
   </developerConceptualDocument>
 </topic>
diff --git a/docs/TipsNTricks.aml b/docs/TipsNTricks.aml
index 45326f977..30ccf3f9f 100644
--- a/docs/TipsNTricks.aml
+++ b/docs/TipsNTricks.aml
@@ -87,6 +87,29 @@ glIsEnabled(GL_DEBUG_TOOL_EXT);
 #define GL_DEBUG_TOOL_EXT                 0x6789
 #define GL_DEBUG_TOOL_NAME_EXT            0x678A
 #define GL_DEBUG_TOOL_PURPOSE_EXT         0x678B
+</code></para></listItem>
+			  <listItem><para>RenderDoc can be informed about separated debug shader blobs through API specific ways:
+<code language="cpp">
+// For D3D11:
+GUID RENDERDOC_ShaderDebugMagicValue = RENDERDOC_ShaderDebugMagicValue_value; // GUID value in renderdoc_app.h
+
+ID3D11VertexShader *shader = ...;
+std::string pathName = ...; // path name is in UTF-8
+
+// string parameter must be NULL-terminated, and in UTF-8
+shader->SetPrivateData(RENDERDOC_ShaderDebugMagicValue, (UINT)pathName.length(), pathName.c_str());
+
+// Alternatively at build time:
+struct { GUID guid; char name[MAX_PATH]; } path;
+
+path.guid = RENDERDOC_ShaderDebugMagicValue;
+// must include NULL-terminator, and be in UTF-8
+memcpy(path.name, debugPath.c_str(), debugPath.length() + 1);
+
+size_t pathSize = sizeof(GUID) + debugPath.length() + 1;
+
+D3DSetBlobPart(strippedBlob->GetBufferPointer(), strippedBlob->GetBufferSize(), D3D_BLOB_PRIVATE_DATA, 0, &amp;path, pathSize, &amp;annotatedBlob);
+// use annotatedBlob instead of strippedBlob from here on
 </code></para></listItem>
 			  <listItem><para>More coming soon hopefully :).</para></listItem>
 			</list>