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

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.

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).