From f124f3f389a273e6414afe6122bf50be6a977d07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matth=C3=A4us=20G=2E=20Chajdas?= Date: Sun, 15 May 2016 12:27:02 +0200 Subject: [PATCH] Port the remaining pages where I know how to style them. --- docs/getting_started/gotchas_known_issues.rst | 2 +- docs/getting_started/quick_start.rst | 20 +-- docs/getting_started/tips_tricks.rst | 8 +- docs/how/how_capture_log.rst | 4 +- docs/how/how_inspect_pixel.rst | 2 +- docs/index.rst | 2 +- docs/window/api_inspector.rst | 40 ++++++ docs/window/buffer_viewer.rst | 100 ++++++++++++++ docs/window/capture_connection.rst | 69 ++++++++++ docs/window/capture_log_attach.rst | 2 + docs/window/debug_messages.rst | 22 +++ docs/window/event_browser.rst | 125 ++++++++++++++++++ docs/window/index.rst | 15 +++ docs/window/options_window.rst | 2 + docs/window/pipeline_state.rst | 48 +++++++ docs/window/python_shell.rst | 26 ++++ docs/window/texture_viewer.rst | 2 + docs/window/timeline_bar.rst | 66 +++++++++ 18 files changed, 536 insertions(+), 19 deletions(-) create mode 100644 docs/window/api_inspector.rst create mode 100644 docs/window/buffer_viewer.rst create mode 100644 docs/window/capture_connection.rst create mode 100644 docs/window/capture_log_attach.rst create mode 100644 docs/window/debug_messages.rst create mode 100644 docs/window/event_browser.rst create mode 100644 docs/window/index.rst create mode 100644 docs/window/options_window.rst create mode 100644 docs/window/pipeline_state.rst create mode 100644 docs/window/python_shell.rst create mode 100644 docs/window/texture_viewer.rst create mode 100644 docs/window/timeline_bar.rst diff --git a/docs/getting_started/gotchas_known_issues.rst b/docs/getting_started/gotchas_known_issues.rst index 3acc9f634..3cb7c6122 100644 --- a/docs/getting_started/gotchas_known_issues.rst +++ b/docs/getting_started/gotchas_known_issues.rst @@ -10,7 +10,7 @@ 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 <../how/capture_log>` 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. + You can override this behaviour by selecting 'Save All Initials' in the :doc:`capture options <../how/how_capture_log>` 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. diff --git a/docs/getting_started/quick_start.rst b/docs/getting_started/quick_start.rst index 874b95ad6..77792a67d 100644 --- a/docs/getting_started/quick_start.rst +++ b/docs/getting_started/quick_start.rst @@ -18,7 +18,7 @@ To capture a log, begin by opening the File menu and selecting Capture Log. By d 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`. +More details of the specific options and their functionality can be found in the details page for the :doc:`../window/capture_log_attach`. .. note:: @@ -42,7 +42,7 @@ When ready, press the Capture Key (:kbd:`F12` or :kbd:`Print Screen`) and the ne 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! +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:`../window/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 ---------------- @@ -59,7 +59,7 @@ Each of these windows has a section that is much more in depth and gives details Texture Viewer -------------- -More details can be found on the :doc:`texture_viewer` page. +More details can be found on the :doc:`../window/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. @@ -74,11 +74,11 @@ There are various visualisation controls that allow you to select different chan * 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`. +* 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/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. + 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:`../window/texture_viewer` page. Event Browser ````````````` @@ -87,7 +87,7 @@ Event Browser The Event Browser -More details can be found on the :doc:`event_browser` page. +More details can be found on the :doc:`../window/event_browser` page. .. |timeline_marker| image:: ../images/timeline_marker.png @@ -117,7 +117,7 @@ API Inspector The API Calls + Callstack Panel -More details can be found on the :doc:`api_inspector` page. +More details can be found on the :doc:`../window/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. @@ -133,7 +133,7 @@ Timeline Bar The Timeline Bar -More details can be found on the :doc:`timeline_bar` page. +More details can be found on the :doc:`../window/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. @@ -150,7 +150,7 @@ Pipeline State The Pipeline State Viewer -More details can be found on the :doc:`pipeline_state` page. +More details can be found on the :doc:`../window/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. @@ -170,7 +170,7 @@ Mesh Output Mesh Output Viewer -More details can be found on the :doc:`mesh_view` page. +More details can be found on the :doc:`../window/buffer_viewer` page. .. |undo_arrow| image:: ../images/UndoArrow.png .. |cog| image:: ../images/cog.png diff --git a/docs/getting_started/tips_tricks.rst b/docs/getting_started/tips_tricks.rst index 7a82405ae..f353a0491 100644 --- a/docs/getting_started/tips_tricks.rst +++ b/docs/getting_started/tips_tricks.rst @@ -6,7 +6,7 @@ Tips & Tricks 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. +#. File associations for .rdc and .cap files can be set up in the installer or in the :doc:`../window/option_window`. These allow automatic opening of capture logs or capture settings files directly from files. .. note:: @@ -15,9 +15,9 @@ This page is a random hodge-podge of different tips and tricks that might not be #. 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. + For more information check out the :doc:`../window/capture_log_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`. +#. 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:`../window/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/how_view_texture>` tab @@ -46,7 +46,7 @@ This page is a random hodge-podge of different tips and tricks that might not be 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. +#. To get API debug or error messages, enable "Create Debug Device" when capturing then check out the :doc:`../window/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++ diff --git a/docs/how/how_capture_log.rst b/docs/how/how_capture_log.rst index bc6a5dca7..20d907e4b 100644 --- a/docs/how/how_capture_log.rst +++ b/docs/how/how_capture_log.rst @@ -1,7 +1,7 @@ How do I capture a log? ======================= -Capturing logfiles is the starting point to using RenderDoc. Although the basic use is very simple, there are various customisations and more advanced uses. More information on these can be found in the details of the :doc:`../window/capture_log` window. +Capturing logfiles is the starting point to using RenderDoc. Although the basic use is very simple, there are various customisations and more advanced uses. More information on these can be found in the details of the :doc:`../window/capture_log_attach` window. Capturing logs -------------- @@ -56,4 +56,4 @@ You can also use the "Auto start" option - when this option is enabled then a .c See Also -------- -* :doc:`../window/capture_log` +* :doc:`../window/capture_log_attach` diff --git a/docs/how/how_inspect_pixel.rst b/docs/how/how_inspect_pixel.rst index eab073424..2ad3f2932 100644 --- a/docs/how/how_inspect_pixel.rst +++ b/docs/how/how_inspect_pixel.rst @@ -19,7 +19,7 @@ At any point while hovering over the texture the status bar contains the current Hover Status Bar: The status bar showing position and colour -When the right mouse button is pressed, the currently hovered pixel value will be displayed with the current float precision settings - for more information on how to tune these look at the window reference for the :doc:`../window/option`. +When the right mouse button is pressed, the currently hovered pixel value will be displayed with the current float precision settings - for more information on how to tune these look at the window reference for the :doc:`../window/options_window`. For depth textures the depth and stencil values will be displayed separately. The stencil value (as with any integer formatted texture) will be displayed as an integer. diff --git a/docs/index.rst b/docs/index.rst index 511834674..5c8343d8a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,10 +16,10 @@ Contents: getting_started/index behind_scenes/index how/index + window/index Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/docs/window/api_inspector.rst b/docs/window/api_inspector.rst new file mode 100644 index 000000000..2eded5fa1 --- /dev/null +++ b/docs/window/api_inspector.rst @@ -0,0 +1,40 @@ +API Inspector +============= + +.. toctree:: + + +Although not the most complex part of the RenderDoc's UI, this page details the features and functionality of the API Inspector. + +UI Elements +----------- + +The API Inspector is divided into two sections - the top section is the most common, detailing all of the API calls leading up to and including the current drawcall. The special case for this is the end of the frame where there may not be a final drawcall but the API Inspector lists the API calls that preceded the final flip of the backbuffer that marks the end of RenderDoc's captured frame. + +The bottom section is less common but shows the callstack from user code into the API entry point, if such a callstack is available and the symbols are resolved. For more information check out the page on :doc:`../how/how_capture_callstack`. + +API Calls +--------- + +This section lists the series of API calls made between the preceding drawcall and the currently selected drawcall. The current drawcall is always the last element in this list and is highlighted in bold. By default it is also the selected element. + +Each API call can be expanded to see the parameters that were passed to it, in the form that they were serialised out to the log file. + +.. figure:: ../images/APIList.png + + API Calls: A list of API calls made up to the current draw. + +Callstack +--------- + +The callstack section can be expanded by double clicking on the separator and collapsed in the same way. Once open its size can be adjusted by clicking and dragging on the separator. + +This section will either show "No callstack available" or "Need to resolve symbols" as appropriate when the callstacks aren't ready for display. + +The callstack follows the currently selected API call in the other section, and will update both as that selected call change and as the current event changes (as this implicitly changes the API call selected to whichever the current drawcall is). + +For more information see :doc:`../how/how_capture_callstack` + +.. figure:: ../images/CallstackPanel.png + + Callstack: The callstack in user code where this API call was made. diff --git a/docs/window/buffer_viewer.rst b/docs/window/buffer_viewer.rst new file mode 100644 index 000000000..32e7c1858 --- /dev/null +++ b/docs/window/buffer_viewer.rst @@ -0,0 +1,100 @@ +Buffer Viewer/Mesh Output +========================= + +The buffer viewer has two reasonably distinct modes - the first rather specialised to show meshes and mesh data as it passes through the pipeline. The other shows a raw arbitrary buffer with a custom (and arbitrary) formatting. + +Mesh Viewer +----------- + +The Mesh Viewer shows both the mesh data as well as a visual representation of the mesh at different stages - pre VS, post VS, etc. For instanced drawcalls you can choose which instance to view in the toolbar at the top. + +.. |arrow_join| image:: ../images/arrow_join.png + +Each distinct point has a display that shows the mesh data, the format of which is pulled from the relevant stage of the pipeline - shader input or output, or input layout. You can choose to sync these views |arrow_join| as well as specify an offset which will stay consistent, so that you can see the same row as you move between different events. + +Below this is a 3D view which will show one stage at any given time, and can be switched with the tabs above it. There are two control schemes for viewing the 3D mesh - Arcball which is the default for pre-transform (VS in), and WASD controls which is the default for post-transform (VS out). You can switch between these at any time with the dropdown on the toolbar above the mesh view. + +.. note:: + + When tessellation is active, VS out behaves similarly to VS in as they are both considered input data (rather than post-transform data). + +.. |arrow_undo| image:: ../images/arrow_undo.png + +You can reset the camera to its default location with the reset button |arrow_undo|. For VS Input this resets to an arcball at some radius from the object. For VS Output this resets to a view from the projected eye. + +.. |wand| image:: ../images/wand.png + +You can also auto-fit the camera to the mesh for the VS Input mesh. The auto-fit button |wand| will fit the camera to the axis-aligned bounding box of the mesh. + +To be able to view the post-transform mesh in view-space, RenderDoc attempts to guess the projection matrix and unprojects the output data. + +By default the projection matrix is guessed as a standard perspective matrix. Using the post-projection w and z values and the aspect ratio of the output targets a reasonable approximation can be estimated. The FOV must be specified though - the default is 90 but this can be refined by opening the options. + +.. |cog| image:: ../images/cog.png + +Opening the options |cog| you can specify the FOV used in the projection matrix. If you used an orthographic matrix instead you can specify this - although this requires manual tuning of the matrix parameters. + +.. figure:: ../images/BufferOptions.png + + Options: The options pop-out of the buffer viewer. + +Also available in the options is a simple speed multiplier for the WASD controls, to fine-tune how fast it moves to the dimensions of the mesh. + +Mesh Preview +------------ + +In the 3D Mesh preview, you have the option to display the mesh with some solid shading modes, not just as a wireframe mesh. When solid shading you can toggle the wireframe on and off. + +* Solid Colour simply displays a solid colour for each triangle. +* Flat Shaded will perform basic flat lighting calculations based on triangle normals to give a better idea of the topology of the mesh. +* Secondary will display the selected secondary mesh element. + +To select which element will be displayed as secondary, simply right click on the column you would like to use. This can be done on the input and output separately, and 4-component columns have the option to either show RGB as colour, or alpha as greyscale. + +The selection will be remembered as long as the mesh format stays consistent between draws. + +You can also use this if the position data isn't detected in your inputs and you'd like to choose which element contains the positions, or if you'd like to visualise some other data such as UV co-ordinates as positional (in effect rendering the mesh in uv-space). + +.. figure:: ../images/SolidPreview.png + + Preview: Previewing the uv co-ordinates as colour on the mesh. + +Raw Buffer Viewer +----------------- + +When opening a buffer as a raw display, sometimes a default layout will be specified e.g. if available from shader reflection data. If not, the layout will default to 4 32bit unsigned integers. + +This format can be refined and customised by entering a structure-like definition into the text box at the bottom of the window. The given types are listed below, and can be combined in hlsl- or glsl-like fashion specifying n-wide vector elements. + +In addition to this, you can specify a row offset which is useful in remaining at the same row while watching the change in a buffer between different events, as well as a byte offset to shift the data along from the start of the buffer (e.g. if what you are interested in starts only part-way through the buffer but is not aligned along the data stride you enter). + +.. figure:: ../images/RawBuffer.png + + Buffer specification: Specifying a custom buffer format. + +Below are listed the basic types. You can append a number to each of these to make an N-wide vector (e.g. ushort4 or float3, or uvec4/vec3). You can also specify matrices as float3x4 or mat3x4. By default matrices are column major, but you can change this by prepending row_major as you would in hlsl. + +* ``uint`` - unsigned 32bit integer +* ``bool`` - unsigned 32bit integer (this is the format for hlsl bools) +* ``int`` - signed 32bit integer +* ``ushort`` - unsigned 16bit integer +* ``short`` - signed 16bit integer +* ``ubyte`` - unsigned 8bit integer +* ``byte`` - signed 8bit integer +* ``double`` - 64bit floating point +* ``float`` - 32bit floating point +* ``half`` - 16bit floating point + +There are also some non-hlsl types for displaying other formats which don't have a corresponding native hlsl type + +* ``unormb`` - 8bit unsigned normalised value +* ``unormh`` - 16bit unsigned normalised value +* ``unormf`` - 32bit unsigned normalised value +* ``snormb`` - 8bit signed normalised value +* ``snormh`` - 16bit signed normalised value +* ``snormf`` - 32bit signed normalised value +* ``uintten`` - 4 component unsigned integer format, packed as 10:10:10:2 +* ``unormten`` - 4 component unsigned normalised format, packed as 10:10:10:2 +* ``xuint`` - hex-formatted 32bit integer +* ``xshort`` - hex-formatted 16bit integer +* ``xbyte`` - hex-formatted 8bit integer diff --git a/docs/window/capture_connection.rst b/docs/window/capture_connection.rst new file mode 100644 index 000000000..ffec5d836 --- /dev/null +++ b/docs/window/capture_connection.rst @@ -0,0 +1,69 @@ +Capture Connection +================== + +.. toctree:: + + +The Live capture window opens up when you launch a capture of a program, as well as when you attach to an existing program. + +Attaching to an existing instance +--------------------------------- + +After you've launched a program through RenderDoc and its hooks are added you can freely disconnect (by closing the live capture window) or close the main UI. You can then connect to this again later, either from the same computer or another computer connecting over the network. + +To connect to an existing hooked program, select Attach to Running Instance from the File menu. This opens up the attach window that allows you to select a remote host to connect to. By default localhost is already in the list, but you can add and remove other hosts. + +.. warning:: + + Please note that none of the connections RenderDoc makes or uses are encrypted or protected, so if this is a concern you should look into securing the connections by hand. + +.. figure:: ../images/AttachInstance.png + + Remote Hosts: Attaching to a running instance either locally or remotely. + +When the window opens, when you add a new host or when you click refresh then the hosts will be queried across the network to see if a connection exists. While this is in progress the host will be listed in italics and with a busy icon. + +Once a host has been scanned, if any instances are found then that host can be expanded to see the list, and details are listed about each instance. The name is OS-dependent but is usually the executable name. The API name is listed, as well as the username of any user that is already connected. + +When you click connect, a live capture window will be opened up - just the same as the window that is automatically opened when you start a program. Any captures that have already been made before you connect will then populate. + +.. note:: + + If you connect to a running instance, any existing user will be kicked off. Just seeing the instances running on a host will not. + + +Capture Connection window +------------------------- + +When a capture is launched (or attached to) the connection window is opened in the main UI. If you end up only taking one capture and closing the program afterwards the connection window will automatically close - likewise if you take no captures at all. These cases don't need the management options the connection window provides. + +In addition to managing captures that have been taken, you can also trigger a capture (optionally with a countdown timer). + +.. figure:: ../images/MultipleCaptures.png + + Connection Window: Viewing multiple captures taken in a program. + +In this example we have a connection window open to the CascadedShadowMaps11 sample from the DirectX SDK. Two captures have been made and we can see their thumbnails to help distinguish between them. This is visible at any point, regardless of whether you have close the program or not - you can simply switch back to RenderDoc while it's running. + +.. note:: + + Note, if you have remotely connected you will need to wait while the captures copy across the network to your PC, after which point everything behaves the same as a local capture. + +From here you can save these captures out - as currently they are only temporary copies that will be cleaned up on close. You can also manually delete any capture you wish to discard. + +Double clicking on any capture will close any current open capture in the RenderDoc UI, and open up that capture for inspection. You may also right click or use the drop-down menu on the open button to launch a new instance of RenderDoc for viewing the log. This is mostly useful if you want to compare two captures side-by-side easily. + +.. figure:: ../images/OpenCapNewInstance.png + + New instance: Launch new RenderDoc instance to open this capture.
+ +Child Processes +--------------- + +RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check "Hook into Children" in the :doc:`capture_log_attach`. + + +RenderDoc has a particular handling of child processes to help you navigate to the process of interest. Whenever a child process is launched, the UI is notified and a list of processes is displayed in a box on the capture connection window. You can double click on any of these entries to open up a new connection to that process, in a new window. + + +If a process exits, instead of just closing the connection window if there have been no captures, instead RenderDoc looks at the child processes - if there is only one child process, it assume that process must be of interest and immediately switches to tracking that process. If there are *more* than one child process open, the capture connection window will stay open to give you a chance to double click on those child processes to open a new connection window. diff --git a/docs/window/capture_log_attach.rst b/docs/window/capture_log_attach.rst new file mode 100644 index 000000000..52302a3fb --- /dev/null +++ b/docs/window/capture_log_attach.rst @@ -0,0 +1,2 @@ +Capture Log & Attach +==================== diff --git a/docs/window/debug_messages.rst b/docs/window/debug_messages.rst new file mode 100644 index 000000000..86a30f1d0 --- /dev/null +++ b/docs/window/debug_messages.rst @@ -0,0 +1,22 @@ +Debug Messages +============== + +The Debug Messages window shows messages from the API including warnings about performance issues or concerns about potential hazards, as well as errors on invalid use of the API. + +RenderDoc will alert you if there are any debug messages to show from the log, by flashing in the status bar. Sometimes RenderDoc will also add new alerts there that aren't part of the original log if there are warnings or problems that it encounters while processing and analysing the log. + +Capturing with debug messages included +-------------------------------------- + +To include these debug messages in a log, check on the "Create Debug Device" option in the capture options. For more information see :doc:`capture_log_attach` + +Debug Messages +-------------- + +This window is fairly simple. Each message retrieved from the api will be listed on its own row showing the event ID that triggered the message, along with a severity and category. + +Double clicking on any row will take you to the corresponding event ID in the event browser. + +.. figure:: ../images/DebugMessages.png + + Debug Messages: The Debug Messages window showing some API messages. diff --git a/docs/window/event_browser.rst b/docs/window/event_browser.rst new file mode 100644 index 000000000..3bcaa2c64 --- /dev/null +++ b/docs/window/event_browser.rst @@ -0,0 +1,125 @@ +Event Browser +============= + +The Event Browser is the primary method of browsing the frame and selecting different drawcalls. It displays the user-annotated hierarchical display of sections. + +Annotating your frame +--------------------- + +The Event Browser becomes most useful when the application has user-defined annotations of sections and subsections of the frames, to allow for a more logical and ordered browsing of the frame. + +Doing this is API and platform specific. Example code for D3D11 is included below, using the D3DPERF library that is defined in d3d9.lib, which can still be used in D3D11. (The newer ID3DUserDefinedAnnotation API is also supported). + +.. code:: c++ + + D3DPERF_BeginEvent(0xffffffff, L"Start of example"); + + D3DPERF_BeginEvent(0xff00ff00, L"Sub section"); + // events inside the subsection + D3DPERF_EndEvent(); + + // events outside the subsection + D3DPERF_EndEvent(); + +This will generate a section of the frame with a subsection that includes some events, and then some further events that are siblings of the subsection. + +Selecting available columns +--------------------------- + +By default, the columns in the event browser are EID and Name. Name cannot be removed as it contains the tree, but otherwise the columns can be customised both to hide/display or reorder and resize. + +.. |timeline_marker| image:: ../images/timeline_marker.png + +To select which columns should be visible, right click the header or click the |timeline_marker| select columns button. + +To rearrange the columns simply click and drag on the header. + + +.. note:: + + Note that when timing drawcalls the duration column will automatically be added to display the data. + +Timing drawcalls +---------------- + +.. |time| image:: ../images/time.png + +To time the GPU duration of each drawcall, click the timer button |time|. + +This will automatically run a process to get the time of each drawcall and display it in the duration column, which will be added if necessary. + + +You can configure which time unit is used for the duration column on the fly in the :doc:`options_window`. + +Browsing the frame +------------------ + +The event browser is primarily intended as a tool to browse through the frame. Events are listed as entries in the browser and the hierarchical labels mentioned above become tree nodes. + +.. |flag_green| image:: ../images/flag_green.png + +The currently selected event is highlighted and indicated with a green flag |flag_green|. This is the event that RenderDoc is inspecting and is reflected in all the other windows of the UI. + +.. figure:: ../images/QuickStart4.png + + Current Event: The Event browser showing several sections and the current event. + +The EID column indicates the event ID of the drawcall listed. Event IDs are assigned starting from 1 and increase every time an API call is made - for this reason drawcall EIDs are not necessarily contiguous. + +Simply clicking on a different event will select it as current, and selecting a parent node with some child events will act as if the final child is selected - in other words selecting a node with several children will show the results of all children having happened. + +You can also use keyboard shortcuts to browse through the frame. Pressing up or down arrow key will move up and down through the visible elements, skipping over any sections which are collapsed. These keys will move into and out of a sub-section into the next sibling afterwards - essentially going straight up and down as if there is not a tree and it is a straight list. + +The left and right arrows go into and out of hierarchy levels. When within a level pressing left will jump to the parent node of the current level. Pressing left again will collapse that node, and so on. Pressing right will (if on a node with children) expand that node. + +.. note:: + + This window supports copy and paste, so simply select the entries and ctrl-c to copy to the clipboard + +Bookmarks +--------- + +.. |asterisk_orange| image:: ../images/asterisk_orange.png + +The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`CTRL-B`. + +.. figure:: ../images/BookmarksBar.png + + Bookmarks bar: The bookmarks bar with several EIDs bookmarks. + +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. + +Searching and Jumping +--------------------- + +There are two other controls available in the Event Browser to aid in navigating the frame. + +.. |find| image:: ../images/find.png + +Pressing :kbd:`Ctrl-F` will open the find-event toolbar |find|. This toolbar allows you to type in a partial text filter that will be matched against both labels and drawcall events. The find will be executed when you press enter, although you can then adjust the text and re-search if you wish. + +If the event found lies inside an unexpanded section, the sections will be expanded until the matching event is visible. + +Matching events will be highlighted with a find icon |find|, and pressing enter repeatedly will jump between matching events. + +.. |cross| image:: ../images/cross.png + +The find toolbar isn't dismissed until you press escape in the text box, or click the close button |cross|. + +.. |stepprev| image:: ../images/stepprev.png +.. |stepnext| image:: ../images/stepnext.png + + +You can also jump up and down between find results with the previous |stepprev| and next |stepnext| buttons. + +.. figure:: ../images/FindResults.png + + Highlighted Results: The results of a find are highlighted with an icon. + +Pressing :kbd:`Ctrl-G` will open the jump to EID toolbar. This allows you to type in an EID and jump straight there, expanding nodes as necessary. If the EID typed doesn't exist in the list of drawcalls, the closest matching EID will be jumped to. + +When you hit enter to jump to an EID, the toolbar closes and if you wish to jump again you must press :kbd:`Ctrl-G` again + +.. figure:: ../images/JumpEID.png + + Jumping around: The jump-to-EID toolbar prompting for an event. diff --git a/docs/window/index.rst b/docs/window/index.rst new file mode 100644 index 000000000..36a54c4ea --- /dev/null +++ b/docs/window/index.rst @@ -0,0 +1,15 @@ +Window reference +================ + +.. toctree:: + texture_viewer + api_inspector + buffer_viewer + capture_log_attach + event_browser + options_window + pipeline_state + timeline_bar + capture_connection + debug_messages + python_shell diff --git a/docs/window/options_window.rst b/docs/window/options_window.rst new file mode 100644 index 000000000..8e66ea550 --- /dev/null +++ b/docs/window/options_window.rst @@ -0,0 +1,2 @@ +Options Window +============== diff --git a/docs/window/pipeline_state.rst b/docs/window/pipeline_state.rst new file mode 100644 index 000000000..446f9acb4 --- /dev/null +++ b/docs/window/pipeline_state.rst @@ -0,0 +1,48 @@ +Pipeline State +============== + +The Pipeline Viewer is an information dense but simple window in RenderDoc. It shows all of the stateful settings of the graphics pipeline, including bound resources, rasterizer settings, etc. + +Pipeline flowchart +------------------ + +At the top of the Pipeline Viewer is the pipeline flowchart - this shows the high-level block level diagram of the graphics pipeline. + +Each block is a separate page which contains the relevant state and contents for that piece of the graphics pipeline, with specific details varying by API and the type of data to be displayed. + +The currently selected block is outlined with red, and the page in view reflects the contents of that section of the pipeline. Light grey parts of the pipeline are those which are currently active and participating in this drawcall. Dark grey parts of the pipeline are not present and can be considered pass-through/do-nothing. + +.. figure:: ../images/PipelineBar.png + + Pipeline: Pictured here, the high-level parts of the D3D11 Pipeline. + +.. note:: + + In D3D11, the Stream-Out stage is available under the Geometry Shader block, with the buffers being used for stream-out shown. Similarly for GL, the transform feedback is listed in the geometry shader block. + +Pipeline Section Display +------------------------ + +The pipeline state viewer always displays the state of the pipeline after the execution of the drawcall, as with the other viewers in RenderDoc. + +Any resources that are bound to the pipeline can be opened in more detailed viewers, such as vertex buffers, constant buffers and textures. More details of this process can be found in the page :doc:`../how/how_object_details`. + +.. |page_white_delete| image:: ../images/page_white_delete.png +.. |page_white_database| image:: ../images/page_white_database.png + +The pipeline view attempts to only show what is relevant, and not all possible stateful data. To do this (when available) it uses shader reflection data to only display slots which are actually in use by the shaders, and omit any that are unused. This can be overridden with the Show Disabled Items |page_white_delete| button. + +Likewise it will omit any slots which are completely empty (and also unused), and this behaviour can be overridden with the Show Empty Items |page_white_database| button. + +In some cases whole sections will be omitted unless there is anything set there - this is primarily for unused or rarely used features like shader subroutines/class linkage, and Read/Write bindings (Image load store or UAVs). + +When showing disabled or empty entries, they will either be in *italics* or on a dark red background respectively. + +.. |save| image:: ../images/save.png + +You can also export the pipeline state by clicking on the |save| export button, this will export the entire pipeline state in detail to an HTML file, so you can more easily compare between different logs and different events. + +See Also +-------- + +* :doc:`../how/how_object_details` diff --git a/docs/window/python_shell.rst b/docs/window/python_shell.rst new file mode 100644 index 000000000..39d265c15 --- /dev/null +++ b/docs/window/python_shell.rst @@ -0,0 +1,26 @@ +Python Shell +============ + +The python shell allows a limited form of scripting for RenderDoc, including the ability to run simple scripts over the whole dataset in ways not easy to do in the UI. + +Overview +-------- + +You can open the python shell from the window menu. It offers both an interactive shell and a window that can open and run scripts and display the output. + +Currently the support is fairly bare bones, and typically you will need some understanding of the code to use the scripting support well. The 'renderdoc' object corresponds to the Core object type used throughout the UI, and it provides a jumping off point for most operations from there. + +Examples are: + +* :code:`renderdoc.CurTextures` is an array of FetchTexture with all textures in the current log. +* :code:`renderdoc.GetTextureViewer()` gives a handle to the texture viewer, allowing you to view a particular texture. +* :code:`renderdoc.AppWindow.LoadLogfile("filename", False)` opens a given log. +* :code:`renderdoc.GetDrawcall(0, 151)` will return the drawcall of EID 151. Drawcalls have next/previous/parent/children properties to allow you to step through the frame. +* :code:`renderdoc.SetEventID(None, 0, 151)` browses to EID 151. + + +So while not particularly friendly to discovery, you can use this to perform an automated iteration over e.g. all events or all textures for something of interest. + +.. figure:: ../images/pythonshell.png + + Python Shell: A simple script that looks at textures and their use in a log. diff --git a/docs/window/texture_viewer.rst b/docs/window/texture_viewer.rst new file mode 100644 index 000000000..7a1594247 --- /dev/null +++ b/docs/window/texture_viewer.rst @@ -0,0 +1,2 @@ +Texture Viewer +============== diff --git a/docs/window/timeline_bar.rst b/docs/window/timeline_bar.rst new file mode 100644 index 000000000..f64f906d3 --- /dev/null +++ b/docs/window/timeline_bar.rst @@ -0,0 +1,66 @@ +Timeline Bar +============ + +.. toctree:: + + + +The timeline bar shows an alternate view of the scene to the :doc:`event_browser`. Displaying the scene with time running as the horizontal axis, although it does not show each section in size relative to its timing. + +Introduction +------------ + +The timeline bar shows the scene horizontally with the hierarchical frame markers being expandable from top to bottom. + +This alternate view can be a useful way to get an overview of the whole frame, allowing you to jump around very different parts of the frame. + +Given that the timeline bar shows the whole frame it also provides a secondary function of showing dependencies in a global way. For whichever texture is currently selected in the texture viewer, the timeline bar shows reads and writes to that texture throughout the frame. This can be especially useful for render targets that are used in both ways, as well as simply to see where a given texture is used in a frame without laboriously searching. + +.. figure:: ../images/TimelineBar.png + + Timeline Bar: The timeline bar showing a birds-eye view of a typical application. + +Timeline Display +---------------- + +By default the timeline bar views the whole frame, but with the mouse wheel you can zoom in and out. When zoomed in, you can scroll through the frame with the horizontal scroll bar. + +The timeline bar sizes the sections that it contains to try and make the frame markers as visible as possible. This attempts to keep the frame browsable for as long as possible, such that small sections (in time or number of events) are still visible rather than being crushed to tiny bars. + +For this reason the timeline can resize itself when bars are expanded, as this can reveal new sections which must be allocated enough room. When there is slack space to be allocated it is given to the sections which have more events than others. + +Underneath expanded sections, a blue pip is rendered for each drawcall-type event. The currently selected event is shown as a green pip, as well as there being a light grey vertical line to indicate the current position, such that this is visible even when the relevant section is not expanded. + +Clicking on any section will toggle it between expanded and unexpanded, and any sections underneath a section which is collapsed will remain in their previous state but will not be visible. + +Left clicking on the timeline will jump to the event underneath that point on the horizontal display. + +Resource usage Display +---------------------- + +The timeline bar also shows the usage of the currently displayed texture. + +Whichever texture is currently displayed in the :doc:`texture_viewer` (whether that be a currently bound texture, or a locked tab) will have its usage laid out across the frame on the timeline bar. + +If your textures have their names annotated you will see which texture is being inspected in the label for the usage bar. + +A green arrow will be drawn under each pip that reads from the texture. If the pips are too close together to resolve the arrow, the arrows will stay distinct and lose the 1:1 association with event pips. + +Similarly, a purple arrow will be drawn under pips where the event writes to the texture. In the case that a resource is bound such that it can be read or written, the arrow will be half-green, half-purple. + +Clear calls will be shown with a light grey. + +In cases where the arrows are too close together to show distinctly, they will not all draw. To see exactly what usage is happening you can zoom into the context around that area of the frame. + +.. figure:: ../images/ResourceUsage.png + + Resource Usage: The usage bar showing reads and writes to a texture. + +Pixel history event Display +--------------------------- + +When a pixel history window is focussed, the timeline bar will show the results over each EID with a red triangle to show rejected pixels and green triangles to show passed pixels. + +.. figure:: ../images/PixelHistoryTimeline.png + + Pixel History Results: The timeline bar shows the results of a pixel's history.