lee/renderdoc
1
0
Fork 0
mirror of https://github.com/baldurk/renderdoc.git synced 2026-05-12 13:00:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation to reflect latest changes and features

Browse Source 
* Also in many places OpenGL is now advertised as full support, since it
  is pretty close by now and needs people to jump on it full-time and
  use it in anger.
This commit is contained in:
baldurk
2015-02-27 13:18:54 +00:00
parent cd35c726bc
commit a50445781f
25 changed files with 508 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Credits.aml
+1
View File
@@ -159,6 +159,7 @@
<listItem><para>Luke Lambert</para></listItem>
<listItem><para>Gareth Thomas</para></listItem>
<listItem><para>George Ilenei</para></listItem>
<listItem><para>Matías N. Goldberg</para></listItem>
</list>
</content>
docs/FAQ.aml
+45 -9
View File
@@ -114,15 +114,14 @@
<title>What APIs does RenderDoc support?</title>
<content>
<para>
Currently RenderDoc only supports D3D11 (including the D3D11.1 extensions where available).
Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available),
and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of
what is supported in <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">its own page</link>.
</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 is currently under development
also.
</para>
<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.
In future API support is planned for at D3D9 when time and scheduling allows. glNext will
be developed once there is something to write against.
Support for Mantle and D3D12 are currently under development also.
</para>
</content>
</section>
@@ -175,8 +174,14 @@
<title>What are the requirements for RenderDoc?</title>
<content>
<para>
Currently RenderDoc only supports Feature Level 11.0 and above for D3D11. Lower levels
may capture successfully but if uou can't create a FL11.0 device they will not replay.
Currently RenderDoc expects Feature Level 11.0 hardware and above for D3D11. Lower levels
will capture successfully, but on replay RenderDoc will fall back to WARP software emulation
which will run quite slowly.
</para>
<para>
For OpenGL RenderDoc will only capture core profile applications, in general, and expects
to be able to create a core 4.3 context which includes EXT_direct_state_access. For more
details see the <link xlink:href="11ea4311-b9ea-450a-8c80-b510ffc8b1a6">OpenGL</link> page.
</para>
</content>
</section>
@@ -305,5 +310,36 @@
</para>
</content>
</section>
<section address="FAQ14">
<title>I'd like to use RenderDoc's texture viewer for dds files, or other images. Can I?</title>
<content>
<para>
Yes you can!
</para>
<para>
Simply drag in an image file, or open it via file &#8594; open. RenderDoc will open the image
if it is supported, and display it as if there were a log open with only one texture.
</para>
<para>
RenderDoc supports these formats: .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. For
dds files RenderDoc supports all DXGI formats, compressed formats, arrays and mips -
all of which will display as expected.
</para>
</content>
</section>
<section address="FAQ15">
<title>I think I might be overwriting Map() boundaries, can I check this?</title>
<content>
<para>
Yes RenderDoc can be configured to insert a boundary marker at the end of the memory returned
from a Map() call. If this marker gets overwritten during a captured frame then a message box
will pop up alerting you, and clicking Yes will break into the program in the debugger so that
you can investigate the callstack.
</para>
<para>
To enable this behaviour, select the 'Verify Map() Writes' option when <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">capturing</link>.
</para>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Features.aml
+87 -3
View File
@@ -8,11 +8,21 @@
be interested in the <link xlink:href="632271c3-3d72-4360-b4a0-dc570fcd541e" />.
</para>
<para>
Currently RenderDoc is limited to Windows and D3D11 only. The plan is to increase this scope
as soon as possible, to include OpenGL and D3D9 and possibly other platforms.
Currently RenderDoc supports D3D11, OpenGL, Windows and Linux, although the UI only
runs on Windows currently. API support for other APIs (particularly
the new APIs, Mantle, D3D12 and glNext) is planned and in some cases underway. A Qt UI
will be written to fully support Linux and in future OS X, but currently this is just at
the drawing board stage.
</para>
<para>
RenderDoc can also double as an image viewer in a simplistic fashion, separate to its
functionality as a debugger. Drag in or open any of a variety of image file formats and
RenderDoc will display them as a texture in a log. This way it can be used as a simple
e.g. dds viewer, with support for all sorts of formats, encodings and things typical
image viewers don't tend to handle like mips, cubemaps and arrays.
</para>
</introduction>
<section address="Features">
<section address="D3D11Features">
<title>Current Windows+D3D11 Feature set</title>
<content>
<para>
@@ -34,6 +44,7 @@
data with the shader to clarify usage.</para></listItem>
<listItem><para>Structured buffers have their total element count displayed, and UAVs
also show the current structure count.</para></listItem>
<listItem><para>Export of the pipeline to HTML file.</para></listItem>
</list>
</listItem>
<listItem><para>Shader source display (where possible - i.e. debug info available).</para></listItem>
@@ -76,6 +87,8 @@
<listItem><para>Hot shader editing and replacement.</para></listItem>
<listItem><para>Auto-range fitting to min/max values in texture data, and histogram display.</para></listItem>
<listItem><para>Simple per-drawcall timings.</para></listItem>
<listItem><para>Python scripting console, giving access to some of the RenderDoc internals and core
data structures.</para></listItem>
</list>
</para>
<para>
@@ -83,6 +96,77 @@
</para>
</content>
</section>
<section address="GLFeatures">
<title>Current OpenGL Feature set</title>
<content>
<para>Most features are present and supported for both D3D11 and OpenGL, but some are
still in development. Feature parity is an important goal, but for now we list them
separately just to be clear.</para>
<para>
<list class="bullet">
<listItem><para>Support for OpenGL Core profile 3.2+ on Windows and Linux.</para></listItem>
<listItem><para>Optional network support. The main use case is capture &amp; replay on
the same machine, but you can also attach over the network, and replay on a remote host.</para></listItem>
<listItem><para>Event browsing, with standard ARB extension based tree.</para></listItem>
<listItem><para>Full OpenGL Pipeline display.</para>
<list class="bullet">
<listItem><para>Resources are shown on the stage that references them, so each shader stage
shows a list of the resources, image read/writes, uniform buffers etc that it uses.</para></listItem>
<listItem><para>Where available KHR_debug glObjectLabel names are displayed, along with reflection
data with the shader to clarify usage.</para></listItem>
</list>
</listItem>
<listItem><para>Shader source display.</para></listItem>
<listItem><para>Timeline bar of the scene hierarchy.</para>
<list class="bullet">
<listItem><para>Displays scene left-to-right in time, event hierarchy top-to-bottom.</para></listItem>
<listItem><para><legacyItalic>Not</legacyItalic> scaled based on time of each drawcall</para></listItem>
<listItem><para>Individual draw events are shown as dots when the tree is full expanded.</para></listItem>
<listItem><para>The currently selected resource in the texture viewer is highlighted below
individual drawcalls visible that use it - e.g. purple for 'used for write', green for 'used for read'</para></listItem>
</list>
</listItem>
<listItem><para>For each drawcall, a list of all API calls (state/resource setting) is available, with
each call optionally having a complete callstack to locate where it came from in-app.</para></listItem>
<listItem><para>Mesh buffer inspection and visualisation before/after vertex shader and at the end of the geometry
pipeline (after GS or TES, whichever is later). All views have arcball
and flycam controls, Projected data is not limited to the 2D viewport, RenderDoc attempts to unproject to allow viewing in
world-space.</para></listItem>
<listItem><para>'Raw' buffer inspection, e.g. for SSBOs, VBs or other buffers. Custom format can be set with
GLSL-lite syntax.</para></listItem>
<listItem><para>Buffer export to CSV or raw binary blob and texture saving to DDS.</para></listItem>
<listItem><para>Texture/render target viewer.</para>
<list class="bullet">
<listItem><para>List of textures/RTs in the frame, and filtering system.</para></listItem>
<listItem><para>Standard visualisation controls - zoom/fit to window, mip/face/slice selection.</para></listItem>
<listItem><para>RGBA channels or depth/stencil selection as appropriate for the type of resource.</para></listItem>
<listItem><para>Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).</para></listItem>
<listItem><para>Currently set RT/textures thumbnail strip - updates as you move through the frame. Follows the
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, quad overdraw.</para></listItem>
</list>
</listItem>
<listItem><para>Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.</para></listItem>
<listItem><para>Hot shader editing and replacement.</para></listItem>
<listItem><para>Auto-range fitting to min/max values in texture data, and histogram display.</para></listItem>
<listItem><para>Simple per-drawcall timings.</para></listItem>
<listItem><para>Python scripting console, giving access to some of the RenderDoc internals and core
data structures.</para></listItem>
</list>
</para>
<para>
Capturing on Linux is possible, although there is no native UI. The renderdoccmd
program allows capturing on the command line, as well as opening a 'preview'
window of the final frame of the framebuffer. For most work though, you have to transfer the
.rdc capture file (by default placed in /tmp) to windows and open it in the UI there - logs are
completely interchangeable between windows and linux.
</para>
</content>
</section>
<relatedTopics>
<link xlink:href="632271c3-3d72-4360-b4a0-dc570fcd541e" />
</relatedTopics>
docs/Gotchas.aml
+9 -25
View File
@@ -36,12 +36,12 @@
<para>RenderDoc relies on saving out the graphics command stream and replaying it
back at inspection time. This means if a bug is timing, machine or driver specific it is
in no way guaranteed to reproduce the bug on a different machine or driver.</para>
<para>RenderDoc has no dependencies on Visual Studio or the DirectX or Windows SDK,
<para>RenderDoc has no runtime dependencies on Visual Studio or the DirectX or Windows SDK,
and should run anywhere that a normal DirectX application will run - i.e. on
Artist or QA machines. The only requirement is the DirectX runtime to ensure D3DCompiler.dll
is available.</para>
<para>Currently RenderDoc also requires feature level 11+ hardware for the replay app, although
it can capture lower level applications.</para>
Artist or QA machines.</para>
<para>Currently RenderDoc also assumes feature level 11+ hardware for the replay app. It can
capture applications running at a lower feature level, but when replaying if 11+ hardware
isn't available, RenderDoc will fall back to WARP software emulation and will run slowly.</para>
</listItem>
<listItem>
<para>If capturing callstacks from the app, ensure that dbghelp.dll is not loaded or
@@ -73,26 +73,6 @@
use-cases. Let me know if you find a use-case that breaks, as I don't have many test programs!
</para>
</listItem>
<listItem>
<para>In the mesh viewer the Solid Shading option will only apply to the vertex input tab.
(or to the vertex output tab when tessellating).
</para>
<para>Similarly the options to draw "only this draw" or "since last clear" only work for the
vertex output/geometry output tabs.
</para>
<alert class="caution">
<para>The "since last clear" option is likely to be slow when there are a lot of vertices being drawn. Use with care!</para>
</alert>
</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 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
@@ -100,6 +80,10 @@
a little different from their official function signature.
</para>
</listItem>
<listItem>
<para>There are several such notes for OpenGL, which are noted on <link xlink:href="11ea4311-b9ea-450a-8c80-b510ffc8b1a6">its own page</link>.
</para>
</listItem>
</list>
</para>
</content>
docs/HowTo/HowToCustomShader.aml
+73 -7
View File
@@ -9,8 +9,10 @@
<section address="intro">
<title>Introduction</title>
<content>
<para>The basic process of setting up the custom shader involves writing a .hlsl file that
will be compiled and used by RenderDoc.</para>
<para>The basic process of setting up the custom shader involves writing a .hlsl or .glsl
file that will be compiled and used by RenderDoc. Note that the type used matches the API
used, and RenderDoc will automatically list only the hlsl shaders you have if you load
a log with D3D11, and vice-versa for OpenGL.</para>
<para>There are several special global variables that can be specified and will
be filled in with values by RenderDoc.</para>
<para>Your pixel shader defines an operation that transforms the raw value from the input
@@ -20,8 +22,8 @@
<para>Multisampled textures will be resolved before being passed to your function.
Depth and stencil textures will be bound separately and passed as multisampled resources.</para>
<para>To set up your shader, it's recommended that you use the UI defined in the documentation for the
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />, but you can manually create a .hlsl file in
<codeInline>%APPDATA%\RenderDoc\</codeInline>. The file must contain an hlsl function main() that
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />, but you can manually create a .hlsl or .glsl file in
<codeInline>%APPDATA%\RenderDoc\</codeInline>. The file must contain an entry point main() that
returns float4, and uses any of the below inputs. These shaders are loaded when RenderDoc
loads a logfile, and RenderDoc watches for any changes to the files (either externally or in
the shader editor in RenderDoc) and automatically reloads them.</para>
@@ -38,6 +40,10 @@
<para>Type and capitalisation is important for these variables, so ensure you use the right
declaration!</para>
</alert>
<para>The shader editor when using the UI can be used to insert these snippets for you,
with the right type and spelling. Be careful for GL though, as these snippets are inserted
at the top of the file and so are inserted before the #version statement.</para>
<table>
<tableHeader>
@@ -47,7 +53,7 @@
</row>
</tableHeader>
<row>
<entry><para>UV co-ordinates</para></entry>
<entry><para>UV co-ordinates (D3D11 only)</para></entry>
<entry>
<code language="hlsl">
float4 main(<markup><u>float4 pos : SV_Position</u></markup>, <markup><u>float4 uv : TEXCOORD0</u></markup>) : SV_Target0
@@ -69,7 +75,8 @@ co-ordinates from 0 to 1 in each dimension over the size of the texture (or text
<entry><para>Texture dimensions</para></entry>
<entry>
<code language="hlsl">
uint4 RENDERDOC_TexDim;
uint4 RENDERDOC_TexDim; // hlsl
uvec4 RENDERDOC_TexDim; // glsl
</code>
<para>This variable will be filled out with the following values:</para>
@@ -99,6 +106,12 @@ uint RENDERDOC_TextureType;
<para>This variable will be set to a given integer value, depending on the type of
the current texture being displayed. This can be used to sample from the correct resource.</para>
<alert class="note">
<para>The value varies depending on whether this is an HLSL shader or GLSL, as they have different
resource types.</para>
</alert>
<para>D3D11 / HLSL</para>
<list class="ordered">
<listItem><para>1D texture</para></listItem>
<listItem><para>2D texture</para></listItem>
@@ -111,10 +124,24 @@ uint RENDERDOC_TextureType;
<listItem><para>2D texture (Multisampled)</para></listItem>
</list>
<para>OpenGL / GLSL</para>
<list class="ordered">
<listItem><para>1D texture</para></listItem>
<listItem><para>2D texture</para></listItem>
<listItem><para>3D texture</para></listItem>
<listItem><para>Cubemap</para></listItem>
<listItem><para>1D array texture</para></listItem>
<listItem><para>2D array texture</para></listItem>
<listItem><para>Cubemap array</para></listItem>
<listItem><para>Rectangle</para></listItem>
<listItem><para>Buffer texture</para></listItem>
<listItem><para>2D texture (Multisampled)</para></listItem>
</list>
</entry>
</row>
<row>
<entry><para>Samplers</para></entry>
<entry><para>Samplers (D3D11 only)</para></entry>
<entry>
<code language="hlsl">
SamplerState pointSampler : register(s0);
@@ -128,6 +155,7 @@ SamplerState linearSampler : register(s1);
<row>
<entry><para>Resources</para></entry>
<entry>
<para>D3D11 / HLSL</para>
<code language="hlsl">
Texture1DArray&lt;float4&gt; texDisplayTex1DArray : register(t1);
Texture2DArray&lt;float4&gt; texDisplayTex2DArray : register(t2);
@@ -148,6 +176,44 @@ 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>OpenGL / GLSL</para>
<code language="hlsl">
// Unsigned int samplers
layout (binding = 1) uniform usampler1D texUInt1D;
layout (binding = 2) uniform usampler2D texUInt2D;
layout (binding = 3) uniform usampler3D texUInt3D;
// skip cube = 4
layout (binding = 5) uniform usampler1DArray texUInt1DArray;
layout (binding = 6) uniform usampler2DArray texUInt2DArray;
// skip cube array = 7
layout (binding = 8) uniform usampler2DRect texUInt2DRect;
layout (binding = 9) uniform usamplerBuffer texUIntBuffer;
layout (binding = 10) uniform usampler2DMS texUInt2DMS;
// Int samplers
layout (binding = 1) uniform isampler1D texSInt1D;
layout (binding = 2) uniform isampler2D texSInt2D;
layout (binding = 3) uniform isampler3D texSInt3D;
// skip cube = 4
layout (binding = 5) uniform isampler1DArray texSInt1DArray;
layout (binding = 6) uniform isampler2DArray texSInt2DArray;
// skip cube array = 7
layout (binding = 8) uniform isampler2DRect texSInt2DRect;
layout (binding = 9) uniform isamplerBuffer texSIntBuffer;
layout (binding = 10) uniform isampler2DMS texSInt2DMS;
// Floating point samplers
layout (binding = 1) uniform sampler1D tex1D;
layout (binding = 2) uniform sampler2D tex2D;
layout (binding = 3) uniform sampler3D tex3D;
layout (binding = 4) uniform samplerCube texCube;
layout (binding = 5) uniform sampler1DArray tex1DArray;
layout (binding = 6) uniform sampler2DArray tex2DArray;
layout (binding = 7) uniform samplerCubeArray texCubeArray;
layout (binding = 8) uniform sampler2DRect tex2DRect;
layout (binding = 9) uniform samplerBuffer texBuffer;
layout (binding = 10) uniform sampler2DMS tex2DMS;
</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
docs/HowTo/HowToEditShader.aml
+2 -2
View File
@@ -13,13 +13,13 @@
<para><link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018">Custom visualisation shaders</link> allow you to define
your own transformation on any texture you're viewing before it is displayed. Mostly this is useful for decoding
packed or custom-format data, or displaying some data in a more visually intuitive fashion.</para>
<para>These shaders live as .hlsl files in <codeInline>%APPDATA%\RenderDoc\</codeInline>, and can be edited in your
<para>These shaders live as .hlsl/.glsl files in <codeInline>%APPDATA%\RenderDoc\</codeInline>, and can be edited in your
editor of choice, any changes saved will be reloaded. Note however that there is currently no way to see the
compile warnings or errors produced. This is probably best for when you have an existing shader to drop-in.</para>
<para>To edit a shader inside RenderDoc simply click the edit button
<mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline> when you have selected your custom shader
for use. This will launch a new window with the custom shader and any changes you make to this shader will be
saved to the .hlsl file and compiled and reflected in the texture viewer as long as you have that custom shader
saved to the .hlsl/.glsl file and compiled and reflected in the texture viewer as long as you have that custom shader
selected.</para>
</content>
</section>
docs/HowTo/HowToInspectPixel.aml
+1 -2
View File
@@ -72,8 +72,7 @@
<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>
pixel. If you select a particular fragment or primitive, this will be the fragment that is debugged.</para>
</content>
</section>
<relatedTopics>
docs/HowTo/HowToViewDetails.aml
+10
View File
@@ -75,6 +75,10 @@
<caption placement="after" lead="Custom Buffer Layout">Customising the layout of the buffer by defining a structure.</caption>
<image xlink:href="RawBuffer"/>
</mediaLink>
<alert class="note">
<para>This window supports copy and paste, so simply select the entries and ctrl-c to
copy to the clipboard</para>
</alert>
</content>
</section>
<section address="constants">
@@ -89,6 +93,12 @@
<caption placement="after" lead="Constant Buffer">An updating preview of the contents of this constant buffer.</caption>
<image xlink:href="CBuffer"/>
</mediaLink>
<alert class="note">
<para>This window supports copy and paste, so simply select the entries and ctrl-c to
copy to the clipboard</para>
</alert>
</content>
</section>
</developerConceptualDocument>
docs/Introduction.aml
+1 -1
View File
@@ -5,7 +5,7 @@
<para>
<mediaLinkInline><image xlink:href="logo"/></mediaLinkInline>
Welcome to RenderDoc - a graphics debugger, currently available for
D3D11 development on windows.
D3D11 and OpenGL development on windows.
</para>
</summary>
<introduction>
docs/Layout.content
+18 -1
View File
@@ -34,6 +34,8 @@
<HelpKeyword index="K" term="Tips &amp; Tricks" />
<HelpKeyword index="K" term="Code Integration, Manually triggered log capture" />
<HelpKeyword index="K" term="How To, Manually trigger a capture" />
<HelpKeyword index="K" term="How To, View Image File" />
<HelpKeyword index="K" term="Image Viewer" />
</HelpKeywords>
</Topic>
</Topic>
@@ -48,6 +50,13 @@
<HelpKeyword index="K" term="RenderDoc Internals" />
</HelpKeywords>
</Topic>
<Topic id="11ea4311-b9ea-450a-8c80-b510ffc8b1a6" visible="True" title="OpenGL Support">
<HelpKeywords>
<HelpKeyword index="K" term="OpenGL" />
<HelpKeyword index="K" term="OpenGL Support" />
<HelpKeyword index="K" term="GL Support" />
</HelpKeywords>
</Topic>
</Topic>
<Topic id="708163f7-01b1-4d92-919d-f79a0bf8a365" visible="True" noFile="true" isExpanded="true" title="How do I... ?">
<Topic id="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629" visible="True" title="How do I debug a shader?">
@@ -62,7 +71,7 @@
<HelpKeyword index="K" term="Capture Options" />
</HelpKeywords>
</Topic>
<Topic id="F1C1E449-55ED-46FE-BBFD-11D1A0511501" visible="True" isSelected="true" title="How do I inspect a pixel value?">
<Topic id="F1C1E449-55ED-46FE-BBFD-11D1A0511501" visible="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" />
@@ -176,6 +185,14 @@
<HelpKeyword index="K" term="API Messages" />
</HelpKeywords>
</Topic>
<Topic id="6e2e26be-982c-4a2c-9d45-629009f0a479" visible="True" isSelected="true" title="Python Shell">
<HelpKeywords>
<HelpKeyword index="K" term="Python Scripting" />
<HelpKeyword index="K" term="Python Shell" />
<HelpKeyword index="K" term="Python" />
<HelpKeyword index="K" term="Scripting" />
</HelpKeywords>
</Topic>
</Topic>
<Topic id="ddeda389-3bd8-460d-b420-20e563003da4" visible="True" title="Credits &amp; Acknowledgements">
<HelpKeywords>
docs/OpenGL.aml
+87
View File
@@ -0,0 +1,87 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="11ea4311-b9ea-450a-8c80-b510ffc8b1a6" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>
This page documents the support of OpenGL in RenderDoc. This gives an overview of
what RenderDoc is capable of, and primarily lists information that is relevant. You might also
be interested in the <link xlink:href="86b8bce7-b7cd-4b10-aa61-706463d14fe0">full list of features</link>.
</para>
<para>
The latest information and up-to-date support is always available on the
<externalLink>
<linkText>GitHub wiki</linkText>
<linkAlternateText>OpenGL wiki page on GitHub</linkAlternateText>
<linkUri>https://github.com/baldurk/renderdoc/wiki/OpenGL</linkUri>
</externalLink>.
</para>
</introduction>
<section address="Features">
<title>OpenGL requirements, and limitations</title>
<content>
<para>
RenderDoc only supports the core profile of OpenGL - from 3.2 up to 4.5 inclusive. This
means any compatibility profile functionality will generally not be supported. There are
a couple of concessions where it was easy to do so - like allowing the use of VAO 0, or
luminance/intensity formats, but this in general will not happen. Note that to be more
compatible with applications, RenderDoc will still attempt to capture on an older context,
or on a compatibility context, but it will not replay successfully unless the given subset
of functionality is used.
</para>
<para>
RenderDoc assumes your hardware/software configuration is able to create a core 4.3 context
for replay, and also that EXT_direct_state_access is available, both on replay and in capture.
</para>
<para>
Regarding multiple contexts and multithreading, RenderDoc assumes that all GL commands (with
the exception of perhaps a SwapBuffers call) for frames will come from a single thread, and
that all contexts are set up to share objects with each other. This means that e.g. if commands
come from a second thread during loading, or some time during initialisation, this will be
supported only if the second context shares with the primary context. During frame capture
all commands are serialised as if they come from a single thread.
</para>
<para>
RenderDoc supports some ARB, EXT and other extensions - primarily those that are either very
widespread and commonly used but aren't in core, or are quite simple to support. In general
RenderDoc won't support extensions unless they match one of these requirements, and this
means most vendor extensions will not be supported.
</para>
</content>
</section>
<section address="Todo">
<title>OpenGL remaining work</title>
<content>
<para>
There are several places where OpenGL is not yet at feature parity with D3D11.
</para>
<list class="bullet">
<listItem><para>Multiple frame capture is not supported - after one capture is made, the application
must be restarted before you can capture again.</para></listItem>
<listItem><para>Full &amp; complete support for multiple threads feeding GL simultaneously, or
multiple contexts that don't share with each other (or only share within defined groups).</para></listItem>
<listItem><para>Shader debugging is not supported on any shader stage.</para></listItem>
<listItem><para>Pixel history is not implemented.</para></listItem>
<listItem><para>Resource usage throughout the frame (e.g. listing a texture as used as framebuffer attachment
or image or texture at different draw calls) is not gathered.</para></listItem>
<listItem><para>Logfiles currently contain every live resource at the time of capture, and they are
not 'trimmed' down to only the resources referenced.</para></listItem>
<listItem><para>Some initial contents aren't properly fetched or stored, so in some cases changes
from a previous frame would not be saved at capture time.</para></listItem>
</list>
</content>
</section>
<section address="Linux">
<title>Linux and OS X</title>
<content>
<para>Linux and OS X support follows naturally when thinking about OpenGL support. Currently
there is full support for capturing and replaying on linux, however there is no UI as yet.
The recommended method is to capture on linux, and then replay on windows.</para>
</content>
</section>
<relatedTopics>
<link xlink:href="86b8bce7-b7cd-4b10-aa61-706463d14fe0" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/TheFuture.aml
+2 -3
View File
@@ -26,9 +26,8 @@
<listItem><para>Perfkit/PerfHUD integration for vendor-specific detailed
performance timers.</para></listItem>
<listItem><para>Multiple frames in a single capture/logfile.</para></listItem>
<listItem><para>D3D9 support.</para></listItem>
<listItem><para>OpenGL support.</para></listItem>
<listItem><para>Linux/OS X support.</para></listItem>
<listItem><para>D3D9, D3D12, Mantle and glNext support.</para></listItem>
<listItem><para>Linux/OS X UI.</para></listItem>
<listItem><para>Diffing events in a given frame.</para></listItem>
<listItem><para>Modifying the pipeline on the fly to change state.</para></listItem>
<listItem><para>Highlighting redundant state-setting.</para></listItem>
docs/TipsNTricks.aml
+5
View File
@@ -21,6 +21,11 @@
<para>These associations must be re-created if RenderDoc is moved to another folder.</para>
</alert>
</listItem>
<listItem><para>RenderDoc can be used as an image viewer! If you drag in or use file &#8594; open, you can
open images in a variety of formats - .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. The image
will load up in RenderDoc's texture viewer and you can use the normal controls to view it as if it were
a texture in a log. Note that dds files support all DXGI formats, compressed formats, arrays and mips -
all of which will display as expected.</para></listItem>
<listItem><para>If a .cap file is saved with the "auto-start" option enabled, launching RenderDoc
by opening this file will cause RenderDoc to automatically trigger a capture with the given options.
This is useful for saving a common path &amp; set of options that you regularly re-run.</para>
docs/Windows/BufferViewer.aml
+22 -5
View File
@@ -10,7 +10,8 @@
<title>Mesh Viewer</title>
<content>
<para>The Mesh Viewer shows both the mesh data as well as a visual representation
of the mesh at different stages - pre VS, post VS, etc.</para>
of the mesh at different stages - pre VS, post VS, etc. For instanced drawcalls you
can choose which instance to view in the toolbar at the top.</para>
<para>Each distinct point has a display that shows the mesh data, the format of which
is pulled from the relevant stage of the pipeline - shader input or output, or input
layout. You can choose to sync these views <mediaLinkInline><image xlink:href="arrow_join"/></mediaLinkInline>
@@ -50,15 +51,30 @@
</mediaLink>
<para>Also available in the options is a simple speed multiplier for the WASD controls,
to fine-tune how fast it moves to the dimensions of the mesh.</para>
<para>In the vertex input preview, you have the option to display the mesh with some solid
</content>
</section>
<section address="secondary">
<title>Mesh Preview</title>
<content>
<para>In the 3D Mesh preview, you have the option to display the mesh with some solid
shading modes, not just as a wireframe mesh. When solid shading you can toggle the wireframe
on and off.</para>
<list class="bullet">
<listItem><para>Solid Colour simply displays a solid colour for each triangle.</para></listItem>
<listItem><para>Flat Shaded will perform basic flat lighting calculations based on triangle normals to give a better idea of the topology of the mesh.</para></listItem>
<listItem><para>TEXCOORD0 and COLOR0 will display the relevant input element, if detected in the mesh.</para></listItem>
<listItem><para>Secondary will display the selected secondary mesh element.</para></listItem>
</list>
<para>To select which element will be displayed as secondary, simply right click on the column
you would like to use. This can be done on the input and output separately, and 4-component
columns have the option to either show RGB as colour, or alpha as greyscale.</para>
<para>The selection will be remembered as long as the mesh format stays consistent between
draws.</para>
<para>You can also use this if the position data isn't detected in your inputs and you'd like
to choose which element contains the positions, or if you'd like to visualise some other data
such as UV co-ordinates as positional (in effect rendering the mesh in uv-space).</para>
<mediaLink>
<caption placement="after" lead="Preview">Previewing the uv co-ordinates as colour on the mesh.</caption>
<image xlink:href="SolidPreview"/>
@@ -73,7 +89,7 @@
32bit unsigned integers.</para>
<para>This format can be refined and customised by entering a structure-like definition
into the text box at the bottom of the window. The given types are listed below, and
can be combined in hlsl-like fashion specifying n-wide vector elements.</para>
can be combined in hlsl- or glsl-like fashion specifying n-wide vector elements.</para>
<para>In addition to this, you can specify a row offset which is useful in remaining
at the same row while watching the change in a buffer between different events, as well
as a byte offset to shift the data along from the start of the buffer (e.g. if what you
@@ -86,7 +102,8 @@
</mediaLink>
<para>Below are listed the basic types. You can append a number to each of these to make an N-wide
vector (e.g. ushort4 or float3). You can also specify matrices as float3x4. By default matrices
vector (e.g. ushort4 or float3, or uvec4/vec3). You can also specify matrices as float3x4 or mat3x4.
By default matrices
are column major, but you can change this by prepending row_major as you would in hlsl.</para>
<list class="bullet">
docs/Windows/CaptureDialog.aml
+29 -2
View File
@@ -127,7 +127,7 @@
<entry><para>Create Debug Device causes RenderDoc to enable the API's built-in debugging, and where
possible serialise this out and include it in the logfile for later inspection. e.g. on D3D11 this will
activate the D3D debug layer and save out any messages, which can later be viewed in the
<link xlink:href="1f098896-0e60-485a-b879-900a4a320b80" /> window.
<link xlink:href="1f098896-0e60-485a-b879-900a4a320b80" /> window. For OpenGL this means ARB_debug_output.
The overhead from enabling this option is largely the same as the overhead of enabling the
debug device without RenderDoc involved.</para></entry>
<entry><para>Disabled</para></entry>
@@ -137,7 +137,8 @@
<entry><para>This option causes RenderDoc to hook into CreateProcess and intercept any calls to it from
the target application. When this option is enabled those child processes will be injected with RenderDoc
in the same way as the parent - which can be useful if you must launch your program through a launcher
or level of indirection and still wish to use RenderDoc with one of the child processes.</para></entry>
or level of indirection and still wish to use RenderDoc with one of the child processes.</para>
<para>See below for more information on handling of child processes.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
@@ -183,6 +184,14 @@
</entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Verify Map() Writes</para></entry>
<entry><para>This option adds checking to any Map() calls that adds a boundary marker after any Map() pointer
returned during a captured frame. These markers are checked on Unmap() and if they have been modified a
message box will pop up alerting you to this, and you can click Yes to break in the debugger in the target
application and investigate the problem.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Auto start</para></entry>
<entry><para>This option is slightly different from the others in that it doesn't change anything for an
@@ -201,6 +210,24 @@
</content>
</section>
<section address="childprocs">
<title>Child Processes</title>
<content>
<para>RenderDoc is able to automatically inject into any child processes started by the initial
process launched from the UI. To do this simply check "Hook into Children" in the options above.</para>
<para>RenderDoc has a particular handling of child processes to help you navigate to the process
of interest. Whenever a child process is launched, the UI is notified and a list of processes is
displayed in a box on the <link xlink:href="6f4dad92-3db3-448f-9f1a-79af65f74492" /> window.
You can double click on any of these entries to open up a new connection to that process,
in a new window.</para>
<para>If a process exits, instead of just closing the connection window if there have been no
captures, instead RenderDoc looks at the child processes - if there is only one child process,
it assume that process must be of interest and immediately switches to tracking that process.
If there are <legacyItalic>more</legacyItalic> than one child process open, the capture
connection window will stay open to give you a chance to double click on those child processes
to open a new connection window.</para>
</content>
</section>
<section address="globalhook">
<title>Global Process Hook</title>
<content>
docs/Windows/DebugMessages.aml
+4
View File
@@ -4,6 +4,10 @@
<introduction>
<para>The Debug Messages window shows messages from the API including warnings about performance
issues or concerns about potential hazards, as well as errors on invalid use of the API.</para>
<para>RenderDoc will alert you if there are any debug messages to show from the log, by flashing
in the status bar. Sometimes RenderDoc will also add new alerts there that aren't part of the
original log if there are warnings or problems that it encounters while processing and analysing
the log.</para>
</introduction>
<section address="capture">
<title>Capturing with debug messages included</title>
docs/Windows/EventBrowser.aml
+4
View File
@@ -86,6 +86,10 @@ D3DPERF_EndEvent();
pressing left will jump to the parent node of the current level. Pressing left again
will collapse that node, and so on. Pressing right will (if on a node with children)
expand that node.</para>
<alert class="note">
<para>This window supports copy and paste, so simply select the entries and ctrl-c to
copy to the clipboard</para>
</alert>
</content>
</section>
<section address="searching">
docs/Windows/LiveCapture.aml
+19
View File
@@ -104,5 +104,24 @@
</content>
</section>
<section address="childprocs">
<title>Child Processes</title>
<content>
<para>RenderDoc is able to automatically inject into any child processes started by the initial
process launched from the UI. To do this simply check "Hook into Children" in the
<link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">Capture options</link>.</para>
<para>RenderDoc has a particular handling of child processes to help you navigate to the process
of interest. Whenever a child process is launched, the UI is notified and a list of processes is
displayed in a box on the capture connection window.
You can double click on any of these entries to open up a new connection to that process,
in a new window.</para>
<para>If a process exits, instead of just closing the connection window if there have been no
captures, instead RenderDoc looks at the child processes - if there is only one child process,
it assume that process must be of interest and immediately switches to tracking that process.
If there are <legacyItalic>more</legacyItalic> than one child process open, the capture
connection window will stay open to give you a chance to double click on those child processes
to open a new connection window.</para>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/Options.aml
+17 -8
View File
@@ -88,14 +88,6 @@
<para>With a value of 2, <codeInline>123456789.0f</codeInline> will be displayed as <math>1.2345E8</math></para></entry>
<entry><para>7</para></entry>
</row>
<row>
<entry><para>Allow periodic anonymous update checks</para></entry>
<entry><para>Every couple of days RenderDoc will send a single web request to a server to see if a new version
is available and let you know about it. The only information transmitted is the version of RenderDoc that is running.</para>
<para>If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's
recommended that you manually check for updates as new versions will be made available regularly with bugfixes.</para></entry>
<entry><para>Enabled</para></entry>
</row>
<row>
<entry><para>Allow global process hooking</para></entry>
<entry><para>This option enables the functionality allowing capturing of programs that aren't
@@ -105,6 +97,14 @@
<link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">capture options</link> page.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Allow periodic anonymous update checks</para></entry>
<entry><para>Every couple of days RenderDoc will send a single web request to a server to see if a new version
is available and let you know about it. The only information transmitted is the version of RenderDoc that is running.</para>
<para>If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's
recommended that you manually check for updates as new versions will be made available regularly with bugfixes.</para></entry>
<entry><para>Enabled</para></entry>
</row>
</table>
</content>
@@ -127,6 +127,15 @@
and forth between two textures will also reset the range.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Visible channels &amp; mip/slice saved per-texture</para></entry>
<entry><para>Selecting which channels are displayed (red, green, blue, alpha or depth/stencil),
as well as choosing the mip or slice/cubemap face to display, are remembered for the texture
you were looking at. In other words if you display a render target with only the alpha channel
visible, then switching to view another texture will default back to RGB - and switching back
to that render target will view alpha again.</para></entry>
<entry><para>Enabled</para></entry>
</row>
</table>
</content>
</section>
docs/Windows/PipelineState.aml
+9 -1
View File
@@ -25,7 +25,8 @@
<alert class="note">
<para>In D3D11, the Stream-Out stage is available under the Geometry Shader block, with the buffers
being used for stream-out shown.</para>
being used for stream-out shown. Similarly for GL, the transform feedback is listed in the geometry
shader block.</para>
</alert>
</content>
@@ -44,8 +45,15 @@
Items <mediaLinkInline><image xlink:href="page_white_delete"/></mediaLinkInline> button.</para>
<para>Likewise it will omit any slots which are completely empty (and also unused), and this behaviour
can be overridden with the Show Empty Items <mediaLinkInline><image xlink:href="page_white_database"/></mediaLinkInline> button.</para>
<para>In some cases whole sections will be omitted unless there is anything set there - this is primarily
for unused or rarely used features like shader subroutines/class linkage, and Read/Write bindings
(Image load store or UAVs).</para>
<para>When showing disabled or empty entries, they will either be in <legacyItalic>italics</legacyItalic>
or on a dark red background respectively.</para>
<para>You can also export the pipeline state by clicking on the
<mediaLinkInline><image xlink:href="save"/></mediaLinkInline> export button, this will export the
entire pipeline state in detail to an HTML file, so you can more easily compare between different
logs and different events.</para>
</content>
</section>
<relatedTopics>
docs/Windows/PythonShell.aml
+38
View File
@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="6e2e26be-982c-4a2c-9d45-629009f0a479" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>The python shell allows a limited form of scripting for RenderDoc, including
the ability to run simple scripts over the whole dataset in ways not easy to do
in the UI.</para>
</introduction>
<section address="python">
<title>Python Shell</title>
<content>
<para>You can open the python shell from the window menu. It offers both an interactive
shell and a window that can open and run scripts and display the output.</para>
<para>Currently the support is fairly bare bones, and typically you will need some
understanding of the code to use the scripting support well. The 'renderdoc' object
corresponds to the Core object type used throughout the UI, and it provides a
jumping off point for most operations from there.</para>
<para>Examples are:</para>
<list class="bullet">
<listItem><para>renderdoc.CurTextures is an array of FetchTexture with all textures in the current log.</para></listItem>
<listItem><para>renderdoc.GetTextureViewer() gives a handle to the texture viewer, allowing you to
view a particular texture.</para></listItem>
<listItem><para>renderdoc.AppWindow.LoadLogfile("filename", False) opens a given log.</para></listItem>
<listItem><para>renderdoc.GetDrawcall(0, 151) will return the drawcall of EID 151.
Drawcalls have next/previous/parent/children properties to allow you to step through the frame.</para></listItem>
<listItem><para>renderdoc.SetEventID(None, 0, 151) browses to EID 151.</para></listItem>
</list>
<para>So while not particularly friendly to discovery, you can use this to perform
an automated iteration over e.g. all events or all textures for something of interest.</para>
<mediaLink>
<caption placement="after" lead="Python Shell">A simple script that looks at textures and their use in a log.</caption>
<image xlink:href="pythonshell" />
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/TextureViewer.aml
+18 -1
View File
@@ -173,6 +173,13 @@
a texture to view as well as how to display it and if any transformations or overlays
should be applied.</para>
<alert class="note">
<para>The channel selection, and mip/slice selection, are stored by default as a per-texture state.
In other words if you display a render target with only the alpha channel
visible, then switching to view another texture will default back to RGB - and switching back
to that render target will view alpha again.</para>
</alert>
<alert class="note">
<para>The visible range/range adaption control is detailed in the section above and will not be covered here.</para>
</alert>
@@ -211,9 +218,13 @@
RGB and alpha, or for looking at individual channels in a packed texture or render target.</para>
</alert>
<para>Note that these channel selections are by default saved as per-texture state, so switching to a
different texture will revert back to the default RGB, but going back to the first texture will remember
which channels you were viewing. See the option in the <link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" />.</para>
<para>When <ui>RGBM</ui> is selected, the RGB value will be multiplied by the specified multiplier and then by
the alpha value. This is a common encoding used to pack a larger range into an 8-bit RGB image.</para>
<para>With <ui>Custom</ui> selected a dropdown will be populated with any .hlsl files in the
<para>With <ui>Custom</ui> selected a dropdown will be populated with any .hlsl or .glsl files as appropriate in the
<codeInline>%APPDATA%\renderdoc</codeInline> folder. When choosing a custom shader the raw image will be
passed through this shader before being displayed with the usual controls on the main display.</para>
<para>You can create a new custom shader with the <mediaLinkInline><image xlink:href="add"/></mediaLinkInline> button,
@@ -258,6 +269,12 @@
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>
<para>Note that these selections are by default saved as per-texture state, so switching to a
different texture will revert back to the default first slice or face, and top mip.
Going back to the first texture though will remember
which subresource you were viewing. See the option in the <link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" />.</para>
</entry>
</row>
<row>
docs/imgs/Screenshots/SolidPreview.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 77 KiB

docs/imgs/Screenshots/pythonshell.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 214 KiB

docs/renderdoc.shfbproj
+7 -2
View File
@@ -8,7 +8,7 @@
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{d6d6e2b1-866b-497e-b691-ff8026647d16}</ProjectGuid>
<SHFBSchemaVersion>1.9.5.0</SHFBSchemaVersion>
<SHFBSchemaVersion>1.9.9.0</SHFBSchemaVersion>
<!-- AssemblyName, Name, and RootNamespace are not used by SHFB but Visual
Studio adds them anyway -->
<AssemblyName>Documentation</AssemblyName>
@@ -82,7 +82,8 @@
<ResourceItems Include="Resources.items" />
</ItemGroup>
<ItemGroup>
<None Include="Blank.aml" />
<None Include="Windows\PythonShell.aml" />
<None Include="OpenGL.aml" />
<None Include="Windows\DebugMessages.aml" />
<None Include="Windows\LiveCapture.aml" />
<None Include="HowTo\HowToEditShader.aml" />
@@ -118,6 +119,10 @@
<Tokens Include="Tokens.tokens" />
</ItemGroup>
<ItemGroup>
<Image Include="imgs\Screenshots\pythonshell.png">
<ImageId>pythonshell</ImageId>
<AlternateText>Python Shell</AlternateText>
</Image>
<Image Include="imgs\icons\flip_y.png">
<ImageId>flip_y</ImageId>
<AlternateText>flip y</AlternateText>