Resources

Description

Create/edit/destroy resources (images and buffers).

Typedefs
using	tz::gpu::resource_handle = tz::handle<buffer_info>
	Corresponds to a previously-created resource (buffer or image).

Classes
struct	tz::gpu::buffer_info
	Specifies creation flags for a buffer. More...
struct	tz::gpu::image_info
	Specifies creation flags for an image. More...

Function Documentation

create_buffer()

std::expected< resource_handle, tz::error_code > tz::gpu::create_buffer

(

buffer_info

)

Create a new buffer.

Returns

On success: A resource_handle corresponding to the newly-created buffer.

tz::error_code::precondition_failure If the buffer info you provided was malformed (99% you are trying to use a zero-sized buffer which isn't supported).

tz::error_code::oom If CPU memory is exhausted whilst trying to create the buffer.

tz::error_code::voom If GPU memory is exhausted whilst trying to create the buffer.

tz::error_code::unknown_error If some other undocumented error occurs.

Once you successfully create a resource, you can use the returned resource_handle to create a new renderer that uses that resource.

Once you're done with a resource, you can destroy it using destroy_resource.

Note

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

create_image()

std::expected< resource_handle, tz::error_code > tz::gpu::create_image

(

image_info

)

Create a new image.

Returns

On success: A resource_handle corresponding to the newly-created image.

tz::error_code::oom If CPU memory is exhausted whilst trying to create the image.

tz::error_code::voom If GPU memory is exhausted whilst trying to create the image.

tz::error_code::unknown_error If some other undocumented error occurs.

Once you successfully create a resource, you can use the returned resource_handle to create a new renderer that uses that resource.

Once you're done with a resource, you can destroy it using destroy_resource.

Note

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

destroy_resource()

tz::error_code tz::gpu::destroy_resource

(

resource_handle

res

)

Manually destroy a resource.

Returns

tz::error_code::invalid_value If you attempt to delete the null resource tz::nullhand.

tz::error_code::invalid_value If you attempt to delete the window resource tz::gpu::window_resource.

tz::error_code::invalid_value If the resource handle provided is invalid. This usually happens due to memory corruption or an accidental double-delete.

tz::error_code::concurrent_usage If the resource is being used by at least one pass.

If you know a resource uses alot of memory, or you're sure you're not going to use it anymore, you can destroy it here, causing all of its memory to be available for reuse.

Note

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

Warning

You must not delete a resource that has been registered for use by an existing pass, until you delete all such passes first.

resource_write()

tz::error_code tz::gpu::resource_write	(	resource_handle	res,
		std::span< const std::byte >	new_data,
		std::size_t	offset = 0 )

Write some new data to a resource. The thread will block until the changes are resident GPU-side.

Parameters

res	Resource whose data should be changed.
new_data	Region containing new memory for the provided resource.

Returns

tz::error_code::invalid_value If the write is too large. The size of the new data + offset must be less than or equal to the resource's size.

If the region of new data is smaller than the total size of the resource's underlying data, then all bytes beyond the new data region will be unchanged and keep their previous state.

Regarding buffer resources:

• If the buffer is dynamic_access, the cost of the transfer should be in the same ballpark as a memcpy. In all other cases, a resource write is much slower. Regarding image resources:
• The data should be in the format of a tightly-packed array containing rows of pixels.
  • If the image was created with image_type::rgba, then each pixel should be 4 bytes - one for each component (0-255).
  • If the image was created with image_type::depth or image_type::floats, then each pixel should be 4 bytes - a single signed 32-bit float.

resource_size()

std::size_t tz::gpu::resource_size

(

resource_handle

res

)

Retrieve the size of a resource's data, in bytes.

image_get_width()

unsigned int tz::gpu::image_get_width

(

resource_handle

res

)

Retrieve the width of an image resource.

• It is valid to pass tz::gpu::window_resource, in which case the width of the window image will be returned.
• If you do not pass a valid image resource (e.g a buffer resource, or the null handle), then 0 is returned.

image_get_height()

unsigned int tz::gpu::image_get_height

(

resource_handle

res

)

Retrieve the height of an image resource.

• It is valid to pass tz::gpu::window_resource, in which case the height of the window image will be returned.
• If you do not pass a valid image resource (e.g a buffer resource, or the null handle), then 0 is returned.

resource_read()

std::span< const std::byte > tz::gpu::resource_read

(

resource_handle

res

)

Retrieves the current data within a resource.

You aren't allowed to read from tz::gpu::window_resource.

buffer_resize()

void tz::gpu::buffer_resize	(	resource_handle	bufh,
		std::size_t	new_size_bytes )

Resize a buffer resource.

• If the size of the buffer increases, the new memory at the end will be of unspecified value.
• Any data within the buffer that you have previously written to will be preserved.

image_resize()

void tz::gpu::image_resize	(	resource_handle	imgh,
		unsigned int	new_width,
		unsigned int	new_height )

Resize an image resource.

• If the size of the image increases, the new rows/columns of the image will be of unspecified value.
• Any data within the image that you have previously written to will be preserved.

index_buffer_write()

tz::error_code tz::gpu::index_buffer_write	(	resource_handle	index_buffer,
		std::span< const index_t >	indices )

Write indices into a buffer resource.

This is a helper function which will call resource_write under-the-hood.

draw_buffer_write()

tz::error_code tz::gpu::draw_buffer_write	(	resource_handle	draw_buffer,
		std::uint32_t	count,
		std::span< const draw_t >	draws )

Write draw-indirect-count + commands into a buffer resource.

This is a helper function which will call resource_write under-the-hood.

draw_buffer_indexed_write()

tz::error_code tz::gpu::draw_buffer_indexed_write	(	resource_handle	draw_buffer,
		std::uint32_t	count,
		std::span< const draw_indexed_t >	draws )

Write draw-indirect-count + indexed commands into a buffer resource.

This is a helper function which will call resource_write under-the-hood.

Typedef Documentation

resource_handle

using tz::gpu::resource_handle = tz::handle<buffer_info>

Corresponds to a previously-created resource (buffer or image).

Enumeration Type Documentation

buffer_flag

enum tz::gpu::buffer_flag

Specifies optional behaviours for a buffer.

Enumerator
index	Buffer can be used as an index buffer by a graphics pass.
draw	Buffer can be used as a draw buffer by a graphics pass.
dynamic_access	Buffer data will be writable directly from the CPU. Resource writes targetting buffers that are dynamic_access will be extremely fast. On some hardware, dynamic_access buffers will be slower to read/write from a shader.

image_type

enum class tz::gpu::image_type

strong

Describes the internal format of an image's data.

You are not able to choose a specific sized format.

Enumerator
rgba	Image data is in a 32-bit RGBA unsigned normalised format.
depth	Image is comprised of 32-bit floats per pixel, but is only used as a depth image.
floats	Image is comprised of 32-bit floats per pixel, but cannot be used as a depth image. Useful for normal maps.

image_flag

enum tz::gpu::image_flag

Specifies optional behaviours for a buffer.

Enumerator
colour_target	Image can be used as a colour target by a graphics pass.
depth_target	Image can be used as a depth target by a graphics pass.
resize_to_match_window_resource	Image will be automatically resized to match the dimensions of the window. In addition, tz::gpu::image_info::width and tz::gpu::image_info::height are ignored.

Variable Documentation

window_resource

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

constexpr

Corresponds to either the window image (as a colour target) or the system depth image (as a depth target). Note that it is invalid to use this value for anything other than pass_graphics_state::colour_targets or pass_graphics_state::depth_target.