Example: Show and save a texture

This example demonstrates how to enumerate textures, show one in the texture viewer, and save the texture to disk.

Fetching Texture Metadata

First we iterate through the list of textures (:meth:~qrenderdoc.CaptureContext.GetTextures) and print their dimensions as we go. We keep track of which texture has the largest area.

.. highlight:: python .. code:: python

highestArea = 0
largest = None
for tex in pyrenderdoc.GetTextures():
    name = pyrenderdoc.GetResourceName(tex.resourceId)
    print(f"{name} is {tex.width} x {tex.height}")
    area = tex.width * tex.height
    if area > highestArea:
        highestArea = area
        largest = tex

Opening in Texture Viewer

Once we've found the largest texture, we print its information again as a summary and then show (:meth:~qrenderdoc.CaptureContext.ShowTextureViewer) and ask the :class:~qrenderdoc.TextureViewer to display it as a new locked tab (:meth:~qrenderdoc.TextureViewer.ViewTexture).

.. highlight:: python .. code:: python

if largest is not None:
    name = pyrenderdoc.GetResourceName(largest.resourceId)
    print(f"\n+++ Largest texture is {name}")

    # open largest texture (by area) in texture viewer, and focus
    pyrenderdoc.ShowTextureViewer()
    pyrenderdoc.GetTextureViewer().ViewTexture(largest.resourceId,
                                            renderdoc.CompType.Typeless,
                                            True)

.. figure:: ../../imgs/Screenshots/CurrentVsLockedTab.png

An example locked tab that has been opened from the python script.

To go further we will now save this texture to disk in a couple of different formats.

Saving Texture to Disk

We will need to obtain the :class:~renderdoc.ReplayController which controls RenderDoc's underlying analysis.

.. tip:: Although not shown in this example, with the texture ID you can use :meth:~renderdoc.ReplayController.GetTextureData to fetch the raw bytes for a given subresource in a texture, for arbitrary processing.

For convenience we will fetch a blocking version (:meth:~qrenderdoc.CaptureContext.GetBlockingController) that stalls the python script and executes the given command. If this code ran in a UI extension that could cause the UI to become unresponsive while the texture is processed and written to disk so this work could be done on a thread instead - see :ref:pythreading.

.. highlight:: python .. code:: python

controller = pyrenderdoc.GetBlockingController()

Next so that we know where to save the file, we prompt the user to browse to a filename (:meth:qrenderdoc.ExtensionManager.SaveFileName). We'll replace the extension so trim off any .jpg we get.

.. highlight:: python .. code:: python

filename = pyrenderdoc.Extensions().SaveFileName(
    "Choose where to save JPG/PNG/DDS texture files", "", "*.jpg"
)

filename = filename.replace(".jpg", "")

Saving textures to disk can require a few different configuration options, which is contained in the :class:~renderdoc.TextureSave configuration structure.

Not all textures map cleanly to normal texture formats and some textures may have multiple mips or array slices. To start with we will specify that when writing a texture format without an alpha channel RenderDoc should blend to a checkerboard pattern (:data:~renderdoc.AlphaMapping.BlendToCheckerboard). We also choose to save mip 0 if there are multiple mips, and if there are multiple slices save only slice 0. Other options are possible to e.g. lay out all slices in a grid atlas.

.. highlight:: python .. code:: python

texsave = renderdoc.TextureSave()
texsave.resourceId = largest.resourceId

# Blend alpha to a checkerboard pattern for formats without alpha support
texsave.alpha = renderdoc.AlphaMapping.BlendToCheckerboard

# Most formats can only display a single image per file, so we select the
# first mip and first slice
texsave.mip = 0
texsave.slice.sliceIndex = 0

With that done we can save the texture in both :data:~renderdoc.FileType.JPG and :data:~renderdoc.FileType.PNG formats with a call to :meth:~renderdoc.ReplayController.SaveTexture.

.. highlight:: python .. code:: python

texsave.destType = renderdoc.FileType.JPG
controller.SaveTexture(texsave, filename + ".jpg")

# For formats with an alpha channel, preserve it
texsave.alpha = renderdoc.AlphaMapping.Preserve

texsave.destType = renderdoc.FileType.PNG
controller.SaveTexture(texsave, filename + ".png")

Finally we will save to :data:~renderdoc.FileType.DDS, and in this case we now have a texture format that can support mips and array slices. We'll change the configuration to ensure that all mips and all array slices are written to the same file.

.. code:: python

# DDS textures can save multiple mips and array slices, so instead
# of the default behaviour of saving mip 0 and slice 0, we set -1
# which saves *all* mips and slices
texsave.mip = -1
texsave.slice.sliceIndex = -1

texsave.destType = renderdoc.FileType.DDS
controller.SaveTexture(texsave, filename + ".dds")

Example Source

This example can be found under the name "Show and save a texture" in the python scripting window.

.. only:: html and not htmlhelp

:download:`Download the example script <show_texture.py>`.

.. literalinclude:: show_texture.py