Description

Efficiently render a large number of 2D quads.

Create a quad renderer via create_quad_renderer.
Create a bunch of quads using repeated calls to quad_renderer_create_quad.
Every frame, retrieve the graph via quad_renderer_graph and pass that to tz::gpu::execute to render all the 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...

Function Documentation

◆ create_quad_renderer()

std::expected< quad_renderer_handle, tz::error_code > tz::ren::create_quad_renderer ( quad_renderer_info info )

Create a new quad renderer.

Returns: On success: A quad_renderer_handle corresponding to the newly-created quad renderer.; On failure: Any error returned by the automatic call to create_pass.

◆ destroy_quad_renderer()

tz::error_code tz::ren::destroy_quad_renderer ( quad_renderer_handle renh )

Manually destroy a quad renderer.

Returns: On failure: Any error returned by the automatic calls to destroy_resource.

◆ quad_renderer_create_quad()

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.

Returns: On success, a handle corresponding to the newly created quad.; 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.

◆ quad_renderer_add_texture()

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.

Returns: On success, a integer representing the texture-id corresponding to the image. You can cause a quad to use this texture via set_quad_texture.; On failure: Any error returned by the automatic call to pass_add_image_resource.

◆ get_quad_position()

tz::v2f tz::ren::get_quad_position	(	quad_renderer_handle	renh,
		quad_handle	quad )

Retrieve the position of a quad, in world-space.

◆ set_quad_position()

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.

◆ get_quad_layer()

short tz::ren::get_quad_layer	(	quad_renderer_handle	renh,
		quad_handle	quad )

Get the layer value of a given quad.

Note that layer values only have an effect if layering (see quad_renderer_flag::enable_layering) is enabled.

◆ set_quad_layer()

void tz::ren::set_quad_layer	(	quad_renderer_handle	renh,
		quad_handle	quad,
		short	layer )

Set the layer value of a given quad.

Parameters

layer New layer value. Should be between -100 and 100.

Note that layer values only have an effect if layering (see quad_renderer_flag::enable_layering) is enabled.

◆ get_quad_scale()

tz::v2f tz::ren::get_quad_scale	(	quad_renderer_handle	renh,
		quad_handle	quad )

Retrieve the scale factor of a quad, in both dimensions.

◆ set_quad_scale()

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.

◆ get_quad_colour()

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.

◆ set_quad_colour()

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.

◆ get_quad_texture0()

std::uint32_t tz::ren::get_quad_texture0	(	quad_renderer_handle	renh,
		quad_handle	quad )

Retrieve the first texture-id currently being used by a quad.

Returns: (-1) If the quad was not using a texture.

◆ get_quad_texture1()

std::uint32_t tz::ren::get_quad_texture1	(	quad_renderer_handle	renh,
		quad_handle	quad )

Retrieve the second texture-id currently being used by a quad.

Returns: (-1) If the quad was not using a texture.

◆ set_quad_texture0()

void tz::ren::set_quad_texture0	(	quad_renderer_handle	renh,
		quad_handle	quad,
		std::uint32_t	texture_id )

Set a new first 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.

◆ set_quad_texture1()

void tz::ren::set_quad_texture1	(	quad_renderer_handle	renh,
		quad_handle	quad,
		std::uint32_t	texture_id )

Set a new second 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.

◆ quad_renderer_graph()

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.

◆ quad_renderer_update()

void tz::ren::quad_renderer_update ( quad_renderer_handle renh )

Update internal state for a quad renderer.

This does not render anything.
You should call this every frame, before rendering.

Typedef Documentation

◆ quad_handle

using tz::ren::quad_handle = tz::handle<detail::quad_t>

Represents a single quad. Owned by a quad_renderer_handle.

◆ 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.

Enumeration Type Documentation

◆ quad_renderer_flag

enum tz::ren::quad_renderer_flag : std::int64_t

Specifies optional, extra functionality for a quad renderer.

Enumerator
alpha_clipping	If the alpha-component of any fragment in a quad (after texture sampling) is very low (<0.05f), then that fragment will be discarded.
graph_present_after	Sets tz::gpu::graph_flag::present_after on the graph representing the quad renderer.
allow_negative_scale	Normally if a quad has a negative scale in any dimension, the triangles are no longer in the correct winding order and will thus be invisible. Setting this flags disables face culling, meaning triangles scaled negatively (and thus in the wrong winding order) will still display as normal.
enable_layering	Enables the use of the layer property of a quad. By default, everything is on layer 0. Layer values are between -100 and 100. A quad with a higher layer will be drawn over a quad with a lower layer.
custom_fragment_shader	Enables the use of quad_renderer_info::custom_fragment_shader.