Structured Data

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.

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

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