VertexAttributeDescriptor

Description

Information about a single VertexAttribute of a Mesh vertex.

Mesh vertex data comprised of different Vertex Attributes. For example, a vertex can include a Position, Normal, TexCoord0, and Color. Meshes usually use a known format for data layout, for example, a position is most often a 3-component float vector (Vector3), but you can also specify non-standard data formats and their layout for a Mesh.

You can use VertexAttributeDescriptor to specify custom mesh data layout in Mesh.SetVertexBufferParams.

Vertex data is laid out in separate "streams" (each stream goes into a separate vertex buffer in the underlying graphics API). While Unity supports up to 4 vertex streams, most meshes use just one. Separate streams are most useful when some vertex attributes don't need to be processed.

For a mesh to be compatible with a SkinnedMeshRenderer, it must have multiple vertex streams: one for deformed data (positions, normals, tangents), one for static data (colors and texture coordinates), and one for skinning data (blend weights and blend indices).

Within each stream, attributes of a vertex are laid out one after another, in this order: VertexAttribute.Position, VertexAttribute.Normal, VertexAttribute.Tangent, VertexAttribute.Color, VertexAttribute.TexCoord0, ..., VertexAttribute.TexCoord7, VertexAttribute.BlendWeight, VertexAttribute.BlendIndices.

Not all format and dimension combinations are valid. Specifically, the data size of a vertex attribute must be a multiple of 4 bytes. For example, a VertexAttributeFormat.Float16 format with dimension 3 is not valid. Additional resources: SystemInfo.SupportsVertexAttributeFormat.

var mesh = new Mesh();
// specify vertex layout with:
// - floating point positions,
// - half-precision (FP16) normals with two components,
// - low precision (UNorm8) tangents
var layout = new[]
{
    new VertexAttributeDescriptor(VertexAttribute.Position, VertexAttributeFormat.Float32, 3),
    new VertexAttributeDescriptor(VertexAttribute.Normal, VertexAttributeFormat.Float16, 2),
    new VertexAttributeDescriptor(VertexAttribute.Tangent, VertexAttributeFormat.UNorm8, 4),
};
var vertexCount = 10;
mesh.SetVertexBufferParams(vertexCount, layout);

A C# struct (for use with Mesh.SetVertexBufferData) matching this vertex layout could look like this:

[System.Runtime.InteropServices.StructLayout(System.Runtime.InteropServices.LayoutKind.Sequential)]
struct ExampleVertex
{
    public Vector3 pos;
    public ushort normalX, normalY;
    public Color32 tangent;
}

Additional resources: Mesh.SetVertexBufferParams, Mesh.SetVertexBufferData, Mesh.GetVertexAttributes.

Properties

Constructors