diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000000..e69de29bb2 diff --git a/bc_s.png b/bc_s.png new file mode 100644 index 0000000000..224b29aa98 Binary files /dev/null and b/bc_s.png differ diff --git a/bc_sd.png b/bc_sd.png new file mode 100644 index 0000000000..31ca888dc7 Binary files /dev/null and b/bc_sd.png differ diff --git a/classtz_1_1handle-members.html b/classtz_1_1handle-members.html new file mode 100644 index 0000000000..17dd6ae3a2 --- /dev/null +++ b/classtz_1_1handle-members.html @@ -0,0 +1,112 @@ + + +
+ + + + ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
This is the complete list of members for tz::handle< T >, including all inherited members.
+operator!=(nullhand_t) const | tz::handle< T > | inline |
operator=(hanval value) | tz::handle< T > | inline |
operator==(nullhand_t) const | tz::handle< T > | inline |
peek() const | tz::handle< T > | inline |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Represents a generic opaque handle.
+To create your own opaque handle types, simply create a type alias for a handle<T>
where T
is any unique type identifier.
#include "handle.hpp"
+Public Member Functions | |
std::underlying_type_t< hanval > | peek () const |
Disregard the concept of "opaqueness" of an opaque handle by peeking at the underlying value. You should avoid the use of this outside of debug tools. | |
handle & | operator= (hanval value) |
Assign a handle to the null handle, meaning it is now invalid. | |
bool | operator== (nullhand_t) const |
Compare a handle to the null handle. This comparison will return false if the handle is valid. | |
bool | operator!= (nullhand_t) const |
Compare a handle to the null handle. This comparison will return true if the handle is valid. | |
+
|
+ +inline | +
Disregard the concept of "opaqueness" of an opaque handle by peeking at the underlying value. You should avoid the use of this outside of debug tools.
+ +
+
|
+ +inline | +
Assign a handle to the null handle, meaning it is now invalid.
+ +
+
|
+ +inline | +
Compare a handle to the null handle. This comparison will return false if the handle is valid.
+ +
+
|
+ +inline | +
Compare a handle to the null handle. This comparison will return true if the handle is valid.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+Files | |
graph.hpp | |
hardware.hpp | |
pass.hpp | |
resource.hpp | |
settings.hpp | |
shader.hpp | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+Directories | |
core | |
detail | |
gpu | |
io | |
os | |
ren | |
+Files | |
main.hpp | |
topaz.hpp | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+Files | |
error.hpp | |
handle.hpp | |
job.hpp | |
lua.hpp | |
matrix.hpp | |
memory.hpp | |
quaternion.hpp | |
time.hpp | |
trs.hpp | |
vector.hpp | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
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... | |
void tz::initialise | +( | +appinfo | info = {} | ) | ++ |
Initialise the engine.
+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.
+ +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.
+ +#define tz_assert | +( | +cond, | +|
+ | + | fmt, | +|
+ | + | ... ) | +
Assert that the given condition must be true. Cause a tz_error if not.
+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. |
#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.
+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. |
#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.
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({...}));
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Lowest-level libraries, structs and functionality. Everything is expected to depend on this.
++Topics | |
Job System | |
Submit async jobs to an internal threadpool. | |
Lua Scripting | |
Execute lightweight lua code within the engine. | |
Mathematics | |
Basic mathematical geometric types. | |
+Classes | |
class | tz::handle< T > |
Represents a generic opaque handle. More... | |
+
|
+ +strong | +
Error codes for Topaz.
+Enumerator | |
---|---|
success | Correct behaviour has occurred. No need to do any sanity checking. + |
partial_success | Nothing erroneous happened, but the process did not complete fully or otherwise provide an ideal result. + |
precondition_failure | An error has occurred because some previously-required setup has not been complete. The most common cause of this is not initialising the engine via tz::initialise. + |
invalid_value | An error has occurred because an illegal/incorrect value has been detected. + |
machine_unsuitable | An error has occurred because the currently running machine does not support the given operation. + |
engine_bug | An error has occurred due to an engine-side logic error, and you should submit a bug report. + |
driver_hazard | An error has occurred due to a serious hazard relating to the driver/hardware. This most likely means a graphics driver crash/hardware-lost. + |
unknown_error | An error has occurred, but it's not clear why. + |
oom | An error has occurred due to lack of CPU memory. + |
voom | An error has occurred due to lack of GPU memory. + |
concurrent_usage | An error has occurred due to an operation being invalid while a given resource is in use by something else. + |
+
|
+ +constexpr | +
Represents the null handle. You can assign any tz::handle<T> to the null handle, meaning it no longer corresponds to something valid. You can also compare any handle to the null handle.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Submit async jobs to an internal threadpool.
++Typedefs | |
using | tz::job_function = std::function<void()> |
Represents a function that will be executed on a job worker via job_execute. | |
job_handle tz::job_execute | +( | +job_function | fn | ) | ++ |
Execute a function as a new job.
+This creates a new job which will be picked up by any worker thread as soon as possible. You can query the job's progress via job_complete, or block the wait for it to finish via job_wait.
+There is no guarantee or hint as to which worker thread ultimately picks up your work. If you need that, consider job_execute_on. There is also no safety mechanism in place for avoiding deadlocks – there is nothing stopping you from writing race conditions, nor does some hidden feature exist to protect you from them.
+job_handle tz::job_execute_on | +( | +job_function | fn, | +
+ | + | job_worker | worker ) | +
Execute a function as a new job - but can only be picked up by a specific worker.
+At any given time, there are a set of worker threads available for use (number of worker threads is equal to job_worker_count). Unlike job_execute, the job created by this function is tailored to only a single worker thread. Aside from this, the behaviour of this function exactly matches that of job_execute.
+You might want to do this for a couple of reasons:
void tz::job_wait | +( | +job_handle | job | ) | ++ |
Block the current thread until the job specified has been fully completed.
+ +bool tz::job_complete | +( | +job_handle | job | ) | ++ |
Query as to whether the specific job has been fully completed or not.
+ +std::size_t tz::job_count | +( | +) | ++ |
Estimate the total number of jobs that have been created but not yet completed.
+You should assume the returned value to be an estimate – a lower bound on the real number. It is also absolutely possible that many jobs are completed between the time of you calling this function and inspecting the result.
+ +std::size_t tz::job_worker_count | +( | +) | ++ |
Retrieve the number of worker threads.
+The returned value is unaffected by whether these worker threads are currently carrying out work/are idle. You can assume this number will never change throughout your application's runtime.
+ +using tz::job_function = std::function<void()> | +
Represents a function that will be executed on a job worker via job_execute.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Execute lightweight lua code within the engine.
++Typedefs | |
using | tz::lua_fn = int(*)() |
Represents the signature for a function that can be called from lua. | |
tz::error_code tz::lua_execute_file | +( | +std::filesystem::path | path | ) | ++ |
Attempt to execute a local lua file on the current thread.
+path | Path to a local file containing lua code. |
tz::error_code tz::lua_execute | +( | +std::string_view | lua_src | ) | ++ |
Attempt to execute some lua code on the current thread.
+lua_src | String containing lua code to execute. |
tz::error_code tz::lua_set_nil | +( | +std::string_view | varname | ) | ++ |
Set a variable in lua to be nil.
+varname | Name of the variable to set. |
tz::error_code tz::lua_set_emptytable | +( | +std::string_view | varname | ) | ++ |
Set a variable in lua to be the empty table "{}".
+varname | Name of the variable to set. |
tz::error_code tz::lua_set_bool | +( | +std::string_view | varname, | +
+ | + | bool | v ) | +
Set a variable in lua to a new bool value.
+varname | Name of the variable to set. |
v | Value to set |
tz::error_code tz::lua_set_int | +( | +std::string_view | varname, | +
+ | + | std::int64_t | v ) | +
Set a variable in lua to a new int value.
+varname | Name of the variable to set. |
v | Value to set |
tz::error_code tz::lua_set_number | +( | +std::string_view | varname, | +
+ | + | double | v ) | +
Set a variable in lua to a new number value.
+varname | Name of the variable to set. |
v | Value to set |
tz::error_code tz::lua_set_string | +( | +std::string_view | varname, | +
+ | + | std::string | str ) | +
Set a variable in lua to a new string value.
+varname | Name of the variable to set. |
str | Value to set |
tz::error_code tz::lua_define_function | +( | +std::string_view | varname, | +
+ | + | lua_fn | fn ) | +
Define a new function in lua.
+varname | Name of the function when called in lua code. |
fn | Pointer to an existing function to expose to lua. |
std::expected< bool, tz::error_code > tz::lua_get_bool | +( | +std::string_view | varname | ) | ++ |
Retrieve the value of a bool variable.
+varname | Name of the variable to retrieve. |
std::expected< std::int64_t, tz::error_code > tz::lua_get_int | +( | +std::string_view | varname | ) | ++ |
Retrieve the value of a int variable.
+varname | Name of the variable to retrieve. |
std::expected< double, tz::error_code > tz::lua_get_number | +( | +std::string_view | varname | ) | ++ |
Retrieve the value of a number variable.
+varname | Name of the variable to retrieve. |
std::expected< std::string, tz::error_code > tz::lua_get_string | +( | +std::string_view | varname | ) | ++ |
Retrieve the value of a string variable.
+varname | Name of the variable to retrieve. |
std::expected< bool, tz::error_code > tz::lua_stack_get_bool | +( | +std::size_t | id | ) | ++ |
Retrieve a bool from the stack at the given index.
+id | Position on the stack to retrieve. |
std::expected< std::int64_t, tz::error_code > tz::lua_stack_get_int | +( | +std::size_t | id | ) | ++ |
Retrieve a int from the stack at the given index.
+id | Position on the stack to retrieve. |
std::expected< double, tz::error_code > tz::lua_stack_get_number | +( | +std::size_t | id | ) | ++ |
Retrieve a number from the stack at the given index.
+id | Position on the stack to retrieve. |
std::expected< std::string, tz::error_code > tz::lua_stack_get_string | +( | +std::size_t | id | ) | ++ |
Retrieve a string from the stack at the given index.
+id | Position on the stack to retrieve. |
void tz::lua_push_nil | +( | +) | ++ |
Push a nil value onto the stack.
+ +void tz::lua_push_bool | +( | +bool | v | ) | ++ |
Push a bool value onto the stack.
+ +void tz::lua_push_int | +( | +std::int64_t | v | ) | ++ |
Push an int value onto the stack.
+ +void tz::lua_push_number | +( | +double | v | ) | ++ |
Push a number value onto the stack.
+ +void tz::lua_push_string | +( | +std::string | v | ) | ++ |
Push a string value onto the stack.
+ +std::size_t tz::lua_stack_size | +( | +) | ++ |
Retrieve the number of values on the stack currently.
+ +std::string tz::lua_debug_callstack | +( | +) | ++ |
Retreieve a string describing the lua callstack right now.
+This might be useful for debugging purposes.
+ +std::string tz::lua_debug_stack | +( | +) | ++ |
Retreieve a string describing the entire lua stack right now.
+This might be useful for debugging purposes.
+ +std::tuple< Ts... > tz::lua_parse_args | +( | +) | ++ |
Retreve a set of arguments from the stack.
+using tz::lua_fn = int(*)() | +
Represents the signature for a function that can be called from lua.
+You might be expecting int(lua_State*)
if you're used to using Lua directly. However, lua headers are not available to you, so this is the only signature you will worry about. Like in default lua, the return value of any lua function represents how many values you have returned (put onto the stack). To retrieve an argument in a lua function, you can either:
Example: C function callable in lua:
In your lua code:
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Basic mathematical geometric types.
++Typedefs | |
using | tz::v2i = vector<int, 2> |
2d integer vector. | |
using | tz::v3i = vector<int, 3> |
3d integer vector. | |
using | tz::v4i = vector<int, 4> |
4d integer vector. | |
using | tz::v2u = vector<unsigned int, 2> |
2d unsigned integer vector. | |
using | tz::v3u = vector<unsigned int, 3> |
3d unsigned integer vector. | |
using | tz::v4u = vector<unsigned int, 4> |
4d unsigned integer vector. | |
using | tz::v2f = vector<float, 2> |
2d single-precision floating-point vector. | |
using | tz::v3f = vector<float, 3> |
3d single-precision floating-point vector. | |
using | tz::v4f = vector<float, 4> |
4d single-precision floating-point vector. | |
using | tz::v2d = vector<double, 2> |
2d double-precision floating-point vector. | |
using | tz::v3d = vector<double, 3> |
3d double-precision floating-point vector. | |
using | tz::v4d = vector<double, 4> |
4d double-precision floating-point vector. | |
+Classes | |
struct | tz::vector< T, N > |
Represents the generic vector. More... | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Abstract rendering API for low-level, high-performance 3D desktop graphics.
+This library provides a API to interact with a single desktop GPU, agnostic of whichever graphics API runs under-the-hood (e.g Vulkan/OpenGL/D3D12). When you use this library, the implementation will use one of these graphics APIs (which one is used depends on your platform and is configurable at compile-time) automatically with minimal overhead.
+If you intend to do 3D graphics in Topaz, you should first consult the Rendering Library incase a high-level implementation of what you want to achieve already exists. It is unlikely that the Rendering Library contains all the rendering components you need for a modern game, especially if your game has some more bespoke graphical features or its own unique style. In which case, you should use this library to build your feature from the ground-up.
+The GPU Library works as follows:
An example graph could be comprised of:
The timeline of GPU execution of this graph could look as follows:
+Topics | |
Graphs | |
Documentation for render graphs - describes the execution of Passes. | |
Hardware | |
Documentation specialised for iterating over rendering hardware and selecting one to be used for rendering. | |
Passes | |
Documentation for render/compute passes - each a single node within Graphs. | |
Resources | |
Create/edit/destroy resources (images and buffers). | |
Settings | |
Global settings that affect all passes and graphs. The kind of stuff you'd expect to see in a game's video options. | |
Shaders | |
Create shaders to carry out programmable GPU work. | |
+Typedefs | |
using | tz::gpu::index_t = std::uint32_t |
Represents a single index. Indices are always 32-bit unsigned integers. | |
+Classes | |
struct | tz::gpu::draw_t |
Represents a single unindexed draw-call. More... | |
struct | tz::gpu::draw_indexed_t |
Represents a single indexed draw-call. More... | |
using tz::gpu::index_t = std::uint32_t | +
Represents a single index. Indices are always 32-bit unsigned integers.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Documentation for render graphs - describes the execution of Passes.
++Classes | |
struct | tz::gpu::graph_info |
Specifies creation flags for a new graph. More... | |
struct | tz::gpu::graph_builder |
Helper struct for creating a new graph. Follows the builder pattern. More... | |
std::expected< graph_handle, tz::error_code > tz::gpu::create_graph | +( | +graph_info | graph | ) | ++ |
Create a new graph, which can be used for rendering a frame.
+void tz::gpu::execute | +( | +graph_handle | ) | ++ |
Execute the graph - invoking all passes contained a single time.
+ +enum tz::gpu::graph_flag | +
Specifies optional, extra functionality for a graph.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
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... | |
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.
+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. |
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:
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.
+ +error_code tz::gpu::use_hardware | +( | +hardware | hw | ) | ++ |
Select a piece of hardware to use for future graphical operations.
+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.
+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.
+ +
+
|
+ +strong | +
Describes a specific type of rendering hardware.
+
+
|
+ +strong | +
Describes what kind of GPU operations a rendering hardware can carry out when used.
+
+
|
+ +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. + |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
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... | |
std::expected< pass_handle, tz::error_code > tz::gpu::create_pass | +( | +pass_info | ) | ++ |
Create a new 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.
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.
+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.
void tz::gpu::pass_set_kernel | +( | +pass_handle | compute_pass, | +
+ | + | tz::v3u | kernel ) | +
Set the compute kernel of an existing compute pass.
+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.
void tz::gpu::pass_set_scissor | +( | +pass_handle | graphics_pass, | +
+ | + | tz::v4u | scissor ) | +
Set the scissor rectangle of an existing graphics pass.
+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.
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.
+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.
+ +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.
+using tz::gpu::pass_handle = tz::handle<pass_info> | +
Corresponds to a previously-created pass.
+ +
+
|
+ +strong | +
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. +
|
+
|
+ +strong | +
+
|
+ +constexpr | +
Meta-pass that acts as an action to present the system image to the screen.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
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... | |
std::expected< resource_handle, tz::error_code > tz::gpu::create_buffer | +( | +buffer_info | ) | ++ |
Create a new buffer.
+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.
std::expected< resource_handle, tz::error_code > tz::gpu::create_image | +( | +image_info | ) | ++ |
Create a new image.
+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.
tz::error_code tz::gpu::destroy_resource | +( | +resource_handle | res | ) | ++ |
Manually destroy a resource.
+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.
+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.
+res | Resource whose data should be changed. |
new_data | Region containing new memory for the provided resource. |
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:
std::size_t tz::gpu::resource_size | +( | +resource_handle | res | ) | ++ |
Retrieve the size of a resource's data, in bytes.
+ +unsigned int tz::gpu::image_get_width | +( | +resource_handle | res | ) | ++ |
Retrieve the width of an image resource.
+unsigned int tz::gpu::image_get_height | +( | +resource_handle | res | ) | ++ |
Retrieve the height of an image resource.
+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.
+ +void tz::gpu::buffer_resize | +( | +resource_handle | bufh, | +
+ | + | std::size_t | new_size_bytes ) | +
Resize a buffer resource.
+void tz::gpu::image_resize | +( | +resource_handle | imgh, | +
+ | + | unsigned int | new_width, | +
+ | + | unsigned int | new_height ) | +
Resize an image resource.
+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.
+ +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.
+ +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.
+ +using tz::gpu::resource_handle = tz::handle<buffer_info> | +
Corresponds to a previously-created resource (buffer or image).
+ +enum tz::gpu::buffer_flag | +
Specifies optional behaviours for a buffer.
+
+
|
+ +strong | +
Describes the internal format of an image's data.
+You are not able to choose a specific sized format.
+enum tz::gpu::image_flag | +
+
|
+ +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.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Global settings that affect all passes and graphs. The kind of stuff you'd expect to see in a game's video options.
+bool tz::gpu::settings_get_vsync | +( | +) | ++ |
Query as to whether vsync is enabled.
+By default, vsync is disabled.
+ +void tz::gpu::settings_set_vsync | +( | +bool | enabled | ) | ++ |
Enable/disable vsync.
+By default, vsync is disabled. You should assume that this function will take a significantly long time.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Create shaders to carry out programmable GPU work.
++Typedefs | |
using | tz::gpu::shader_handle = tz::handle<shader_tag_t> |
Corresponds to a previously-created shader program (for graphics or compute). | |
std::expected< shader_handle, tz::error_code > tz::gpu::create_graphics_shader | +( | +std::string_view | vertex_source, | +
+ | + | std::string_view | fragment_source ) | +
Create a new shader intended for graphics GPU work, comprised of a vertex and fragment shader.
+vertex_source | Code for the vertex shader, in SPIRV. |
fragment_source | Code for the fragment shader, in SPIRV. |
std::expected< shader_handle, tz::error_code > tz::gpu::create_compute_shader | +( | +std::string_view | compute_source | ) | ++ |
Create a new shader intended for compute GPU work, comprised of a single compute shader.
+compute_source | Code for the compute shader, in SPIRV. |
void tz::gpu::destroy_shader | +( | +shader_handle | ) | ++ |
Manually destroy a previously-created shader.
+If you are certain that you are done with a shader program, you can destroy it here, causing all of its memory to be available for reuse.
+#define ImportedShaderHeader | +( | +shader_name, | +|
+ | + | shader_type ) | +
Retrieves a file path which is intended to be #included in a application's main source file. Once included, the imported shader's source code can be retrieved as a constexpr string_view via ImportedShaderSource
+ +#define ImportedShaderSource | +( | +shader_name, | +|
+ | + | shader_type ) | +
Retrieves a token representing a std::string_view
which contains the shader's compiled results. On Vulkan, this will be SPIRV, and GLSL source code for OpenGL. You can only retrieve an imported shader's source if the imported header has been included via ImportedShaderHeader
using tz::gpu::shader_handle = tz::handle<shader_tag_t> | +
Corresponds to a previously-created shader program (for graphics or compute).
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
High-level library for wrangling files of various formats.
+This library contains support for a handful of common file formats, allowing you to import them without having to implement a parser yourself.
++Classes | |
struct | tz::io::image_header |
Describes basic information about an image. More... | |
std::expected< image_header, tz::error_code > tz::io::image_info | +( | +std::span< const std::byte > | img_file_data | ) | ++ |
Retrieve info about an image loaded in memory.
+img_file_data | Data read directly from an image file. See below for the list of supported image file formats. |
The image file formats guaranteed are:
Other file formats that aren't listed here might still work, but you should consider anything not on this list an implementation detail that could lose support suddenly in a new release.
+ +tz::error_code tz::io::parse_image | +( | +std::span< const std::byte > | img_file_data, | +
+ | + | std::span< std::byte > | buffer ) | +
Load an image from file data resident in memory.
+img_file_data | Data read directly from an image file. See the detailsof image_info for a list of supported image file formats. |
buffer | A buffer of memory into which decoded image data will be written. It is your responsibility to provide a buffer that is of sufficient size. To decipher the size needed, see image_info. |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Cross-platform API to interact with operating-system level components, such as windowing, hardware input, and machine non-GPU hardware.
++Topics | |
Input System | |
Retrieve keyboard/mouse input. | |
Window System | |
Creating, modifying and destroying OS windows. | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Retrieve keyboard/mouse input.
+tz::error_code tz::os::install_char_typed_callback | +( | +char_type_callback | callback | ) | ++ |
Install a callback which will be invoked whenever the user types a character on the keyboard.
+callback | Pointer to a function which will be called whenever a character is typed. If you pass nullptr, the callback will safely be ignored. |
bool tz::os::is_key_pressed | +( | +key | k | ) | ++ |
Query as to whether a specific key is pressed right now.
+k | Keyboard key to query |
std::pair< unsigned int, unsigned int > tz::os::get_mouse_position | +( | +) | ++ |
Retrieve the mouse cursor's current position, in pixels, relative to the top-left of the window.
+If for whatever reason the cursor pos cannot be retrieved, {-1, -1} is returned. Some reasons could include:
+
|
+ +strong | +
Represents a key on your keyboard.
+ ++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Creating, modifying and destroying OS windows.
++Classes | |
struct | tz::os::window_info |
Basic customisation of a newly-opened window. More... | |
tz::error_code tz::os::open_window | +( | +window_info | winfo | ) | ++ |
Open a new window.
+Only one window can be open at a time - If you have called this function before but have not since closed the previous window, it will automatically be closed.
+ +tz::error_code tz::os::close_window | +( | +) | ++ |
Close a previously-opened window.
+Only one window can be open at a time - If you have called this function before but have not since closed the previous window, it will automatically be closed.
+ +bool tz::os::window_is_open | +( | +) | ++ |
Query as to whether a window has been opened that has not yet been closed.
+void tz::os::window_update | +( | +) | ++ |
Poll updates for a window, advancing input events etc.
+If an open window does not exist, this function safely does nothing.
+ +window_handle tz::os::get_window_handle | +( | +) | ++ |
Retrieve a opaque handle corresponding to the underlying window native.
+HWND
via (HWND)(uintptr_t)handle.peek()
unsigned int tz::os::window_get_width | +( | +) | ++ |
Retrieve the width of the window, in pixels.
+See window_set_dimensions to programatically resize the window.
+ +unsigned int tz::os::window_get_height | +( | +) | ++ |
Retrieve the height of the window, in pixels.
+See window_set_dimensions to programatically resize the window.
+ +void tz::os::window_set_dimensions | +( | +unsigned int | width, | +
+ | + | unsigned int | height ) | +
Set a new width and height for the open window.
+std::string tz::os::window_get_title | +( | +) | ++ |
Retrieve the title of the window.
+void tz::os::window_set_title | +( | +std::string_view | title | ) | ++ |
Set a new title for the open window.
+void tz::os::window_maximise | +( | +) | ++ |
Maximise the window, causing it to cover the whole screen.
+void tz::os::window_minimise | +( | +) | ++ |
Minimise the window, causing it to no longer be visible until maximised/shown.
+void tz::os::window_show | +( | +) | ++ |
Show the window as normal, even if it is currently maximised/minimised/fullscreen.
+void tz::os::window_fullscreen | +( | +) | ++ |
Display the window in proper fullscreen.
+enum tz::os::window_flags | +
Optional behaviours/attributes when opening windows.
+Enumerator | |
---|---|
centered_window | Ignore the x and y coordinates provided within window_info and position the window approximately in the middle of the screen instead. + |
maximised | Ignore the width and height provided within window_info and set set the window as maximised instead. + |
transparent | When a pixel of the window's framebuffer is never drawn to, instead of being a clamped colour it is instead fully transparent. Your mileage may vary, depending on your platform. + |
invisible | When the window is "opened", it is completely invisible to the user. They won't see the window, nor will it be visible in the OS' taskbar. + |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
High-level declarative rendering API built upon the GPU Library.
+This library contains some pre-created high-level rendering systems used for common tasks, such as rendering 3D models, or user interface. These components are intended to be used in most Topaz games, with the goal of not needing to reinvent the wheel in every single game using the Rendering Library.
++Topics | |
Quad Renderer | |
Efficiently render a large number of 2D quads. | |
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Efficiently render a large number of 2D quads.
++Typedefs | |
using | tz::ren::quad_handle = tz::handle<detail::quad_t> |
Represents a single quad. Owned by a quad_renderer_handle. | |
using | tz::ren::quad_renderer_handle = tz::handle<detail::quadren_t> |
Represents a single quad renderer instance. | |
+Classes | |
struct | tz::ren::quad_renderer_info |
Specifies creation flags for a quad renderer. More... | |
struct | tz::ren::quad_info |
Specifies initial data for a single quad. More... | |
std::expected< quad_renderer_handle, tz::error_code > tz::ren::create_quad_renderer | +( | +quad_renderer_info | info | ) | ++ |
Create a new quad renderer.
+tz::error_code tz::ren::destroy_quad_renderer | +( | +quad_renderer_handle | renh | ) | ++ |
Manually destroy a quad renderer.
+std::expected< quad_handle, tz::error_code > tz::ren::quad_renderer_create_quad | +( | +quad_renderer_handle | renh, | +
+ | + | quad_info | info ) | +
Create a new quad to be rendered by an existing quad renderer.
+Next time the quad renderer executes, this new quad will be visible with the info provided.
+ +std::expected< std::uint32_t, tz::error_code > tz::ren::quad_renderer_add_texture | +( | +quad_renderer_handle | renh, | +
+ | + | tz::gpu::resource_handle | image ) | +
Associate an existing image resource with the provided quad renderer, allowing quads to use it as a texture.
+tz::v2f tz::ren::get_quad_position | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad ) | +
Retrieve the position of a quad, in world-space.
+ +void tz::ren::set_quad_position | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad, | +
+ | + | tz::v2f | position ) | +
Set a new position of a quad, in world-space.
+ +tz::v2f tz::ren::get_quad_scale | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad ) | +
Retrieve the scale factor of a quad, in both dimensions.
+ +void tz::ren::set_quad_scale | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad, | +
+ | + | tz::v2f | scale ) | +
Set a new scale factor of a quad, in both dimensions.
+ +tz::v3f tz::ren::get_quad_colour | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad ) | +
Retrieve the colour of a quad.
+See quad_info::colour for more details.
+ +void tz::ren::set_quad_colour | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad, | +
+ | + | tz::v3f | colour ) | +
Set a new colour of a quad.
+See quad_info::colour for more details.
+ +std::uint32_t tz::ren::get_quad_texture | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad ) | +
Retrieve the texture-id currently being used by a quad.
+void tz::ren::set_quad_texture | +( | +quad_renderer_handle | renh, | +
+ | + | quad_handle | quad, | +
+ | + | std::uint32_t | texture_id ) | +
Set a new texture-id to be used by a quad.
+Note: Passing -1 as the texture-id will cause the quad to no longer sample from a texture.
+ +tz::gpu::graph_handle tz::ren::quad_renderer_graph | +( | +quad_renderer_handle | renh | ) | ++ |
Retrieve a graph representing the quad renderer.
+To actually execute a quad renderer, you must retrieve it's graph and pass it to tz::gpu::execute. See Graphs for more info.
+ +void tz::ren::quad_renderer_update | +( | +quad_renderer_handle | renh | ) | ++ |
Update internal state for a quad renderer.
+using tz::ren::quad_handle = tz::handle<detail::quad_t> | +
Represents a single quad. Owned by a quad_renderer_handle.
+ +using tz::ren::quad_renderer_handle = tz::handle<detail::quadren_t> | +
Represents a single quad renderer instance.
+You can have multiple quad renderers at the same time. Any quad_handle retrieved from creating a quad will be owned solely by whichever quad renderer you used to create it.
+ +enum tz::ren::quad_renderer_flag | +
Specifies optional, extra functionality for a quad renderer.
++ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
Topaz is a 3D graphics engine.
Topaz 4.2.0 is the most recent release of the Topaz Engine. The next version is Topaz 5.0, currently in early development on the master branch.
+The Topaz project has been ongoing since it began as a school project in 2015.
+Each major version is a total rewrite and thus completely different from the previous. Each minor version typically consists of API-breaking feature changes. Patch versions are not formally shipped unless they contain emergency bugfixes for a flawed release.
Topaz Version | Release Date | Branch | Documentation |
---|---|---|---|
5.0 | TBD | master | harrand.github.io |
4.2.0 | Apr 23, 2024 | Topaz4.2 | Branch: gh-pages-tz4.2 |
4.1.0 | Dec 1, 2023 | Topaz4.1 | Branch: gh-pages-tz4.1 |
4.0.0 | July 9, 2023 | Topaz4.0 | Branch: gh-pages-tz4.0 |
3.6.1 | Dec 10, 2022 | Topaz3.6 | Branch: gh-pages-tz3.6 |
3.6.0 | Dec 8, 2022 | Topaz3.6 | Branch: gh-pages-tz3.6 |
3.5.0 | Sep 22, 2022 | Topaz3.5 | Branch: gh-pages-tz3.5 |
3.4.0 | Aug 3, 2022 | Topaz3.4 | Branch: gh-pages-tz3.4 |
3.3.0 | Jun 12, 2022 | Topaz3.3 | Branch: gh-pages-tz3.3 |
3.2.0 | Apr 23, 2022 | Topaz3.2 | Branch: gh-pages-tz3.2 |
3.1.0 | Feb 13, 2022 | Topaz3.1 | Branch: gh-pages-tz3.1 |
3.0.0 | Sep 17, 2021 | Topaz3.0 | Branch: gh-pages-tz3 |
2.0.0 | May 9, 2021 | Topaz2.0 | Branch: gh-pages-tz2 |
1.0.0 | Sep 25, 2020 | Topaz1.0 | Branch: gh-pages-tz1 |
Topaz Version | Release Date | Release |
---|---|---|
0.7.0 | Apr 10, 2019 | Raycasts, Octrees & Improved Utility |
0.6.0 | Jul 18, 2018 | Shadow Mapping & Physics |
0.5.1 | Dec 12, 2017 | Refactoring 1 |
0.5.0 | Oct 8, 2017 | Physics & Collision |
0.4.0 | Sep 25, 2017 | Displacement Maps & Skyboxes |
0.3.0 | Sep 21, 2017 | GUI & Flexible |
0.2.0 | Jun 5, 2017 | Prettier, faster and more features |
0.1.6 | Apr 16, 2017 | Skybox & Audio |
0.1.5 | Apr 11, 2017 | Dynamic Lighting |
0.1.4 | Apr 9, 2017 | Audio |
0.1.3 | Mar 29, 2017 | World Construction |
0.1.2 | Mar 25, 2017 | Hightail House Construction |
0.1.1 | Mar 24, 2017 | Parallax Displacement Mapping |
0.1.0 | Mar 21, 2017 | Dev Test |
Configure CMake. It is recommended you use a preset.
+Example: cmake --preset host_vulkan_debug
topaz
target to build the engine. Run the tztest
target to build and run all unit-tests.The table below shows all the engine's dependencies.
+Dependency | Render API | Build Config | Dependency Type |
---|---|---|---|
Vulkan SDK | Vulkan | All | Needs pre-installation |
The following requirements apply for all possible build configurations:
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+
+ |
+ Topaz 5.0
+
+ Topaz Game Engine
+ |
+