Should I ever use a `vec3` inside of a uniform buffer or shader storage buffer object?

11,568

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 vec3s, then make them arrays of vec4s. 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 vec3s.

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

Share:
11,568
Nicol Bolas
Author by

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, 2022

Comments

  • Nicol Bolas
    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
    ratchet freak almost 8 years
    You 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
    Nicol Bolas almost 8 years
    @ratchetfreak: Yes, with offset and align, 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
    krOoze almost 8 years
    Well, 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
    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
    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
    krOoze almost 8 years
    ^ Actually notbug'ed here I think: github.com/KhronosGroup/glslang/issues/201
  • Nicol Bolas
    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
    AzP over 6 years
    @NicolBolas, any chance we can get an extension to this post, related to std430?
  • Nicol Bolas
    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 about vec3s, since the base alignment of them is always that of a vec4.
  • Philip Guin
    Philip Guin about 6 years
    Important thing I learned reading this: The spec allows a float to immediately follow a vec3 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 a vec3 vs a vec4, in terms of alignment. I.e. size != base alignment only in case of vectors with three components that also aren't array elements.
  • Krupip
    Krupip over 5 years
    Doesn'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
    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
    Krupip over 5 years
    Okay, I confused your two vec3 examples and vec3 + float example my bad.
  • Fox1942
    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
    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
    Kalen over 2 years
    Thank you for the informative post here. So little info on vulkan its good to see those with dos and donts