Python Interface

GPA Python Module

Lets you script GPA capture, playback, metrics etc.

class GPA.ApiLog

Stores a list of the api calls used in the original workload.

class GPA.BufferMetadata

Represents the metadata such as: length and type of a buffer

buffer_type

The type of buffer.

length

The length of the buffer.

class GPA.BufferRange

Represents the offset and range of a buffer.

offset

The offset into the buffer in bytes where the bound range begins.

range

The length of the bound range.

class GPA.Experiment
add_shader()

Add a shader to the experiment object. Shader stage is inferred from object and replaces existing shader set for that stage if any.

pipeline_as_json

Pipeline state as a json string representation

remove_shader()

Takes a shader stage string as input and removes shader object set for that stage from the Experiment

class GPA.ImageBinding
array_index

The array index within a descriptor binding, if applicable.

binding

Descriptor binding.

descriptor_set

Descriptor set.

handle

Texture handle.

class GPA.ImageData
data

Raw texture data.

handle

Texture handle.

metadata

Texture metadata

class GPA.ImageMetadata
depth

Depth of the texture

format

Format of the texture

height

Height of the texture

mips

Number of mip levels within the texture

slices

Number of textures within the texture array

total_size

Total size in bytes of the texture

width

width of the texture

class GPA.InputResource

This class is used to represent metadata for input resources.

Parameters

resource_id (int) – The Id uniquely identifying the resource.

resource_id

The resource id.

class GPA.MetadataExtractor

This class is used to extract metadata API calls.

get_all_bound_resources()

Returns all unique resources IDs that are used (bound) within the range of interest

get_all_resource_bindings()

Returns the resource bindings for all api calls as a list

get_metadata_for_resource()

Returns true if a resource exists in the range with the given resource ID

get_resource_bindings_at_index()

Returns the resource bindings for a given call index within the range.

Parameters

index (int) – The index of the api call to get the resource bindings from

Return type

ResourceBindings

Example

binding = metaDataExtractor.get_resource_bindings_at_index(17)

get_sampler_json()

Get a sampler’s create info as a json string.

get_source_for_shader()

Returns the requested shading language version of a shader, given that the representation is valid for the requested shader.

Parameters

shader_request (ShaderRequest) – ShaderRequest object containing details about which representation to return for which shader.

Returns

The source code corresponding to the requested representation, or empty if an invalid request was made.

Return type

ShaderSource

Example
>>> shader_request = ShaderRequest(resourceID, ShaderLanguageEnum.GLSL)
>>> shader_source = metaDataExtractor.get_source_for_shader(shader_request)
Note

The shading language must be supported by API shader object; for example, Vulkan shaders (SPIR-V bytecode) can be written in GLSL, HLSL, etc.

is_valid_resource()

Returns true if a resource exists in the range with the given resource ID

pipeline_json_at_erg()

Get the pipeline state as a json string.

resource_count

The number of unique resources used within in the range

class GPA.OutputResource

This class is used to represent metadata for output resources.

Parameters

resource_id (int) – The Id uniquely identifying the resource.

resource_id

The resource id.

class GPA.PlaybackEngine

Provides high level control over RangePlayer execution for results extraction with experiment application.

apply_experiment()

Apply an experiment to an erg or a list of ergs. List should contain integer type elements. Other types will be ignored

disable_calls()

Skips execution of the API calls at the given indices.

Parameters

indices (list[int]) – list of api call indices to disable

>>> if callables[100]._category & CallableTypeEnum.Draw || callables[100]._category & CallableTypeEnum.Dispatch:
...     playback_engine.disable_calls([100])
enable_all_calls()

Clears the list of disabled calls set by the user, returning it to the default state whereall API calls are executed.

enable_calls()

Re-enables execution of calls previously disabled by disable_calls().

Parameters

indices (list[int]) – list of api call indices to enable

Example

playback_engine.enable_calls([100,200,300])

execute()

Execute a metrics request

execute_range()

Executes this PlaybackeEngine’s RangePlayer.

execute_resource_request()

Execute a metadata request

get_metadata()

Get the metadata extractor

get_metrics_extractor()

Get the metrics extractor

validate_shader()

Validate a given shader source object. Returns True if validation succeeds. Validation is a requirement before using shader in an experiment

class GPA.Player

Used to play back the api calls within a stream.

Example

>>> layers = ["hud-layer", ("screenshot", [('frame','200')])]
>>> player = GPA.Player(stream=stream_object, pre_layer=layers, post_layer=["logging"])
play_stream()

Play back a stream from the beginning or from a keyframe to any desired point.

Parameters
  • start (float) – Position in the stream to start (default 0). In range [0.0, 1.0). The stream will always play from the beginning if no keyframes were captured

  • end (float) – Postion in the stream to end playback (default 1). In range [0.0, 1.0].

Raises

valueError – If start position is greater than end position

Example

>>> player.play_stream(start=0.5, end=0.7)
>>> player.play_stream(start=0.7)
>>> player.play_stream()
play_stream_by_range()

Play back a stream from the beginning or from a keyframe to any desired point.

Parameters
  • start (int) – Range in the stream to start (default 0). The stream will always play from the beginning if no keyframes were captured

  • end (int) – Postion in the stream to end playback (default to last range).

Raises

valueError – If start range is greater than end range

Example

>>> player.play_stream_by_range(start=25, end=50)
>>> player.play_stream_by_range(start=60)
>>> player.play_stream_by_range()
class GPA.RangePlayer
play_range()

Play the given range

prepare_for_metrics_collection()

Validate a given range for metrics collection and sets internal state. :param first: The index to begin preparing for metrics collection :type first: int :param last: The last prepare for metrics collection :type last: int :raise: GPA.InvalidRangeException if range is not valid :raise: GPA.Error if an error occurred

range_cache

The processed callable cache.

class GPA.RequestedResource
buffer

Buffer request parameters

id

Resource ID

resource_type

Resource Type

texture

Texture request parameters

class GPA.ResourceBindings
indexBuffers

List of resource IDs representing indexBuffers.

inputs

List of input resources.

is_draw_call

True if this resource binding is bound to a draw call.

outputs

List of outputs resources.

shaders

List of resource IDs representing shaders.

vertexBuffers

List of resource IDs representing vertexBuffers.

class GPA.ResourceData
resource_data

Memory view of the raw data from the return buffer

resource_id

ID of the xtracted resource

class GPA.ResourceDataRequest
index

Index of requested API call

resource_list

A list of resource IDs

class GPA.ResourceExperiment
image_bindings

Dictionary with (integer)set and (integer)binding tuple as the key and ImageBindings as the value.

image_data

Dictionary of (integer)handles as keys and ImageData objects as values.

remove_image_binding()

Undos any currently set modification made to the given resource binding.

remove_image_data()

Disassociates the image associated with the given ID and removes its data on this ResourceExperiment.

set_image_at_binding()

Requests that the resource associated with the given ID is set at the given binding.

set_image_data()

Hands over user resource data to the ResourceExperiment that the user would like to use when making a binding modification later.

class GPA.ResourceMetadata
debug_name

The working name for this resource

depth

The depth of the texture resource

format

The data format of this texture resource

height

The height of the texture resource

length

The length in bytes of the buffer resource

mips

The number of mip levels in this texture resource

resource_type

The type of resource this metadata is for

sample_count

The sample count of this texture resource; 1 (single sampled) by default

sampler_metadata

Sampler metadata struct object

shader_source

A list of shader source metadata

slices

The number of slices in this texure resource

sub_type

The subType of this resource

width

The width of the texture resource

class GPA.ResultResourceMetadata
buffer

Metadata for the extracted buffer.

debug_name

The debug name, if set, empty otherwise.

metadata_type

The type of resource this metadata is for.

texture

Metadata for the extracted texture.

class GPA.SamplerMetadata
address_mode_u

Method to use for resolving an x texture coordinate that is outside the 0 to 1 range.

address_mode_v

Method to use for resolving a v texture coordinate that is outside the 0 to 1 range.

address_mode_w

Method to use for resolving a w texture coordinate that is outside the 0 to 1 range.

border_color

Border color to use if kTextureAddressBorder is specified for addressModeU, addressModeV, or addressModeW. Range must be between 0.0 and 1.0 inclusive. Equivalent to (Vk) VkBorderColor, (DX) FLOAT BorderColor[4]

compare_enable

True if comparision operations are enabled during lookups.

compare_op

The comparison function to apply to fetched data before filtering.

flags

Creation flags

mag_filter

Value specifying the magnification filter to apply to lookups.

max_anisotropy

Anisotropy clamp value

max_lod

Used to clamp the computed LOD value.

min_filter

Value specifying the minification filter to apply to lookups.

min_lod

Used to clamp the computed LOD value.

mip_lod_bias

Offset from the calculated mipmap level.

mipmap_mode

Value specifying the mipmap filter to apply to lookups.

unnormalized_coordinates

Controls whether to use unnormalized or normalized texel coordinates to address texels of the image.

class GPA.ShaderMetadata
shader_sources

A list of shader source code.

shader_stage

The graphics pipline stage that this shader is bound to.

class GPA.ShaderRequest

Represents a request for a shader source code of a particular language.

language

The desired language enum

resource_id

Resource ID

class GPA.ShaderSource
contents

Shader contents(source code) as a string. Needs validation if modified before use.

language

The name of the shader language (as a string) being used

stage

The stage of graphics pipeline (as a string), the shader is meant to be used.

class GPA.SimpleFragmentShaderExperiment

This class provides a prebuilt simple fragment shader experiment object with configurable RGBA color property

color

Set color as list of floats

class GPA.Stream

The main interface for capturing and parsing/accessing streams of graphics (and other) API calls, and associated data.

Constructor: Open a GPA stream folder. :param arg: Path to stream folder :type arg: str or os.PathLike :returns A Stream object representing the loaded GPA Stream :rtype Stream

>>> Stream("/GPA/GameStream/")
get_range()

Return a Range representing the callables within the specified boundaries.

get_storage_count()

Return the number of Storage “substreams” within this stream.

range_count

The number of ranges in the stream.

class GPA.StreamData
header_info

get stream header info

class GPA.StreamHeaderInfo
architecture

32 or 64 bit architecture

bios_date
bios_version
color_depth
cores_count
developer_mode_enabled
dram_memory

physical memory of capture computer

file_version

Current file version

gpa_build_number
gpa_release_quarter
gpa_release_sprint
gpa_release_year
gpu_driver_date

GPU driver revision data mm/dd/yyyy

gpu_driver_version

GPU driver version

gpu_name

Name of the used gpu

gpu_product_id
gpu_stepping
gpu_vendor

Name of the used gpu vendor

graphics_API

Graphics API name

graphics_API_version

Graphics API version

hostname

Name of the capture computer

locale
num_api_calls

Number of api calls captured

num_frames

Number of frames captured

os_version

Operating system version

resolution_height

Height of the window

resolution_width

Width of the window

secure_boot_enabled
class GPA.StreamScrubber
play_to_bookmark()

Play to the bookmark in the stream (this will use keyframing, if available)

class GPA.TextureBox
depth

depth of the box.

height

height of the box.

width

width of the box.

x

x coordinate of the box.

y

y coordinate of the box.

z

z coordinate of the box.

class GPA.TextureSlice
array_index

Index of the desired texture within the texure array.

aspect

Enum representing the type of data this texture is storing.

mip_index

The mip level within the texture.

class GPA.TextureSubresourceDesc
box

The region of interest within the texture.

format

The format of the texture data.

row_stride

The row stride of texture data.

slice

The subresource texture.

texure_type

The type of texture to request.

class GPA.TwoByTwoTextureReplacementExperiment

This class provides a prebuilt resource experiment object which is api agnostic

SetTextureColor()

Sets the four colors used in the two by two texture.

add_target_replacement_binding()

Adds a new binding to the list of texture bindings that should be replaced with a 2x2 image.

clear_replacment_bindings()

Clears the list of bindings where images should be replaced.

color1

Set color as list of floats

color2

Set color as list of floats

color3

Set color as list of floats

color4

Set color as list of floats

class GPA.WireframeExperiment

This class provides a prebuilt wireframe objectwhich is api agnostic

GPA.capture_stream()

Run a graphics application injected under GPA (and optionally capture stream) This function blocks until application exits, but you can run it on a separate thread and it wont pause other python threads(due to not using the GIL internally)

Parameters
  • target_name (str) – path to application to run injected under GPA

  • layer_list (List[Union[str, Tuple[str, List[str]]]]) – (optional) list of layers where every element is a layer_name str or a (layer_name, layer_args_list) tuple if passing layer args layers include hud-layer/screenshot/capture/validation(see layers directory/ for others) details about layer arguments can be found by running gpa-help executable passing the layer name or on the gpa README.md

  • target_args (List[str]) – (optional) arguments to pass to target application

>>> capture_stream(path_to_application, ["hud-layer", ("capture", ['directory='+non_defautl_captures_folder])])
>>> capture_stream(path_to_application, [("screenshot", ['frame=100']), "capture"])
#if you don't include capture layer gpa wont capture, it will only inject
>>> capture_stream(path_to_application, target_args=['-a', '-noheartbeatthread', '-fullscreen'])
#or more usefully inject and screenshot
>>> capture_stream(path_to_application, [("screenshot", ['frame=100'])], ['-a', '-noheartbeatthread', '-fullscreen'])
GPA.init_gpa_metrics()

Perform one-time metrics setup activities that need to be performed before any graphics devices exist for the process regardless of it they will be used for metrics collection (for example, before performing playback).