Chapter 90: ShaderMaterial

Core Idea

A material rendered with custom shaders. A shader is a small program written in GLSL. that runs on the GPU. You may want to use a custom shader if you need to implement an effect not included with any of the built-in materials.

There are the following notes to bear in mind when using a ShaderMaterial:

• ShaderMaterial can only be used with WebGLRenderer.
• Built in attributes and uniforms are passed to the shaders along with your code. If you don't want that, use RawShaderMaterial instead.
• You can use the directive #pragma unroll_loop_start and #pragma unroll_loop_end in order to unroll a for loop in GLSL by the shader preprocessor. The directive has to be placed right above the loop. The loop formatting has to correspond to a defined standard.
  • The loop has to be normalized.
  • The loop variable has to be i.
  • The value UNROLLED_LOOP_INDEX will be replaced with the explicitly value of i for the given iteration and can be used in preprocessor statements.

Key Concepts

• clipping : boolean: Defines whether this material supports clipping; true to let the renderer pass the clippingPlanes uniform.
• defaultAttributeValues : Object: When the rendered geometry doesn't include these attributes but the material does, these default values will be passed to the shaders. This…
• defines : Object: Defines custom constants using #define directives within the GLSL code for both the vertex shader and the fragment shader; each key/value…
• extensions : Object: This object allows to enable certain WebGL 2 extensions.
• fog : boolean: Defines whether the material color is affected by global fog settings; true to pass fog uniforms to the shader.
• forceSinglePass : boolean: Overwritten and set to true by default.
• fragmentShader : string: Fragment shader GLSL code. This is the actual code for the shader.
• glslVersion : GLSL1 | GLSL3: Defines the GLSL version of custom shader code.
• index0AttributeName : string | undefined: If set, this calls gl.bindAttribLocation to bi…
• isShaderMaterial : boolean (readonly): This flag can be used for type testing.

Code Examples

const material = new THREE.ShaderMaterial( {
	uniforms: {
		time: { value: 1.0 },
		resolution: { value: new THREE.Vector2() }
	},
	vertexShader: document.getElementById( 'vertexShader' ).textContent,
	fragmentShader: document.getElementById( 'fragmentShader' ).textContent
} );

• What it demonstrates: Typical usage of ShaderMaterial.

Reference Tables

Constructor

Signature
new ShaderMaterial( parameters : Object )

Properties

Property	Description
.clipping : boolean	Defines whether this material supports clipping; true to let the renderer pass the clippingPlanes uniform.
.defaultAttributeValues : Object	When the rendered geometry doesn't include these attributes but the material does, these default values will be passed to the shaders. This avoids errors when buffer data is missing.
.defines : Object	Defines custom constants using #define directives within the GLSL code for both the vertex shader and the fragment shader; each key/value pair yields another directive.
.extensions : Object	This object allows to enable certain WebGL 2 extensions.
.fog : boolean	Defines whether the material color is affected by global fog settings; true to pass fog uniforms to the shader.
.forceSinglePass : boolean	Overwritten and set to true by default.
.fragmentShader : string	Fragment shader GLSL code. This is the actual code for the shader.
`.glslVersion : GLSL1	GLSL3`
`.index0AttributeName : string	undefined`
.isShaderMaterial : boolean (readonly)	This flag can be used for type testing.
.lights : boolean	Defines whether this material uses lighting; true to pass uniform data related to lighting to this shader.
.linewidth : number	Controls line thickness or lines.
.uniforms : Object	An object of the form:
.uniformsGroups : Array.<UniformsGroup>	An array holding uniforms groups for configuring UBOs.
.uniformsNeedUpdate : boolean	Can be used to force a uniform update while changing uniforms in Object3D#onBeforeRender.
.vertexShader : string	Vertex shader GLSL code. This is the actual code for the shader.
.wireframe : boolean	Renders the geometry as a wireframe.
.wireframeLinewidth : number	Controls the thickness of the wireframe.

Methods

Method	Description
.fromJSON( json : Object, textures : Object.<string, Texture> ) : ShaderMaterial	Deserializes the material from the given JSON.

Key Takeaways

1. ShaderMaterial extends: EventDispatcher → Material
2. Most relevant properties: clipping, defaultAttributeValues, defines, extensions.
3. Key methods: fromJSON.

Connects To

• EventDispatcher: parent class
• Material: parent class
• Source: src/materials/ShaderMaterial.js