diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..11ecc5041 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ +# RenderDoc documentation + +This readme only covers the documentation. For general information about renderdoc check out [the main github repository](https://github.com/baldurk/renderdoc). + +## Generating documentation + +Generating the documentation requires the same python version as was used to build the version of RenderDoc you are testing. On windows this is likely python 3.6 as that's what comes with the repository. + +The documentation uses restructured text with [Sphinx](http://www.sphinx-doc.org/en/master/). Sphinx can be acquired via `pip install Sphinx` + +To generate the documentation, run make.bat or make.sh found in this folder. Run `make help` to see all options, but `make html` is a likely place to start. + +License +-------------- + +RenderDoc is released under the MIT license, see [the main github repository](https://github.com/baldurk/renderdoc) for full details. + +The documentation uses [Sphinx](http://www.sphinx-doc.org/en/master/), which is BSD licensed. diff --git a/docs/window/texture_viewer.rst b/docs/window/texture_viewer.rst index 1ffb939af..1fc39f907 100644 --- a/docs/window/texture_viewer.rst +++ b/docs/window/texture_viewer.rst @@ -181,6 +181,8 @@ Gamma display of Linear Data A proper explanation of this is available in the :ref:`FAQ `. In short, linear data is 'over-corrected' to look as expected, but this behaviour can be overridden by toggling off this option. +.. _Alpha background: + Alpha background ~~~~~~~~~~~~~~~~ .. |color_wheel| image:: ../imgs/icons/color_wheel.png @@ -330,8 +332,12 @@ This is a powerful tool for quickly diagnosing issues and can be very useful for * ``Clipping`` will simply highlight in red any values that are below the current black point (as defined by the range control - see above), and in green any values above the white point. This can be useful in identifying invalid ranges if the range control is adjusted correctly, or in combination with a custom shader visualiser. -* ``Clear before Pass`` will act as if the current target had been cleared to black right before the current pass. This can sometimes make it easier to see the results of a draw, especially if it is blending and only makes a subtle change. If the current API does not have the concept of a pass, it is defined as all the drawcalls with the same set of render targets. +* ``Clear before Pass`` will act as if the current target had been cleared right before the current pass. This can sometimes make it easier to see the results of a draw, especially if it is blending and only makes a subtle change. If the current API does not have the concept of a pass, it is defined as all the drawcalls with the same set of render targets. + * If the current target is a render target, it is cleared to the :ref:`Alpha background` color. + + * If the current target is a depth/stencil target, the behavior depends on the depth function for the current draw. If it is ``EQUAL``, ``NOT EQUAL``, or ``ALWAYS``, the target is not cleared. If it is ``LESS`` or ``LESS EQUAL``, it is cleared to 1. If it is ``GREATER`` or ``GREATER EQUAL``, it is cleared to 0. Stencil is never cleared. + * ``Clear before Draw`` works similarly to the above overlay, but clearing immediately before the selected draw. * ``Quad Overdraw (Pass)`` will show a visualisation of the level of 2x2 quad overdraw in the 'pass' up to the selected draw. If the current API does not have the concept of a pass, it is defined as all the drawcalls with the same set of render targets. diff --git a/util/test/README.md b/util/test/README.md index d323a1b48..3188ae934 100644 --- a/util/test/README.md +++ b/util/test/README.md @@ -45,6 +45,8 @@ The demos project contains helper libraries, so the best way to get started is t Similarly for tests, which often come 1:1 with demos, you can copy-paste an existing test and add your own checks. +When adding a test that needs to compare against a reference image, first run the first without a reference image. It will output the image that it would compare against. Run this image through pngcrush (ensuring that RGBA output is preserved) to reduce repository bloat. + License -------------- diff --git a/util/test/data/D3D11_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png b/util/test/data/D3D11_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png new file mode 100644 index 000000000..01f2f422a Binary files /dev/null and b/util/test/data/D3D11_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png differ diff --git a/util/test/data/D3D12_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png b/util/test/data/D3D12_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png new file mode 100644 index 000000000..01f2f422a Binary files /dev/null and b/util/test/data/D3D12_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png differ diff --git a/util/test/data/GL_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png b/util/test/data/GL_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png new file mode 100644 index 000000000..01f2f422a Binary files /dev/null and b/util/test/data/GL_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png differ diff --git a/util/test/data/VK_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png b/util/test/data/VK_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png new file mode 100644 index 000000000..01f2f422a Binary files /dev/null and b/util/test/data/VK_Overlay_Test/DebugOverlay.ClearBeforeDraw.Depth.png differ diff --git a/util/test/tests/D3D11/D3D11_Overlay_Test.py b/util/test/tests/D3D11/D3D11_Overlay_Test.py index 3b6a94de4..797e8a212 100644 --- a/util/test/tests/D3D11/D3D11_Overlay_Test.py +++ b/util/test/tests/D3D11/D3D11_Overlay_Test.py @@ -5,6 +5,35 @@ import renderdoc as rd class D3D11_Overlay_Test(rdtest.TestCase): demos_test_name = 'D3D11_Overlay_Test' + def check_clearbeforedraw_depth(self, out, depthId): + # Test ClearBeforeDraw with a depth target + tex = rd.TextureDisplay() + tex.overlay = rd.DebugOverlay.ClearBeforeDraw + tex.resourceId = depthId + + out.SetTextureDisplay(tex) + out.GetDebugOverlayTexID() # Called to refresh the overlay + + overlay = rd.DebugOverlay.ClearBeforeDraw + test_name = str(overlay) + '.Depth' + + overlay_path = rdtest.get_tmp_path(test_name + '.png') + ref_path = self.get_ref_path(test_name + '.png') + + save_data = rd.TextureSave() + save_data.resourceId = depthId + save_data.destType = rd.FileType.PNG + save_data.channelExtract = 0 + + tolerance = 2 + + self.controller.SaveTexture(save_data, overlay_path) + + if not rdtest.png_compare(overlay_path, ref_path, tolerance): + raise rdtest.TestFailureException("Reference and output image differ for overlay {}".format(test_name), overlay_path, ref_path) + + rdtest.log.success("Reference and output image are identical for {}".format(test_name)) + def check_capture(self): self.check_final_backbuffer() @@ -91,4 +120,6 @@ class D3D11_Overlay_Test(rdtest.TestCase): rdtest.log.success("Reference and output image are identical for stencil") + self.check_clearbeforedraw_depth(out, pipe.GetDepthTarget().resourceId) + out.Shutdown() diff --git a/util/test/tests/D3D12/D3D12_Overlay_Test.py b/util/test/tests/D3D12/D3D12_Overlay_Test.py index 764cd5667..4a32df050 100644 --- a/util/test/tests/D3D12/D3D12_Overlay_Test.py +++ b/util/test/tests/D3D12/D3D12_Overlay_Test.py @@ -5,6 +5,35 @@ import renderdoc as rd class D3D12_Overlay_Test(rdtest.TestCase): demos_test_name = 'D3D12_Overlay_Test' + def check_clearbeforedraw_depth(self, out, depthId): + # Test ClearBeforeDraw with a depth target + tex = rd.TextureDisplay() + tex.overlay = rd.DebugOverlay.ClearBeforeDraw + tex.resourceId = depthId + + out.SetTextureDisplay(tex) + out.GetDebugOverlayTexID() # Called to refresh the overlay + + overlay = rd.DebugOverlay.ClearBeforeDraw + test_name = str(overlay) + '.Depth' + + overlay_path = rdtest.get_tmp_path(test_name + '.png') + ref_path = self.get_ref_path(test_name + '.png') + + save_data = rd.TextureSave() + save_data.resourceId = depthId + save_data.destType = rd.FileType.PNG + save_data.channelExtract = 0 + + tolerance = 2 + + self.controller.SaveTexture(save_data, overlay_path) + + if not rdtest.png_compare(overlay_path, ref_path, tolerance): + raise rdtest.TestFailureException("Reference and output image differ for overlay {}".format(test_name), overlay_path, ref_path) + + rdtest.log.success("Reference and output image are identical for {}".format(test_name)) + def check_capture(self): self.check_final_backbuffer() @@ -91,4 +120,6 @@ class D3D12_Overlay_Test(rdtest.TestCase): rdtest.log.success("Reference and output image are identical for stencil") + self.check_clearbeforedraw_depth(out, pipe.GetDepthTarget().resourceId) + out.Shutdown() diff --git a/util/test/tests/GL/GL_Overlay_Test.py b/util/test/tests/GL/GL_Overlay_Test.py index f1e89df20..f82174510 100644 --- a/util/test/tests/GL/GL_Overlay_Test.py +++ b/util/test/tests/GL/GL_Overlay_Test.py @@ -5,6 +5,35 @@ import renderdoc as rd class GL_Overlay_Test(rdtest.TestCase): demos_test_name = 'GL_Overlay_Test' + def check_clearbeforedraw_depth(self, out, depthId): + # Test ClearBeforeDraw with a depth target + tex = rd.TextureDisplay() + tex.overlay = rd.DebugOverlay.ClearBeforeDraw + tex.resourceId = depthId + + out.SetTextureDisplay(tex) + out.GetDebugOverlayTexID() # Called to refresh the overlay + + overlay = rd.DebugOverlay.ClearBeforeDraw + test_name = str(overlay) + '.Depth' + + overlay_path = rdtest.get_tmp_path(test_name + '.png') + ref_path = self.get_ref_path(test_name + '.png') + + save_data = rd.TextureSave() + save_data.resourceId = depthId + save_data.destType = rd.FileType.PNG + save_data.channelExtract = 0 + + tolerance = 2 + + self.controller.SaveTexture(save_data, overlay_path) + + if not rdtest.png_compare(overlay_path, ref_path, tolerance): + raise rdtest.TestFailureException("Reference and output image differ for overlay {}".format(test_name), overlay_path, ref_path) + + rdtest.log.success("Reference and output image are identical for {}".format(test_name)) + def check_capture(self): self.check_final_backbuffer() @@ -91,4 +120,6 @@ class GL_Overlay_Test(rdtest.TestCase): rdtest.log.success("Reference and output image are identical for stencil") + self.check_clearbeforedraw_depth(out, pipe.GetDepthTarget().resourceId) + out.Shutdown() diff --git a/util/test/tests/Vulkan/VK_Overlay_Test.py b/util/test/tests/Vulkan/VK_Overlay_Test.py index 38cdd16f6..0bf1bc3c2 100644 --- a/util/test/tests/Vulkan/VK_Overlay_Test.py +++ b/util/test/tests/Vulkan/VK_Overlay_Test.py @@ -4,6 +4,35 @@ import renderdoc as rd class VK_Overlay_Test(rdtest.TestCase): demos_test_name = 'VK_Overlay_Test' + + def check_clearbeforedraw_depth(self, out, depthId): + # Test ClearBeforeDraw with a depth target + tex = rd.TextureDisplay() + tex.overlay = rd.DebugOverlay.ClearBeforeDraw + tex.resourceId = depthId + + out.SetTextureDisplay(tex) + out.GetDebugOverlayTexID() # Called to refresh the overlay + + overlay = rd.DebugOverlay.ClearBeforeDraw + test_name = str(overlay) + '.Depth' + + overlay_path = rdtest.get_tmp_path(test_name + '.png') + ref_path = self.get_ref_path(test_name + '.png') + + save_data = rd.TextureSave() + save_data.resourceId = depthId + save_data.destType = rd.FileType.PNG + save_data.channelExtract = 0 + + tolerance = 2 + + self.controller.SaveTexture(save_data, overlay_path) + + if not rdtest.png_compare(overlay_path, ref_path, tolerance): + raise rdtest.TestFailureException("Reference and output image differ for overlay {}".format(test_name), overlay_path, ref_path) + + rdtest.log.success("Reference and output image are identical for {}".format(test_name)) def check_capture(self): self.check_final_backbuffer() @@ -91,4 +120,6 @@ class VK_Overlay_Test(rdtest.TestCase): rdtest.log.success("Reference and output image are identical for stencil") + self.check_clearbeforedraw_depth(out, pipe.GetDepthTarget().resourceId) + out.Shutdown()