API Reference: Formats¶

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.

Sections

Resource Format

Resource Format ¶

class renderdoc.ResourceFormat¶

Description of the format of a resource or element.

BGRAOrder()¶

Returns: True if the components are to be read in BGRA order.

Note

The convention is that components are in RGBA order. Whether that means first byte to last byte, or in bit-packed formats red in the lowest bits.

With BGRA order this means blue is in the first byte/lowest bits, but alpha is still always expected in the last byte/uppermost bits.

Return type: bool

BlockFormat()¶

Returns: True if the ResourceFormat is a block-compressed type.
Return type: bool

ElementSize()¶

Return the size of a single element in this format, usually a pixel. For regular sized formats this is just compByteWidth times compCount, for special packed formats it’s the tightly packed size of a single element, with no padding.

Block-compressed formats define an ‘element’ as a whole block of texels.

YUV formats where texel size varies depending on subsampling will return the size of a decompressed texel.

Returns: The size of an element
Return type: int

Name()¶

Returns: The name of the format.
Return type: str

SRGBCorrected()¶

Equivalent to checking if compType is CompType.UNormSRGB

Returns: True if the components are SRGB corrected on read and write.
Return type: bool

SetBGRAOrder(flag)¶

Set BGRA order flag. See BGRAOrder().

Parameters: flag# (bool) – The new flag value.

SetYUVPlaneCount(planes)¶

Set number of YUV planes. See YUVPlaneCount().

Invalid values will result in 1 being set.

Parameters: planes# (int) – The new number of YUV planes.

SetYUVSubsampling(subsampling)¶

Set YUV subsampling rate. See YUVSubsampling().

The value should be e.g. 444 for 4:4:4 or 422 for 4:2:2. Invalid values will result in 0 being set.

Parameters: subsampling# (int) – The new subsampling rate.

Special()¶

Returns: True if the ResourceFormat is a ‘special’ non-regular type.
Return type: bool

YUVPlaneCount()¶

Get the number of planes for a YUV format. Only valid when type is a YUV format like ResourceFormatType.YUV8.

For other formats, 1 is returned.

Returns: The number of planes
Return type: int

YUVSubsampling()¶

Get the subsampling rate for a YUV format. Only valid when type is a YUV format like ResourceFormatType.YUV8.

For other formats, 0 is returned.

Returns: The subsampling rate, e.g. 444 for 4:4:4 or 420 for 4:2:0
Return type: int

compByteWidth¶: The width in bytes of each component.

compCount¶: The number of components in each element.

compType¶

The type of each component.

Type: CompType

type¶

The ResourceFormatType of this format. If the value is not ResourceFormatType.Regular then it’s a non-uniform layout like block-compressed.

Type: ResourceFormatType

class renderdoc.ResourceFormatType(value)¶

A resource format’s particular type. This accounts for either block-compressed textures or formats that don’t have equal byte-multiple sizes for each channel.

Regular¶: This format has no special layout, so its format is described by a number of components, a CompType and a byte width per component.

Undefined¶: This format is undefined or unknown, or does not map to any known regular format.

BC1¶

A block-compressed texture in BC1 format (RGB with 1-bit alpha, 0.5 bytes per pixel)

Formerly known as DXT1, commonly used for color maps.

BC2¶

A block-compressed texture in BC2 format (RGB with 4-bit alpha, 1 byte per pixel)

Formerly known as DXT3, rarely used.

BC3¶

A block-compressed texture in BC3 format (RGBA, 1 byte per pixel)

Formerly known as DXT5, commonly used for color + alpha maps, or color with attached single channel data.

BC4¶

A block-compressed texture in BC4 format (Single channel, 0.5 bytes per pixel)

Commonly used for single component data such as gloss or height data.

BC5¶

A block-compressed texture in BC5 format (Two channels, 1 byte per pixel)

Commonly used for normal maps.

BC6¶

A block-compressed texture in BC6 format (RGB floating point, 1 byte per pixel)

Commonly used for HDR data of all kinds.

BC7¶

A block-compressed texture in BC7 format (RGB or RGBA, 1 byte per pixel)

Commonly used for high quality color maps, with or without alpha.

ETC2¶

A block-compressed texture in ETC2 format (RGB with 1-bit alpha, 0.5 bytes per pixel)

Commonly used on mobile or embedded platforms.

Note that the mode added in EAC with 1 byte per pixel and full 8-bit alpha is grouped as EAC, with a component count of 4. See EAC.

EAC¶

A block-compressed texture in EAC format, expanded from ETC2.

Commonly used on mobile or embedded platforms.

The single and dual channel formats encode 11-bit data with 0.5 bytes per channel (so the single channel format is 0.5 bytes per pixel total, and the dual channel format is 1 byte per pixel total). The four channel format is encoded similarly to ETC2 for the base RGB data and similarly to the single channel format for the alpha, giving 1 byte per pixel total. See ETC2.

ASTC¶

A block-compressed texture in ASTC format (Representation varies a lot)

The ASTC format encodes each block as 16 bytes, but the block size can vary from 4x4 (so 1 byte per pixel) up to 12x12 (0.11 bytes per pixel).

Each block can encode between one and three channels of data, either correlated or uncorrelated, in low or high dynamic range.

Commonly used on mobile or embedded platforms.

R10G10B10A2¶: Each pixel is stored in 32 bits. Red, green and blue are stored in 10-bits each and alpha in 2 bits. The data can either be unsigned normalised or unsigned integer.

R11G11B10¶: Each pixel is stored in 32 bits. Red and green are stored as an 11-bit float with no sign bit, 5-bit exponent and 6-bit mantissa. Blue is stored with 5-bit exponent and 5-bit mantissa.

R5G6B5¶: Each pixel is stored in 16 bits. Red and blue are stored as 5 bits, and green is stored as six. The data is unsigned normalised.

R5G5B5A1¶: Each pixel is stored in 16 bits. Red, green, and blue are stored as 5 bits, with 1-bit alpha. The data is unsigned normalised.

R9G9B9E5¶: Each pixel is stored in 32 bits. Red, green, and blue are stored with individual 9-bit mantissas and a shared 5-bit exponent. There are no sign bits.

R4G4B4A4¶: Each pixel is stored in 16 bits. Red, green, blue, and alpha are stored as 4-bit unsigned normalised values.

R4G4¶: Each pixel is stored in 8 bits. Red and green are stored as 4-bit unsigned normalised values.

D16S8¶: Each pixel is considered a packed depth-stencil value with 16 bit normalised depth and 8 bit stencil.

D24S8¶: Each pixel is considered a packed depth-stencil value with 24 bit normalised depth and 8 bit stencil.

D32S8¶: Each pixel is considered a packed depth-stencil value with 32 bit floating point depth and 8 bit stencil.

S8¶: Each pixel is an 8 bit stencil value.

YUV8¶: The pixel data is 8-bit in YUV subsampled format. More information about subsampling setup is stored separately

YUV10¶: The pixel data is 10-bit in YUV subsampled format. More information about subsampling setup is stored separately

YUV12¶: The pixel data is 12-bit in YUV subsampled format. More information about subsampling setup is stored separately

YUV16¶: The pixel data is 16-bit in YUV subsampled format. More information about subsampling setup is stored separately

PVRTC¶: PowerVR properitary texture compression format.

A8¶: 8-bit unsigned normalised alpha - equivalent to standard R8 with a pre-baked swizzle.

class renderdoc.CompType(value)¶

Represents the component type of a channel in a texture or element in a structure.

Typeless¶: A component that has no concrete type.

Float¶: An IEEE floating point value of 64-bit, 32-bit or 16-bit size.

UNorm¶: An unsigned normalised floating point value. This is converted by dividing the input value by the maximum representable unsigned integer value, to produce a value in the range [0, 1]

SNorm¶

A signed normalised floating point value in range. This is converted by dividing the input value by the maximum representable positive signed integer value, to produce a value in the range [-1, 1]. As a special case, the maximum negative signed integer is also mapped to -1 so there are two representations of -1. This means there is only one 0 value and that there is the same range of available values for positive and negative values.

For example, signed 16-bit integers range from -32768 to +32767. -32768 is mapped to -1, and then any other value is divided by 32767 giving an equal set of values in the range [-1, 0] as in the range [0, 1].

UInt¶: An unsigned integer value.

SInt¶: A signed integer value.

UScaled¶: An unsigned scaled floating point value. This is converted from the input unsigned integer without any normalisation as with UNorm, so the resulting values range from 0 to the maximum unsigned integer value 2^N - 1.

SScaled¶: A signed scaled floating point value. This is converted from the input unsigned integer without any normalisation as with SNorm, so the resulting values range from the minimum signed integer value -2^(N-1) to the maximum signed integer value 2^(N-1) - 1.

Depth¶: An opaque value storing depth information, either floating point for 32-bit depth values or else unsigned normalised for other bit sizes.

UNormSRGB¶: Similar to UNorm normalised between the minimum and maximum unsigned values to 0.0 - 1.0, but with an sRGB gamma curve applied.

API Reference: Formats¶

Resource Format¶

Resource Format ¶