Module luminance::tess

Expand description

Vertex sets.

Tess is a type that represents the gathering of vertices and the way to connect / link them. A Tess has several intrinsic properties:

Its primitive mode — Mode. That object tells the GPU how to connect the vertices.
A default number of vertex to render. When passing the Tess to the GPU for rendering, it’s possible to specify the number of vertices to render or just let the Tess render a default number of vertices (typically, the whole Tess).
A default number of instances, which allows for geometry instancing. Geometry instancing is the fact of drawing with the same Tess several times, only changing the instance index every time a new render is performed. This is done entirely on the backend to prevent bandwidth exhaustion. The index of the instance, in the shader stages, is often used to pick material properties, matrices, etc. to customize each instances. Instances can manually be asked when using a TessView.
An indexed configuration, allowing to tell the GPU how to render the vertices by referring to them via indices.
For indexed configuration, an optional primitive restart index can be specified. That index, when present in the indexed set, will make some primitive modes “restart” and create new primitives. More on this on the documentation of Mode.

Tessellation creation

Tess is not created directly. Instead, you need to use a TessBuilder. Tessellation builders make it easy to customize what a Tess will be made of before actually requesting the GPU to create them. They support a large number of possible situations:

Attributeless: when you only specify the Mode and number of vertices to render (and optionally the number of instances). That will create a vertex set with no vertex data. Your vertex shader will be responsible for creating the vertex attributes on the fly.
Direct geometry: when you pass vertices directly.
Indexed geometry: when you pass vertices and reference from with indices.
Instanced geometry: when you ask to use instances, making the graphics pipeline create several instances of your vertex set on the GPU.

Tessellation views

Once you have a Tess — created from TessBuilder::build, you can now render it in a TessGate. In order to do so, you need a TessView.

A TessView is a temporary view into a Tess, describing what part of it should be drawn. It is also responsible in providing the number of instances to draw. Creating TessViews is a cheap operation, and can be done in two different ways:

By directly using the methods from TessView.
By using the View trait.

The View trait is a convenient way to create TessView. It provides the View::view and View::inst_view (for instanced rendering) methods, which accept Rust’s range operators to create the TessViews in a more comfortable way.

Tessellation mapping

Sometimes, you will want to edit tessellations in a dynamic way instead of re-creating new ones. That can be useful for streaming data of for using a small part of a big Tess. The Tess type has several methods to obtain subparts, allow you to map values and iterate over them via standard Rust slices. See these for further details:

Tess::vertices Tess::vertices_mut to map tessellations’ vertices.
Tess::indices Tess::indices_mut to map tessellations’ indices.
Tess::instances Tess::instances_mut to map tessellations’ instances.

Note: because of their slice nature, mapping a tessellation (vertices, indices or instances) will not help you with resizing a Tess, as this is not currently supported. Creating a large enough Tess is preferable for now.