Material

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:

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

Examples

webgl / animation / cloth
webgl / buffergeometry / custom / attributes / particles
webgl / buffergeometry / selective / draw
webgl / custom / attributes
webgl / custom / attributes / lines
webgl / custom / attributes / points
webgl / custom / attributes / points2
webgl / custom / attributes / points3
webgl / depth / texture
webgl / gpgpu / birds
webgl / gpgpu / protoplanet
webgl / gpgpu / water
webgl / hdr
webgl / interactive / points
webgl / kinect
webgl / lights / hemisphere
webgl / marchingcubes
webgl / materials / bumpmap / skin
webgl / materials / envmaps
webgl / materials / lightmap
webgl / materials / parallaxmap
webgl / materials / shaders / fresnel
webgl / materials / skin
webgl / materials / texture / hdr
webgl / materials / wireframe
webgl / modifier / tessellation
webgl / nearestneighbour
webgl / postprocessing / dof2
webgl / postprocessing / godrays

var material = new v3d.ShaderMaterial({ uniforms: { time: { value: 1.0 }, resolution: { value: new v3d.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:

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

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

The WebGLRenderer provides many attributes and uniforms to shaders by default; definitions of these variables are prepended to your fragmentShader and vertexShader code by the WebGLProgram when the shader is compiled; you don't need to declare them yourself. See WebGLProgram for details of these variables.

Some of these uniforms or attributes (e.g. those pertaining lighting, fog, etc.) 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.

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

Custom attributes and uniforms

Both custom attributes and uniforms must be declared in your GLSL shader code (within vertexShader and/or fragmentShader). Custom uniforms must be defined in both the uniforms property of your ShaderMaterial, whereas any custom attributes must be defined via BufferAttribute instances. Note that varyings only need to be declared within the shader code (not within the material).

To declare a custom attribute, please reference the BufferGeometry page for an overview, and the BufferAttribute page for a detailed look at the BufferAttribute API.

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

Attribute sizes
GLSL type JavaScript type Size
float Number 1
vec2 v3d.Vector2 2
vec3 v3d.Vector3 3
vec3 v3d.Color 3
vec4 v3d.Vector4 4

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 v3d.Vector2() } }

You're recommended to update custom Uniform values depending on object and camera in Object3D.onBeforeRender because Material can be shared among meshes, matrixWorld of Scene and Camera are updated in WebGLRenderer.render, and some effects(ex:VREffect) render a scene with private their own cameras.

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.

.index0AttributeName : String

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

.isShaderMaterial : Boolean

Used to check whether this or derived classes are shader materials. Default is true.

You should not change this, as it used internally for optimisation.

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

.morphTargets : Boolean

Defines whether the material uses morphTargets; true morphTarget attributes to this shader

.morphNormals : boolean

Defines whether the material uses morphNormals. Set as true to pass morphNormal attributes from the Geometry to the shader. Default is false.

.program : WebGLProgram

The compiled shader program associated with this material, generated by WebGLRenderer. You should not need to access this property.

.flatShading : Boolean

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

.skinning : Boolean

Define whether the material uses skinning; true to pass skinning attributes to the shader. 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.

.vertexColors : Number

Define how the vertices are colored, by defining how the colors attribute gets populated. Possible values are v3d.NoColors, v3d.FaceColors and v3d.VertexColors. Default is v3d.NoColors.

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

Source

For more info on how to obtain the source code of this module see this page.