API Reference: Structured Data¶
This is the API reference for the functions, classes, and enums in the renderdoc module which represents the underlying interface that the UI is built on top of. For more high-level information and instructions on using the python API, see Python API.
Type information¶
- class renderdoc.SDType¶
Details the name and properties of a structured type
- 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
SDTypeFlagsflags 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
Structotherwise. SeeSDChunk.
- 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.- AsBool()¶
Interprets the object as a
booland returns its value. Invalid if the object is not actually abool.- 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
ResourceIdand returns its value. Invalid if the object is not actually aResourceId.- Returns
The interpreted ID.
- Return type
- 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.
- FindChild(childName)¶
Find a child object by a given name. If no matching child is found,
Noneis returned.
- FindChildRecursively(childName)¶
Find a child object by a given name recursively. If no matching child is found,
Noneis returned.The order of the search is not guaranteed, so care should be taken when the name may not be unique.
- GetChild(index)¶
Find a child object by a given index. If the index is out of bounds,
Noneis returned.
- GetParent()¶
Get the parent of this object. If this object has no parent,
Noneis returned.- Returns
A reference to the parent object if valid, or
Noneif not.- Return type
- HasEqualValue(obj)¶
Checks if the given object has the same value as this one. This equality is defined recursively through children.
- 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
SDObjectDatawith the contents of this object.
- name¶
The name of this object.
- class renderdoc.SDObjectData¶
The data inside an
SDObjectwhether 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.- metadata¶
The
SDChunkMetaDatawith the metadata for this chunk.
- class renderdoc.SDChunkMetaData¶
The metadata that goes along with a
SDChunkto 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
SDChunkFlagsfor 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¶
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.
- renderdoc.makeSDBool(name, val)¶
Make a structured object as a boolean value.
- 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.
- 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.
- 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.
- 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.
- 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
- renderdoc.makeSDString(name, val)¶
Make a structured object as a string value.
- 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.
- 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.
- 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.