Passes

Description

Documentation for render/compute passes - each a single node within Graphs.

Typedefs
using	tz::gpu::pass_handle = tz::handle<pass_info>
	Corresponds to a previously-created pass.

Classes
struct	tz::gpu::pass_graphics_state
	Specifies creation flags for a new graphics pass. More...
struct	tz::gpu::pass_compute_state
	Specifies creation flags for a new compute pass. More...
struct	tz::gpu::pass_info
	Specifies creation flags for a new pass. More...

Function Documentation

create_pass()

std::expected< pass_handle, tz::error_code > tz::gpu::create_pass

(

pass_info

)

Create a new pass.

Returns

On success: A pass_handle corresponding to the newly created pass.

tz::error_code::invalid_value If you fail to provide a valid shader program.

tz::error_code::invalid_value If you provide a malformed shader program. A shader program is only well-formed if it consists of only a compute shader, OR it consists of a single vertex and fragment shader.

tz::error_code::invalid_value For a graphics pass if you fail to provide at least one colour target.

tz::error_code::invalid_value For a graphics pass if you provide a colour target that is invalid. A valid colour target is either a.) the window resource (and you have opened a window), b.) an image resource created with tz::gpu::image_flag::colour_target

tz::error_code::precondition_failure For a graphics pass if any colour target provided does not exactly match the dimensions of all other provided colour targets. All colour targets must be images with the same dimensions. This does mean that if you provide the window resource as a colour target, all other colour targets must have the same dimensions as the window.

tz::error_code::machine_unsuitable If the currently-used hardware does not support the pass you're attempting to create, for example if you attempt to create a graphics pass but your hardware has hardware_capabilities::compute_only.

tz::error_code::oom If CPU memory is exhausted while trying to create the pass.

tz::error_code::voom If GPU memory is exhausted while trying to create the pass.

Once you successfully create a pass, you can add it to a TODO: write docs on timelines

Once you're done with a pass, you can manually destroy it using destroy_pass.

Note

If you never destroy a pass manually, it will automatically be destroyed for you when you call tz::terminate.

pass_set_triangle_count()

void tz::gpu::pass_set_triangle_count	(	pass_handle	graphics_pass,
		std::size_t	triangle_count )

Set the triangle count of an existing graphics pass.

Parameters

graphics_pass	Graphics pass to target. If you provide a compute pass, nothing interesting happens.
triangle_count	New number of triangles to render every frame.

When you created a graphics pass, you set an initial triangle count via pass_graphics_state::triangle_count. This function will override that count, meaning the next time a pass submits GPU work, the new number of triangles will be rendered.

There are no GPU-sync considerations involved when calling this function.

Warning

If you fail to pass a valid pass_handle to this function, the behaviour is undefined.

pass_set_kernel()

void tz::gpu::pass_set_kernel	(	pass_handle	compute_pass,
		tz::v3u	kernel )

Set the compute kernel of an existing compute pass.

Parameters

compute_pass	Compute pass to target. If you provide a graphics pass, nothing interesting happens.
kernel	New workgroup dimensions to be dispatched every frame.

When you created a compute pass, you set an initial kernel size via pass_compute_state::kernel. This function will override those dimensions, meaning the next time a pass submits GPU work, the new workgroup dimensions will be dispatched.

There are no GPU-sync considerations involved when calling this function.

Warning

If you fail to pass a valid pass_handle to this function, the behaviour is undefined.

pass_set_scissor()

void tz::gpu::pass_set_scissor	(	pass_handle	graphics_pass,
		tz::v4u	scissor )

Set the scissor rectangle of an existing graphics pass.

Parameters

graphics_pass	Graphics pass to target. If you provide a graphics pass, nothing interesting happens.
scissor	Scissor rectangle, see pass_graphics_state::scissor for further details.

When you created a graphics pass, you may or may not have explicitly set an initial scissor rectangle via pass_graphics_state::scissor. This function will override those dimensions, meaning the next time a pass submits GPU work, the new scissor rectangle will be used.

There are no GPU-sync considerations involved when calling this function.

Warning

If you fail to pass a valid pass_handle to this function, the behaviour is undefined.

pass_add_image_resource()

tz::error_code tz::gpu::pass_add_image_resource	(	pass_handle	pass,
		resource_handle	res )

Add a new image resource to be used in the pass.

Returns

tz::error_code::invalid_value If you fail to provide a valid image resource. Note that this excludes buffer resources, the window resource, and the null resource.

tz::error_code::driver_hazard If there are too many images used by the pass already. Passes have an implementation-defined maximum image count that is guaranteed to be at least 4096.

This will permanently increase the number of resources used in the pass. It is not possible to change the shader used by a pass, so the shader associated with the pass is expected to conditionally use the new image id anyway.

All other resources used by the pass are unchanged. The index of this new image to be used in the shader will be equal to the previous number of images.

destroy_pass()

void tz::gpu::destroy_pass

(

pass_handle

)

Manually destroy a pass.

Passes can be quite heavy in the context of both CPU and GPU memory. This is due to internal components such as recorded command buffers, synchronisation primitives and compiled shader code.

Because of this, it might sometimes be necessary to manually destroy a pass once you are certain you have no further use of it. This will free up a bunch of CPU/GPU memory.

Warning

If you fail to pass a valid pass_handle to this function, the behaviour is undefined.

Typedef Documentation

pass_handle

using tz::gpu::pass_handle = tz::handle<pass_info>

Corresponds to a previously-created pass.

Enumeration Type Documentation

pass_type

enum class tz::gpu::pass_type

strong

Describes what kind of GPU work a pass will involve.

Enumerator
render	Render Pass - involves rendering some kind of geometry via a vertex and fragment shader.
compute	Compute Pass - involves bespoke GPU-side processing via a compute shader.

graphics_flag

enum tz::gpu::graphics_flag

Specifies optional behaviours for a graphics pass.

Enumerator
dont_clear	Do not clear the colour target images prior to rendering - whatever data they held previously will be loaded prior to rendering.
no_depth_test	Disable depth testing - i.e fragments that are behind another may still draw over it.
no_depth_write	Disable depth writes - i.e when a depth test is passed by a fragment, the old depth value is not overwritten, but stays as it was before. Note Depth writes are always disabled if depth testing is disabled (see graphics_flag::no_depth_test).

cull

enum class tz::gpu::cull

strong

Specifies face culling behaviour of a graphics pass.

Enumerator
both	Cull front and back faces.
front	Cull the front face.
back	Cull the back face.
none	Do not perform any face culling.

Variable Documentation

present_pass

auto tz::gpu::present_pass = static_cast<tz::hanval>(std::numeric_limits<std::underlying_type_t<tz::hanval>>::max() - 1)

constexpr

Meta-pass that acts as an action to present the system image to the screen.