Hardware

Description

Documentation specialised for iterating over rendering hardware and selecting one to be used for rendering.

Classes
struct	tz::gpu::hardware
	Contains some basic information about a particular piece of hardware on the machine that the driver thinks could do GPU work. More...

Function Documentation

iterate_hardware()

error_code tz::gpu::iterate_hardware	(	std::span< hardware >	hardwares,
		std::size_t *	hardware_count = nullptr )

Retrieve information about all detected rendering hardware currently available on the machine.

Parameters

hardwares	A region of memory through which hardware information shall be written to. As many hardware components as possible will be written, until all hardware has been listed or the region does not have enough available space.
hardware_count	A pointer to a value which (if not-null) will be updated with the total number of rendering hardware components available on the machine.

Returns

- error_code::partial_success If the span of hardwares provides is not large enough to store all hardwares on the machine.

- error_code::precondition_failure If Topaz has not yet been initialised via tz::initialise.

- error_code::unknown_error If some other error occurs.

If you aren't interested in choosing a hardware yourself, and are happy to let Topaz figure out the best for you, use find_best_hardware instead of this.

You should use this function if you:

• Want to examine all hardware available on the machine.
• Know what you're doing and have a very specific set of requirements for your application, so much so that you cannot trust Topaz to give you the ideal result via find_best_hardware.

find_best_hardware()

hardware tz::gpu::find_best_hardware

(

)

Retrieve the "best" hardware hardware on your machine.

This function prefers desktop GPUs that handle compute/graphics/transfer on the same queue.

If you want more control over which hardware is used, or you don't trust Topaz's opinion, consider calling iterate_hardware and choosing one yourself.

Unlike iterate_hardware, any error that the driver reports is considered fatal and will emit a tz_error.

use_hardware()

error_code tz::gpu::use_hardware

(

hardware

hw

)

Select a piece of hardware to use for future graphical operations.

Parameters

hw	A hardware component of your choice that you wish to use to perform some GPU work.

You must select a piece of hardware using this API call before attempting to submit any GPU work. There is no default hardware selection.

Note

All previous tz::gpu state will be invalidated if you use a new piece of hardware. It is recommended to select your hardware once after tz::initialise, use it with this function and never attempt to use other hardware.

get_used_hardware()

hardware tz::gpu::get_used_hardware

(

)

Retrieve the hardware that's currently being used.

This will return the hardware selected in a previous call to use_hardware. If you have never selected a hardware component by calling this previous function, this function will emit a tz_error.

Enumeration Type Documentation

hardware_type

enum class tz::gpu::hardware_type

strong

Describes a specific type of rendering hardware.

Enumerator
gpu	A discrete GPU, the most ideal hardware for graphics/compute. Typically seen on desktop PCs.
integrated_gpu	An integrated GPU, typically seen on laptops.
cpu	A CPU. One should expect subpar performance, but there may be reasons to use a CPU.
unknown	Your graphics driver failed to identify the hardware, or Topaz does not support whatever it is. You should not attempt to create a hardware using this hardware.

hardware_capabilities

enum class tz::gpu::hardware_capabilities

strong

Describes what kind of GPU operations a rendering hardware can carry out when used.

Enumerator
graphics_compute	Both graphics and compute. These are always preferred.
graphics_only	Graphics only. Attempting to carry out compute work on this hardware will fail.
compute_only	Compute only. Attempting to carry out graphics work (rasterisation) on this hardware will fail.
neither	The hardware is useless for Topaz. You should not attempt to create a hardware using this hardware.

hardware_feature_coverage

enum class tz::gpu::hardware_feature_coverage

strong

Describes to what extent the rendering hardware supports all the features that Topaz requires.

Enumerator
ideal	The hardware supports everything Topaz needs to do to support all GPU Library features.
insufficient	The hardware does not support all features, and as such could crash.
poor	The hardware does not come close to supporting all required features, and as such should not be attempted to be used.