Chapter 786: UniformsGroup

Core Idea

A class for managing multiple uniforms in a single group. The renderer will process such a definition as a single UBO.

Since this class can only be used in context of ShaderMaterial, it is only supported in WebGLRenderer.

Key Concepts

• buffer : Float32Array: A Float32 array buffer with the uniform values.
• byteLength : number: The byte length of the buffer with correct buffer alignment.
• id : number (readonly): The ID of the 3D object.
• isUniformsGroup : boolean (readonly): This flag can be used for type testing.
• isUniformsGroup : boolean (readonly): This flag can be used for type testing.
• name : string: The name of the uniforms group.
• uniforms : Array.<Uniform>: An array holding the uniforms.
• uniforms : Array.<Uniform>: An array of uniform objects.
• usage : StaticDrawUsage | DynamicDrawUsage | StreamDrawUsage | StaticReadUsage | DynamicReadUsage | StreamReadUsage | StaticCopyUsage | DynamicCopyUsage | StreamCopyUsage: The buffer usage.
• values : Array.<number>: An array with the raw uniform values.

Reference Tables

Constructor

Signature
new UniformsGroup()

Properties

Property	Description
.buffer : Float32Array	A Float32 array buffer with the uniform values.
.byteLength : number	The byte length of the buffer with correct buffer alignment.
.id : number (readonly)	The ID of the 3D object.
.isUniformsGroup : boolean (readonly)	This flag can be used for type testing.
.isUniformsGroup : boolean (readonly)	This flag can be used for type testing.
.name : string	The name of the uniforms group.
.uniforms : Array.<Uniform>	An array holding the uniforms.
.uniforms : Array.<Uniform>	An array of uniform objects.
`.usage : StaticDrawUsage	DynamicDrawUsage
.values : Array.<number>	An array with the raw uniform values.

Methods

Method	Description
.add( uniform : Uniform ) : UniformsGroup	Adds the given uniform to this uniforms group.
.addUniform( uniform : Uniform ) : UniformsGroup	Adds a uniform to this group.
.addUniformUpdateRange( uniform : Uniform )	Adds a uniform's update range to this buffer.
.clearUpdateRanges()	Clears all update ranges of this buffer.
.clone() : UniformsGroup	Returns a new uniforms group with copied values from this instance.
.copy( source : UniformsGroup ) : UniformsGroup	Copies the values of the given uniforms group to this instance.
.dispose()	Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
.release()	Releases the buffer.
.remove( uniform : Uniform ) : UniformsGroup	Removes the given uniform from this uniforms group.
.removeUniform( uniform : Uniform ) : UniformsGroup	Removes a uniform from this group.
.setName( name : string ) : UniformsGroup	Sets the name of this uniforms group.
`.setUsage( value : StaticDrawUsage	DynamicDrawUsage
.update() : boolean	Updates this group by updating each uniform object of the internal uniform list. The uniform objects check if their values has actually changed so this method only returns true if there is a real v…
.updateByType( uniform : Uniform ) : boolean	Updates a given uniform by calling an update method matching the uniforms type.
.updateColor( uniform : ColorUniform ) : boolean	Updates a given Color uniform.
.updateMatrix3( uniform : Matrix3Uniform ) : boolean	Updates a given Matrix3 uniform.
.updateMatrix4( uniform : Matrix4Uniform ) : boolean	Updates a given Matrix4 uniform.
.updateNumber( uniform : NumberUniform ) : boolean	Updates a given Number uniform.
.updateVector2( uniform : Vector2Uniform ) : boolean	Updates a given Vector2 uniform.
.updateVector3( uniform : Vector3Uniform ) : boolean	Updates a given Vector3 uniform.
.updateVector4( uniform : Vector4Uniform ) : boolean	Updates a given Vector4 uniform.

Key Takeaways

1. UniformsGroup extends: EventDispatcher
2. Most relevant properties: buffer, byteLength, id, isUniformsGroup.
3. Key methods: add, addUniform, addUniformUpdateRange, clearUpdateRanges.

Connects To

• EventDispatcher: parent class
• Source: src/core/UniformsGroup.js