123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496 |
- <!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.
- </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: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>
|