# Structured Data

Contents

- Structured Data

  - Type information

  - Objects

  - Chunks

  - Structured File

  - Creation Helper Functions

## Type information

class renderdoc.SDType

  Details the name and properties of a structured type

  basetype

    The `SDBasic` category that this type belongs to.

  byteSize

    The size in bytes that an instance of this type takes up.

    This is only valid for whole chunks (where it contains the whole chunk size), for buffers that have an arbitrary size, or for basic types such as integers and floating point values where it gives the size/precision of the type.

    For variable size types like structs, arrays, etc it will be set to 0.

  flags

    The `SDTypeFlags` flags for this type.

  name

    The name of this type.

class renderdoc.SDBasic(value)

  The basic irreducible type of an object. Every other more complex type is built on these.

  Chunk

    A ‘special’ type indicating that the object is a chunk. A chunk can be treated like a `Struct` otherwise. See `SDChunk`.

  Struct

    A composite type with some number of children of different types, each child with its own name. May in some cases be empty, so the presence of children should not be assumed.

  Array

    A composite type with some number of children with an identical type and referred to purely by their index in the array. May be empty.

  Null

    An indicator that an object could be here, but is optional and is currently not present. See `SDTypeFlags.Nullable`.

  Buffer

    An opaque byte buffer.

  String

    A string, encoded as UTF-8.

  Enum

    An enum value - stored as an integer but with a distinct set of possible named values.

  UnsignedInteger

    An unsigned integer.

  SignedInteger

    An signed integer.

  Float

    A floating point value.

  Boolean

    A boolean true/false value.

  Character

    A single byte character. Wide/multi-byte characters are not supported (these would be stored as a string with 1 character and multiple bytes in UTF-8).

  Resource

    A ResourceId. Equivalent to (and stored as) an 8-byte unsigned integer, but specifically contains the unique Id of a resource in a capture.

class renderdoc.SDTypeFlags(value)

  Bitfield flags that could be applied to a type.

  NoFlags

    This type has no special properties.

  HasCustomString

    This type has a custom string. This could be used for example for enums, to display the string value of the enum as well as the integer storage, or perhaps for opaque types that should be displayed to the user as a string even if the underlying representation is not a string.

  Hidden

    This type is considered an implementation detail and should not typically be displayed to the user.

  Nullable

    This type is nullable and can sometimes be removed and replaced simply with a Null type. See `SDBasic.Null`.

  NullString

    Special flag to indicate that this is a C-string which was NULL, not just empty.

  FixedArray

    Special flag to indicate that this is array was a fixed-size real array, rather than a complex container type or a pointer & length.

  Union

    Special flag to indicate that this is structure is stored as a union, meaning all children share the same memory and some external flag indicates which element is valid.

  Important

    Indicates that this object is important or significant, to aid in generating a summary/one-line view of a particular chunk by only including important children.

    This property can be recursive - so an important child which is a structure can have only some members which are important.

  ImportantChildren

    Indicates that only important children should be processed, as noted in `Important`. This may appear on an object which has no important children - which indicates explicitly that there are no important children so when summarising no parameters should be shown.

  HiddenChildren

    Indicates that some children are marked as hidden. This can be important for cases where the number of children is important.

  OffsetOrSize

    Special flag to indicate that this type will be used as a byte offset or byte size, which is used to control the formatting mode when the value is displayed in the UI.

## Objects

class renderdoc.SDObject

  Defines a single structured object. Structured objects are defined recursively and one object can either be a basic type (integer, float, etc), an array, or a struct. Arrays and structs are defined similarly.

  Each object owns its children and they will be deleted when it is deleted. You can use `Duplicate()` to make a deep copy of an object.

  AddChild(child)

    Add a new child object.

    Parameters

      child (SDObject) – The new child to add

  AsBool()

    Interprets the object as a `bool` and returns its value. Invalid if the object is not actually a `bool`.

    Returns

      The interpreted bool value.

    Return type

      bool

  AsFloat()

    Interprets the object as a floating point number and returns its value. Invalid if the object is not actually a floating point number.

    Returns

      The interpreted float.

    Return type

      float

  AsInt()

    Interprets the object as an integer and returns its value. Invalid if the object is not actually an integer.

    Returns

      The interpreted integer.

    Return type

      int

  AsResourceId()

    Interprets the object as a `ResourceId` and returns its value. Invalid if the object is not actually a `ResourceId`.

    Returns

      The interpreted ID.

    Return type

      ResourceId

  AsString()

    Interprets the object as a string and returns its value. Invalid if the object is not actually a string.

    Returns

      The interpreted string.

    Return type

      str

  DeleteChildren()

    Delete all child objects.

  Duplicate()
    Returns

      A new deep copy of this object, which the caller owns.

    Return type

      SDObject

  FindChild(childName)

    Find a child object by a given name. If no matching child is found, `None` is returned.

    Parameters

      childName (str) – The name to search for.

    Returns

      A reference to the child object if found, or `None` if not.

    Return type

      SDObject

  FindChildRecursively(childName)

    Find a child object by a given name recursively. If no matching child is found, `None` is returned.

    The order of the search is not guaranteed, so care should be taken when the name may not be unique.

    Parameters

      childName (str) – The name to search for.

    Returns

      A reference to the child object if found, or `None` if not.

    Return type

      SDObject

  GetChild(index)

    Find a child object by a given index. If the index is out of bounds, `None` is returned.

    Parameters

      index (int) – The index to look up.

    Returns

      A reference to the child object if valid, or `None` if not.

    Return type

      SDObject

  GetParent()

    Get the parent of this object. If this object has no parent, `None` is returned.

    Returns

      A reference to the parent object if valid, or `None` if not.

    Return type

      SDObject

  HasEqualValue(obj)

    Checks if the given object has the same value as this one. This equality is defined recursively through children.

    Parameters

      obj (SDObject) – The object to compare against

    Returns

      A boolean indicating if the object is equal to this one.

    Return type

      bool

  NumChildren()

    Get the number of child objects.

    Returns

      The number of children this object contains.

    Return type

      int

  RemoveChild(index)

    Delete the child object at an index. If the index is out of bounds, nothing happens.

    Parameters

      index (int) – The index to remove.

  data

    The `SDObjectData` with the contents of this object.

  name

    The name of this object.

  type

    The `SDType` of this object.

class renderdoc.SDObjectData

  The data inside an `SDObject` whether it’s plain old data or complex children.

  basic

    The plain-old data contents of the object, in a `SDObjectPODData`.

  string

    The string contents of the object.

class renderdoc.SDObjectPODData

  The plain-old-data contents of an `SDObject`.

  Only one member is valid, as defined by the type of the `SDObject`.

  b

    The value as a boolean.

  c

    The value as a single byte character.

  d

    The value as a floating point number.

  i

    The value as a signed integer.

  id

    The value as a `ResourceId`.

  u

    The value as an unsigned integer.

## Chunks

class renderdoc.SDChunk

  Defines a single structured chunk, which is a `SDObject`.

  Duplicate()
    Returns

      A new deep copy of this chunk, which the caller owns.

    Return type

      SDChunk

  metadata

    The `SDChunkMetaData` with the metadata for this chunk.

class renderdoc.SDChunkMetaData

  The metadata that goes along with a `SDChunk` to detail how it was recorded.

  callstack

    The frames of the CPU-side callstack leading up to the chunk.

  chunkID

    The internal chunk ID - unique given a particular driver in use.

  durationMicro

    The duration in microseconds that this chunk took. This is the time for the actual work, not the serialising. Since 0 is a possible value for this (for extremely fast calls), -1 is the invalid/not present value.

  flags

    The `SDChunkFlags` for this chunk.

  length

    The length in bytes of this chunk - may be longer than the actual sum of the data if a conservative size estimate was used on creation to avoid seeking to fix-up the stored length.

  threadID

    The ID of the thread where this chunk was recorded.

  timestampMicro

    The point in time when this chunk was recorded, in microseconds since program start.

class renderdoc.SDChunkFlags(value)

  Bitfield flags that could be applied to an `SDChunk`.

  NoFlags

    This chunk has no special properties.

  OpaqueChunk

    This chunk wasn’t supported for decoding or was skipped for another reason and was detailed as an opaque byte stream. It should be preserved as-is and will remain in native RDC format.

  HasCallstack

    This chunk has a callstack. Used to indicate the presence of a callstack even if it’s empty (perhaps due to failure to collect the stack frames).

## Structured File

class renderdoc.SDFile

  Contains the structured information in a file. Owns the buffers and chunks.

  Swap(other)

    Swaps the contents of this file with another.

    Parameters

      other (SDFile) – The other file to swap with.

  buffers

    The buffers in the file, as referenced by the chunks in `chunks`.

    Type

      List[bytes]

  chunks

    The chunks in the file in order.

    Type

      List[SDChunk]

  version

    The version of this structured stream, typically only used internally.

## Creation Helper Functions

renderdoc.makeSDArray(name)

  Make a structured object which is an array.

  The array will be created empty, and new members can be added using methods on `SDObject`.

  Parameters

    name (str) – The name of the object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDBool(name, val)

  Make a structured object as a boolean value.

  Parameters

    - name (str) – The name of the object.

    - val (bool) – The bool which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDEnum(name, val)

  Make a structured object as an enum value.

  Note

  The enum will be stored just as an integer value, but the string name of the enumeration value can be set with `SDObject.SetCustomString()` if desired.

  Parameters

    - name (str) – The name of the object.

    - val (int) – The integer value of the enum itself.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDFloat(name, val)

  Make a structured object as a 32-bit float.

  Note

  You should ensure that the value you pass in has already been truncated to the appropriate range for the storage, as the resulting object will be undefined if the value is out of the valid range.

  Parameters

    - name (str) – The name of the object.

    - val (float) – The float which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDInt32(name, val)

  Make a structured object as a signed 32-bit integer.

  Note

  You should ensure that the value you pass in has already been truncated to the appropriate range for the storage, as the resulting object will be undefined if the value is out of the valid range.

  Parameters

    - name (str) – The name of the object.

    - val (int) – The integer which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDInt64(name, val)

  Make a structured object as a signed 64-bit integer.

  Note

  You should ensure that the value you pass in has already been truncated to the appropriate range for the storage, as the resulting object will be undefined if the value is out of the valid range.

  Parameters

    - name (str) – The name of the object.

    - val (int) – The integer which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDResourceId(name, val)

  Make a structured object as a ResourceId value.

  Parameters

    - name (str) – The name of the object.

    - val (ResourceId) – The ID which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDString(name, val)

  Make a structured object as a string value.

  Parameters

    - name (str) – The name of the object.

    - val (str) – The string which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDStruct(name, structtype)

  Make a structured object which is a struct.

  The struct will be created empty, and new members can be added using methods on `SDObject`.

  Parameters

    - name (str) – The name of the object.

    - structtype (str) – The typename of the struct.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDUInt32(name, val)

  Make a structured object as an unsigned 32-bit integer.

  Note

  You should ensure that the value you pass in has already been truncated to the appropriate range for the storage, as the resulting object will be undefined if the value is out of the valid range.

  Parameters

    - name (str) – The name of the object.

    - val (int) – The integer which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject

renderdoc.makeSDUInt64(name, val)

  Make a structured object as an unsigned 64-bit integer.

  Note

  You should ensure that the value you pass in has already been truncated to the appropriate range for the storage, as the resulting object will be undefined if the value is out of the valid range.

  Parameters

    - name (str) – The name of the object.

    - val (int) – The integer which will be stored in the returned object.

  Returns

    The new object, owner by the caller.

  Return type

    SDObject