Three.js Tutorial

Three.js Tutorial Three.js Installation Compatibility and Running Locally Three.js Lines and Texts Three.js Loading 3D Models Three.js Updating Things Three.js Disposing of an Object Three.js Creating VR Content Three.js Using post-processing Three.js Matrix Transformations Three.js Animation Systems Three.js Testing with NPM Three.js AnimationAction Three.js AnimationClip Three.js AnimationMixer Animation Object Group and Utils Three.js Keyframe Track Property Binding and Mixer Three.js Animation/ Tracks Three.js Audio Three.js Camera Three.js Buffer Attribute Three.js Buffer Geometry Three.js Interleaved Buffer Three.js Layers Three.js Object3D Three.js Raycaster Three.js Uniform Three.js Curves Three.js Geometries- 1 Three.js Helpers- 1 Three.js Helpers- 2 Three.js Lights Three.js Shadows Three.js Loaders- 1 Three.js Loaders- 2 Three.js Managers Three.js Materials Three.js Materials- Mesh Three.js Materials- 3 Three.js Math Three.js Interpolant Three.js Objects Three.js Renderers Three.js Scenes

ThreeJS Materials 3
2022-04-19 14:22:12

ThreeJS Materials 3

RawShaderMaterial

This class works just like ShaderMaterial, except that definitions of built-in uniforms and attributes are not automatically prepended to the GLSL shader code.

Code Example

const material = new THREE.RawShaderMaterial( {

            uniforms: {

                        time: { value: 1.0 }

            },

            vertexShader: document.getElementById( 'vertexShader' ).textContent,

            fragmentShader: document.getElementById( 'fragmentShader' ).textContent,


} );

Constructor

RawShaderMaterial( parameters : Object )

parameters - (optional) an object with one or more properties defining the material's appearance. Any property of the material (including any property inherited from Material and ShaderMaterial) can be passed in here.

Properties

See the base Material and ShaderMaterial classes for common properties.

Methods

See the base Material and ShaderMaterial classes for common methods.

ShaderMaterial

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
  • combine many objects into a single BufferGeometry in order to improve performance

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

  • A ShaderMaterial will only be rendered properly by WebGLRenderer, since the GLSL code in the vertexShader and fragmentShader properties must be compiled and run on the GPU using WebGL.
  • As of THREE r72, directly assigning attributes in a ShaderMaterial is no longer supported. A BufferGeometry instance must be used instead, using BufferAttribute instances to define custom attributes.
  • As of THREE r77, WebGLRenderTarget or WebGLCubeRenderTarget instances are no longer supposed to be used as uniforms. Their texture property must be used instead.
  • Built in attributes and uniforms are passed to the shaders along with your code. If you don't want the WebGLProgram to add anything to your shader code, you can use RawShaderMaterial instead of this class.
  • 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.

#pragma unroll_loop_start

for ( int i = 0; i < 10; i ++ ) {

          // ...

}

#pragma unroll_loop_end

Code Example

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

} );

Vertex shaders and fragment shaders

You can specify two different types of shaders for each material:

  • The vertex shader runs first; it receives attributes, calculates / manipulates the position of each individual vertex, and passes additional data (varyings) to the fragment shader.
  • The fragment ( or pixel ) shader runs second; it sets the color of each individual "fragment" (pixel) rendered to the screen.

There are three types of variables in shaders: uniforms, attributes, and varyings:

  • Uniforms are variables that have the same value for all vertices - lighting, fog, and shadow maps are examples of data that would be stored in uniforms. Uniforms can be accessed by both the vertex shader and the fragment shader.
  • Attributes are variables associated with each vertex---for instance, the vertex position, face normal, and vertex color are all examples of data that would be stored in attributes. Attributes can only be accessed within the vertex shader.
  • Varyings are variables that are passed from the vertex shader to the fragment shader. For each fragment, the value of each varying will be smoothly interpolated from the values of adjacent vertices.

Note that within the shader itself, uniforms and attributes act like constants; you can only modify their values by passing different values to the buffers from your JavaScript code.

Built-in attributes and uniforms

Many attributes and uniforms are provided by default to shaders by the WebGLRenderer; definitions of these variables are prepended to your fragmentShader and vertexShader code by the WebGLProgram when the shader is compiled; you do not need to declare them yourself. Details on these variables can be found in WebGLProgram.

Some of these uniforms or attributes (for example, those related to lighting, fog, and so on) require properties to be set on the material in order for WebGLRenderer to copy the appropriate values to the GPU - make sure to set these flags if you want to use these features in your own shader.

You can use RawShaderMaterial instead of this class if you don't want WebGLProgram to add anything to your shader code.

Custom attributes and uniforms

Custom attributes and uniforms must both be declared in GLSL shader code (within vertexShader and/or fragmentShader). Custom uniforms must be defined in your ShaderMaterial's uniforms property, and any custom attributes must be defined using BufferAttribute instances. Variables must only be declared within the shader code (not within the material).

Please see the BufferGeometry page for an overview and the BufferAttribute page for a detailed look at the BufferAttribute API before declaring a custom attribute.

When creating your attributes, each typed array that you create to hold your attribute's data must be a multiple of your data type's size. For example, if your attribute is a THREE.Vector3 type, and you have 3000 vertices in your BufferGeometry, your typed array value must be created with a length of 3000 * 3, or 9000 (one value per-component). A table of each data type's size is shown below for reference:

Note that attribute buffers are not refreshed automatically when their values change. To update custom attributes, set the needsUpdate flag to true on the BufferAttribute of the geometry (see BufferGeometry for further details).

To declare a custom Uniform, use the uniforms property:

uniforms:

{
          time: { value: 1.0 },

          resolution: { value: new THREE.Vector2() }
}

Constructor

ShaderMaterial( parameters : Object )

parameters - (optional) an object with one or more properties defining the material's appearance. Any property of the material (including any property inherited from Material) can be passed in here.

Properties

See the base Material class for common properties.

.clipping : Boolean

Defines whether this material supports clipping; true to let the renderer pass the clippingPlanes uniform. Default is false.

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

this.defaultAttributeValues = {

          'color': [ 1, 1, 1 ],

          'uv': [ 0, 0 ],

          'uv2': [ 0, 0 ]

};

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

defines: {

          FOO: 15,

          BAR: true

}

yields the lines

#define FOO 15

#define BAR true

in the GLSL code.

.extensions : Object

An object with the following properties:

this.extensions = {

          derivatives: false, // set to use derivatives

          fragDepth: false, // set to use fragment depth values

          drawBuffers: false, // set to use draw buffers

          shaderTextureLOD: false // set to use shader texture LOD

};

.fog : Boolean

Define whether the material color is affected by global fog settings; true to pass fog uniforms to the shader. Default is false.

.fragmentShader : String

Fragment shader GLSL code. This is the actual code for the shader. In the example above, the vertexShader and fragmentShader code is extracted from the DOM; it could be passed as a string directly or loaded via AJAX instead.

.glslVersion : String

Defines the GLSL version of custom shader code. Only relevant for WebGL 2 in order to define whether to specify GLSL 3.0 or not. Valid values are THREE.GLSL1 or THREE.GLSL3. Default is null.

.index0AttributeName : String

If set, this calls gl.bindAttribLocation to bind a generic vertex index to an attribute variable. Default is undefined.

.isShaderMaterial : Boolean

Read-only flag to check whether a given object is of type ShaderMaterial.

.lights : Boolean

Defines whether this material uses lighting; true to pass uniform data related to lighting to this shader. Default is false.

.linewidth : Float

Controls wireframe thickness. Default is 1.

Due to limitations of the OpenGL Core Profile with the WebGL renderer on most platforms linewidth will always be 1 regardless of the set value.

.flatShading : Boolean

Define whether the material is rendered with flat shading. Default is false.

.uniforms : Object

An object of the form:

{ "uniform1": { value: 1.0 }, "uniform2": { value: 2 } }

specifying the uniforms to be passed to the shader code; keys are uniform names, values are definitions of the form

{ value: 1.0 }

where value is the value of the uniform. Names must match the name of the uniform, as defined in the GLSL code. Note that uniforms are refreshed on every frame, so updating the value of the uniform will immediately update the value available to the GLSL code.

.uniformsNeedUpdate : Boolean

Can be used to force a uniform update while changing uniforms in Object3D.onBeforeRender(). Default is false.

.vertexColors : Boolean

Defines whether vertex coloring is used. Default is false.

.vertexShader : String

Vertex shader GLSL code. This is the actual code for the shader. In the example above, the vertexShader and fragmentShader code is extracted from the DOM; it could be passed as a string directly or loaded via AJAX instead.

.wireframe : Boolean

Render geometry as wireframe (using GL_LINES instead of GL_TRIANGLES). Default is false (i.e. render as flat polygons).

.wireframeLinewidth : Float

Controls wireframe thickness. Default is 1.

Due to limitations of the OpenGL Core Profile with the WebGL renderer on most platforms linewidth will always be 1 regardless of the set value.

Methods

See the base Material class for common methods.

.clone () : ShaderMaterial this : ShaderMaterial

Generates a shallow copy of this material. Note that the vertexShader and fragmentShader are copied by reference, as are the definitions of the attributes; this means that clones of the material will share the same compiled WebGLProgram. However, the uniforms are copied by value, which allows you to have different sets of uniforms for different copies of the material.

ShadowMaterial

This material can receive shadows, but otherwise is completely transparent.

Code Example

const geometry = new THREE.PlaneGeometry( 2000, 2000 );

geometry.rotateX( - Math.PI / 2 );

const material = new THREE.ShadowMaterial();

material.opacity = 0.2;

const plane = new THREE.Mesh( geometry, material );

plane.position.y = -200;

plane.receiveShadow = true;

scene.add( plane );

Constructor

ShadowMaterial( parameters : Object )

parameters - (optional) an object with one or more properties defining the material's appearance. Any property of the material (including any property inherited from Material) can be passed in here.

Properties

See the base Material classes for common properties.

.color : Color

Color of the material, by default set to black (0x000000).

.transparent : Boolean

Defines whether this material is transparent. Default is true.

Methods

See the base Material classes for common methods.

SpriteMaterial

A material for a use with a Sprite.

Code Example

const map = new THREE.TextureLoader().load( 'textures/sprite.png' );

const material = new THREE.SpriteMaterial( { map: map, color: 0xffffff } );



const sprite = new THREE.Sprite( material );

sprite.scale.set(200, 200, 1)

scene.add( sprite );

Constructor

SpriteMaterial( parameters : Object )

parameters - (optional) an object with one or more properties defining the material's appearance. Any property of the material (including any property inherited from Material) can be passed in here.

The exception is the property color, which can be passed in as a hexadecimal string and is 0xffffff (white) by default. Color.set( color ) is called internally. SpriteMaterials are not clipped by using Material.clippingPlanes.

Properties

See the base Material class for common properties.

.alphaMap : Texture

The alpha map is a grayscale texture that controls the opacity across the surface (black: fully transparent; white: fully opaque). Default is null.

Only the color of the texture is used, ignoring the alpha channel if one exists. For RGB and RGBA textures, the WebGL renderer will use the green channel when sampling this texture due to the extra bit of precision provided for green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and luminance/alpha textures will also still work as expected.

.color : Color

Color of the material, by default set to white (0xffffff). The .map is multiplied by the color.

.isSpriteMaterial : Boolean

Read-only flag to check whether a given object is of type SpriteMaterial.

.map : Texture

The texture map. Default is null.

.rotation : Radians

The rotation of the sprite in radians. Default is 0.

.sizeAttenuation : Boolean

Whether the size of the sprite is attenuated by the camera depth. (Perspective camera only.) Default is true.

.transparent : Boolean

Defines whether this material is transparent. Default is true.

Methods

See the base Material class for common methods.