Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Better Documentation for Structured Uniforms #10759
Description of the problem
By structured uniform, I mean a uniform of the form:
Currently, the uniform documentation only states that
but doesn't go into further detail on how to set such uniforms using three.js. I had to figure out the proper syntax by stepping through the source code. For future reference, the syntax is:
This old issue thread is the only reference I could find on structured uniforms in three.js. Moreover, said issue doesn't conclude on a single syntax (nor is the correct syntax even mentioned).
It would be nice to have this topic covered in the official documentation. Just like there already is a nice example of regular (non-structured) uniform usage.
Hardware Requirements (graphics card, VR Device, ...)
Sure. I understood how we can pass a set of uniforms as a struct to a shader from the first comment, but I don't know how I can pass an array of a struct. For example, I would like to pass an array of
Would you provide an example of how I can pass actual values to
I was finally able to find a way by myself. For example,
worked to parse an array of structured uniforms to a shader. I can add it to the documentation if it is appropriate.
I am also thinking that it would be great to have this functionality to
@hayatoikoma I think it would be sufficient to add an example of passing a struct, and an example of passing an array of structs, to https://threejs.org/docs/?q=unifor#Reference/Core/Uniform.
Thanks for the ping, Ben!
The docs on structured uniforms (including multidimensional arrays) read:
And some types are marked with
This is rather detailed.
Put bluntly, you either have to go "completely high level" or "flat" for the innermost array (where a one-dimensional array is always "innermost" - the "flat" way is a direct pass-through to WebGL / OpenGL ES2, see specs for details).
The rest is just like you'd expect: Structure members are mapped to object properties (which is pretty much the JS equivalent) and arrays to arrays. Wouldn't hurt to state that explicitly, I guess, but since there are no restrictions except those imposed by GLSL, there's really not much more to say about it.
I understood that the description describes every types supported in Three.js, but I guess it would be more informative to write some examples as I couldn't figure it out easily. As a matter of fact, the only example I found for an array of structured uniforms in
So, is it safe to provide example like the following code?
What would happen if some of the elements does not have the same properties? As I still have questions on the behaviors and don't understand the implementation details, I may not be qualified to write more examples...
Yes, that's basically how it works.
I don't remember - it's not a good idea on the JS end (heterogeneous arrays poison JIT compilation) and diversity of that kind lets suspect a chaotic programming style, so I wouldn't promote it in the docs and, due to the performance critical nature of uniform upload with WebGL (version 1), it's probably best left undefined behavior.
Actually, I never indented this interface to be the final thing, since uniforms do not belong onto a scene graph. Similarly, materials are not the same as shaders. Instead the data that goes into a uniform is either the property of an object or its associated material, or something managed by the renderer (e.g. camera or lights that can reach the object). A custom shader would declare those bindings, but not the associated data. Multiple materials can share the same shader, while the renderer would manage its multiple instances that need to be compiled for everything to just work.