Buffer Format¶
Description¶
A buffer format is a short string describing the layout of data in a vertex buffer object (VBO).
A VBO often contains a homogeneous array of C-like structures. The buffer
format describes what each element of the array looks like. For example,
a buffer containing an array of high-precision 2D vertex positions might have
the format "2f8"
- each element of the array consists of two floats, each
float being 8 bytes wide, ie. a double.
Buffer formats are used in the Context.vertex_array()
constructor,
as the 2nd component of the content arg. See the Example of simple usage below.
Syntax¶
A buffer format looks like:
[count]type[size] [[count]type[size]...] [/usage]
Where:
count
is an optional integer. If omitted, it defaults to1
.type
is a single character indicating the data type:f
floati
intu
unsigned intx
padding
size
is an optional number of bytes used to store the type. If omitted, it defaults to 4 for numeric types, or to 1 for padding bytes.A format may contain multiple, space-separated
[count]type[size]
triples (See the Example of single interleaved array), followed by:/usage
is optional. It should be preceded by a space, and then consists of a slash followed by a single character, indicating how successive values in the buffer should be passed to the shader:/v
per vertex. Successive values from the buffer are passed to each vertex. This is the default behavior if usage is omitted./i
per instance. Successive values from the buffer are passed to each instance./r
per render. the first buffer value is passed to every vertex of every instance. ie. behaves like a uniform.
When passing multiple VBOs to a VAO, the first one must be of usage
/v
, as shown in the Example of multiple arrays with differing /usage.
Valid combinations of type and size are:
size | ||||
---|---|---|---|---|
type | 1 | 2 | 4 | 8 |
f | Unsigned byte (normalized) | Half float | Float | Double |
i | Byte | Short | Int | - |
u | Unsigned byte | Unsigned short | Unsigned int | - |
x | 1 byte | 2 bytes | 4 bytes | 8 bytes |
The entry f1
has two unusual properties:
- Its type is
f
(for float), but it defines a buffer containing unsigned bytes. For this size of floats only, the values are normalized, ie. unsigned bytes from 0 to 255 in the buffer are converted to float values from 0.0 to 1.0 by the time they reach the vertex shader. This is intended for passing in colors as unsigned bytes. - Three unsigned bytes, with a format of
3f1
, may be assigned to avec3
attribute, as one would expect. But, from ModernGL v6.0, they can alternatively be passed to avec4
attribute. This is intended for passing a buffer of 3-byte RGB values into an attribute which also contains an alpha channel.
There are no size 8 variants for types i
and u
.
This buffer format syntax is specific to ModernGL. As seen in the usage
examples below, the formats sometimes look similar to the format strings passed
to struct.pack
, but that is a different syntax (documented here.)
Buffer formats can represent a wide range of vertex attribute formats.
For rare cases of specialized attribute formats that are not expressible
using buffer formats, there is a VertexArray.bind()
method, to
manually configure the underlying OpenGL binding calls. This is not generally
recommended.
Examples¶
Example buffer formats¶
"2f"
has a count of 2
and a type of f
(float). Hence it describes
two floats, passed to a vertex shader’s vec2
attribute. The size of the
floats is unspecified, so defaults to 4
bytes. The usage of the buffer is
unspecified, so defaults to /v
(vertex), meaning each successive pair of
floats in the array are passed to successive vertices during the render call.
"3i2/i"
means three i
(integers). The size of each integer is 2
bytes, ie. they are shorts, passed to an ivec3
attribute.
The trailing /i
means that consecutive values
in the buffer are passed to successive instances during an instanced render
call. So the same value is passed to every vertex within a particular instance.
Buffers contining interleaved values are represented by multiple space separated count-type-size triples. Hence:
"2f 3u x /v"
means:
2f
: two floats, passed to avec2
attribute, followed by3u
: three unsigned bytes, passed to auvec3
, thenx
: a single byte of padding, for alignment.
The /v
indicates successive elements in the buffer are passed to successive
vertices during the render. This is the default, so the /v
could be
omitted.
Example of simple usage¶
Consider a VBO containing 2D vertex positions, forming a single triangle:
# a 2D triangle (ie. three (x, y) vertices)
verts = [
0.0, 0.9,
-0.5, 0.0,
0.5, 0.0,
]
# pack all six values into a binary array of C-like floats
verts_buffer = struct.pack("6f", *verts)
# put the array into a VBO
vbo = ctx.buffer(verts_buffer)
# use the VBO in a VAO
vao = ctx.vertex_array(
shader_program,
[
(vbo, "2f", "in_vert"), # <---- the "2f" is the buffer format
]
index_buffer_object
)
The line (vbo, "2f", "in_vert")
, known as the VAO content, indicates that
vbo
contains an array of values, each of which consists of two floats.
These values are passed to an in_vert
attribute,
declared in the vertex shader as:
in vec2 in_vert;
The "2f"
format omits a size
component, so the floats default to
4-bytes each. The format also omits the trailing /usage
component, which
defaults to /v
, so successive (x, y) rows from the buffer are passed to
successive vertices during the render call.
Example of single interleaved array¶
A buffer array might contain elements consisting of multiple interleaved values.
For example, consider a buffer array, each element of which contains a 2D vertex position as floats, an RGB color as unsigned ints, and a single byte of padding for alignment:
position | color | padding | |||
x | y | r | g | b | - |
float | float | unsigned byte | unsigned byte | unsigned byte | byte |
Such a buffer, however you choose to contruct it, would then be passed into a VAO using:
vao = ctx.vertex_array(
shader_program,
[
(vbo, "2f 3f1 x", "in_vert", "in_color")
]
index_buffer_object
)
The format starts with 2f
, for the two position floats, which will
be passed to the shader’s in_vert
attribute, declared as:
in vec2 in_vert;
Next, after a space, is 3f1
, for the three color unsigned bytes, which
get normalized to floats by f1
. These floats will be passed to the shader’s
in_color
attribute:
in vec3 in_color;
Finally, the format ends with x
, a single byte of padding, which needs
no shader attribute name.
Example of multiple arrays with differing /usage
¶
To illustrate the trailing /usage
portion, consider rendering a dozen cubes
with instanced rendering. We will use:
vbo_verts_normals
contains vertices (3 floats) and normals (3 floats) for the vertices within a single cube.vbo_offset_orientation
contains offsets (3 floats) and orientations (9 float matrices) that are used to position and orient each cube.vbo_colors
contains colors (3 floats). In this example, there is only one color in the buffer, that will be used for every vertex of every cube.
Our shader will take all the above values as attributes.
We bind the above VBOs in a single VAO, to prepare for an instanced rendering call:
vao = ctx.vertex_array(
shader_program,
[
(vbo_verts_normals, "3f 3f /v", "in_vert", "in_norm"),
(vbo_offset_orientation, "3f 9f /i", "in_offset", "in_orientation"),
(vbo_colors, "3f /r", "in_color"),
]
index_buffer_object
)
So, the vertices and normals, using /v
, are passed to each vertex within
an instance. This fulfills the rule tha the first VBO in a VAO must have usage
/v
. These are passed to vertex attributes as:
in vec3 in_vert;
in vec3 in_norm;
The offsets and orientations pass the same value to each vertex within an instance, but then pass the next value in the buffer to the vertices of the next instance. Passed as:
in vec3 in_offset;
in mat3 in_orientation;
The single color is passed to every vertex of every instance.
If we had stored the color with /v
or /i
, then we would have had to
store duplicate identical color values in vbo_colors - one per instance or
one per vertex. To render all our cubes in a single color, this is needless
duplication. Using /r
, only one color is require the buffer, and it is
passed to every vertex of every instance for the whole render call:
in vec3 in_color;
An alternative approach would be to pass in the color as a uniform, since it is constant. But doing it as an attribute is more flexible. It allows us to reuse the same shader program, bound to a different buffer, to pass in color data which varies per instance, or per vertex.