[ren] major documentation pass for quad_renderer

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.

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<detail::quad_t>;
+	/**
+	 * @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<detail::quadren_t>;
 
+	/**
+	 * @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<int>(lhs) & static_cast<int>(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<quad_renderer_flag>(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<quad_renderer_flag>(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<quad_renderer_handle, tz::error_code> 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_handle, tz::error_code> 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<std::uint32_t, tz::error_code> 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);
 }