From 4897bbfe04619553327bb0c47b6edd8c22cb7cb1 Mon Sep 17 00:00:00 2001 From: Harrand Date: Sun, 3 Nov 2024 14:52:51 +0000 Subject: [PATCH] [ren] major documentation pass for quad_renderer --- include/tz/gpu/graph.hpp | 4 ++ include/tz/ren/quad.hpp | 125 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 128 insertions(+), 1 deletion(-) diff --git a/include/tz/gpu/graph.hpp b/include/tz/gpu/graph.hpp index f532e73aca..141d7f1abd 100644 --- a/include/tz/gpu/graph.hpp +++ b/include/tz/gpu/graph.hpp @@ -11,6 +11,10 @@ namespace tz::gpu * @brief Documentation for render graphs - describes the execution of @ref tz_gpu_pass. */ + /** + * @ingroup tz_gpu_graph + * @brief Specifies optional, extra functionality for a graph. + */ enum graph_flag { /// After the graph has completed execution, present the system image to the window. diff --git a/include/tz/ren/quad.hpp b/include/tz/ren/quad.hpp index a340aaed54..fe015064ce 100644 --- a/include/tz/ren/quad.hpp +++ b/include/tz/ren/quad.hpp @@ -11,12 +11,39 @@ namespace tz::ren struct quad_t{}; struct quadren_t{}; } + /** + * @ingroup tz_ren + * @defgroup tz_ren_quad Quad Renderer + * @brief Efficiently render a large number of 2D quads. + * + * 1. Create a quad renderer via @ref create_quad_renderer. + * 2. Create a bunch of quads using repeated calls to @ref quad_renderer_create_quad. + * 3. Every frame, retrieve the graph via @ref quad_renderer_graph and pass that to @ref tz::gpu::execute to render all the quads. + */ + + /** + * @ingroup tz_ren_quad + * @brief Represents a single quad. Owned by a @ref quad_renderer_handle. + */ using quad_handle = tz::handle; + /** + * @ingroup tz_ren_quad + * @brief Represents a single quad renderer instance. + * + * You can have multiple quad renderers at the same time. Any @ref quad_handle retrieved from creating a quad will be owned solely by whichever quad renderer you used to create it. + */ using quad_renderer_handle = tz::handle; + /** + * @ingroup tz_ren_quad + * @brief Specifies optional, extra functionality for a quad renderer. + */ enum quad_renderer_flag { + /// If the alpha-component of any fragment in a quad (after texture sampling) is very low (<0.05f), then that fragment will be discarded. alpha_clipping = 0b0001, + /// Sets @ref tz::gpu::graph_flag::present_after on the graph representing the quad renderer. + graph_present_after = 0b0010, }; constexpr quad_renderer_flag operator|(quad_renderer_flag lhs, quad_renderer_flag rhs) @@ -29,41 +56,137 @@ namespace tz::ren return static_cast(lhs) & static_cast(rhs); } + /** + * @ingroup tz_ren_quad + * @brief Specifies creation flags for a quad renderer. + * + * See @ref create_quad_renderer for usage. + */ struct quad_renderer_info { + /// When the main pass is executed, the colour target will be cleared to this colour value. tz::v4f clear_colour = {0.0f, 0.0f, 0.0f, 1.0f}; - quad_renderer_flag flags = static_cast(0); + /// Specifies the colour target to render into. By default, this is the window resource (i.e the quad renderer will draw to the window unless you specify a different colour target). tz::gpu::resource_handle colour_target = tz::gpu::window_resource; + /// Any extra optional flags to specify? + quad_renderer_flag flags = static_cast(0); }; + /** + * @ingroup tz_ren_quad + * @brief Create a new quad renderer. + * @return On success: A @ref quad_renderer_handle corresponding to the newly-created quad renderer. + * @return On failure: Any error returned by the automatic call to @ref create_pass. + */ std::expected create_quad_renderer(quad_renderer_info info); + /** + * @ingroup tz_ren_quad + * @brief Manually destroy a quad renderer. + * @return On failure: Any error returned by the automatic calls to @ref destroy_resource. + */ tz::error_code destroy_quad_renderer(quad_renderer_handle renh); + /** + * @ingroup tz_ren_quad + * @brief Specifies initial data for a single quad. + */ struct quad_info { + /// Position of the quad, in world-space. You can change this later via @ref set_quad_position. tz::v2f position = tz::v2f::zero(); + /// Rotation of the quads, in radians. float rotation = 0.0f; + /// Scale factors of the quad, in both dimensions. You can change this later via @ref set_quad_scale. tz::v2f scale = tz::v2f::filled(1.0f); + /// Texture to display on the quad. Defaults to -1 (no texture). If no texture is used, then the quad will have a solid colour corresponding to @ref colour. You can change this later via @ref set_quad_texture. std::uint32_t texture_id = -1; + /// Colour of the quad. If the quad has no texture, this will be the exact colour of the whole quad. If the quad *does* have a texture, then the sampled texture colour will be multiplied by this value (in which case you will often want to provide {1, 1, 1}). You can change this later via @ref set_quad_colour. tz::v3f colour = tz::v3f::filled(1.0f); }; + + /** + * @ingroup tz_ren_quad + * @brief Create a new quad to be rendered by an existing quad renderer. + * @return On success, a handle corresponding to the newly created quad. + * @return @ref tz::error_code::invalid_value If you provide an invalid texture-id. + * + * Next time the quad renderer executes, this new quad will be visible with the info provided. + */ std::expected quad_renderer_create_quad(quad_renderer_handle renh, quad_info info); + /** + * @ingroup tz_ren_quad + * @brief Associate an existing image resource with the provided quad renderer, allowing quads to use it as a texture. + * @return On success, a integer representing the texture-id corresponding to the image. You can cause a quad to use this texture via @ref set_quad_texture. + * @return On failure: Any error returned by the automatic call to @ref pass_add_image_resource. + */ std::expected quad_renderer_add_texture(quad_renderer_handle renh, tz::gpu::resource_handle image); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the position of a quad, in world-space. + */ tz::v2f get_quad_position(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new position of a quad, in world-space. + */ void set_quad_position(quad_renderer_handle renh, quad_handle quad, tz::v2f position); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the scale factor of a quad, in both dimensions. + */ tz::v2f get_quad_scale(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new scale factor of a quad, in both dimensions. + */ void set_quad_scale(quad_renderer_handle renh, quad_handle quad, tz::v2f scale); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the colour of a quad. + * + * See @ref quad_info::colour for more details. + */ tz::v3f get_quad_colour(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief Set a new colour of a quad. + * + * See @ref quad_info::colour for more details. + */ void set_quad_colour(quad_renderer_handle renh, quad_handle quad, tz::v3f colour); + /** + * @ingroup tz_ren_quad + * @brief Retrieve the texture-id currently being used by a quad. + * @return (-1) If the quad was not using a texture. + */ std::uint32_t get_quad_texture(quad_renderer_handle renh, quad_handle quad); + /** + * @ingroup tz_ren_quad + * @brief 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. + */ void set_quad_texture(quad_renderer_handle renh, quad_handle quad, std::uint32_t texture_id); + /** + * @ingroup tz_ren_quad + * @brief Retrieve a graph representing the quad renderer. + * + * To actually execute a quad renderer, you must retrieve it's graph and pass it to @ref tz::gpu::execute. See @ref tz_gpu_graph for more info. + */ tz::gpu::graph_handle quad_renderer_graph(quad_renderer_handle renh); + /** + * @ingroup tz_ren_quad + * @brief Update internal state for a quad renderer. + * + * - This does *not* render anything. + * - You should call this every frame, before rendering. + */ void quad_renderer_update(quad_renderer_handle renh); }