Example: Show buffer with format
================================

This example shows how to fetch the information and contents of a buffer, as well as opening up a view of it in the UI.

This could for example be run as a command line argument when starting the UI, to avoid repetitive steps or automate a repro case.

Fetching Buffer Metadata
------------------------

First we iterate through the list of buffers (:meth:`~qrenderdoc.CaptureContext.GetBuffers`) to find the one we want. The selection criteria would be up to you, in this case we look at the buffer's name (:meth:`~qrenderdoc.CaptureContext.GetResourceName`) and choose a buffer using that - however it could also be a particular size, or the buffer :doc:`bound to a shader <shader_refl>` at a given event. To keep the example flexible we will default to using the last buffer in the list if one doesn't match the criteria.

.. tip::

    If you already have the :ref:`Resource ID <resourceids>` of the buffer you want, you can use :meth:`~qrenderdoc.CaptureContext.GetBuffer` to fetch the descriptor for it.

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

    mybuf = renderdoc.ResourceId.Null()

    for buf in pyrenderdoc.GetBuffers():
        print(f"buf {buf.resourceId} is {pyrenderdoc.GetResourceName(buf.resourceId)}")

        mybuf = buf.resourceId

        # here put your actual selection criteria - i.e. look for a particular name
        if "Vertex" in pyrenderdoc.GetResourceName(buf.resourceId):
            break

    print(f"selected {pyrenderdoc.GetResourceName(mybuf)}")

Opening Buffer Viewer
---------------------

Once we've identified the buffer we want to view, we create a buffer viewer (:meth:`~qrenderdoc.CaptureContext.ViewBuffer`) and display it on the main tool area (:meth:`~qrenderdoc.CaptureContext.AddDockWindow`).

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

    formatter = """
    float3 pos;
    half norms[6];
    uint flags;
    """

    if mybuf != renderdoc.ResourceId.Null():
        # Open a new buffer viewer for this buffer, with the given format
        bufview = pyrenderdoc.ViewBuffer(0, 0, mybuf, formatter)

        # Show the buffer viewer on the main tool area
        pyrenderdoc.AddDockWindow(bufview.Widget(), qrenderdoc.DockReference.MainToolArea, None)

.. figure:: ../../imgs/python/BufferViewer.png

	The buffer viewer we opened for the buffer we chose.

Fetching Buffer Contents
------------------------

Lastly we'll go a step further and fetch the buffer data (:meth:`~renderdoc.ReplayController.GetBufferData`) ourselves to print the first 8 bytes. To access this we will need to obtain the :class:`~renderdoc.ReplayController` which controls RenderDoc's underlying analysis.

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 buffer data is fetched so this work could be done on a thread instead - see :ref:`pythreading`.

.. note::
    As with most data retrieved from RenderDoc, this buffer data is relative to the :ref:`current event <currentevent>` - the same as if a buffer viewer is opened in the UI. Changing to a different current event may mean different data is fetched and printed.

With the replay controller we can request a given byte range by its offset and length. If we wanted to get the whole buffer we could specify a length of 0. This is returned as a python ``bytes`` object which encapsulates a raw byte sequence, and ``struct.unpack_from`` is a python function that interprets bytes into values - see the `python documentation <https://docs.python.org/3/library/struct.html>`_ for how to write format strings to pull out floats and different byte-width values.

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

    controller = pyrenderdoc.GetBlockingController()

    data_bytes = controller.GetBufferData(mybuf, 0, 8)

    data_decoded = struct.unpack_from("8B", data_bytes)

    print(f"The first 8 bytes of the buffer are: {data_decoded}")

Final output from the script with this decoding:

.. sourcecode:: text

    buf ResourceId::111 is Buffer 111
    selected Buffer 111
    The first 8 bytes of the buffer are: (69, 64, 190, 191, 12, 146, 122, 191)

Example Source
--------------

This example can be found under the name "Show buffer with format" in the python scripting window.

.. only:: html and not htmlhelp

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

.. literalinclude:: show_buffer.py