API Reference

Description

C++ API for the Topaz Engine.

Topics
	Core Libraries
	Lowest-level libraries, structs and functionality. Everything is expected to depend on this.
	OS Libraries
	Cross-platform API to interact with operating-system level components, such as windowing, hardware input, and machine non-GPU hardware.
	GPU Library
	Abstract rendering API for low-level, high-performance 3D desktop graphics.
	Rendering Library
	High-level declarative rendering API built upon the GPU Library.
	IO Library
	High-level library for wrangling files of various formats.

Classes
struct	tz::appinfo
	Contains information about the application being initialised. More...

Function Documentation

initialise()

void tz::initialise

(

appinfo

info = {}

)

Initialise the engine.

Parameters

info	Some basic information about your application. If you don't provide this, some placeholder values will be provided for you.

This function must be the first Topaz API call you make, ideally at the start of your program's runtime.

You should expect this function to take a significantly long time.

terminate()

void tz::terminate

(

)

Terminate the engine, cleaning up all resources.

This function should be the last Topaz API call you make before the end of your program's runtime.

You should expect this function to take a significantly long time.

Macro Definition Documentation

tz_assert

#define tz_assert	(		cond,
			fmt,
			... )

Assert that the given condition must be true. Cause a tz_error if not.

Parameters

cond	Condition which must evaluate to true.
fmt	Format string, following the fmtlib convention (i.e the n'th instance of {} in the string will be replaced with the n'th variadic parameter).
...	Additional arguments (size should correspond to the number of occurrences of {} in fmt) that shall be substituted into the format string.

tz_error

#define tz_error	(		fmt,
			... )

Cause a runtime error. If a debugger is present, a breakpoint will occur at the call-site. Otherwise, the program will terminate.

Parameters

fmt	Format string, following the fmtlib convention (i.e the n'th instance of {} in the string will be replaced with the n'th variadic parameter).
...	Additional arguments (size should correspond to the number of occurrences of {} in fmt) that shall be substituted into the format string.

tz_must

#define tz_must

(

fnret

)

Cause a runtime error if the expected value is erroneous. If not, the unwrapped expected value is returned.

Many API functions in Topaz return some variant of std::expected. Handling them on an individual basis can be verbose and unnecessary. Surround the call with this macro to instead yield the expected value directly, and emit a runtime error if an error code was returned instead.

Note

You should only use this macro on a return value if you are happy to crash if the value is erroneous. Treat it as a glorified tz_assert.

Example before:

std::expected<tz::gpu::resource_handle, tz::error_code> img = tz::gpu::create_image({...});

Example after:

tz::gpu::resource_handle img = tz_must(tz::gpu::create_image({...}));