Topaz 4.2.0

TODO: Document changes ;)

Full Changelog: 4.1.0...4.2.0

Topaz 4.1.0

Topaz 4.1 brings some new major features and enhancements to Topaz.

Topaz Core (tz::core)

• Added tz::vecXus - a vector for unsigned shorts.
• Added tz::trs, a non-matrix representation of a transform in 3D space (TRS => translate, rotate, scale).
• Added tz::transform_hierarchy, which is a representation of a hierarchy of nodes within 3D space, with a customiseable payload.
• New job system backend. Uses a blockingconcurrentqueue under-the-hood aswell as condition variables, as opposed to the previous implementation which uses a non-blocking concurrentqueue and used sleeps to mitigate CPU spinning. Thread sleeps are really dreadful, because you sleep for at least what you specify, which could be way, way more than what you bargained for. When blocking for a job, the previous implementation could block for some fixed value (~16ms, an entire frame budget) just because a job took upwards of 1ms. Now, this is all mitigated and its a large upgrade.
• Added datastore. A datastore is a large container of values of differing types. Datastore values can be:
  • null (nullptr)
  • bool
  • float
  • double
  • int
  • unsigned int
  • std::string
• The datastore has a bit of latency on reads/writes, but is completely thread-safe. You can write from any worker thread, read from any worker thread and its entirely fine. This makes it ideal if jobs are currently spawning which need read/write access to shared data.

Topaz Lua (tz::lua)

• Created! Allow your game code to run in Lua aswell as C++. The lua binding is very barebones, and is thus close-to-the-metal. Each worker thread has its own lua state.
• It is not sensible to go over all lua features here, it will be provided in future documentation & wiki entries.

Topaz Rendering Library (tz::ren)

• Created!
• Whereas tz::gl is a low-level graphics API wrapped around vulkan/opengl, tz::ren provides high-level renderer classes for common use-cases
• Added tz::ren::mesh_renderer, a high-level renderer class to draw static 3d meshes.
• Added tz::ren::animation-renderer, a high-level renderer class to draw animated 3d models via GLTF.

Topaz Debug UI Library (tz::dbgui)

• Added lua console. Allows you to run lua code arbitrarily at runtime. Any code you ran has its output printed within the console.

Topaz Window System Integration (tz::wsi)

• Added tz::window::request_close to programatically request a window to close.

Topaz IO Library (tz::io)

• GLTF now fully supports animated 3D models via scenes, nodes and skins.

**Full Changelog**: https://github.com/harrand/Topaz/compare/4.0.0...4.1.0

Topaz 4.0.0

Topaz 4.0 brings many major API breaking changes, although the least breaking changes between any major release. Unlike 1 -> 2 and 2 -> 3, this is not a complete rewrite, but a major refactor and introduction of a few new core feature.

Notable Changes

• Coding style change: Classes and structs (i.e types) are no longer PascalCase, they are all snake_case. All public API types have been refactored accordingly. This means any project against Topaz 3.6.1 or earlier will require major refactoring fixes to move to Topaz 4.0.0. See the range of commits starting at de62eb7

Topaz Core (tz::core)

• HDK has been removed as a submodule, and all its major features have made its way into tz::core in various ways.
• Win32: Fixed an issue where if the mouse cursor left the window region while a button press/release was occurring, the behaviour would be erratic. 18c209d
• Win32: Fixed an issue where tz::window()::set_dimensions(tz::vec2ui) would treat its parameter as the full window dimensions, including border. This was different to what tz::window().get_dimensions() returned - the dimensions of the client window rectangle. Now, both deal with the client rect. 4562e48
• Added tz::delay::elapsed() which returns the time elapsed since the delay object was created. c7129ac
• Added tz::begin_frame() and tz::end_frame(), which you are now expected to invoke at the beginning and end of your main application loop respectively.
• tz::static_for now works as expected at compile-time. 25972b0

Topaz Graphics Library (tz::gl)

Major

• Draw Indirect Count support has been added, allowing true GPU-driven-rendering. Notable features include:
  • TZSL input variable in::draw_id which represents the GLSL gl_DrawID built-in variable. 65e3e08
  • Added tz::gl::renderer_option::draw_indirect_count, which indicates that the draw-indirect buffer of a renderer is assumed to contain a std::uint32_t value representing the draw count at the beginning of the buffer data. The rest of the buffer data should start at the byte after that value, essentially being shifted forward 4 bytes. 330133b
• Vulkan: The vulkan renderer has been mostly rewritten. Aswell as vastly improved performance/maintainability, Some new features include:
  • Timeline Semaphore support. c146f3b
  • Dynamic Rendering support. 63e05df
• Added support for render graphs and render scheduling. See tz::gl::get_device().render_graph(). A render graph is composed of a timeline, representing the basic order of execution for all mainline renderers, and a set of dependencies for each renderer. If Renderer A has a dependency on Renderer B, that means a timeline semaphore will ensure that the GPU work for Renderer A does not begin until the GPU work for Renderer B is complete.

Moderate

• Vulkan: Added support for timeline semaphores. c146f3b
• tz::gl::renderer::render(tri_count : std::size_t) no longer exists. Instead, the tri_count can be set initially in tz::gl::renderer_info::state().graphics.tri_count, and changed at a later date using a renderer edit. d1c6540
• You are no longer expected to invoke tz::gl::renderer::render(...). Instead, you should populate the timeline and dependency graph via tz::gl::get_device().render_graph() and then invoke a new render on the device directly, e.g tz::gl::get_device().render().

Minor

• OpenGL: Fixed an issue where an OGL renderer would present to the screen even if its renderer output was an offscreen image. 4c88695
• Added tz::gl::device::full_wait() and tz::gl::device::frame_wait(). A full wait blocks the current thread until all scheduled GPU work has been completed, and frame wait blocks the current thread until all scheduled GPU work from the previous thread has been completed.

Topaz Debug UI Library (tz::dbgui)

• Added game bar, allowing applications to specify their own dbgui game bar at the bottom of the screen on debug builds. 905acc6

Topaz Window System Integration (tz::wsi)

• Created!
• Entirely replaces GLFW, and ships with a Win32 or X11 backend for windowing, mouse and keyboard input.
• This work was initially made into a new Tangle repository, but ultimately the code made its way into tz::wsi instead of a submodule.

Topaz IO Library (tz::io)

• Created!
• Mainly right now, is for loading and importing data in various formats.
• Supports loading images from memory or files, and retrieving the image data and dimensions. See tz::io::image in e26a4af. Note that tz::io::image only supports RGBA32_UNorm.
• Supports loading GLTF files through the GLB binary format, using tz::io::gltf. See the commit range around 2c755c9 for more info.

Demos and Tests

• Added tz_mesh_demo, a demo which loads in a GLTF model (GLB) and then displays it in 3d using some basic lighting and shading.

**Full Changelog**: https://github.com/harrand/Topaz/compare/3.6.1...4.0.0

Topaz 3.6.1

Note: Due to an unforseen, serious breakage in Topaz 3.6.0, this release entirely supercedes Topaz 3.6.0. The former is no longer available, however all the change-notes are the same.
Note: This release contains an extremely large amount of API-breaking changes. Expect a larger-than-usual amount of maintenance if updating an existing codebase to this engine version.

Big changes:

• API Change: ImageResource creation has been refactored. See f0ee3d5 for details.
• API Change: BufferResource creation has been refactored. See 25bd29e for details.
• Added ResourceFlags for image filtering and wrapping support:
  • ImageFilterNearest, ImageFilterLinear, ImageMipNearest, ImageMipLinear. More details in 318d168
  • ImageWrapClampEdge, ImageWrapRepeat, ImageWrapMirroredRepeat. More details in a835fb9
• API Change: Devices now store renderers, instead of the user creating renderer objects directly. This completely transforms the lifetime semantics for renderers, and you no longer need to worry about it. Details in 1055a77, but look through documentation for new API usage. I'm afraid this will break alot of existing game code.
• Added ImageFormats RGBA128_SFloat and RGBA64_SFloat. HDR support.
• API Change: Renderer resource references are now more explicit, and is done by a new RenderInfo::ref_resource function. See a7f8fa5 for details and new API usage within documentation.
• Added support for Draw Indirect Buffers and gpu-driven-rendering.
  • Draw commands can be found in a new tz/gl/draw.hpp header, namely tz::gl::DrawIndirectCommand and tz::gl::DrawIndexedIndirectCommand.
  • TZSL also has a new standard library header, containing tz::draw::DrawIndirectCommand and tz::draw::DrawIndexedIndirectCommand to be used for read/writes to indirect buffer resources within shaders.
• Major API Changes: HDK integration. Lots of core functionality has been removed and the HDK library has been added instead. In reality, almost all of the removed functionality exists with the exact same API within hdk, only the namespace is hdk instead of tz. HDK also now exists within the Topaz documentation.
• Added a job system via HDK. See HDK documentation for more info and usage. Right now it's currently not used by any engine feature/test/demo, although dbgui does display the current number of jobs within the job system.
• Added a new RenderState class, which exists within RendererInfo and Renderer. This is where buffer handles for the index buffer and draw indirect buffer live, aswell as triangle count, clear colour, compute kernel etc... It is mutable only within RendererInfo, although there are plans to be able to modify a Renderer's RenderState via a new RendererEdit.

Medium changes:

• Added tz_bloom_demo
• Fixed a bug where multiple-render-targets would not function correctly on OpenGL builds.
• Added a basic dbgui menu item for the window, although it's very barebones.
• Added some detailed dbgui for the tz::gl Device and all renderers you create.

Small changes:

• Improved some lifetime semantics regarding ImageResource and BufferResource objects. Previously, these objects lifetimes needed to last until any Renderer created with them inside a RendererInfo was created. Now, the RendererInfo object deep-copies the resource information, so these objects can now die as soon as they're specified with add_resource. Note that the behaviour regarding add_component is unchanged.
• Improved support for running vulkan_debug builds if no vulkan SDK is installed. It is not well-tested, but it should simply fail to initialise validation layers, and try again to succeed without them. This does obviously however disable a bunch of debug-checks.
• Dbgui has received some profiling instrumentation

Topaz 3.5

Big changes:

• ImGui integration via a new tz::dbgui module. Debug ui exists and is documented, but is entirely compiled out if !TZ_DEBUG (aka non debug builds)
• A new global device is available, with the new tz::gl::device() from gl/api/device.hpp. You should no longer create tz::gl::Device instances yourself, always use the global device. All tests/demos have been updated to use this new API, and the old behaviour has been removed and is no longer supported.

Medium changes:

• Added RendererEdit::ResourceWrite. This allows you to write a span of bytes to an existing resource. This works for images and buffers of any access specifier, meaning it's always available. Note that for dynamic resources this is not recommended because the data can be written to already using the resource span. This is new tested properly in tz_renderer_test.
• tz::MouseButtonState contains a new get_scroll_offset() variable. You can use this to detect scrolling of the mouse wheel. This is used internally by dbgui.
• tz::gl::RendererOption::BlockingCompute has been renamed to RenderWait
  • It also now works for both compute and graphics renderers. Previously it only had an affect on compute renderers.
• Added a new tz::gl::ViewportRegion and tz::gl::ScissorRegion, which are included in an IOutput. You can use this to set viewport and scissor rectangles during rendering. Dbgui uses this internally.
• CMake: add_app now allows you to specify a CUSTOM_ICON, which will set the icon of a release executable on windows. This is not yet implemented for linux however. If no custom icon is set, the topaz logo is used for the icon instead on release builds.
• Minor refactoring of RendererEdit and its inner structs. Documentation has been updated so you can use that if you need details. However, tz::gl::RendererEditBuilder continues to be the recommendation , instead of filling the internal structs yourself.

Small changes:

• Fixed an issue where RendererOption::RenderWait (BlockingCompute) would happen after presentation instead of beforehand.
• ImageResources are now available on OGL builds without bindless textures enabled. It is still however not recommended for use, due to poor performance and lack of testing coverage (it may well be broken).
• Added a remove method for tz::EnumField, also an operator|= overload for another EnumField.
• std::hash specialisation for tz::Vector<T, S>. This includes tz::Vec2 etc...

Topaz 3.4

Big changes:

• Include paths for all headers has been changed to prepend "tz/".
  • Example: "src/core/tz.hpp" -> "tz/src/core/tz.hpp"
• Topaz now uses the depth range [0, 1] (like Vulkan). Previously it used [-1, 1] (like OGL).
  • tz_dynamic_triangle_demo has been changed to account for this, as it yielded a visible change. This may produce visual differences in applications, so you should make sure to account for this.

Medium changes:

• A new RendererOption::NoClearOutput has been added.
  • If two renderers are invoked every frame, the second renderer to be invoked might want this flag if it wants to draw/read from the output image/depth-buffer from the results of the first renderer.
  • In this scenario, the first renderer will also want to use RendererOption::NoPresent.
• A new RendererOption::NoPresent has been added.
  • If a renderer is invoked with this option enabled, the scheduled GPU work is done as normal, but nothing will be presented to the screen, even if you're drawing directly into a window. This has no effect if the renderer output is an image and not a window. This also has no effect if the renderer does compute work.
• Debug names have been implemented. You can set a debug name for a Renderer via RendererInfo::debug_name(name) and retrieve it via RendererInfo::debug_get_name(). This will be visible from vulkan validation layers, OGL error callbacks and debugging tools such as RenderDoc. By default, renderers have a debug name describing their basic anatomy (output type, resource counts and whether its compute, etc...)
  • All debug naming functionality is stubbed out on non-debug builds.
• TZSL
  • TZSL standard library functionality is now fully documented. You will notice a new module in the doxygen module list.
  • tz_printf has been replaced with tz::debug::printf which is available in the new standard library header.
  • tz::debug::assert has been added, which will tz_assert on the given condition through the shader. Note that the number of times this can be invoked is very limited, so be very careful about using this on a shader with many invocations in a single render invocation.

Minor changes/bugfixes:

• Fixed a bug OGL-side where tz::window().update() would present to the screen, and not the renderers. This changed so that all renderers always present if they're drawing into the window, unless RendererOption::NoPresent is specified. This now matches the VK behaviour.
• Added tz:;gl::RendererEditBuilder. This is a helper class using the builder pattern which you should use to compile renderer edits, instead of painstakingly filling a massive tz::gl::RendererEditRequest struct. You're still free to fill the struct yourself, but it is recommended to always use the builder instead.
• CI
  • Vastly simplified github workflows logic for code builds.

Topaz 3.3

• The following shader types have been added:
  • Compute Shader
  • Tessellation Control Shader
  • Tessellation Evaluation Shader
• Wireframe mode is now supported. By default it is disabled, but it can be enabled with a new renderer edit.
• Refactor of TZSLC and various improvements and language features.
  • Namely, TZSL now ships with a standard library!
• TZSLC no longer links against Topaz.
• textc has been removed, and re-added as a separate repository submodule.
• Renderer outputs have now been properly implemented. You can set the renderer output to an image output which can render into an existing image components. This allows a renderer to use the result of another.
• Added following functionality to Renderer edits:
  • Compute Edits, allowing you to set the compute kernel dimensions on-demand
  • Renderer State Edits, allowing you to set some renderer state on-demand.
    • At present, this only includes the ability to toggle wireframe mode rendering.
• Added the following demos:
  • tz_blur_triangle_demo. Draws a single triangle, but blurs it so it looks like two. This is achieved by setting the output of a Renderer to an image component, and then performing post-processing in a second renderer.
  • tz_compute_demo. Contains a buffer resource which a compute shader constantly changes. The buffer data is used to set the colour of each window pixel.
  • tz_terrain_demo. Renders a pretty, low-poly terrain with a single 4-triangle draw-call. This is achieved by using the new tessellation shaders.

Topaz 3.2

Notable features:

• Various VK bugfixes.
• Renderer edits, allows you to resize a buffer or image resource on-demand if its variadic.
• A better-than-ever tz_dynamic_triangle_demo.
• Much better looking documentation.

Topaz 3.1

Notable features:

• Rewrite of vulkan frontend and backend. Vastly improved maintainability of vulkan codebase, and improved performance.
• More intuitive renderer and resource APIs

Topaz 3.0

Complete rewrite. Utterly different from Topaz 2.0.

Notable features:

• Support for Vulkan aswell as OpenGL.
• Vastly simplified API usage.
• Dramatically increased performance