Batch update for bits of documentation that were out of date

baldurk · Sep 24, 2014 · 7dbb80b · 7dbb80b
1 parent 082a8af
commit 7dbb80b
Show file tree

Hide file tree

Showing 13 changed files with 114 additions and 51 deletions.
diff --git a/docs/FAQ.aml b/docs/FAQ.aml
@@ -118,11 +118,10 @@
         </para>
         <para>
           In future API support is planned for at least OpenGL and D3D9 as soon as time and scheduling
-          allows - OpenGL support is under development. Support for Mantle would be nice but I can't
-          promise it just yet until the API is
-          public.
+          allows - OpenGL support is under development. Support for Mantle is currently under development
+          also.
         </para>
-        <para>Other APIs could be supported once the source is open as I've tried to structure
+        <para>Other APIs could be supported as I've tried to structure
           things such that different back-ends can be slotted in without significant code changes.
         </para>
       </content>
@@ -246,5 +245,49 @@
         </para>
       </content>
     </section>
+    <section address="FAQ12">
+      <title>RenderDoc makes my bug go away! Or causes new artifacts that weren't there</title>
+      <content>
+        <para>
+          For various tedious reasons RenderDoc's replay isn't (and in most cases <em>can't be</em>) a
+          perfect reproduction of what your code was executing in the application when captured, and it
+          can change the circumstances while running.
+        </para>
+        <para>
+          During capture the main impact of having RenderDoc enabled is that timings will change, and
+          more memory (sometimes much more) will be allocated. There are also slight differences to the
+          interception of Map() calls as they go through an intermediate buffer to be captured. Generally
+          the only problem this can expose is that when capturing a frame, if something is timing dependent
+          RenderDoc causes one or two <em>very</em> slow frames, and can cause the bug to disappear.
+        </para>
+        <para>
+          The two primary causes of differences between the captured program and the replayed log (for
+          better or for worse) are:
+        </para>
+
+<list class="ordered">
+  <listItem>
+	  <para>
+	    Map()s that use DISCARD are filled with a marker value, so any values that aren't written
+	    to the buffer will be different - in application you can get lucky and they can be previous
+	    values that were uploaded, but in replay they will be 0xCCCCCCCC.
+	  </para>
+  </listItem>
+  <listItem>
+	  <para>
+	    RenderDoc as an optimisation will not save or restore the contents of render targets at the
+	    start of the frame if it believes they will be entirely overwritten in the frame. This
+	    detection is typically accurate but means targets are cleared to black or full depth rather
+	    than accumulating, even if that accumulation is not intentional it may be the cause of the bug.
+	  </para>
+	  <para>
+	    This behaviour can be overridden by enabling 'Save all initials' in the
+	    <link xlink:href="0dd6fe0d-4130-46f4-b2ea-9565de13111d">capture options</link>.
+	  </para>
+  </listItem>
+</list>
+
+      </content>
+    </section>
   </developerConceptualDocument>
 </topic>
diff --git a/docs/Features.aml b/docs/Features.aml
@@ -65,10 +65,12 @@
 			  		currently selected pipeline slot as it changes, rather than remaining on the given texture.</para></listItem>
 			  		<listItem><para>Tabbed view for locking a view of a particular resource over time.</para></listItem>
 			  		<listItem><para>Pixel value picking.</para></listItem>
+			  		<listItem><para>Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.</para></listItem>
 			  		<listItem><para>Several debug overlays for render targets - Wireframe, Depth pass/fail, Stencil pass/fail,
-			  		Clipping (below black/above white points), NaN/-ve/INF highlight.</para></listItem>
+			  		Clipping (below black/above white points), NaN/-ve/INF highlight, quad overdraw.</para></listItem>
 			  	</list>
 			  </listItem>
+			  <listItem><para>Pixel history view.</para></listItem>
 			  <listItem><para>Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.</para></listItem>
 			  <listItem><para>Vertex, Pixel and Compute shader debugging.</para></listItem>
 			  <listItem><para>Hot shader editing and replacement.</para></listItem>

diff --git a/docs/Gotchas.aml b/docs/Gotchas.aml
@@ -86,23 +86,13 @@
 </alert>
 
 			  </listItem>
-			  <listItem>
-			    <para>There is no pixel history at present. When pixel debugging you must select the
-			    exact drawcall that you are interested in debugging.
-			    </para>
-			  </listItem>
 			  <listItem>
 			    <para>If a debugged pixel is overdrawn multiple times by the same drawcall RenderDoc will attempt
 			    to pick the pixel that last passed the depth test, but this may not necessarily be entirely
 			    accurate and in the case of blending there's no way currently to pick other pixels that passed
 			    the depth test.
 			    </para>
 			  </listItem>
-			  <listItem>
-			    <para>The instruction set for shader debugging is not complete, and some instructions may be
-			    unimplemented leading to incorrect results when debugging.
-			    </para>
-			  </listItem>
 			  <listItem>
 			    <para>The API Inspector shows essentially the raw serialised form of the commands in the log
 			    file and so is not always very useful beyond showing which functions were called. There isn't

diff --git a/docs/HowTo/HowToCustomShader.aml b/docs/HowTo/HowToCustomShader.aml
@@ -107,6 +107,8 @@ uint RENDERDOC_TextureType;
   <listItem><para>Depth + Stencil</para></listItem>
   <listItem><para>Depth (Multisampled)</para></listItem>
   <listItem><para>Depth + Stencil (Multisampled)</para></listItem>
+  <listItem><para>Cubemap</para></listItem>
+  <listItem><para>2D texture (Multisampled)</para></listItem>
 </list>
 
 </entry>
@@ -135,14 +137,17 @@ Texture2DArray&lt;uint2&gt; texDisplayTexStencilArray : register(t5);
 Texture2DMSArray&lt;float2&gt; texDisplayTexDepthMSArray : register(t6);
 Texture2DMSArray&lt;uint2&gt; texDisplayTexStencilMSArray : register(t7);
 Texture2DArray&lt;float4&gt; texDisplayTexCubeArray : register(t8);
+Texture2DMSArray&lt;float4&gt; texDisplayTex2DMSArray : register(t9);
 
 Texture1DArray&lt;uint4&gt; texDisplayUIntTex1DArray : register(t11);
 Texture2DArray&lt;uint4&gt; texDisplayUIntTex2DArray : register(t12);
 Texture3D&lt;uint4&gt; texDisplayUIntTex3D : register(t13);
+Texture2DMSArray&lt;uint4&gt; texDisplayUIntTex2DMSArray : register(t19);
 
 Texture1DArray&lt;int4&gt; texDisplayIntTex1DArray : register(t21);
 Texture2DArray&lt;int4&gt; texDisplayIntTex2DArray : register(t22);
 Texture3D&lt;int4&gt; texDisplayIntTex3D : register(t23);
+Texture2DMSArray&lt;int4&gt; texDisplayIntTex2DMSArray : register(t29);
 </code>
 <para>These resources are bound sparsely with the appropriate type for the
     current texture. With a couple of exceptions there will only be one texture bound

diff --git a/docs/HowTo/HowToDebugShader.aml b/docs/HowTo/HowToDebugShader.aml
@@ -144,8 +144,8 @@
       	output register along with a swizzle and typecast.</para>
       	<para>Swizzles follow the standard hlsl rules - .[xyzw] or .[rgba] in any permutation or repetition
       	will show those channels.</para>
-      	<para>The custom typecast can be any of ,x ,i ,d ,f ,u to display the register as hex, signed integer,
-      	double, float or unsigned respectively.</para>
+      	<para>The custom typecast can be any of ,x ,i ,d ,f ,u ,b to display the register as hex, signed integer,
+      	double, float, unsigned, or bitwise respectively.</para>
         <mediaLink>
 <caption placement="after" lead="Watch window">Watch window - custom register expressions evaluated.</caption>
 <image xlink:href="ShaderWatch"/>

diff --git a/docs/HowTo/HowToInspectPixel.aml b/docs/HowTo/HowToInspectPixel.aml
@@ -60,6 +60,22 @@
         about this is available: <link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629" />.</para>
       </content>
     </section>
+    <section address="PixelHistory">
+      <title>Pixel History</title>
+      <content>
+        <para>When you have a pixel selected, you can click 'History' to open up a pixel history view
+        showing every modification to the selected texture from the start of the frame to the currently
+        selected event.</para>
+        <para>This display shows each modifying event as its own row, coloured as to whether any modifications
+        happened from this event or not - green for fragments that passed all pipeline tests, red for
+        where fragments failed some test, and light grey for UAV writes where it's unknown if there was a write.</para>
+        <para>You can expand each event to see if there were multiple fragments, and see the shader output
+        value from each fragment.</para>
+        <para>Right clicking will allow you to launch the shader debugger at the given event for the selected
+        pixel. Currently this does not debug the specific fragment you selected, only the default behaviour
+        for debugging that event.</para>
+      </content>
+    </section>
     <relatedTopics>
       <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
     </relatedTopics>

diff --git a/docs/Introduction.aml b/docs/Introduction.aml
@@ -14,17 +14,26 @@
         and explanation of which features are available in RenderDoc and how to
         best use them.
       </para>
+      <para>
+        The latest information and discussion is always available on the
+        <externalLink>
+<linkText>GitHub wiki</linkText>
+<linkAlternateText>wiki on GitHub</linkAlternateText>
+<linkUri>https://github.com/baldurk/renderdoc/wiki</linkUri>
+</externalLink>.
+      </para>
     </introduction>
     <section address="guide">
       <title>License</title>
 	  <content>
 	    <para>
 	      RenderDoc is released under the MIT license, so there are no restrictions on your use of it either
-	      commercial or non-commercial.
-	    </para>
-	    <para>
-	      This license will also not change when the source is released, so any source modifications will be
-	      equally unrestricted.
+	      commercial or non-commercial. This includes the source release available on the
+	      <externalLink>
+<linkText>GitHub repository</linkText>
+<linkAlternateText>Source on GitHub</linkAlternateText>
+<linkUri>https://github.com/baldurk/renderdoc/issues</linkUri>
+</externalLink>.
 	    </para>
 	    <para>
 	      Details of the licenses of third party software used in RenderDoc are included in the LICENSE file

diff --git a/docs/Layout.content b/docs/Layout.content
@@ -29,7 +29,7 @@
         <HelpKeyword index="K" term="Features" />
       </HelpKeywords>
     </Topic>
-    <Topic id="e2878f27-34d3-458a-9077-d0fb32c16829" visible="True" isSelected="true" title="Tips &amp; Tricks">
+    <Topic id="e2878f27-34d3-458a-9077-d0fb32c16829" visible="True" title="Tips &amp; Tricks">
       <HelpKeywords>
         <HelpKeyword index="K" term="Tips &amp; Tricks" />
         <HelpKeyword index="K" term="Code Integration, Manually triggered log capture" />
@@ -62,10 +62,11 @@
         <HelpKeyword index="K" term="Capture Options" />
       </HelpKeywords>
     </Topic>
-    <Topic id="F1C1E449-55ED-46FE-BBFD-11D1A0511501" visible="True" title="How do I inspect a pixel value?">
+    <Topic id="F1C1E449-55ED-46FE-BBFD-11D1A0511501" visible="True" isSelected="true" title="How do I inspect a pixel value?">
       <HelpKeywords>
         <HelpKeyword index="K" term="How To, Inspect pixel value" />
         <HelpKeyword index="K" term="Pixel Picking" />
+        <HelpKeyword index="K" term="Pixel History" />
       </HelpKeywords>
     </Topic>
     <Topic id="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" visible="True" title="How do I view a specific texture?">

diff --git a/docs/TheFuture.aml b/docs/TheFuture.aml
@@ -14,17 +14,6 @@
         or delayed indefinitely.
       </para>
     </introduction>
-    <section address="Source">
-      <title>Source Code Release</title>
-      <content>
-        <para>
-          At current the source is not available, but the plan is to release the code onto github
-          at some point in the future, hopefully soon. Primarily it will be once RenderDoc has stabilised
-          and there is a good feature set available, as opposed to the very basic features currently
-          available.
-        </para>
-      </content>
-    </section>
     <section address="Features">
       <title>Planned Features</title>
       <content>

diff --git a/docs/TipsNTricks.aml b/docs/TipsNTricks.aml
@@ -56,6 +56,9 @@ triggerFunc();
 			  </para>
 			  <para>The next <codeInline>Swap()</codeInline> after this call will begin the captured frame,
 			  and the <codeInline>Swap()</codeInline> after that will end it (barring complications)</para>
+			  <para>You can also use the RENDERDOC_StartFrameCapture and RENDERDOC_EndFrameCapture functions
+			  to precisely define the period to be captured. For more information look at the renderdoc_app.h
+			  header in the source code.</para>
 			  </listItem>
 			  <listItem><para>When you have right clicked to select a pixel in the texture viewer, you can
 			  perform precise refinements with the arrow keys to nudge the selection in each direction.</para></listItem>

diff --git a/docs/Tokens.tokens b/docs/Tokens.tokens
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <content xml:space="preserve" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
   <item id="Baldur Contact"><ddue:externalLink xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
-   <ddue:linkText>RenderDoc Contact</ddue:linkText>
-   <ddue:linkAlternateText>RenderDoc @ Crytek</ddue:linkAlternateText>
+   <ddue:linkText>Contact me</ddue:linkText>
+   <ddue:linkAlternateText>RenderDoc developer - Baldur Karlsson</ddue:linkAlternateText>
    <ddue:linkUri>mailto:[email protected]?subject=RenderDoc%20feedback</ddue:linkUri>
    </ddue:externalLink></item>
-</content>
+</content>
diff --git a/docs/Windows/BufferViewer.aml b/docs/Windows/BufferViewer.aml
@@ -114,6 +114,9 @@
   <listItem><para>snormf - 32bit signed normalised value</para></listItem>
   <listItem><para>uintten - 4 component unsigned integer format, packed as 10:10:10:2</para></listItem>
   <listItem><para>unormten - 4 component unsigned normalised format, packed as 10:10:10:2</para></listItem>
+  <listItem><para>xuint - hex-formatted 32bit integer</para></listItem>
+  <listItem><para>xshort - hex-formatted 16bit integer</para></listItem>
+  <listItem><para>xbyte - hex-formatted 8bit integer</para></listItem>
 </list>
 
       </content>

diff --git a/docs/Windows/TextureViewer.aml b/docs/Windows/TextureViewer.aml
@@ -103,6 +103,12 @@
 <caption placement="after" lead="Pixel context">Pixel context displaying the surrounds of the picked pixel.</caption>
 <image xlink:href="PixelContext"/>
 </mediaLink>
+		<para>From here, once you have selected a pixel, you can also launch the
+		<link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629">pixel debugger</link> if you have
+		the drawcall that yo uwant to debug selected. You can also launch the
+		<link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501">pixel history</link> view which shows all
+		modifications that have happened to the texture since the start of the frame to the currently selected
+		event.</para>
       </content>
     </section>
     <section address="range">
@@ -250,25 +256,17 @@
     <para>For 3D textures and 2D arrays you can select the slice to display here from the drop-down, and for cubemaps
     you can select the face. For cubemap arrays these two controls are combined to show a list of the faces for the first
     cubemap, then the second, etc.</para>
+    <para>For Multisampled textures, this will allow you to select either a single sample to view across the image,
+    or to see a default-resolved image.</para>
 	</entry>
   </row>
   <row>
     <entry>
       <para><mediaLinkInline><image xlink:href="save"/></mediaLinkInline> Save Texture</para>
     </entry>
-    <entry><para>This allows you to save the currently visible texture. Currently only .dds format is supported, and
-    there are some limitations in the formats that can be saved - e.g. there is no standard way to support multisampled
-    dds files, so this will fail. Most common formats can be saved to disk in this way.</para>
-	</entry>
-  </row>
-  <row>
-    <entry>
-      <para><mediaLinkInline><image xlink:href="wrench"/></mediaLinkInline> Debug a Pixel</para>
-    </entry>
-    <entry><para>This button is only enabled after a
-    <link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629">pixel has been picked</link>.</para>
-    <para>This will do exactly the same as the button underneath the pixel context display - it will
-    launch a pixel debugger for the currently picked pixel.</para>
+    <entry><para>This allows you to save the currently visible texture. Several formats are supported and options are
+    available for mapping down complex formats (such as multisampled or 3D textures) to formats that don't support them
+    such as .png or .jpg.</para>
 	</entry>
   </row>
   <row>
@@ -334,6 +332,10 @@
   black point (as defined by the range control - see above), and in green any values above the white point. This can
   be useful in identifying invalid ranges if the range control is adjusted correctly, or in combination with a custom
   shader visualiser.</para></listItem>
+  <listItem><para><command>Quad Overdraw (Pass)</command> will show a visualisation of the level of 2x2 quad overdraw
+  in the 'pass' - defined as all the drawcalls up to current with the same set of render targets.</para></listItem>
+  <listItem><para><command>Quad Overdraw (Draw)</command> will show a similar visualisation to the above option, but
+  limited only to the current drawcall.</para></listItem>
 </list>
 
 <alert class="note">