Should I ever use a `vec3` inside of a uniform buffer or shader storage buffer object?
NO! Never do this!
When declaring UBOs/SSBOs, pretend that all 3-element vector types don't exist. This includes column-major matrices with 3 rows or row-major matrices with 3 columns. Pretend that the only types are scalars, 2, and 4 element vectors (and matrices). You will save yourself a very great deal of grief if you do so.
If you want the effect of a vec3 + a float, then you should pack it manually:
layout(std140) uniform UBO
{
vec4 data1;
vec4 data2and3;
};
Yes, you'll have to use data2and3.w
to get the other value. Deal with it.
If you want arrays of vec3
s, then make them arrays of vec4
s. Same goes for matrices that use 3-element vectors. Just banish the entire concept of 3-element vectors from your SSBOs/UBOs; you'll be much better off in the long run.
There are two reasons why you should avoid vec3
:
It won't do what C/C++ does
If you use std140
layout, then you will probably want to define data structures in C or C++ that match the definition in GLSL. That makes it easy to mix&match between the two. And std140
layout makes it at least possible to do this in most cases. But its layout rules don't match the usual layout rules for C and C++ compilers when it comes to vec3
s.
Consider the following C++ definitions for a vec3
type:
struct vec3a { float a[3]; };
struct vec3f { float x, y, z; };
Both of these are perfectly legitimate types. The sizeof
and layout of these types will match the size&layout that std140
requires. But it does not match the alignment behavior that std140
imposes.
Consider this:
//GLSL
layout(std140) uniform Block
{
vec3 a;
vec3 b;
} block;
//C++
struct Block_a
{
vec3a a;
vec3a b;
};
struct Block_f
{
vec3f a;
vec3f b;
};
On most C++ compilers, sizeof
for both Block_a
and Block_f
will be 24. Which means that the offsetof
b
will be 12.
In std140 layout however, vec3
is always aligned to 4 words. And therefore, Block.b
will have an offset of 16.
Now, you could try to fix that by using C++11's alignas
functionality (or C11's similar _Alignas
feature):
struct alignas(16) vec3a_16 { float a[3]; };
struct alignas(16) vec3f_16 { float x, y, z; };
struct Block_a
{
vec3a_16 a;
vec3a_16 b;
};
struct Block_f
{
vec3f_16 a;
vec3f_16 b;
};
If the compiler supports 16-byte alignment, this will work. Or at least, it will work in the case of Block_a
and Block_f
.
But it won't work in this case:
//GLSL
layout(std140) Block2
{
vec3 a;
float b;
} block2;
//C++
struct Block2_a
{
vec3a_16 a;
float b;
};
struct Block2_f
{
vec3f_16 a;
float b;
};
By the rules of std140
, each vec3
must start on a 16-byte boundary. But vec3
does not consume 16 bytes of storage; it only consumes 12. And since float
can start on a 4-byte boundary, a vec3
followed by a float
will take up 16 bytes.
But the rules of C++ alignment don't allow such a thing. If a type is aligned to an X byte boundary, then using that type will consume a multiple of X bytes.
So matching std140
's layout requires that you pick a type based on exactly where it is used. If it's followed by a float
, you have to use vec3a
; if it's followed by some type that is more than 4 byte aligned, you have to use vec3a_16
.
Or you can just not use vec3
s in your shaders and avoid all this added complexity.
Note that an alignas(8)
-based vec2
will not have this problem. Nor will C/C++ structs&arrays using the proper alignment specifier (though arrays of smaller types have their own issues). This problem only occurs when using a naked vec3
.
Implementation support is fuzzy
Even if you do everything right, implementations have been known to incorrectly implement vec3
's oddball layout rules. Some implementations effectively impose C++ alignment rules to GLSL. So if you use a vec3
, it treats it like C++ would treat a 16-byte aligned type. On these implementations, a vec3
followed by a float
will work like a vec4
followed by a float
.
Yes, it's the implementers' fault. But since you can't fix the implementation, you have to work around it. And the most reasonable way to do that is to just avoid vec3
altogether.
Note that, for Vulkan (and OpenGL using SPIR-V), the SDK's GLSL compiler gets this right, so you don't need to be worried about it for that.
Nicol Bolas
I am a game developer with a fairly broad knowledgebase in the fields of animation and graphics, with a touch of AI. Projects: A series of tutorials/eBook on graphics programming The Unofficial OpenGL Software Development Kit The OpenGL Loader Generator, a much better alternative to GLEW
Updated on June 06, 2022Comments
-
Nicol Bolas about 2 years
The
vec3
type is a very nice type. It only takes up 3 floats, and I have data that only needs 3 floats. And I want to use one in a structure in a UBO and/or SSBO:layout(std140) uniform UBO { vec4 data1; vec3 data2; float data3; }; layout(std430) buffer SSBO { vec4 data1; vec3 data2; float data3; };
Then, in my C or C++ code, I can do this to create matching data structures:
struct UBO { vector4 data1; vector3 data2; float data3; }; struct SSBO { vector4 data1; vector3 data2; float data3; };
Is this a good idea?
-
ratchet freak almost 8 yearsYou can do your layout manually in glsl though (and will be layed out explicitly in the spir-V that the glsl gets compiled to)
-
Nicol Bolas almost 8 years@ratchetfreak: Yes, with
offset
andalign
, you can do your own layout. What you cannot do is violate the basic layout rules; the GLSL specification is semi-clear on that.offset
cannot place a variable "within the previous member of the block". Now, what makes this "semi-clear" is what "within" means. Does a member take up its base alignment's worth of space, or does it only take up just its own space? With Vulkan, things are equally unclear, as the SPIR-V layout rules say that objects can't overlap (kinda), but again nothing is said about base alignment. -
krOoze almost 8 yearsWell, I recently reverse-engineered it and at least
glslangValidator
packs that tightly in SPIR-V as expected (member offsets 0, 16, 28 respectively). If it's only about alignment, then better example would be vec3 following scalar float. -
Nicol Bolas almost 8 years@krOoze: "at least glslangValidator packs that tightly in SPIR-V as expected (member offsets 0, 16, 28 respectively)." Well that's a bug. KHR_vulkan_glsl does not change the std140 layout rules. So unless you explicitly declare offsets, it must do what the OpenGL standard says.
-
krOoze almost 8 years@NicolBolas Well, there is ambiguity (which I think you would know, since I believe you started GitHub Issue about it). It's more clearly in OGL spec than VK (since it at least defines most of the terms used) I would lean that "basic machine unit consumed by the previous member" there still means 3N B for
vec3
("alignment" should not change that - that's not what the word means). -
krOoze almost 8 years^ Actually notbug'ed here I think: github.com/KhronosGroup/glslang/issues/201
-
Nicol Bolas almost 8 years@krOoze: I've looked over all of this and discovered that you are right. So I've changed the reasoning for avoiding them.
-
AzP over 6 years@NicolBolas, any chance we can get an extension to this post, related to
std430
? -
Nicol Bolas over 6 years@AzP: The only thing
std430
changes about the layout rules is the base alignment for arrays and structs of scalars and two-element vectors. It changes nothing aboutvec3
s, since the base alignment of them is always that of avec4
. -
Philip Guin about 6 yearsImportant thing I learned reading this: The spec allows a
float
to immediately follow avec3
in memory, so that they both take up a total of 16 bytes. This appears to be the main (if not only) distinguishing feature of avec3
vs avec4
, in terms of alignment. I.e. size != base alignment only in case of vectors with three components that also aren't array elements. -
Krupip over 5 yearsDoesn't vec3 + float work in this circumstance in std140, example? Alignment might be 16, but the float is still offset 12 bytes right?
-
Nicol Bolas over 5 years@opa: But it won't work for
vec3 + vec3
. My point is that no single type definition will result in any GLSL struct having the same layout as the C++ equivalent. The goal is to not have to remember the rules, just to copy the GLSL struct and to change the member types to C++ named types. -
Krupip over 5 yearsOkay, I confused your two
vec3
examples andvec3 + float
example my bad. -
Fox1942 about 4 years@NicolBolas You mentioned, that std430 "changes nothing about vec3s, since the base alignment of them is always that of a vec4". In the chosen answer of another question (stackoverflow.com/questions/29531237/…) I read, that in case of std430 "three-component vectors are not rounded up to the size of four-component vectors". I am confused. Are any of the above statements wrong? What am I understanding wrong?
-
Nicol Bolas about 4 years@Tom: All of the examples in that answer are correct, but the text quoted is not from the OpenGL specification; it's from a book. And that quote is incorrect. The specification states that, for std430, the rounding rules for arrays and structs don't apply. But the vec3 issue is not from rounding rules; it's alignment is not based on rounding for arrays and structs. The base alignment of a vec3 is directly specified to be 16 bytes.
-
Kalen over 2 yearsThank you for the informative post here. So little info on vulkan its good to see those with dos and donts