You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
503 lines
17 KiB
HTML
503 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<base href="../../../" />
|
|
<script src="page.js"></script>
|
|
<link type="text/css" rel="stylesheet" href="page.css" />
|
|
</head>
|
|
<body>
|
|
<h1>[name]</h1>
|
|
|
|
<p class="desc">
|
|
Abstract base class for materials.<br /><br />
|
|
|
|
Materials describe the appearance of [page:Object objects]. They are
|
|
defined in a (mostly) renderer-independent way, so you don't have to
|
|
rewrite materials if you decide to use a different renderer.<br /><br />
|
|
|
|
The following properties and methods are inherited by all other material
|
|
types (although they may have different defaults).
|
|
</p>
|
|
|
|
<h2>Constructor</h2>
|
|
|
|
<h3>[name]()</h3>
|
|
<p>This creates a generic material.</p>
|
|
|
|
<h2>Properties</h2>
|
|
|
|
<h3>[property:Boolean alphaHash]</h3>
|
|
<p>
|
|
Enables alpha hashed transparency, an alternative to [page:.transparent] or [page:.alphaTest].
|
|
The material will not be rendered if opacity is lower than a random threshold.
|
|
Randomization introduces some grain or noise, but approximates alpha blending without
|
|
the associated problems of sorting. Using TAARenderPass can reduce the resulting noise.
|
|
</p>
|
|
|
|
<h3>[property:Float alphaTest]</h3>
|
|
<p>
|
|
Sets the alpha value to be used when running an alpha test. The material
|
|
will not be rendered if the opacity is lower than this value. Default is
|
|
`0`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean alphaToCoverage]</h3>
|
|
<p>
|
|
Enables alpha to coverage. Can only be used with MSAA-enabled contexts
|
|
(meaning when the renderer was created with *antialias* parameter set to
|
|
`true`). Enabling this will smooth aliasing on clip plane edges and alphaTest-clipped edges.
|
|
Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Float blendAlpha]</h3>
|
|
<p>
|
|
Represents the alpha value of the constant blend color. Default is `0`.
|
|
|
|
This property has only an effect when using custom blending with [page:CustomBlendingEquation ConstantAlpha] or [page:CustomBlendingEquation OneMinusConstantAlpha].
|
|
</p>
|
|
|
|
<h3>[property:Color blendColor]</h3>
|
|
<p>
|
|
Represent the RGB values of the constant blend color. Default is `0x000000`.<br />
|
|
|
|
This property has only an effect when using custom blending with [page:CustomBlendingEquation ConstantColor] or [page:CustomBlendingEquation OneMinusConstantColor].
|
|
</p>
|
|
|
|
<h3>[property:Integer blendDst]</h3>
|
|
<p>
|
|
Blending destination. Default is [page:CustomBlendingEquation OneMinusSrcAlphaFactor].
|
|
See the destination factors [page:CustomBlendingEquation constants] for all possible values.<br />
|
|
The material's [page:Constant blending] must be set to [page:Materials CustomBlending]
|
|
for this to have any effect.
|
|
</p>
|
|
|
|
<h3>[property:Integer blendDstAlpha]</h3>
|
|
<p>
|
|
The transparency of the [page:.blendDst]. Uses [page:.blendDst] value if
|
|
null. Default is `null`.
|
|
</p>
|
|
|
|
<h3>[property:Integer blendEquation]</h3>
|
|
<p>
|
|
Blending equation to use when applying blending. Default is
|
|
[page:CustomBlendingEquation AddEquation]. See the blending equation
|
|
[page:CustomBlendingEquation constants] for all possible values.<br />
|
|
The material's [page:Constant blending] must be set to [page:Materials CustomBlending]
|
|
for this to have any effect.
|
|
</p>
|
|
|
|
<h3>[property:Integer blendEquationAlpha]</h3>
|
|
<p>
|
|
The transparency of the [page:.blendEquation]. Uses [page:.blendEquation]
|
|
value if null. Default is `null`.
|
|
</p>
|
|
|
|
<h3>[property:Blending blending]</h3>
|
|
<p>
|
|
Which blending to use when displaying objects with this material. <br />
|
|
This must be set to [page:Materials CustomBlending] to use custom
|
|
[page:Constant blendSrc], [page:Constant blendDst] or [page:Constant blendEquation].<br />
|
|
See the blending mode [page:Materials constants] for all possible values.
|
|
Default is [page:Materials NormalBlending].
|
|
</p>
|
|
|
|
<h3>[property:Integer blendSrc]</h3>
|
|
<p>
|
|
Blending source. Default is [page:CustomBlendingEquation SrcAlphaFactor].
|
|
See the source factors [page:CustomBlendingEquation constants] for all
|
|
possible values.<br />
|
|
The material's [page:Constant blending] must be set to [page:Materials CustomBlending]
|
|
for this to have any effect.
|
|
</p>
|
|
|
|
<h3>[property:Integer blendSrcAlpha]</h3>
|
|
<p>
|
|
The transparency of the [page:.blendSrc]. Uses [page:.blendSrc] value if
|
|
null. Default is `null`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean clipIntersection]</h3>
|
|
<p>
|
|
Changes the behavior of clipping planes so that only their intersection is
|
|
clipped, rather than their union. Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Array clippingPlanes]</h3>
|
|
<p>
|
|
User-defined clipping planes specified as THREE.Plane objects in world
|
|
space. These planes apply to the objects this material is attached to.
|
|
Points in space whose signed distance to the plane is negative are clipped
|
|
(not rendered). This requires [page:WebGLRenderer.localClippingEnabled] to
|
|
be `true`. See the [example:webgl_clipping_intersection WebGL / clipping /intersection] example. Default is `null`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean clipShadows]</h3>
|
|
<p>
|
|
Defines whether to clip shadows according to the clipping planes specified
|
|
on this material. Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean colorWrite]</h3>
|
|
<p>
|
|
Whether to render the material's color. This can be used in conjunction
|
|
with a mesh's [page:Integer renderOrder] property to create invisible
|
|
objects that occlude other objects. Default is `true`.
|
|
</p>
|
|
|
|
<h3>[property:Object defines]</h3>
|
|
<p>
|
|
Custom defines to be injected into the shader. These are passed in form of
|
|
an object literal, with key/value pairs. `{ MY_CUSTOM_DEFINE: '' , PI2:
|
|
Math.PI * 2 }`. The pairs are defined in both vertex and fragment shaders.
|
|
Default is `undefined`.
|
|
</p>
|
|
|
|
<h3>[property:Integer depthFunc]</h3>
|
|
<p>
|
|
Which depth function to use. Default is [page:Materials LessEqualDepth].
|
|
See the depth mode [page:Materials constants] for all possible values.
|
|
</p>
|
|
|
|
<h3>[property:Boolean depthTest]</h3>
|
|
<p>
|
|
Whether to have depth test enabled when rendering this material. Default
|
|
is `true`. When the depth test is disabled, the depth write will also be
|
|
implicitly disabled.
|
|
</p>
|
|
|
|
<h3>[property:Boolean depthWrite]</h3>
|
|
<p>
|
|
Whether rendering this material has any effect on the depth buffer.
|
|
Default is `true`.<br /><br />
|
|
|
|
When drawing 2D overlays it can be useful to disable the depth writing in
|
|
order to layer several things together without creating z-index artifacts.
|
|
</p>
|
|
|
|
<h3>[property:Boolean forceSinglePass]</h3>
|
|
<p>
|
|
Whether double-sided, transparent objects should be rendered with a single
|
|
pass or not. Default is `false`.<br /><br />
|
|
|
|
The engine renders double-sided, transparent objects with two draw calls
|
|
(back faces first, then front faces) to mitigate transparency artifacts.
|
|
There are scenarios however where this approach produces no quality gains
|
|
but still doubles draw calls e.g. when rendering flat vegetation like
|
|
grass sprites. In these cases, set the `forceSinglePass` flag to `true` to
|
|
disable the two pass rendering to avoid performance issues.
|
|
</p>
|
|
|
|
<h3>[property:Boolean isMaterial]</h3>
|
|
<p>Read-only flag to check if a given object is of type [name].</p>
|
|
|
|
<h3>[property:Boolean stencilWrite]</h3>
|
|
<p>
|
|
Whether stencil operations are performed against the stencil buffer. In
|
|
order to perform writes or comparisons against the stencil buffer this
|
|
value must be `true`. Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilWriteMask]</h3>
|
|
<p>
|
|
The bit mask to use when writing to the stencil buffer. Default is `0xFF`.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilFunc]</h3>
|
|
<p>
|
|
The stencil comparison function to use. Default is [page:Materials AlwaysStencilFunc].
|
|
See stencil function [page:Materials constants] for
|
|
all possible values.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilRef]</h3>
|
|
<p>
|
|
The value to use when performing stencil comparisons or stencil
|
|
operations. Default is `0`.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilFuncMask]</h3>
|
|
<p>
|
|
The bit mask to use when comparing against the stencil buffer. Default is
|
|
`0xFF`.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilFail]</h3>
|
|
<p>
|
|
Which stencil operation to perform when the comparison function returns
|
|
false. Default is [page:Materials KeepStencilOp]. See the stencil
|
|
operations [page:Materials constants] for all possible values.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilZFail]</h3>
|
|
<p>
|
|
Which stencil operation to perform when the comparison function returns
|
|
true but the depth test fails. Default is [page:Materials KeepStencilOp].
|
|
See the stencil operations [page:Materials constants] for all possible
|
|
values.
|
|
</p>
|
|
|
|
<h3>[property:Integer stencilZPass]</h3>
|
|
<p>
|
|
Which stencil operation to perform when the comparison function returns
|
|
true and the depth test passes. Default is [page:Materials KeepStencilOp].
|
|
See the stencil operations [page:Materials constants] for all possible
|
|
values.
|
|
</p>
|
|
|
|
<h3>[property:Integer id]</h3>
|
|
<p>Unique number for this material instance.</p>
|
|
|
|
<h3>[property:String name]</h3>
|
|
<p>
|
|
Optional name of the object (doesn't need to be unique). Default is an
|
|
empty string.
|
|
</p>
|
|
|
|
<h3>[property:Boolean needsUpdate]</h3>
|
|
<p>Specifies that the material needs to be recompiled.</p>
|
|
|
|
<h3>[property:Float opacity]</h3>
|
|
<p>
|
|
Float in the range of `0.0` - `1.0` indicating how transparent the
|
|
material is. A value of `0.0` indicates fully transparent, `1.0` is fully
|
|
opaque.<br />
|
|
If the material's [page:Boolean transparent] property is not set to
|
|
`true`, the material will remain fully opaque and this value will only
|
|
affect its color. <br />
|
|
Default is `1.0`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean polygonOffset]</h3>
|
|
<p>
|
|
Whether to use polygon offset. Default is `false`. This corresponds to the
|
|
`GL_POLYGON_OFFSET_FILL` WebGL feature.
|
|
</p>
|
|
|
|
<h3>[property:Integer polygonOffsetFactor]</h3>
|
|
<p>Sets the polygon offset factor. Default is `0`.</p>
|
|
|
|
<h3>[property:Integer polygonOffsetUnits]</h3>
|
|
<p>Sets the polygon offset units. Default is `0`.</p>
|
|
|
|
<h3>[property:String precision]</h3>
|
|
<p>
|
|
Override the renderer's default precision for this material. Can be
|
|
`"highp"`, `"mediump"` or `"lowp"`. Default is `null`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean premultipliedAlpha]</h3>
|
|
<p>
|
|
Whether to premultiply the alpha (transparency) value. See
|
|
[Example:webgl_materials_physical_transmission WebGL / Materials / Physical / Transmission]
|
|
for an example of the difference. Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean dithering]</h3>
|
|
<p>
|
|
Whether to apply dithering to the color to remove the appearance of
|
|
banding. Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:Integer shadowSide]</h3>
|
|
<p>
|
|
Defines which side of faces cast shadows. When set, can be [page:Materials THREE.FrontSide],
|
|
[page:Materials THREE.BackSide], or [page:Materials THREE.DoubleSide].
|
|
Default is `null`. <br />
|
|
If `null`, the side casting shadows is determined as follows: <br />
|
|
</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>[page:Material.side]</th>
|
|
<th>Side casting shadows</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>THREE.FrontSide</td>
|
|
<td>back side</td>
|
|
</tr>
|
|
<tr>
|
|
<td>THREE.BackSide</td>
|
|
<td>front side</td>
|
|
</tr>
|
|
<tr>
|
|
<td>THREE.DoubleSide</td>
|
|
<td>both sides</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>[property:Integer side]</h3>
|
|
<p>
|
|
Defines which side of faces will be rendered - front, back or both.
|
|
Default is [page:Materials THREE.FrontSide]. Other options are
|
|
[page:Materials THREE.BackSide] or [page:Materials THREE.DoubleSide].
|
|
</p>
|
|
|
|
<h3>[property:Boolean toneMapped]</h3>
|
|
<p>
|
|
Defines whether this material is tone mapped according to the renderer's
|
|
[page:WebGLRenderer.toneMapping toneMapping] setting. It is ignored when rendering to a render target or using post processing.
|
|
Default is `true`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean transparent]</h3>
|
|
<p>
|
|
Defines whether this material is transparent. This has an effect on
|
|
rendering as transparent objects need special treatment and are rendered
|
|
after non-transparent objects. <br />
|
|
When set to true, the extent to which the material is transparent is
|
|
controlled by setting its [page:Float opacity] property.
|
|
Default is `false`.
|
|
</p>
|
|
|
|
<h3>[property:String type]</h3>
|
|
<p>
|
|
Value is the string 'Material'. This shouldn't be changed, and can be used
|
|
to find all objects of this type in a scene.
|
|
</p>
|
|
|
|
<h3>[property:String uuid]</h3>
|
|
<p>
|
|
[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of
|
|
this material instance. This gets automatically assigned, so this
|
|
shouldn't be edited.
|
|
</p>
|
|
|
|
<h3>[property:Integer version]</h3>
|
|
<p>
|
|
This starts at `0` and counts how many times [page:Material.needsUpdate .needsUpdate] is set to `true`.
|
|
</p>
|
|
|
|
<h3>[property:Boolean vertexColors]</h3>
|
|
<p>
|
|
Defines whether vertex coloring is used. Default is `false`. The engine
|
|
supports RGB and RGBA vertex colors depending on whether a three (RGB) or
|
|
four (RGBA) component color buffer attribute is used.
|
|
</p>
|
|
|
|
<h3>[property:Boolean visible]</h3>
|
|
<p>Defines whether this material is visible. Default is `true`.</p>
|
|
|
|
<h3>[property:Object userData]</h3>
|
|
<p>
|
|
An object that can be used to store custom data about the Material. It
|
|
should not hold references to functions as these will not be cloned.
|
|
Default is an empty object `{}`.
|
|
</p>
|
|
|
|
<h2>Methods</h2>
|
|
<p>
|
|
[page:EventDispatcher EventDispatcher] methods are available on this
|
|
class.
|
|
</p>
|
|
|
|
<h3>[method:Material clone]( )</h3>
|
|
<p>Return a new material with the same parameters as this material.</p>
|
|
|
|
<h3>[method:this copy]( [param:material material] )</h3>
|
|
<p>Copy the parameters from the passed material into this material.</p>
|
|
|
|
<h3>[method:undefined dispose]()</h3>
|
|
<p>
|
|
Frees the GPU-related resources allocated by this instance. Call this
|
|
method whenever this instance is no longer used in your app.
|
|
</p>
|
|
<p>
|
|
Material textures must be disposed of by the dispose() method of
|
|
[page:Texture Texture].
|
|
</p>
|
|
|
|
<h3>
|
|
[method:undefined onBeforeCompile]( [param:Shader shader], [param:WebGLRenderer renderer] )
|
|
</h3>
|
|
<p>
|
|
An optional callback that is executed immediately before the shader
|
|
program is compiled. This function is called with the shader source code
|
|
as a parameter. Useful for the modification of built-in materials, but the
|
|
recommended approach moving forward is to use `WebGPURenderer` with the new
|
|
Node Material system and [link:https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language TSL].
|
|
</p>
|
|
<p>
|
|
Unlike properties, the callback is not supported by [page:Material.clone .clone](),
|
|
[page:Material.copy .copy]() and [page:Material.toJSON .toJSON]().
|
|
</p>
|
|
<p>
|
|
This callback is only supported in `WebGLRenderer` (not `WebGPURenderer`).
|
|
</p>
|
|
<p>
|
|
[example:webgl_materials_modified WebGL / materials / modified]<br />
|
|
[example:webgl_shadow_contact WebGL / shadow / contact]
|
|
</p>
|
|
|
|
<h3>
|
|
[method:undefined onBeforeRender]( [param:WebGLRenderer renderer], [param:Scene scene], [param:Camera camera], [param:BufferGeometry geometry], [param:Object3D object], [param:Group group] )
|
|
</h3>
|
|
<p>
|
|
An optional callback that is executed immediately before the material is used to
|
|
render a 3D object.
|
|
</p>
|
|
<p>
|
|
Unlike properties, the callback is not supported by [page:Material.clone .clone](),
|
|
[page:Material.copy .copy]() and [page:Material.toJSON .toJSON]().
|
|
</p>
|
|
<p>
|
|
This callback is only supported in `WebGLRenderer` (not `WebGPURenderer`).
|
|
</p>
|
|
|
|
<h3>[method:String customProgramCacheKey]()</h3>
|
|
<p>
|
|
In case onBeforeCompile is used, this callback can be used to identify
|
|
values of settings used in onBeforeCompile, so three.js can reuse a cached
|
|
shader or recompile the shader for this material as needed.
|
|
</p>
|
|
|
|
<p>
|
|
For example, if onBeforeCompile contains a conditional statement like:<br />
|
|
|
|
<code>
|
|
if ( black ) {
|
|
shader.fragmentShader = shader.fragmentShader.replace('gl_FragColor = vec4(1)',
|
|
'gl_FragColor = vec4(0)')
|
|
}
|
|
</code>
|
|
|
|
then customProgramCacheKey should be set like this:<br />
|
|
|
|
<code>
|
|
material.customProgramCacheKey = function() {
|
|
return black ? '1' : '0';
|
|
}
|
|
</code>
|
|
</p>
|
|
|
|
<p>
|
|
Unlike properties, the callback is not supported by [page:Material.clone .clone](),
|
|
[page:Material.copy .copy]() and [page:Material.toJSON .toJSON]().
|
|
</p>
|
|
|
|
<h3>[method:undefined setValues]( [param:Object values] )</h3>
|
|
<p>
|
|
values -- a container with parameters.<br />
|
|
Sets the properties based on the `values`.
|
|
</p>
|
|
|
|
<h3>[method:Object toJSON]( [param:Object meta] )</h3>
|
|
<p>
|
|
meta -- object containing metadata such as textures or images for the
|
|
material.<br />
|
|
Convert the material to three.js
|
|
[link:https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 JSON Object/Scene format].
|
|
</p>
|
|
|
|
<h2>Source</h2>
|
|
|
|
<p>
|
|
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
|
|
</p>
|
|
</body>
|
|
</html>
|