mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-04 09:00:44 +00:00
Initial commit of new restructuredtext docs
This commit is contained in:
Matthäus G. Chajdas
committed by
baldurk
baldurk
parent
6f8e0ae391
commit
c04dd86d8d
+230
@@ -0,0 +1,230 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " applehelp to make an Apple Help Book"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " epub3 to make an epub3"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
@echo " coverage to run coverage check of the documentation (if enabled)"
|
||||
@echo " dummy to check syntax errors of document sources"
|
||||
|
||||
.PHONY: clean
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
.PHONY: html
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
.PHONY: dirhtml
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
.PHONY: singlehtml
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
.PHONY: pickle
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
.PHONY: json
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
.PHONY: htmlhelp
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
.PHONY: qthelp
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/RenderDoc.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/RenderDoc.qhc"
|
||||
|
||||
.PHONY: applehelp
|
||||
applehelp:
|
||||
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
|
||||
@echo
|
||||
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
|
||||
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||
"~/Library/Documentation/Help or install it in your application" \
|
||||
"bundle."
|
||||
|
||||
.PHONY: devhelp
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/RenderDoc"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/RenderDoc"
|
||||
@echo "# devhelp"
|
||||
|
||||
.PHONY: epub
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
.PHONY: epub3
|
||||
epub3:
|
||||
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
|
||||
@echo
|
||||
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
|
||||
|
||||
.PHONY: latex
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
.PHONY: latexpdf
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
.PHONY: latexpdfja
|
||||
latexpdfja:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
.PHONY: text
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
.PHONY: man
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
.PHONY: texinfo
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
.PHONY: info
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
.PHONY: gettext
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
.PHONY: changes
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
.PHONY: linkcheck
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
.PHONY: doctest
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
||||
.PHONY: coverage
|
||||
coverage:
|
||||
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
|
||||
@echo "Testing of coverage in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/coverage/python.txt."
|
||||
|
||||
.PHONY: xml
|
||||
xml:
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
.PHONY: pseudoxml
|
||||
pseudoxml:
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
|
||||
.PHONY: dummy
|
||||
dummy:
|
||||
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
|
||||
@echo
|
||||
@echo "Build finished. Dummy builder generates no files."
|
||||
@@ -0,0 +1,48 @@
|
||||
How RenderDoc works
|
||||
===================
|
||||
|
||||
RenderDoc works on very simple operating principles. This page outlines the basic idea behind its functioning to give people a better idea of what's going on.
|
||||
|
||||
Capturing Logs
|
||||
--------------
|
||||
|
||||
Leaving aside the relatively uninteresting matter of injecting the RenderDoc DLL and calling functions to configure it in the target process, we begin by looking at how RenderDoc captures a logfile.
|
||||
|
||||
We will use D3D11 as an example of a driver for RenderDoc - the driver layer is responsible both for faithfully capturing the logfile's API usage, as well as then replaying and analysing it later. Essentially anything built on top of a driver layer can be used agnostically of the API the application in question is using.
|
||||
|
||||
When the driver initialises it will hook into every entry point into the API such that when application uses the API it passes through the driver wrapper. In the case of D3D11 this is the D3D11CreateDevice and CreateDXGIFactory functions.
|
||||
|
||||
After this point all accesses to the API remain wrapped and the driver essentially "man-in-the-middle"s between the application and the real API.
|
||||
|
||||
The driver initialises in an idle logging state. In this state it's up to the specific implementation about what it serialises. As a general rule, creation and deletion type actions are always serialised, and data-upload calls can sometimes be serialised. In some cases the driver might choose to optimise out some of the data-upload calls and lazy initialise the contents of some resources to save on idle overhead.
|
||||
|
||||
This serialised data is stored in-memory in a chunk-based representation. Although it's up to the driver implementation it is generally refcounted such that resources which end up becoming unbound and destroyed will have their memory overhead deleted.
|
||||
|
||||
When the capture button is hit the driver will enter active logging upon the beginning of the next frame. In this state every API call is serialised out in order and any initial contents and states are saved.
|
||||
|
||||
Once the frame completes this frame capture is serialised to disk along with the in-memory data for any resources that are referenced - by default resources which are not referenced are not included in the log.
|
||||
|
||||
Replaying & Analysing Logs
|
||||
--------------------------
|
||||
|
||||
The replay process is ostensibly simple, but as with the capturing the devil is in the details.
|
||||
|
||||
When replaying, the initial section of the log (up to the beginning of the frame) is read and executed verbatim. Each resource created is mapped to the live version and vice versa so later parts of the log can obtain the replayed representation of the original resource.
|
||||
|
||||
RenderDoc then does an initial pass over the captured frame. This allows us to build up a list of all the 'drawcall' events, analyse dependencies and check which resources are used at each drawcall for read, write, and so on. An internal tree is built up similar to what you see in the Event Browser & API Viewer, as well as a linked list with the linear sequence of drawcalls, since both representations are useful for iterating over the frame.
|
||||
|
||||
After this point most work is done in response to user actions. The basic building block is replaying a partial frame. Most analysis tools are built out of either replaying up to the current event, replaying up to the event - not including the current drawcall - and replaying _only_ the current drawcall.
|
||||
|
||||
Care is taken to minimise this as much as possible as this tends to be the slowest operation given the overheads of serialisation and decoding the command stream.
|
||||
|
||||
When replaying from the beginning of a frame (and not a partial subset of the frame) the initial states of all resources are applied, and the initial pipeline state is restored. Resources which did not have a serialised initial state (e.g. gbuffer textures) have an initial state saved before the first replay of the frame, and this is restored. That way you don't get effects 'leaking' from later in a frame into an earlier point.
|
||||
|
||||
For example, let's assume the user has the 'depth test' overlay enabled, and selects a new event. This is the order of events that occur for the Texture Viewer - other viewers follow similar patterns, with a certain degree of sharing to reduce redundant replays:
|
||||
|
||||
#. The log is replayed up to, but not including, the selected drawcall. After doing this the current pipeline state and contents of all resources exactly match the state at the point of this drawcall.
|
||||
#. We then save a copy of the pristine depth buffer, save the current pipeline state, and set the reversed depth test. Replacing the pixel shader with one that just writes red, we repeat the drawcall to draw all the areas that fail the depth test.
|
||||
#. Restoring the depth buffer and repeating this with a pixel shader which writes green, we fill in the overlay. Both of these renders happen to an off-screen buffer.
|
||||
#. After restoring the pipeline state we finally replay the original drawcall to get the final image.
|
||||
#. When we want to re-paint the viewed texture (either regular painting, or if the user changed a visualisation option which is just a constant buffer value) we bind the current render target as a resource and render it to the texture viewer control, then render the overlay texture on top of that.
|
||||
|
||||
It's also worth mentioning that there is a bit of special handling for deferred contexts. When you select an event in a command list, RenderDoc will replay as normal up to just before the Execute() call, then it will replay all of the commands in the command list up to the currently selected event on the immediate context.
|
||||
@@ -0,0 +1,9 @@
|
||||
Behind the scenes
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
|
||||
planned_features
|
||||
how_works
|
||||
opengl_support
|
||||
vulkan_support
|
||||
@@ -0,0 +1,40 @@
|
||||
OpenGL Support
|
||||
==============
|
||||
|
||||
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 :doc:`full list of features <../getting_started/features>`.
|
||||
|
||||
The latest information and up-to-date support is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/OpenGL>`_.
|
||||
|
||||
OpenGL requirements, and limitations
|
||||
------------------------------------
|
||||
|
||||
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.
|
||||
|
||||
RenderDoc assumes your hardware/software configuration is able to create a core 4.3 context for replay, and also that ``EXT_direct_state_access`` and ``ARB_buffer_storage`` are available, both on replay and in capture.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
OpenGL remaining work
|
||||
---------------------
|
||||
|
||||
There are several places where OpenGL is not yet at feature parity with D3D11.
|
||||
|
||||
* Full & complete support for multiple threads feeding GL simultaneously, or multiple contexts that don't share with each other (or only share within defined groups).
|
||||
* Shader debugging is not supported on any shader stage.
|
||||
* Pixel history is not implemented.
|
||||
|
||||
|
||||
Linux and OS X
|
||||
--------------
|
||||
|
||||
Linux and OS X support follows naturally when thinking about OpenGL support. Currently there is full support for capturing and replaying on linux, however the Qt UI is still heavily work in progress. The recommended method is to capture on linux, and then replay on windows.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../getting_started/features`
|
||||
@@ -0,0 +1,26 @@
|
||||
Planned future features
|
||||
=======================
|
||||
|
||||
This is a list of all features that are planned to be added at some point. Probably none of them have timelines or estimates yet, and they are in no particular order. I just would like to add them eventually. It's mostly here for interest, and for reference if you have a new feature request - it might be on here already!
|
||||
|
||||
For more detail and a more up to date list, check the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki>`_.
|
||||
|
||||
Also note that none of these features are guaranteed. In an ideal world they would all happen but since work hasn't started on any of them some may turn out to be impractical or delayed indefinitely.
|
||||
|
||||
Planned features
|
||||
----------------
|
||||
|
||||
* Debugging of all shader stages.
|
||||
* HLSL Debugging.
|
||||
* Mesh display after HS stage.
|
||||
* Perfkit/PerfHUD integration for vendor-specific detailed performance timers.
|
||||
* Multiple frames in a single capture/logfile.
|
||||
* D3D12 and Vulkan support.
|
||||
* Further work on Qt UI.
|
||||
* Diffing events in a given frame.
|
||||
* Modifying the pipeline on the fly to change state.
|
||||
* Highlighting redundant state-setting.
|
||||
* Tracking the dependencies or dependants of a given drawcall.
|
||||
* Exposing an API to applications so they can give more details or annotation, more tightly integrating with the app itself.
|
||||
* A low-resource mode so RenderDoc can be left on by default whenever running an app, so it's always available if a bug appears.
|
||||
* Attaching to an already-running application
|
||||
@@ -0,0 +1,58 @@
|
||||
Vulkan Support
|
||||
==============
|
||||
|
||||
This page documents the support of Vulkan 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 :doc:`full list of features <../getting_started/features>`.
|
||||
|
||||
|
||||
The latest information and up-to-date support is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/Vulkan>`_.
|
||||
|
||||
Vulkan capture
|
||||
--------------
|
||||
|
||||
RenderDoc's Vulkan support uses the sophisticated layering mechanism built into the Vulkan API. This means that once RenderDoc has registered its capture layers, there is no need for invasive process hooking - we can simply launch the target process with an environment variable set.
|
||||
|
||||
|
||||
The one requirement of this however is that the layer does need to be registered in an OS specific way - on windows this is in the registry, on linux this is in an /etc folder. That way the Vulkan loader can scan and initialise the layer.
|
||||
|
||||
|
||||
Usually this will happen for you if you install RenderDoc with a proper installer, or update from a previous version. However if you are compiling RenderDoc yourself or running a loose unzipped build, the capture panel will show a warning indicating that the layers need to be registered. Just click this and the registration will be applied.
|
||||
|
||||
|
||||
.. figure:: ../images/LayerRegistration.png
|
||||
|
||||
Vulkan Layer Registration
|
||||
|
||||
Performance notes
|
||||
-----------------
|
||||
|
||||
Vulkan is intended as a high-performance low CPU overhead API, and RenderDoc strives to maintain that performance contract at a reasonable level. While some overhead is inevitable RenderDoc aims to have no locks on the 'hot path' of command buffer recording, minimal or no allocation, and in general to have low performance overhead while not capturing.
|
||||
|
||||
Some patterns of access are more or less conducive to good performance on RenderDoc, so if you are having trouble with slow capture, large memory/disk overhead or slow replay you might want to try eliminating use of persistent maps of memory from coherent heaps - you can use vkFlushMappedMemoryRanges to emulate non-coherent heaps and RenderDoc will take advantage of that, or you can use non-persistent maps.
|
||||
|
||||
Likewise try to avoid making very large memory allocations in the range of 1GB and above. By its nature RenderDoc must save one or mor copies of memory allocations to enable proper capture, so having allocations limited to only a few 100s of MBs can help gain granularity of management and limit the memory overhead RenderDoc adds. There may be optimisation of this in future on RenderDoc's side but there are no easy guarantees.
|
||||
|
||||
Current support
|
||||
---------------
|
||||
|
||||
RenderDoc has initial support for Vulkan at the launch of version 1.0, but it contains some caveats. In addition, not all replay features are currently supported, but this is being actively worked on.
|
||||
|
||||
* RenderDoc assumes that even if multiple GPUs are present, that only one VkDevice and one VkQueue will be created and used.
|
||||
* RenderDoc captures will in general not be portable between different systems, only currently supporting capture and replay on the same or similar enough machines.
|
||||
* Sparse textures are only supported for non-arrayed 2D textures with no mips.
|
||||
* Pixel history is not implemented.
|
||||
* Shader debugging is not currently supported.
|
||||
* Edit-and-continue of shaders and custom visualisation shaders are not supported.
|
||||
* Mesh output of geometry/tessellation shader stages is not available.
|
||||
|
||||
Non-windows platforms
|
||||
---------------------
|
||||
|
||||
Linux and other platform support follows naturally when thinking about Vulkan support. Currently there is full support for capturing and replaying on linux, however the Qt UI is still heavily work in progress.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../getting_started/features`
|
||||
+293
@@ -0,0 +1,293 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# RenderDoc documentation build configuration file, created by
|
||||
# sphinx-quickstart on Thu May 12 16:59:09 2016.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
import sys
|
||||
import os
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = []
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#source_encoding = 'utf-8-sig'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'RenderDoc'
|
||||
copyright = '2016, Baldur Karlsson'
|
||||
author = 'Baldur Karlsson'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.29'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.29'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
#today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
#today_fmt = '%B %d, %Y'
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
#default_role = None
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
#add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
#add_module_names = True
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# A list of ignored prefixes for module index sorting.
|
||||
#modindex_common_prefix = []
|
||||
|
||||
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||
#keep_warnings = False
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
#html_theme_path = []
|
||||
|
||||
# The name for this set of Sphinx documents.
|
||||
# "<project> v<release> documentation" by default.
|
||||
#html_title = 'RenderDoc v0.29'
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
#html_short_title = None
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
#html_logo = None
|
||||
|
||||
# The name of an image file (relative to this directory) to use as a favicon of
|
||||
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
#html_favicon = None
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Add any extra paths that contain custom files (such as robots.txt or
|
||||
# .htaccess) here, relative to this directory. These files are copied
|
||||
# directly to the root of the documentation.
|
||||
#html_extra_path = []
|
||||
|
||||
# If not None, a 'Last updated on:' timestamp is inserted at every page
|
||||
# bottom, using the given strftime format.
|
||||
# The empty string is equivalent to '%b %d, %Y'.
|
||||
#html_last_updated_fmt = None
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
#html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
#html_domain_indices = True
|
||||
|
||||
# If false, no index is generated.
|
||||
#html_use_index = True
|
||||
|
||||
# If true, the index is split into individual pages for each letter.
|
||||
#html_split_index = False
|
||||
|
||||
# If true, links to the reST sources are added to the pages.
|
||||
#html_show_sourcelink = True
|
||||
|
||||
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
||||
#html_show_sphinx = True
|
||||
|
||||
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
|
||||
#html_show_copyright = True
|
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
#html_use_opensearch = ''
|
||||
|
||||
# This is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
#html_file_suffix = None
|
||||
|
||||
# Language to be used for generating the HTML full-text search index.
|
||||
# Sphinx supports the following languages:
|
||||
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
|
||||
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
|
||||
#html_search_language = 'en'
|
||||
|
||||
# A dictionary with options for the search language support, empty by default.
|
||||
# 'ja' uses this config value.
|
||||
# 'zh' user can custom change `jieba` dictionary path.
|
||||
#html_search_options = {'type': 'default'}
|
||||
|
||||
# The name of a javascript file (relative to the configuration directory) that
|
||||
# implements a search results scorer. If empty, the default will be used.
|
||||
#html_search_scorer = 'scorer.js'
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'RenderDocdoc'
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'RenderDoc.tex', 'RenderDoc Documentation',
|
||||
'Baldur Karlsson', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
#latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
#latex_use_parts = False
|
||||
|
||||
# If true, show page references after internal links.
|
||||
#latex_show_pagerefs = False
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#latex_show_urls = False
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_domain_indices = True
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'renderdoc', 'RenderDoc Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#man_show_urls = False
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'RenderDoc', 'RenderDoc Documentation',
|
||||
author, 'RenderDoc', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#texinfo_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#texinfo_domain_indices = True
|
||||
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||
#texinfo_show_urls = 'footnote'
|
||||
|
||||
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||
#texinfo_no_detailmenu = False
|
||||
|
||||
|
||||
import sphinx_rtd_theme
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
@@ -0,0 +1,62 @@
|
||||
Credits & Acknowledgements
|
||||
==========================
|
||||
|
||||
.. toctree::
|
||||
|
||||
RenderDoc wouldn't have been possible without both the tools and libraries that were used in its construction, as well as the many people who helped and contributed to make it the program it is today.
|
||||
|
||||
3rd Party Credits
|
||||
-----------------
|
||||
|
||||
The following libraries and components are incorporated into RenderDoc, listed here in no particular order. Thanks go out to the developers and contributors behind each of these libraries who generously donated their work to other free projects!
|
||||
|
||||
* `mhook <http://codefromthe70s.org/mhook23.aspx>`_: DLL hooking library, used to inject RenderDoc into applications
|
||||
* `TreeView with Columns <http://www.codeproject.com/Articles/23746/TreeView-with-Columns>`_: An invaluable control filling a much needed niche in .NET winforms.
|
||||
* `Dock Panel Suite <http://dockpanelsuite.com/>`_: A mature and stable library that adds the docking and flexibility of RenderDoc's UI.
|
||||
* `famfamfam Silk Icon set <http://www.famfamfam.com/lab/icons/silk/>`_: Lending an air of professionalism and artistic quality to the UI, the Silk icon set is used throughout RenderDoc.
|
||||
* `ScintillaNET <http://scintillanet.codeplex.com/>`_ and by extension Scintilla provide a powerful text editor for the shader viewers
|
||||
* `Google Breakpad <https://code.google.com/p/google-breakpad/>`_ provides a rock-solid crash handling and reporting base that help keep RenderDoc stable
|
||||
* `miniz <https://code.google.com/p/miniz/>`_: Public domain zip library is used to compress the crash reports for sending.
|
||||
* `ILM's half implementation <https://github.com/openexr/openexr/tree/master/IlmBase/Half>`_: Used for decoding half data for display.
|
||||
* `jpeg-compressor <https://code.google.com/p/jpeg-compressor/>`_: Used to compress screenshots into jpg format for thumbnail previews.
|
||||
* `lz4 <https://code.google.com/p/lz4/>`_: compresses large data transfers (textures and buffers) when going across network connections.
|
||||
* `stb <https://github.com/nothings/stb>`_: Used to read and write various image formats.
|
||||
* `Source Code Pro <https://github.com/adobe-fonts/source-code-pro>`_: Font used for the in-program overlay.
|
||||
* `IronPython <http://ironpython.net/>`_: Used for the Python shell/integration in the UI.
|
||||
* `tinyexr <https://github.com/syoyo/tinyexr>`_: Used for the OpenEXR file loading and saving.
|
||||
* `glslang <https://github.com/KhronosGroup/glslang>`_: Used for compiling GLSL to SPIR-V.
|
||||
* `Qt <http://www.qt.io/>`_: Used for QRenderDoc replay UI program.
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
There have been many people who have helped in the creation of RenderDoc. Whether testing, feedback or contributing artwork and design critique everyone listed here and many more besides have been invaluable in taking RenderDoc from an idea on paper to its current state. Greets fly out to the following people, listed in no particular order.
|
||||
|
||||
* Chris Bunner, Charlie Cole, James Chilvers, Andrew Khan, Benjamin Hill, Jake Turner, Alex Weighell and the rest of the Crytek UK R&D team.
|
||||
* Colin Bonstead, Marco Corbetta, Pascal Eggert, Marcel Hatam, Sascha Hoba, Theodor Mader, Mathieu Pinard, Chris Raine, Nicolas Schulz, Tiago Sousa, Sean Tracy, Carsten Wenzel, and everyone else at the rest of the Crytek Studios.
|
||||
* Daniel Sexton
|
||||
* Jason Mendel
|
||||
* Jacob Kapostins
|
||||
* Iain Cantlay
|
||||
* Luke Lambert
|
||||
* Gareth Thomas
|
||||
* George Ilenei
|
||||
* Matías N. Goldberg
|
||||
* Louis De Carufel
|
||||
* Steve Marton
|
||||
* Elizabeth Baumel
|
||||
* Jon Ashburn
|
||||
* Greg Fischer
|
||||
* Karen Ghavem
|
||||
* Jens Owen
|
||||
* Derrick Owens
|
||||
* Jon Kennedy
|
||||
* Matthäus G. Chajdas
|
||||
* Dan Ginsburg
|
||||
* Dean Sekulic
|
||||
* Rolando Caloca Olivares
|
||||
* Arne Schober
|
||||
* Michael Vance
|
||||
* Dominik Witczak
|
||||
* Chia-I Wu
|
||||
* Cory Bloor
|
||||
@@ -0,0 +1,193 @@
|
||||
FAQ
|
||||
===
|
||||
|
||||
.. toctree::
|
||||
|
||||
Here is a list of commonly asked questions about RenderDoc. Feel free to contact me if you have another question that isn't covered here or in this document.
|
||||
|
||||
How do I do some particular task?
|
||||
---------------------------------
|
||||
|
||||
Many specific tasks or functions are detailed in the "How Do I... ?" sections. These sections each take a feature or element of a workflow and explain how it fits into the program as a whole as well as any details of how it works.
|
||||
|
||||
If the task you have in mind isn't listed there you might find something similar, or you might find a related feature which can be used to do what you want. If the feature you want doesn't seem to exist at all you might want to check the Planned Future Features to see if it's coming soon - if it's not on that list please feel free to contact me and request it! Contact me. It has often been that simple features are very quick to implement and the prioritisation and scheduling of features is fairly fluid at this stage in development.
|
||||
|
||||
Why did you make RenderDoc?
|
||||
---------------------------
|
||||
|
||||
Although several tools do already exist for graphics debugging, none of them quite suited the functionality I desired and I would often find myself wishing for a feature of one in another and vice versa.
|
||||
|
||||
In addition to this, although the functionality overlaps to some degree many of these tools were primarily designed around the profiling of applications rather than debugging. While being able to inspect the state and contents of resources does often suffice for debugging, it's not necessarily the ideal workflow and often it can become cumbersome.
|
||||
|
||||
In principle I didn't see any reason why I couldn't write a home-brew graphics debugger with some fairly simple operating principles. While there were a whole lot of caveats and little stumbling blocks along the way, the original design has pretty much stayed consistent since the project was started back in July 2012. If you're interested you might want to read about How RenderDoc works.
|
||||
|
||||
Where did the name come from?
|
||||
-----------------------------
|
||||
|
||||
All of the good names were taken :-(.
|
||||
Who can I contact about bugs, feature requests, other queries?
|
||||
|
||||
At the moment there's just me at the wheel - feel free to contact me at Contact me if you have anything you'd like to ask or suggest. I use a github repository for tracking bugs and feature requests so that's the best place to file an issue.
|
||||
|
||||
I work on RenderDoc in my spare time but I am happy to help with anything and work with you if you have any issues that need attention.
|
||||
|
||||
How can I associate RenderDoc's file extensions with the program?
|
||||
-----------------------------------------------------------------
|
||||
|
||||
If you installed RenderDoc via the installer package rather than the zip folder, the option is available there to associate RenderDoc's file extensions with the program. Otherwise you can set them up from the Options Window.
|
||||
Note Note
|
||||
|
||||
RenderDoc will elevate itself to set up these file associations, but otherwise will not hold on to administrator permissions.
|
||||
|
||||
RenderDoc associates .rdc and .cap with itself when desired. The .rdc files are the logfiles output when you capture inside an application. .cap files describe the set up of a particular capture, and can be used to quickly re-launch a capture preset.
|
||||
|
||||
If .rdc files are associated with RenderDoc a thumbnail handler is set up, so that in explorer you'll get thumbnail previews for your captures.
|
||||
|
||||
.. note::
|
||||
|
||||
Note that if you move the directory that RenderDoc is you will need to re-configure the file associations as the registry entries contain absolute paths.
|
||||
|
||||
What APIs does RenderDoc support?
|
||||
---------------------------------
|
||||
|
||||
Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available), Vulkan, and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of what is supported in its own page. Since Vulkan support is in its early stages, it also has its own page.
|
||||
|
||||
In future API support is planned for at D3D9 when time and scheduling allows. Higher priority is D3D12 now that Vulkan support is available. Mantle support will not happen as the API is not planned to be publically available anymore.
|
||||
|
||||
How can I backup or restore my settings?
|
||||
----------------------------------------
|
||||
|
||||
Everything RenderDoc relies upon is stored in %APPDATA%\RenderDoc. You can back up and restore this directory at will as nothing stored in there is machine specific aside from things like recent file lists.
|
||||
|
||||
Deleting this folder will also reset RenderDoc to the defaults - if you uninstall RenderDoc this folder will not be deleted.
|
||||
|
||||
RenderDoc doesn't install any registry keys aside from those to set up file associations.
|
||||
|
||||
Which network ports does RenderDoc use?
|
||||
---------------------------------------
|
||||
|
||||
RenderDoc uses TCP and UDP ports 38920-38927 consecutively for remote access and control (ie. capturing remotely) for each new program that is opened on a machine. Note that even if you initiate a capture locally these ports are still opened for listening. These are the ports that are probed on a remote host to see if a connection exists.
|
||||
|
||||
RenderDoc also uses TCP and UDP ports 39920 for remote replay connections, for when a remote host is used to replay and analyse the log.
|
||||
|
||||
Where can I get the source to RenderDoc?
|
||||
----------------------------------------
|
||||
|
||||
RenderDoc is licensed under the MIT license and the source is available on github.com
|
||||
|
||||
What are the requirements for RenderDoc?
|
||||
----------------------------------------
|
||||
|
||||
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.
|
||||
|
||||
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 and ARB_buffer_storage. For more details see the OpenGL page.
|
||||
|
||||
With Vulkan RenderDoc should fully support any Vulkan application.
|
||||
|
||||
Why does my capture say "Failed to capture frame: Uncapped command list"?
|
||||
-------------------------------------------------------------------------
|
||||
|
||||
At the moment RenderDoc only begins capturing deferred command lists at the point that you trigger a capture. If you replay command lists from before this, RenderDoc will fail to capture the frame and try again next frame (and eventually give up after a few retries).
|
||||
|
||||
To change this behaviour, enable the Capture all cmd lists option - see that page for more details. This will capture all command lists from the start of the program, ready for when you decide to capture a frame. This currently has a fair overhead but it's something I want to improve in future
|
||||
|
||||
Why does my capture say "Failed to capture frame: Uncapped Map()/Unmap()"?
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
If you start a Map() before a Present() call then call Unmap() after the Present() during the frame RenderDoc wants to capture, RenderDoc won't have intercepted this call and so will fail to capture this frame and try again next time. This usually only invalidates the first frame you try to capture, but if you Map() many resources, and Unmap() them one by one in subsequent frames, you could hit this failed capture scenario many times in a row.
|
||||
|
||||
Currently the only solution to this is to change the pattern of Map()/Unmap() such that they are contained within a frame.
|
||||
|
||||
Gamma display of linear data, or "Why doesn't my texture look right?"
|
||||
---------------------------------------------------------------------
|
||||
|
||||
Gamma/SRGB correctness is a rather painful subject. If we could all just agree to store everything in 32bit float data we could probably do away with it. Until that time we have to worry about displaying textures while making sure to respect SRGB.
|
||||
|
||||
For texture formats that explicitly specify that they contain SRGB data this isn't a problem and everything works smoothly. Note that RenderDoc shows picked texel values in linear float format, so if you pick a pixel that is 0.5, 0.5, 0.5, the actual bytes might be stored as say 186, 186, 186.
|
||||
|
||||
For other textures it's more difficult - for starters they may actually contain SRGB data but the correction is handled by shaders so there's no markup. Or indeed the app may not be gamma-correct so the data is SRGB but uncorrected. If we display these textures in a technically correct way, such that the data is not over or under gamma-corrected, the result often looks 'wrong' or unintuitively different from expected.
|
||||
|
||||
Nothing is actually wrong here except perhaps that when visualising linear data it is often more convenient to "overcorrect" such that the data is perceptually linear. A good example to use is a normal map: The classic deep blue of (127,127,255) flat normals is technically incorrect as everyone is used to visualising these textures in programs that display the data as if it were SRGB (which is the convention for normal images that do not represent vectors).
|
||||
|
||||
You can override this behaviour on any texture that isn't listed as explicitly SRGB with the gamma (γ) button - toggle this off and the overcorrection will be disabled.
|
||||
|
||||
RenderDoc makes my bug go away! Or causes new artifacts that weren't there
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
For various tedious reasons RenderDoc's replay isn't (and in most cases can't be) a perfect reproduction of what your code was executing in the application when captured, and it can change the circumstances while running.
|
||||
|
||||
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 very slow frames, and can cause the bug to disappear.
|
||||
|
||||
The two primary causes of differences between the captured program and the replayed log (for better or for worse) are:
|
||||
|
||||
#. 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.
|
||||
|
||||
#. 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.
|
||||
|
||||
This behaviour can be overridden by enabling 'Save all initials' in the :doc:`capture options <capture_options>`.
|
||||
|
||||
I can't launch my program for capture directly. Can I capture it anyway?
|
||||
------------------------------------------------------------------------
|
||||
|
||||
There is an option for capturing programs using RenderDoc where you can't easily set up a direct launch of the process.
|
||||
|
||||
More details can be found in the capture options page which details how to use it, however you should take care to read the warnings! This option isn't without its risks, so you need to be sure you know what you're doing before using it. It should always be used as a last resort when there is no other option.
|
||||
|
||||
I'd like to use RenderDoc's texture viewer for dds files, or other images. Can I?
|
||||
---------------------------------------------------------------------------------
|
||||
|
||||
Yes you can!
|
||||
|
||||
Simply drag in an image file, or open it via file → open. RenderDoc will open the image if it is supported, and display it as if there were a log open with only one texture.
|
||||
|
||||
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.
|
||||
|
||||
Any modifications to the image while open in RenderDoc will be refreshed in the viewer. However if the image metadata changes (dimension, format, etc) then this will likely cause artifacts.
|
||||
|
||||
I think I might be overwriting Map() boundaries, can I check this?
|
||||
------------------------------------------------------------------
|
||||
|
||||
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.
|
||||
|
||||
To enable this behaviour, select the 'Verify Map() Writes' option when :doc:`capturing <capture>`.
|
||||
|
||||
RenderDoc is complaining about my OpenGL app in the overlay - what gives?
|
||||
-------------------------------------------------------------------------
|
||||
|
||||
The first thing to remember is that **RenderDoc only supports Core 3.2 and above OpenGL**. If your app is using features from before 3.2 it almost certainly won't work as most functionality is not supported. A couple of things like not creating a VAO (which are required in core profile) and luminance textures (which don't exist in core profile) are allowed, but none of the fixed function pipeline will work, etc etc.
|
||||
|
||||
If your app is not using the CreateContextAttribs API then RenderDoc will completely refuse to capture, and will display overlay text to this effect using the simplest fixed-function pipeline code, so it will run on any OpenGL app, even on a 1.4 context or similar.
|
||||
|
||||
If your app did use the CreateContextAttribs API, RenderDoc will allow you to capture, but compatibility profiles will have a warning displayed in the overlay - this is because you could easily use old functionality as it is all still available in the context.
|
||||
|
||||
Can I tell via the graphics APIs if RenderDoc is present at runtime?
|
||||
--------------------------------------------------------------------
|
||||
|
||||
Yes indeed. Some APIs offer ways to do this already - D3DPERF_GetStatus(), ID3DUserDefinedAnnotation::GetStatus() and ID3D11DeviceContext2::IsAnnotationEnabled().
|
||||
|
||||
In addition to those:
|
||||
|
||||
Querying an ID3D11Device for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}`` will return an IUnknown* and S_OK when RenderDoc is present.
|
||||
|
||||
`GL_EXT_debug_tool <https://renderdoc.org/debug_tool.txt>`_ is implemented on RenderDoc, which is an extension I've proposed for this purpose (identifying when and which tool is injected in your program). It allows you to query for the presence name and type of a debug tool that's currently hooked. At the time of writing only RenderDoc implements this as I've only just proposed the extension publicly, but in future you can use the queries described in that spec.
|
||||
|
||||
.. note::
|
||||
|
||||
It's unlikely the extension will ever be 'made official', so these enumerants can be used:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
#define GL_DEBUG_TOOL_EXT 0x6789
|
||||
#define GL_DEBUG_TOOL_NAME_EXT 0x678A
|
||||
#define GL_DEBUG_TOOL_PURPOSE_EXT 0x678B
|
||||
|
||||
A similar extension for Vulkan will be proposed after release.
|
||||
My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
For details on this method, check out :doc:`tips_tricks`.
|
||||
@@ -0,0 +1,153 @@
|
||||
Features
|
||||
========
|
||||
|
||||
This page documents the current feature set of RenderDoc. This gives an overview of what RenderDoc is capable of, and where it is in its development. You might also be interested in the :doc:`../behind_scenes/planned_features`.
|
||||
|
||||
Currently RenderDoc supports D3D11, OpenGL, and Vulkan on Windows and Linux, although the UI only runs on Windows currently. API support for other APIs such as D3D12 is planned. 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.
|
||||
|
||||
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.
|
||||
|
||||
Current Windows+D3D11 Feature set
|
||||
---------------------------------
|
||||
|
||||
* Support for D3D11 and D3D11.1, Windows Vista and above.
|
||||
* Trimming capture - capture file only contains data necessary for replaying the frame in question, not all textures & buffers ever created in the lifetime of the app.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Multiple frame capture with ability to open side-by-side to compare.
|
||||
* Event browsing, with standard perfmarker style tree.
|
||||
* Full D3D11 Pipeline display.
|
||||
|
||||
* Resources bound to the pipeline are trimmed to what is actually in use, e.g. if a shader only references SRV slot 0, only SRV slot 0 will be displayed, even if something is bound to slot 1.
|
||||
* Where available D3D11 debug names are displayed, along with reflection data with the shader to clarify usage.
|
||||
* Structured buffers have their total element count displayed, and UAVs also show the current structure count.
|
||||
* Export of the pipeline to HTML file.
|
||||
|
||||
* Shader source display (where possible - i.e. debug info available).
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* Displays scene left-to-right in time, event hierarchy top-to-bottom.
|
||||
* _Not_ scaled based on time of each drawcall
|
||||
* Individual draw events are shown as dots when the tree is full expanded.
|
||||
* 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'
|
||||
|
||||
* 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.
|
||||
* Mesh buffer inspection and visualisation before/after vertex shader and at the end of the geometry pipeline (after GS or DS, 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.
|
||||
* 'Raw' buffer inspection, e.g. for UAVs, VBs or other buffers. Custom format can be set with HLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* 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.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* 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.
|
||||
|
||||
* Pixel history view.
|
||||
* Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.
|
||||
* Vertex, Pixel and Compute shader debugging.
|
||||
* Hot shader editing and replacement.
|
||||
* Auto-range fitting to min/max values in texture data, and histogram display.
|
||||
* Simple per-drawcall timings.
|
||||
* Python scripting console, giving access to some of the RenderDoc internals and core data structures.
|
||||
|
||||
Most of these should be intuitive if you've used a graphics debugger before.
|
||||
|
||||
Current OpenGL Feature set
|
||||
--------------------------
|
||||
|
||||
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.
|
||||
|
||||
* Support for OpenGL Core profile 3.2+ on Windows and Linux.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Event browsing, with standard ARB extension based tree.
|
||||
* Full OpenGL Pipeline display.
|
||||
|
||||
* 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.
|
||||
* Where available ``KHR_debug`` glObjectLabel names are displayed, along with reflection data with the shader to clarify usage.
|
||||
|
||||
* Shader source display.
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* Displays scene left-to-right in time, event hierarchy top-to-bottom.
|
||||
* _Not_ scaled based on time of each drawcall
|
||||
* Individual draw events are shown as dots when the tree is full expanded.
|
||||
* 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'
|
||||
|
||||
* 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.
|
||||
* 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.
|
||||
* 'Raw' buffer inspection, e.g. for SSBOs, VBs or other buffers. Custom format can be set with GLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* 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.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* 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.
|
||||
|
||||
* Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.
|
||||
* Hot shader editing and replacement.
|
||||
* Auto-range fitting to min/max values in texture data, and histogram display.
|
||||
* Simple per-drawcall timings.
|
||||
* Python scripting console, giving access to some of the RenderDoc internals and core data structures.
|
||||
|
||||
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.
|
||||
|
||||
Current Vulkan Feature set
|
||||
--------------------------
|
||||
|
||||
As Vulkan is still in early support, some features are not yet supported. Feature parity is an important goal, but for now we list them separately just to be clear.
|
||||
|
||||
* Support for Vulkan 1.0 on Windows and Linux.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Event browsing, with debug marker extension based tree.
|
||||
* Full Vulkan Pipeline display.
|
||||
|
||||
* Resources are shown on the stage that references them, so each shader stage shows a list of the resources that it uses. Uniform buffers are separated out for clarity, but all other resources are listed together along with their descriptor set and binding point.
|
||||
* Where available debug marker labelled names are displayed, along with reflection data from the SPIR-V to clarify usage.
|
||||
|
||||
* SPIR-V disassembly display.
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* Displays scene left-to-right in time, event hierarchy top-to-bottom.
|
||||
* _Not_ scaled based on time of each drawcall
|
||||
* Individual draw events are shown as dots when the tree is full expanded.
|
||||
* 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'
|
||||
|
||||
* 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.
|
||||
* Mesh buffer inspection and visualisation before/after vertex shader. 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.
|
||||
* 'Raw' buffer inspection, e.g. for SSBOs, VBs or other buffers. Custom format can be set with HLSL or GLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* 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.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* 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.
|
||||
|
||||
* Auto-range fitting to min/max values in texture data, and histogram display.
|
||||
* Simple per-drawcall timings.
|
||||
* Python scripting console, giving access to some of the RenderDoc internals and core data structures.
|
||||
|
||||
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.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../behind_scenes/planned_features`
|
||||
@@ -0,0 +1,33 @@
|
||||
Gotchas & Known Issues
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
|
||||
This page (hopefully) keeps up to date with any known issues, bugs, unimplemented or partially unimplemented features.
|
||||
|
||||
Things to Note
|
||||
--------------
|
||||
|
||||
* RenderDoc doesn't serialise out the initial contents of large graphics resources when it believes that they will not be used in replay. e.g. a G-Buffer render target will not be saved out as it is initialised and written to in-frame. This detection will go wrong if a render target is partially written to but partially re-used, as RenderDoc will count this as initialised in-frame. This could happen e.g. with an accumulating texture that is written to in the frame over the top of previous results.
|
||||
|
||||
You can override this behaviour by selecting 'Save All Initials' in the :doc:`capture options <capture_options>` before capturing, as this will force RenderDoc to serialise out all initial contents regardless, at the cost of larger logfiles and slightly slower replay app analysis.
|
||||
|
||||
* When capturing, only one swapchain is captured at any given time. The in-app overlay renders to all swapchains but only one is considered "active" at any given time - this can be cycled with the F11 key. The capture key will trigger a capture at the next swap of the currently active swapchain.
|
||||
|
||||
* 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
* If capturing callstacks from the app, ensure that dbghelp.dll is not loaded or used by the application as this can easily interfere with RenderDoc's use and cause undefined or empty results. More information on this can be found in :doc:`how_to_capture_callstack`.
|
||||
* RenderDoc can have a significant memory overhead, especially when a lot of resources are allocated as shadow copies in main memory are created.
|
||||
|
||||
If running in 32bit, it's possible that an application can run out of memory - particularly when capturing, as this causes a significant spike in memory use. Improvements in memory management are planned but for now it's recommended to use 64bit, or to limit captures to simple scenes wherever possible.
|
||||
|
||||
Partially Implemented Features
|
||||
------------------------------
|
||||
|
||||
|
||||
* Deferred context & command list support will probably run into problems with non-trivial use-cases. Let me know if you find a use-case that breaks, as I don't have many test programs!
|
||||
* 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 a way yet to see what views a particular ID corresponds to, and some of the parameters are a little different from their official function signature.
|
||||
* There are several such notes for OpenGL, which are noted on :any:`its own page <../behind_scenes/opengl_support>`, as well as for Vulkan on :doc:`its own page <../behind_scenes/vulkan_support>`.
|
||||
@@ -0,0 +1,349 @@
|
||||
In-application API
|
||||
==================
|
||||
|
||||
Reference for RenderDoc in-application API
|
||||
|
||||
|
||||
This page describes the RenderDoc API exposed to applications being captured, both in overall organisation as well as a specific reference on each function.
|
||||
|
||||
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. cpp:function:: void GetAPIVersion(int *major, int *minor, int *patch)
|
||||
|
||||
|
||||
This function returns the actual API version of the implementation returned. Version numbers follow `semantic versioning <http://semver.org/>`_ which means the implementation returned may have a higher minor and/or patch version than requested: New patch versions are identical and backwards compatible in functionality. New minor versions add new functionality in a backwards compatible way.
|
||||
|
||||
:param int* major: will be filled with the major version of the implementation's version.
|
||||
:param int* minor: will be filled with the minor version of the implementation's version.
|
||||
:param int* patch: which will be filled with the patch version of the implementation's version.
|
||||
:return: None
|
||||
|
||||
|
||||
.. cpp:function:: void SetCaptureOptionU32(RENDERDOC_CaptureOption opt, uint32_t val)
|
||||
|
||||
Set one of the options for tweaking some behaviours of capturing. Note that each option only takes effect from after it is set - so it is advised to set these options as early as possible, ideally before any graphics API has been initialised.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be set.
|
||||
:param uint32_t val: the unsigned integer value to set for the above option.
|
||||
:return: The function returns 1 if the option is valid, and the value set on the option is within valid ranges. The function returns 0 if the option is not a :cpp:enum:`RENDERDOC_CaptureOption` enum, or the value is not valid for the option.
|
||||
|
||||
.. cpp:function:: void SetCaptureOptionF32(RENDERDOC_CaptureOption opt, float val)
|
||||
|
||||
Set one of the options for tweaking some behaviours of capturing. Note that each option only takes effect from after it is set - so it is advised to set these options as early as possible, ideally before any graphics API has been initialised..
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be set.
|
||||
:param float val: the floating point value to set for the above option.
|
||||
:return: The function returns 1 if the option is valid, and the value set on the option is within valid ranges. The function returns 0 if the option is not a :cpp:enum:`RENDERDOC_CaptureOption` enum, or the value is not valid for the option.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_CaptureOption
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_AllowVSync
|
||||
|
||||
specifies whether the application is allowed to enable vsync. Default is on.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_AllowFullscreen
|
||||
|
||||
specifies whether the application is allowed to enter exclusive fullscreen. Default is on.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugDeviceMode
|
||||
|
||||
specifies whether (where possible) API-specific debugging is enabled. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureCallstacks
|
||||
|
||||
specifies whether each API call should save a callstack. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureCallstacksOnlyDraws
|
||||
|
||||
specifies whether - if `CaptureCallstacks` is enabled - callstacks are only saved on drawcalls. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DelayForDebugger
|
||||
|
||||
specifies a delay in seconds after launching a process to pause, to allow debuggers to attach. Default is 0.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_VerifyMapWrites
|
||||
|
||||
specifies whether any 'map' type resource memory updates should be bounds-checked for overruns. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_HookIntoChildren
|
||||
|
||||
specifies whether child processes launched by the initial application should be hooked as well - commonly if a launcher process is needed to run the application. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_RefAllResources
|
||||
|
||||
specifies whether all live resources at the time of capture should be included in the log, even if they are not referenced by the frame. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_SaveAllInitials
|
||||
|
||||
specifies whether all initial states of resources at the start of the frame should be saved, rather than omitting large resource contents which are detected to be likely unused. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureAllCmdLists
|
||||
|
||||
specifies whether all command lists should be captured on APIs where multithreaded submission is not optimal such as D3D11, rather than only capturing those submitted during the frame. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugOutputMute
|
||||
|
||||
specifies whether to mute any API debug output messages when `DebugDeviceMode` is enabled. Default is on.
|
||||
|
||||
|
||||
.. cpp:function:: uint32_t GetCaptureOptionU32(RENDERDOC_CaptureOption opt)
|
||||
|
||||
Gets the current value of one of the different options listed above in :cpp:func:`SetCaptureOptionU32`.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be retrieved.
|
||||
:return: The function returns the value of the capture option, if the option is a valid :cpp:enum:`RENDERDOC_CaptureOption` enum. Otherwise returns ``0xffffffff``.
|
||||
|
||||
.. cpp:function:: float GetCaptureOptionF32(RENDERDOC_CaptureOption opt)
|
||||
|
||||
Gets the current value of one of the different options listed above in :cpp:func:`SetCaptureOptionF32`.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be retrieved.
|
||||
:return: The function returns the value of the capture option, if the option is a valid :cpp:enum:`RENDERDOC_CaptureOption` enum. Otherwise returns `-FLT_MAX`.
|
||||
|
||||
.. cpp:function:: void SetFocusToggleKeys(RENDERDOC_InputButton *keys, int num)
|
||||
|
||||
This function changes the key bindings in-application for changing the focussed window.
|
||||
|
||||
:param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is NULL, ``num`` must be 0.
|
||||
:param int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_InputButton
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_0..eRENDERDOC_Key_9
|
||||
|
||||
are the number keys. The values of these match ASCII for '0' .. '9'.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_A..eRENDERDOC_Key_Z
|
||||
|
||||
are the letter keys. The values of these match ASCII for 'A' .. 'Z'.
|
||||
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Divide
|
||||
|
||||
is the Divide key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Multiply
|
||||
|
||||
is the Multiply key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Subtract
|
||||
|
||||
is the Subtract key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Plus
|
||||
|
||||
is the Plus key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_F1
|
||||
|
||||
. eRENDERDOC_Key_F12` are the function keys.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Home
|
||||
|
||||
is the Home key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_End
|
||||
|
||||
is the End key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Insert
|
||||
|
||||
is the Insert key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Delete
|
||||
|
||||
is the Delete key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PageUp
|
||||
|
||||
is the PageUp key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PageDn
|
||||
|
||||
is the PageDn key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Backspace
|
||||
|
||||
is the Backspace key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Tab
|
||||
|
||||
is the Tab key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PrtScrn
|
||||
|
||||
is the PrtScrn key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Pause
|
||||
|
||||
is the Pause key.
|
||||
|
||||
.. cpp:function:: void SetCaptureKeys(RENDERDOC_InputButton *keys, int num)
|
||||
|
||||
This function changes the key bindings in-application for triggering a capture on the current window.
|
||||
|
||||
:param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is NULL, ``num`` must be 0.
|
||||
:param int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled.
|
||||
|
||||
.. cpp:function:: uint32_t GetOverlayBits()
|
||||
|
||||
This function returns the current mask which determines what sections of the overlay render on each window.
|
||||
|
||||
:return: A mask containing bits from :cpp:enum:`RENDERDOC_OverlayBits`.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_OverlayBits
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_Enabled
|
||||
|
||||
is an overall enable/disable bit. If this is disabled, no overlay renders.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_FrameRate
|
||||
|
||||
shows the average, min and max frame time in milliseconds, and the average framerate.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_FrameNumber
|
||||
|
||||
shows the current frame number, as counted by the number of presents.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_CaptureList
|
||||
|
||||
shows how many total captures have been made, and a list of captured frames in the last few seconds.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_Default
|
||||
|
||||
is the default set of bits, which is the value of the mask at startup.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_All
|
||||
|
||||
is equal to `~0U` so all bits are enabled.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_None
|
||||
|
||||
is equal to `0` so all bits are disabled.
|
||||
|
||||
.. cpp:function:: void MaskOverlayBits(uint32_t And, uint32_t Or)
|
||||
|
||||
This function modifies the current mask which determines what sections of the overlay render on each window.
|
||||
|
||||
:param uint32_t And: is a 32-bit value the mask is binary-AND'd with before processing ``Or``.
|
||||
:param uint32_t Or: is a 32-bit value the mask is binary-OR'd with after processing ``And``.
|
||||
|
||||
.. cpp:function:: void Shutdown()
|
||||
|
||||
This function will attempt to shut down and remove RenderDoc and its hooks from the target process. It must be called as early as possible in the process, and will have undefined results if any graphics API functions have been called.
|
||||
|
||||
.. cpp:function:: void UnloadCrashHandler()
|
||||
|
||||
This function will remove RenderDoc's crash handler from the target process. If you have your own crash handler that you want to handle any exceptions, RenderDoc's handler could interfere so it can be disabled.
|
||||
|
||||
.. cpp:function:: void SetLogFilePathTemplate(const char *pathtemplate)
|
||||
|
||||
Set the template for new captures. The template can either be a relative or absolute path, which determines where captures will be saved and how they will be named. If the path template is ``my_captures/example`` then captures saved will be e.g. ``my_captures/example_frame123.rdc`` and ``my_captures/example_frame456.rdc``. Relative paths will be saved relative to the process's current working directory. The default template is in a folder controlled by the UI - initially the system temporary folder, and the filename is the executable's filename.
|
||||
|
||||
:param const char* pathtemplate: specifies the capture path template to set, as UTF-8 null-terminated string.
|
||||
|
||||
.. cpp:function:: const char *GetLogFilePathTemplate()
|
||||
|
||||
Get the current log file path template.
|
||||
|
||||
:return: the current capture path template as a UTF-8 null-terminated string.
|
||||
|
||||
.. cpp:function:: uint32_t GetNumCaptures()
|
||||
|
||||
This function returns the number of frame captures that have been made.
|
||||
:return: Returns the number of frame captures that have been made
|
||||
|
||||
.. cpp:function:: uint32_t GetCapture(uint32_t idx, char *logfile, uint32_t *pathlength, uint64_t *timestamp)
|
||||
|
||||
This function returns the details of a particular frame capture, as specified by an index from 0 to :cpp:func:`GetNumCaptures` - 1.
|
||||
|
||||
:param uint32_t idx: specifies which capture to return the details of. Must be less than the return value of:cpp:func:`GetNumCaptures`.
|
||||
:param char* logfile: is an optional parameter filled with the UTF-8 null-terminated path to the file. There must be enough space in the array to contain all characters including the null terminator. If set to NULL, nothing is written.
|
||||
:param uint32_t* pathlength: is an optional parameter filled with the byte length of the above `logfile` including the null-terminator. If set to NULL, nothing is written.
|
||||
:param uint64_t* timestamp: is an optional parameter filled with the 64-bit timestamp of the file - equivalent to the `time()` system call. If set to NULL, nothing is written.
|
||||
:return: Returns ``1`` if the capture index was valid, or ``0`` if it was out of range.
|
||||
|
||||
.. note::
|
||||
|
||||
It is advised to call this function twice - first to obtain ``pathlength`` so that sufficient space can be allocated. Then again to actually retrieve the path.
|
||||
|
||||
|
||||
The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it may not be an absolute path.
|
||||
|
||||
.. cpp:function:: void TriggerCapture()
|
||||
|
||||
This function will trigger a capture as if the user had pressed one of the capture hotkeys. The capture will be taken from the next frame presented to whichever window is considered current.
|
||||
|
||||
.. cpp:function:: uint32_t IsRemoteAccessConnected()
|
||||
|
||||
This function returns a value to indicate whether the RenderDoc UI is currently connected to the current process.
|
||||
|
||||
:return: Returns ``1`` if the RenderDoc UI is currently connected, or ``0`` otherwise.
|
||||
|
||||
.. cpp:function:: uint32_t LaunchReplayUI(uint32_t connectRemoteAccess, const char *cmdline)
|
||||
|
||||
This function will determine the closest matching replay UI executable for the current RenderDoc module and launch it.
|
||||
|
||||
:param uint32_t connectRemoteAccess: should be set to 1 if the UI should immediately connect to the application.
|
||||
:param const char* cmdline: is an optional UTF-8 null-terminated string to be appended to the command line, e.g. a capture filename. If this parameter is NULL, the command line will be unmodified.
|
||||
:return: If the UI was successfully launched, this function will return the PID of the new process. Otherwise it will return ``0``.
|
||||
|
||||
.. cpp:function:: void SetActiveWindow(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
This function will explicitly set which window is considered active. The active window is the one that will be captured when the keybind to trigger a capture is pressed.
|
||||
|
||||
:param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. Must be valid.
|
||||
:param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. Must be valid.
|
||||
|
||||
.. note::
|
||||
|
||||
``RENDERDOC_DevicePointer`` is a typedef to ``void *``. The contents of it are API specific:
|
||||
|
||||
* For D3D11 it must be the ``ID3D11Device`` device object.
|
||||
* For OpenGL it must be the ``HGLRC`` or ``GLXContext`` context object.
|
||||
* For Vulkan it must be the dispatch table pointer within the ``VkInstance``. This is a pointer-sized value at the location pointed to by the ``VkInstance``. NOTE - this is not the actual ``VkInstance`` pointer itself.
|
||||
|
||||
``RENDERDOC_WindowHandle`` is a typedef to ``void *``. It is the platform specific ``HWND``, ``xcb_window_t``, or Xlib ``Window``.
|
||||
|
||||
.. cpp:function:: void StartFrameCapture(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
This function will immediately begin a capture for the specified device/window combination.
|
||||
|
||||
:param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be NULL to wildcard match.
|
||||
:param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. May be NULL to wildcard match.
|
||||
|
||||
.. note::
|
||||
|
||||
``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`.
|
||||
``device`` and ``wndHandle`` can either or both be set to NULL to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered.
|
||||
|
||||
For example if ``device`` is NULL but ``wndHandle`` is set, RenderDoc will begin a capture on the first API it finds that is active on that window.
|
||||
|
||||
If the wildcard match has multiple possible candidates, it is not defined which will be chosen. Wildcard matching should only be used when e.g. it is known that only one API is active on a window, or there is only one window active for a given API.
|
||||
|
||||
If no window has been created and all rendering is off-screen, NULL can be specified for the window handle and the device object can be passed to select that API. If both are set to NULL, RenderDoc will simply choose one at random so is only recommended for the case where only one is present.
|
||||
|
||||
.. cpp:function:: uint32_t IsFrameCapturing()
|
||||
|
||||
This function returns a value to indicate whether the current frame is capturing.
|
||||
|
||||
:return: Returns ``1`` if the frame is currently capturing, or ``0`` otherwise.
|
||||
|
||||
.. cpp:function:: void EndFrameCapture(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
This function will immediately end an active capture for the specified device/window combination.
|
||||
|
||||
:param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be NULL to wildcard match.
|
||||
:param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. May be NULL to wildcard match.
|
||||
|
||||
.. note::
|
||||
|
||||
``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`.
|
||||
``device`` and ``wndHandle`` can either or both be set to NULL to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered.
|
||||
|
||||
Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`BeginFrameCapture`.
|
||||
|
||||
There will be undefined results if there is not an active frame capture for the device/window combination.
|
||||
@@ -0,0 +1,12 @@
|
||||
Getting started
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
faq
|
||||
gotchas_known_issues
|
||||
quick_start
|
||||
features
|
||||
tips_tricks
|
||||
in_application_api
|
||||
@@ -0,0 +1,191 @@
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
|
||||
This document serves as a brief introduction to how to use RenderDoc to capture and analyse your application. It doesn't go into much detail about exactly what functionality is available for digging into things, as this can be found elsewhere. Instead it focuses on just the workflow from start to finish and roughly where to look for different things.
|
||||
|
||||
For this tutorial we will be using a slightly modified version of the CascadedShadowMaps sample from the Microsoft DirectX SDK (June 2010).
|
||||
|
||||
Capturing a log
|
||||
---------------
|
||||
|
||||
To capture a log, begin by opening the File menu and selecting Capture Log. By default this will open a new docked window where you can configure different settings that will be used when capturing.
|
||||
|
||||
.. figure:: ../images/QuickStart1.png
|
||||
|
||||
Capturing a Log
|
||||
|
||||
The defaults work pretty well in most situations, so you can just either browse to or drag in your exe into the Executable box. If the working directory box is empty then the Executable's directory will be used. Enter any command line you may need and click 'Capture' to launch the application with RenderDoc.
|
||||
|
||||
More details of the specific options and their functionality can be found in the details page for the :doc:`capture_window`.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
It's best to choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa
|
||||
|
||||
You can only capture a 64-bit process with a 64-bit build of RenderDoc. A 32-bit process can be captured by any build of RenderDoc.
|
||||
|
||||
RenderDoc in-app
|
||||
----------------
|
||||
|
||||
RenderDoc has a fairly minimal in-app overlay, just to indicate that RenderDoc has successfully loaded and is ready to capture a frame.
|
||||
|
||||
|
||||
When ready, press the Capture Key (:kbd:`F12` or :kbd:`Print Screen`) and the next frame after the keypress will be captured, and this will show up on the overlay to let you know that a frame has been successfully saved.
|
||||
|
||||
.. figure:: ../images/QuickStart2.png
|
||||
|
||||
The in-application RenderDoc Overlay
|
||||
|
||||
When the application exits, if you captured a log it will automatically start to open in the RenderDoc UI. If you didn't capture a log then nothing will happen and the RenderDoc UI will be back as it was when you clicked Capture.
|
||||
|
||||
|
||||
If you made multiple captures you will see a thumbnail list that allows you to open (in the current instance or a new instance to compare side-by-side), save and delete them as you wish. You can also access this view while the program is still running, see :doc:`capture_connection` for more information on taking multiple frame captures. Note however that for the simple use-case, you don't need to worry about this!
|
||||
|
||||
RenderDoc layout
|
||||
----------------
|
||||
|
||||
RenderDoc's layout can be customised fairly heavily so this section will only cover the default layout. We'll go over the windows that are open by default and how each can be used in analysing your program.
|
||||
|
||||
|
||||
Each of these windows has a section that is much more in depth and gives details about every function and feature, for the more complex windows such as the texture viewer you may well wish to skim these to get an idea of what is available and use them as reference in the future.
|
||||
|
||||
.. figure:: ../images/QuickStart3.png
|
||||
|
||||
The Texture Viewer
|
||||
|
||||
Texture Viewer
|
||||
--------------
|
||||
|
||||
More details can be found on the :doc:`texture_viewer` page.
|
||||
|
||||
The texture viewer does pretty much what you'd expect - it allows you to inspect textures and render targets in your application.
|
||||
|
||||
There are various visualisation controls that allow you to select different channels, mip levels or other aspects of the texture, and more detail is available in the above page. Here we'll just touch on the highlights:
|
||||
|
||||
* The thumbnail strip (by default to the right) lists either the output targets, or shader inputs bound and used at present. Selecting each of these (the red outline on the thumbnail indicating which is selected) will follow whatever resource is bound to that slot as you browse through the scene.
|
||||
|
||||
E.g. if you select render target 0 then the texture display will update to show the currently bound render target 0 regardless of which texture that is. If the slot you are following becomes unbound or unused, the previous texture will still be displayed up until you select a different pipeline slot, or the slot is bound again. Unbound texture slots show up with _Unbound_ listed under their thumbnail.
|
||||
|
||||
To open a specific texture and watch it even as it changes slots or becomes unbound, you can open it in a new locked tab. Right click on the thumbnail and 'open in new locked tab', or :doc:`open it by name <how_view_texture>`.
|
||||
|
||||
* The format and dimensions of the texture are displayed on the status bar just below the texture display itself.
|
||||
Also on this status bar you can see the current pixel co-ordinate that you are hovering over, as well as the 'picked' pixel value which can be inspected by right clicking anywhere on the texture display.
|
||||
|
||||
* Further to this, there is a small zoomed section of context around the last picked pixel available in the bottom right of the texture viewer window. From here you can also launch the pixel history or debugger, as detailed in :doc:`how_debug_shader`.
|
||||
|
||||
* The last thing we will highlight is the range control. This is a fairly flexible tool that allows you to adjust the visible range in the image. This is particular useful when viewing HDR images with a range outside of *[0, 1]*.
|
||||
|
||||
To use the range control you can drag the white and black points to make fine adjustments or type values to change the values of the white and black points (by default 0 and 1 respectively). There are also some useful controls to the right of the range control itself, which are detailed again in the :doc:`texture_viewer` page.
|
||||
|
||||
Event Browser
|
||||
`````````````
|
||||
|
||||
.. figure:: ../images/QuickStart4.png
|
||||
|
||||
The Event Browser
|
||||
|
||||
More details can be found on the :doc:`event_browser` page.
|
||||
|
||||
.. |timeline_marker| image:: ../images/timeline_marker.png
|
||||
|
||||
The Event Browser is the primary method of stepping through the frame and browsing the events that occurred within. The first column EID (Event ID) indicates which event or API call this was in the frame, chronologically. Events which are listed here are generally output/draw type events, including Clears. Copy and Map type calls are not included and are available in the API Calls view (see below).
|
||||
|
||||
The columns can be customised and reordered, the |timeline_marker| select columns button (or right-click) will allow you to choose which columns are displayed.
|
||||
|
||||
Standard performance markers are available and create the hierarchy/labels as you would expect. These can be expanded or collapsed and keyboard browsing is available through normal controls - left and right go higher or lower in the hierarchy, and up and down goes up and down through siblings.
|
||||
|
||||
.. |flag_green| image:: ../images/flag_green.png
|
||||
.. |find| image:: ../images/find.png
|
||||
.. |asterisk_orange| image:: ../images/asterisk_orange.png
|
||||
|
||||
The 'current' event - i.e. the event at which we are inspecting the graphics state - is highlighted with a green Flag |flag_green| and the row is highlighted. As any row is selected it immediately becomes the new current event.
|
||||
|
||||
While the Event Browser is selected, you can press the shortcut keys :kbd:`CTRL-F` or :kbd:`CTRL-G` to find |find| or jump to a given EID |flag_green| respectively.
|
||||
|
||||
|
||||
The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`CTRL-B`.
|
||||
|
||||
A list of bookmarked events will show up on a toolbar at the top of the event browser, they and the shortcut keys :kbd:`CTRL-1` to :kbd:`CTRL-0` will jump to the respective bookmarked EID. These shortcuts will work anywhere in the application.
|
||||
|
||||
API Inspector
|
||||
`````````````
|
||||
|
||||
.. figure:: ../images/QuickStart5.png
|
||||
|
||||
The API Calls + Callstack Panel
|
||||
|
||||
More details can be found on the :doc:`api_inspector` page.
|
||||
|
||||
The API Calls window updates as a new event is selected. It shows the individual API calls and their parameters (in some fashion) between the previous and current event. The bottom entry in this list always corresponds to the event that is currently selected, and each row can be expanded to show the parameters that were passed to that API call.
|
||||
|
||||
At the bottom of the window is an optional expandable section which shows the callstack (if available and recorded) from the application code into the API function.
|
||||
|
||||
|
||||
In order to view these callstacks you must first resolve the symbols recorded with the log. To do this click on :kbd:`Resolve Symbols` under the :kbd:`Tools` menu. More details on this process can be found in the guide: :doc:`how_capture_callstack`.
|
||||
|
||||
Timeline Bar
|
||||
````````````
|
||||
|
||||
.. figure:: ../images/QuickStart6.png
|
||||
|
||||
The Timeline Bar
|
||||
|
||||
More details can be found on the :doc:`timeline_bar` page.
|
||||
|
||||
The timeline bar is essentially an alternate view of the frame, with the horizontal axis being time in the frame. The scale however is non-linear and is weighted to try and show each section of the frame equally and visibly, rather than scaling by duration.
|
||||
|
||||
The frame marker hierarchy is top-down in this case, and can be expanded or collapsed by clicking on each section. In this image, Cascades and Cascade 1 are both expanded, but the other sections remain collapsed. Each drawcall is rendered as a blue circle underneath the section of the hierarchy that it is a child of. The current drawcall (if visible) is rendered as a green circle and there are two vertical bars - red for the current mouse highlight, and light grey for the current drawcall, so it is visible regardless of the hierarchy expansion.
|
||||
|
||||
When the currently selected texture is used in the frame, each drawcall that references it draws a marker below the bar. A purple marker indicates that the drawcall at that point is writing to the texture, and a green marker indicates that it is reading. If the markers are too close together they will space themselves to be readable and will not necessarily line up to a particular drawcall unless you zoom in.
|
||||
|
||||
This can be a very useful tool to trace data through a frame, as well as highlighting potential redundancy or errors if a target is being written to where it should not.
|
||||
|
||||
Pipeline State
|
||||
``````````````
|
||||
|
||||
.. figure:: ../images/QuickStart7.png
|
||||
|
||||
The Pipeline State Viewer
|
||||
|
||||
More details can be found on the :doc:`pipeline_state` page.
|
||||
|
||||
|
||||
The Pipeline State window is perhaps the most detailed but also the simplest to understand. This window simply lists every stateful aspect of the graphics pipeline and what value or object is present at the current event.
|
||||
|
||||
.. |go_arrow| image:: ../images/GoArrow.png
|
||||
|
||||
By default the pipeline will not contain empty or unused entries - i.e. if a shader only reads from resources 0 and 1, even if something is bound to slot 2 it will not be displayed. Likewise say slots 3-128 are empty - they will also not be displayed. This behaviour can be modified by the :guilabel:`Show Disabled Items` and :guilabel:`Show Empty Items` toggles on the toolbar. Show Disabled will show slot 2 even if the shader does not read from it. Show Empty will show slots 3-128.
|
||||
|
||||
The most important thing to note is that most things in the sections for each pipeline stage can be expanded to view in more detail. Look for the Go Icon (|go_arrow|) to indicate that a more detailed view is available. Typically this will mean for shaders the shader source/disassembly will be opened, for texture-type resources the texture viewer will open a new tab for that resource, and for buffers it will open either the Mesh Output window, a raw view of that buffer, or a popup with the constant contents - depending on where the buffer is bound.
|
||||
|
||||
For more details, check out the how-to: :doc:`how_view_object`.
|
||||
|
||||
Mesh Output
|
||||
```````````
|
||||
|
||||
.. figure:: ../images/QuickStart8.png
|
||||
|
||||
Mesh Output Viewer
|
||||
|
||||
More details can be found on the :doc:`mesh_view` page.
|
||||
|
||||
.. |undo_arrow| image:: ../images/UndoArrow.png
|
||||
.. |cog| image:: ../images/cog.png
|
||||
|
||||
Mesh Output allows you to inspect the geometry data as it passes through the pipeline. Both raw data in a grid view and 3D inspection is possible. The tabs in the preview window allow you to choose at which part of the pipeline you'd like to visualise the data.
|
||||
|
||||
When in the VS Input tab (or VS Output if tessellating), you can select to solid shader the object with either flat shading or a secondary shading, which lets you right click on any column to select it as colour data to render on the mesh.
|
||||
|
||||
You can hold or click the right mouse button on the mesh preview to select the vertex in the mesh data tables.
|
||||
|
||||
When in the VS/GS/DS Output tabs there is the option to show the context leading up to this drawcall by showing everything since the last clear. The default view (which you can reset to with the reset button |undo_arrow|) shows the camera at the view origin looking out through the viewport. By default the output attempts to guess a perspective matrix from the output data, but this can be refined or changed to an orthographic view by opening up the options |cog| and entering more accurate or corrected values.
|
||||
|
||||
Closing Notes
|
||||
-------------
|
||||
|
||||
Obviously what you accomplish in the program will vary a lot by what you need to investigate, but hopefully this gives you an overview of the functionality available. There are many more detailed features that are available, and the rest of this help will aid you in finding those.
|
||||
|
||||
It is probably a good idea to check out the :doc:`tips_tricks` page which lists several useful notes that aren't obvious but might save you a lot of time.
|
||||
@@ -0,0 +1,94 @@
|
||||
Tips & Tricks
|
||||
=============
|
||||
|
||||
.. |go_arrow| image:: ../images/GoArrow.png
|
||||
.. |wand| image:: ../images/wand.png
|
||||
|
||||
This page is a random hodge-podge of different tips and tricks that might not be obvious and aren't practical to make clear in the UI - e.g. keyboard shortcuts, edge cases and suchlike.
|
||||
|
||||
#. File associations for .rdc and .cap files can be set up in the installer or in the :doc:`option_window`. These allow automatic opening of capture logs or capture settings files directly from files.
|
||||
|
||||
.. note::
|
||||
|
||||
These associations must be re-created if RenderDoc is moved to another folder.
|
||||
|
||||
#. RenderDoc can be used as an image viewer! If you drag in or use file → 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. If the file is modified, RenderDoc will reload it and display it. Note that changing the image's dimensions or format will likely cause problems.
|
||||
#. 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 & set of options that you regularly re-run.
|
||||
|
||||
For more information check out the :doc:`capture_attach` page.
|
||||
|
||||
#. If you'd like to see the geometry data with each component separated out and formatted, either open "Mesh Output" under the window menu, or click the Go Arrow |go_arrow| on the input layouts in the :doc:`pipeline_state`.
|
||||
#. Right clicking on one of the channel buttons in the texture viewer (R, G, B, A) will either select only that channel, or if it's already the only one selected it will select all of the others. This is useful e.g. to toggle between viewing RGB and alpha, or for looking at individual channels in a packed texture or render target.
|
||||
#. Similarly, right-clicking on the 'auto-fit' button |wand| will auto-fit whenever the texture or event changes, so that the visible range is maintained as you move through the frame. This can be useful if jumping between places where the visible range is very different.
|
||||
#. You can double click on a thumbnail in the texture viewer to open a :doc:`locked texture <how_view_texture>` tab
|
||||
#. You can close tabs by middle clicking on them.
|
||||
#. You can trigger a capture from code. renderdoc.dll exports an :doc:`in_application_api` for this purpose, defined in ``renderdoc_app.h`` in the distributions:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
#include "renderdoc_app.h"
|
||||
|
||||
RENDERDOC_API_1_0_1 *rdoc_api = NULL;
|
||||
|
||||
// At init
|
||||
if(HMODULE mod = GetModuleHandleA("renderdoc.dll"))
|
||||
{
|
||||
pRENDERDOC_GetAPI RENDERDOC_GetAPI = (pRENDERDOC_GetAPI)GetProcAddress(mod, "RENDERDOC_GetAPI");
|
||||
int ret = RENDERDOC_GetAPI(eRENDERDOC_API_Version_1_0_1, (void **)&rdoc_api);
|
||||
assert(ret == 1);
|
||||
}
|
||||
|
||||
// When you wish to trigger the capture
|
||||
if(rdoc_api) rdoc_api->TriggerCapture();
|
||||
|
||||
The next ``Swap()`` after this call will begin the captured frame, and the ``Swap()`` after that will end it (barring complications)
|
||||
|
||||
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.
|
||||
|
||||
#. 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.
|
||||
#. To get API debug or error messages, enable "Create Debug Device" when capturing then check out the :doc:`debug_messages` window.
|
||||
#. Detecting RenderDoc from your code can either be done by trying to load and use the renderdoc :doc:`in_application_api`, or through API specific ways:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
// For D3D11:
|
||||
ID3D11Device *devicePointer = ...;
|
||||
IUnknown *unk = NULL;
|
||||
HRESULT hr = devicePointer->QueryInterface(MAKE_GUID({A7AA6116-9C8D-4BBA-9083-B4D816B71B78}), &unk);
|
||||
if(SUCCEEDED(hr)) { /* renderdoc is present; */ }
|
||||
|
||||
// For OpenGL:
|
||||
// if GL_EXT_debug_tool is present (see https://renderdoc.org/debug_tool.txt)
|
||||
glIsEnabled(GL_DEBUG_TOOL_EXT);
|
||||
|
||||
// Until enumerants are assigned (if that ever happens):
|
||||
#define GL_DEBUG_TOOL_EXT 0x6789
|
||||
#define GL_DEBUG_TOOL_NAME_EXT 0x678A
|
||||
#define GL_DEBUG_TOOL_PURPOSE_EXT 0x678B
|
||||
|
||||
#. RenderDoc can be informed about separated debug shader blobs through API specific ways:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
// 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, &path, pathSize, &annotatedBlob);
|
||||
// use annotatedBlob instead of strippedBlob from here on
|
||||
|
||||
#. More coming soon hopefully :).
|
||||
@@ -0,0 +1,24 @@
|
||||
.. RenderDoc documentation master file, created by
|
||||
sphinx-quickstart on Thu May 12 16:59:09 2016.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to RenderDoc's documentation!
|
||||
=====================================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction
|
||||
credits_acknowledgements
|
||||
getting_started/index
|
||||
behind_scenes/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
@@ -0,0 +1,61 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
.. |renderdoc_logo| image:: images/logo.png
|
||||
|
||||
|renderdoc_logo|
|
||||
|
||||
Welcome to RenderDoc - a graphics debugger, currently available for D3D11, Vulkan and OpenGL development on windows.
|
||||
|
||||
This document serves primarily as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them.
|
||||
|
||||
The latest information and discussion is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki>`_.
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
RenderDoc is released under the MIT license, so there are no restrictions on your use of it either commercial or non-commercial. This includes the source release available on the `GitHub repository <https://github.com/baldurk/renderdoc/issues>`_.
|
||||
|
||||
Details of the licenses of third party software used in RenderDoc are included in the LICENSE file in the RenderDoc directory as well as in the :doc:`credits_acknowledgements`.
|
||||
|
||||
How to browse this documentation
|
||||
--------------------------------
|
||||
|
||||
If you just want to dive straight in and learn how to get started using RenderDoc consider looking at the :doc:`quick_start` section which gives a simple introduction on how to get started. Afterwards there are reference pages on each of the windows available in RenderDoc which can be referred to as you use the program, or skimmed to get a feel for the functionality available.
|
||||
|
||||
|
||||
Those of you familiar with other graphics debuggers will likely find much of RenderDoc recognisable, you might want to check out the :doc:`FAQ`, :doc:`Features`, :doc:`tips_tricks` or browse the How Do I... ? sections which detail how some common tasks are accomplished.
|
||||
|
||||
Regardless of your experience or patience for documentation it's recommended that you read the :doc:`gotchas_known_issues` as this details known bugs and current limitations of the program.
|
||||
|
||||
Important notes
|
||||
---------------
|
||||
|
||||
* RenderDoc is not yet bug free! It is pretty stable but you will still likely encounter bugs depending on your use case. I am *always* happy to spend time to fix them and I can work with you even if you cannot share any details about your project. Get in touch (see below) and I will actively fix your bug!
|
||||
* On the other side of the coin, please do give feedback when RenderDoc works for you and request features that would make your life easier or improve your workflow.
|
||||
* There are a few common issues you might run into, so if you have any problems check the :doc:`FAQ`, or the `issues page on github <https://github.com/baldurk/renderdoc/issues>`_ to see if it's been reported.
|
||||
|
||||
Documentation and Tutorials
|
||||
---------------------------
|
||||
|
||||
I have recorded some `youtube videos <http://www.youtube.com/user/baldurkarlsson/>`_ showing the use of some basic features and an introduction/overview.
|
||||
|
||||
There is also a great presentation by `@Icetigris <https://twitter.com/Icetigris>`_ which goes into some details of how RenderDoc can be used in real world situations: `slides are up here <https://docs.google.com/presentation/d/1LQUMIld4SGoQVthnhT1scoA3k4Sg0as14G4NeSiSgFU/edit#slide-id.p>`_.
|
||||
|
||||
Contact info, Feedback, Bug reports
|
||||
-----------------------------------
|
||||
|
||||
If you want to get in touch with any feature requests, suggestions, comments etc then feel free to contact me: `Contact me <mailto:baldurk@baldurk.org?subject=RenderDoc%20feedback>`_.
|
||||
|
||||
Bug reports can be submitted directly via email, or also on the `github repository <https://github.com/baldurk/renderdoc/issues>`_ where you can also find the full source code.
|
||||
|
||||
The `builds page <https://renderdoc.org/builds>`_ always has the latest stable and beta build downloads, as well as builds made from the source code each night for the bleeding edge. Stable releases update relatively infrequently and are tested the most to ensure they're as reliable as possible. Beta releases update more often to expose the latest fixes and features from the source, but risk more bugs sneaking in.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* `RenderDoc Homepage <http://renderdoc.org/>`_
|
||||
* `Builds page <https://renderdoc.org/builds>`_
|
||||
+281
@@ -0,0 +1,281 @@
|
||||
@ECHO OFF
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set BUILDDIR=_build
|
||||
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
|
||||
set I18NSPHINXOPTS=%SPHINXOPTS% .
|
||||
if NOT "%PAPER%" == "" (
|
||||
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
|
||||
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
if "%1" == "help" (
|
||||
:help
|
||||
echo.Please use `make ^<target^>` where ^<target^> is one of
|
||||
echo. html to make standalone HTML files
|
||||
echo. dirhtml to make HTML files named index.html in directories
|
||||
echo. singlehtml to make a single large HTML file
|
||||
echo. pickle to make pickle files
|
||||
echo. json to make JSON files
|
||||
echo. htmlhelp to make HTML files and a HTML help project
|
||||
echo. qthelp to make HTML files and a qthelp project
|
||||
echo. devhelp to make HTML files and a Devhelp project
|
||||
echo. epub to make an epub
|
||||
echo. epub3 to make an epub3
|
||||
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
|
||||
echo. text to make text files
|
||||
echo. man to make manual pages
|
||||
echo. texinfo to make Texinfo files
|
||||
echo. gettext to make PO message catalogs
|
||||
echo. changes to make an overview over all changed/added/deprecated items
|
||||
echo. xml to make Docutils-native XML files
|
||||
echo. pseudoxml to make pseudoxml-XML files for display purposes
|
||||
echo. linkcheck to check all external links for integrity
|
||||
echo. doctest to run all doctests embedded in the documentation if enabled
|
||||
echo. coverage to run coverage check of the documentation if enabled
|
||||
echo. dummy to check syntax errors of document sources
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "clean" (
|
||||
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
|
||||
del /q /s %BUILDDIR%\*
|
||||
goto end
|
||||
)
|
||||
|
||||
|
||||
REM Check if sphinx-build is available and fallback to Python version if any
|
||||
%SPHINXBUILD% 1>NUL 2>NUL
|
||||
if errorlevel 9009 goto sphinx_python
|
||||
goto sphinx_ok
|
||||
|
||||
:sphinx_python
|
||||
|
||||
set SPHINXBUILD=python -m sphinx.__init__
|
||||
%SPHINXBUILD% 2> nul
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
:sphinx_ok
|
||||
|
||||
|
||||
if "%1" == "html" (
|
||||
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "dirhtml" (
|
||||
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "singlehtml" (
|
||||
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "pickle" (
|
||||
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can process the pickle files.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "json" (
|
||||
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can process the JSON files.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "htmlhelp" (
|
||||
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can run HTML Help Workshop with the ^
|
||||
.hhp project file in %BUILDDIR%/htmlhelp.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "qthelp" (
|
||||
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; now you can run "qcollectiongenerator" with the ^
|
||||
.qhcp project file in %BUILDDIR%/qthelp, like this:
|
||||
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\RenderDoc.qhcp
|
||||
echo.To view the help file:
|
||||
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\RenderDoc.ghc
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "devhelp" (
|
||||
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "epub" (
|
||||
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The epub file is in %BUILDDIR%/epub.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "epub3" (
|
||||
%SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The epub3 file is in %BUILDDIR%/epub3.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latex" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latexpdf" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
cd %BUILDDIR%/latex
|
||||
make all-pdf
|
||||
cd %~dp0
|
||||
echo.
|
||||
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "latexpdfja" (
|
||||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
|
||||
cd %BUILDDIR%/latex
|
||||
make all-pdf-ja
|
||||
cd %~dp0
|
||||
echo.
|
||||
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "text" (
|
||||
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The text files are in %BUILDDIR%/text.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "man" (
|
||||
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The manual pages are in %BUILDDIR%/man.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "texinfo" (
|
||||
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "gettext" (
|
||||
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "changes" (
|
||||
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.The overview file is in %BUILDDIR%/changes.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "linkcheck" (
|
||||
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Link check complete; look for any errors in the above output ^
|
||||
or in %BUILDDIR%/linkcheck/output.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "doctest" (
|
||||
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Testing of doctests in the sources finished, look at the ^
|
||||
results in %BUILDDIR%/doctest/output.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "coverage" (
|
||||
%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Testing of coverage in the sources finished, look at the ^
|
||||
results in %BUILDDIR%/coverage/python.txt.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "xml" (
|
||||
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The XML files are in %BUILDDIR%/xml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "pseudoxml" (
|
||||
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
|
||||
goto end
|
||||
)
|
||||
|
||||
if "%1" == "dummy" (
|
||||
%SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy
|
||||
if errorlevel 1 exit /b 1
|
||||
echo.
|
||||
echo.Build finished. Dummy builder generates no files.
|
||||
goto end
|
||||
)
|
||||
|
||||
:end
|
||||
Reference in New Issue
Block a user