Skip to content

Commit

Permalink
Improved documentation for Constants / Textures (#10001)
Browse files Browse the repository at this point in the history 
* Improved documentation for Materials / Material

* Moved Texture Combine Operations to constanst / materials

* updated Basic, Lambert and Phong .combine property to point to Material constant page

* Improved documentation for constants / textures

* Added Encoding constants to Textures constants page
  • Loading branch information
@looeee @mrdoob
looeee authored and mrdoob committed Nov 3, 2016
1 parent fbdc314 commit a88cf2b
Show file tree
Hide file tree
Showing 5 changed files with 242 additions and 55 deletions.
14 changes: 13 additions & 1 deletion docs/api/constants/Materials.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ <h1>Material Constants</h1>

<div class="desc">
These constants define properties common to all material types,
with the exception of [page:MultiMaterial MultiMaterial] where they are defined for sub-materials.
with the exception of Texture Combine Operations which only apply to [page:MeshBasicMaterial.combine MeshBasicMaterial], [page:MeshLambertMaterial.combine MeshLambertMaterial] and [page:MeshPhongMaterial.combine MeshPhongMaterial].<br />
</div>


Expand Down Expand Up @@ -88,6 +88,18 @@ <h2>Depth Mode</h2>
[page:Materials NotEqualDepth] will return true if the incoming pixel Z-depth is equal to the current buffer Z-depth.<br />
</div>

<h2>Texture Combine Operations</h2>
<code>
THREE.MultiplyOperation
THREE.MixOperation
THREE.AddOperation
</code>
These define how the result of the surface's color is combined with the environment map (if present), for [page:MeshBasicMaterial.combine MeshBasicMaterial], [page:MeshLambertMaterial.combine MeshLambertMaterial] and [page:MeshPhongMaterial.combine MeshPhongMaterial]. <br />
[page:Constant MultiplyOperation] is the default and multiplies the environment map color with the surface color.<br />
[page:Constant MixOperation] uses reflectivity to blend between the two colors.<br />
[page:Constant AddOperation] adds the two colors.


<h2>Source</h2>

[link:https://github.com/mrdoob/three.js/blob/master/src/constants.js src/constants.js]
Expand Down
277 changes: 226 additions & 51 deletions docs/api/constants/Textures.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,83 +10,258 @@
<body>
<h1>Texture Constants</h1>

<h2>Operations</h2>
<div>
THREE.MultiplyOperation<br />
THREE.MixOperation<br />
THREE.AddOperation
</div>

<h2>Mapping Modes</h2>
<div>
THREE.UVMapping<br />
THREE.CubeReflectionMapping<br />
THREE.CubeRefractionMapping<br />
THREE.EquirectangularReflectionMapping<br />
THREE.EquirectangularRefractionMapping<br />
<code>
THREE.UVMapping
THREE.CubeReflectionMapping
THREE.CubeRefractionMapping
THREE.EquirectangularReflectionMapping
THREE.EquirectangularRefractionMapping
THREE.SphericalReflectionMapping
THREE.CubeUVReflectionMapping
THREE.CubeUVRefractionMapping
</code>
<div>
These define the texture's mapping mode.<br />
[page:Constant UVMapping] is the default, and maps the texture using the mesh's UV coordinates.<br /><br />

The rest define environment mapping types.<br /><br />

[page:Constant CubeReflectionMapping] and [page:Constant CubeRefractionMapping] are for
use with a [page:CubeTexture CubeTexture], which is made up of six textures, one for each face of the cube.<br />
[page:Constant CubeReflectionMapping] is the default for a [page:CubeTexture CubeTexture]. <br /><br />

[page:Constant EquirectangularReflectionMapping] and [page:Constant EquirectangularRefractionMapping]
are for use with an equirectangular environment map.<br /><br />

[page:Constant SphericalReflectionMapping] is for use with a spherical reflection map.<br /><br />

See the [example:webgl_materials_envmaps materials / envmaps] example.
</div>


<h2>Wrapping Modes</h2>
<div>
THREE.RepeatWrapping<br />
THREE.ClampToEdgeWrapping<br />
<code>
THREE.RepeatWrapping
THREE.ClampToEdgeWrapping
THREE.MirroredRepeatWrapping
</code>
<div>
These define the texture's [page:Texture.wrapS wrapS] and [page:Texture.wrapT wrapT] properties,
which define horizontal and vertical texture wrapping.<br /><br />

With [page:constant RepeatWrapping] the texture will simply repeat to infinity.<br /><br />

[page:constant ClampToEdgeWrapping] is the default.
The last pixel of the texture stretches to the edge of the mesh.<br /><br />

With [page:constant MirroredRepeatWrapping] the texture will repeats to infinity, mirroring on each repeat.<br />
</div>

<h2>Filters</h2>
<h2>Magnification Filters</h2>
<code>
THREE.NearestFilter
THREE.LinearFilter
</code>
<div>
THREE.NearestFilter<br />
THREE.NearestMipMapNearestFilter<br />
THREE.NearestMipMapLinearFilter<br />
THREE.LinearFilter<br />
THREE.LinearMipMapNearestFilter<br />
THREE.LinearMipMapLinearFilter
For use with a texture's [page:Texture.magFilter magFilter] property,
these define the texture magnification function to be used when the pixel being textured maps to an
area less than or equal to one texture element (texel).<br /><br />

[page:constant NearestFilter] returns the value of the texture element that is nearest
(in Manhattan distance) to the specified texture coordinates.<br /><br />

[page:constant LinearFilter] is the default and returns the weighted average
of the four texture elements that are closest to the specified texture coordinates,
and can include items wrapped or repeated from other parts of a texture,
depending on the values of [page:Texture.wrapS wrapS] and [page:Texture.wrapT wrapT], and on the exact mapping.
</div>

<h2>Data Types</h2>
<h2>Minification Filters</h2>
<code>
THREE.NearestFilter
THREE.NearestMipMapNearestFilter
THREE.NearestMipMapLinearFilter
THREE.LinearFilter
THREE.LinearMipMapNearestFilter
THREE.LinearMipMapLinearFilter
</code>
<div>
THREE.UnsignedByteType<br />
THREE.ByteType<br />
THREE.ShortType<br />
THREE.UnsignedShortType<br />
THREE.IntType<br />
THREE.UnsignedIntType<br />
THREE.FloatType<br />
THREE.HalfFloatType
For use with a texture's [page:Texture.minFilter minFilter] property, these define
the texture minifying function that is used whenever the pixel being textured maps
to an area greater than one texture element (texel).<br /><br />

In addition to [page:constant NearestFilter] and [page:constant LinearFilter],
the following four functions can be used for minification:<br /><br />

[page:constant NearestMipMapNearestFilter] chooses the mipmap that most closely
matches the size of the pixel being textured
and uses the [page:constant NearestFilter] criterion (the texel nearest to the
center of the pixel) to produce a texture value.<br /><br />

[page:constant NearestMipMapLinearFilter] chooses the two mipmaps that most closely
match the size of the pixel being textured and uses the [page:constant NearestFilter] criterion to produce
a texture value from each mipmap. The final texture value is a weighted average of those two values.<br /><br />

[page:constant LinearMipMapNearestFilter] chooses the mipmap that most closely matches
the size of the pixel being textured and uses the [page:constant LinearFilter] criterion
(a weighted average of the four texels that are closest to the center of the pixel)
to produce a texture value.<br /><br />

[page:constant LinearMipMapLinearFilter] is the default and chooses the two mipmaps
that most closely match the size of the pixel being textured and uses the [page:constant LinearFilter] criterion
to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.<br /><br />

See the [example:webgl_materials_texture_filters materials / texture / filters] example.
</div>

<h2>Pixel Types</h2>
<div>
THREE.UnsignedShort4444Type<br />
THREE.UnsignedShort5551Type<br />
<h2>Types</h2>
<code>
THREE.UnsignedByteType
THREE.ByteType
THREE.ShortType
THREE.UnsignedShortType
THREE.IntType
THREE.UnsignedIntType
THREE.FloatType
THREE.HalfFloatType
THREE.UnsignedShort4444Type
THREE.UnsignedShort5551Type
THREE.UnsignedShort565Type
THREE.UnsignedInt248Type
</code>
<div>
For use with a texture's [page:Texture.type type] property, which must correspond to the correct format. See below for details.<br /><br />

[page:constant UnsignedByteType] is the default.
</div>

<h2>Pixel Formats</h2>
<div>
THREE.AlphaFormat<br />
THREE.RGBFormat<br />
THREE.RGBAFormat<br />
THREE.LuminanceFormat<br />
THREE.LuminanceAlphaFormat<br />
<h2>Formats</h2>
<code>
THREE.AlphaFormat
THREE.RGBFormat
THREE.RGBAFormat
THREE.LuminanceFormat
THREE.LuminanceAlphaFormat
THREE.RGBEFormat
THREE.DepthFormat
THREE.DepthStencilFormat
</code>
<div>
For use with a texture's [page:Texture.format format] property, these define
how elements of a 2d texture, or *texels*, are read by shaders.<br /><br />

[page:constant AlphaFormat] discards the red, green and blue components and reads just the alpha component.
The [page:Texture.type type] must be [page:constant UnsignedByteType].<br /><br />

[page:constant RGBFormat] discards the alpha components and reads the red, green and blue components.
The [page:Texture.type type] must be [page:constant UnsignedByteType] or [page:constant UnsignedShort565Type].<br /><br />

[page:constant RGBAFormat] is the default and reads the red, green, blue and alpha components.
The [page:Texture.type type] must be [page:constant UnsignedByteType], [page:constant UnsignedShort4444Type] or [page:constant THREE.UnsignedShort5551Type].<br /><br />

[page:constant LuminanceFormat] reads each element as a single luminance component.
This is then converted to a floating point, clamped to the range [0,1], and then assembled
into an RGBA element by placing the luminance value in the red, green and blue channels,
and attaching 1.0 to the alpha channel. The [page:Texture.type type] must be [page:constant UnsignedByteType].<br /><br />

[page:constant LuminanceAlphaFormat] reads each element as a luminance/alpha double.
The same process occurs as for the [page:constant LuminanceFormat], except that the
alpha channel may have values other than *1.0*. The [page:Texture.type type] must be [page:constant UnsignedByteType].<br /><br />

[page:constant RGBEFormat] is identical to [page:constant RGBAFormat].<br /><br />

[page:constant DepthFormat] reads each element as a single depth value, converts it to floating point, and clamps to the range [0,1].
The [page:Texture.type type] must be [page:constant UnsignedIntType] or [page:constant UnsignedShortType].
This is the default for [page:DepthTexture DepthTexture].<br /><br />

[page:constant DepthStencilFormat] reads each element is a pair of depth and stencil values.
The depth component of the pair is interpreted as in [page:constant DepthFormat].
The stencil component is interpreted based on the depth + stencil internal format.
The [page:Texture.type type] must be [page:constant UnsignedInt248Type].<br /><br />

Note that the texture must have the correct [page:Texture.type type] set, as described above.
See <a href="https://developer.mozilla.org/en/docs/Web/API/WebGLRenderingContext/texImage2D">this page</a> for details.
</div>

<h2>DDS / ST3C Compressed Texture Formats</h2>
<div>
THREE.RGB_S3TC_DXT1_Format<br />
THREE.RGBA_S3TC_DXT1_Format<br />
THREE.RGBA_S3TC_DXT3_Format<br />
<code>
THREE.RGB_S3TC_DXT1_Format
THREE.RGBA_S3TC_DXT1_Format
THREE.RGBA_S3TC_DXT3_Format
THREE.RGBA_S3TC_DXT5_Format
</code>
<div>
For use with a [page:CompressedTexture CompressedTexture]'s [page:Texture.format format] property,
these require support for the
<a href="https://www.khronos.org/registry/webgl/extensions/WEBGL_compressed_texture_s3tc/">WEBGL_compressed_texture_s3tc</a>
extension. <br />
According to <a href="http://webglstats.com/">WebglStats</a>, as of February 2016
over 80% of WebGL enabled devices support this extension.<br /><br />

There are four <a href="https://en.wikipedia.org/wiki/S3_Texture_Compression">S3TC</a> formats available via this extension. These are:<br />
[page:constant RGB_S3TC_DXT1_Format]: A DXT1-compressed image in an RGB image format.<br />
[page:constant RGBA_S3TC_DXT1_Format]: A DXT1-compressed image in an RGB image format with a simple on/off alpha value.<br />
[page:constant RGBA_S3TC_DXT3_Format]: A DXT3-compressed image in an RGBA image format. Compared to a 32-bit RGBA texture, it offers 4:1 compression.<br />
[page:constant RGBA_S3TC_DXT5_Format]: A DXT5-compressed image in an RGBA image format. It also provides a 4:1 compression, but differs to the DXT3 compression in how the alpha compression is done.<br />
</div>

<h2>PVRTC Compressed Texture Formats</h2>
<div>
THREE.RGB_PVRTC_4BPPV1_Format<br />
THREE.RGB_PVRTC_2BPPV1_Format<br />
THREE.RGBA_PVRTC_4BPPV1_Format<br />
<code>
THREE.RGB_PVRTC_4BPPV1_Format
THREE.RGB_PVRTC_2BPPV1_Format
THREE.RGBA_PVRTC_4BPPV1_Format
THREE.RGBA_PVRTC_2BPPV1_Format
</code>
<div>
For use with a [page:CompressedTexture CompressedTexture]'s [page:Texture.format format] property,
these require support for the <a href="https://www.khronos.org/registry/webgl/extensions/WEBGL_compressed_texture_pvrtc/">WEBGL_compressed_texture_pvrtc</a>
extension. <br />
According to <a href="http://webglstats.com/">WebglStats</a>, as of February 2016
less than 8% of WebGL enabled devices support this extenstion.
PVRTC is typically only available on mobile devices with PowerVR chipsets,
which are mainly Apple devices.<br /><br />

There are four <a href="https://en.wikipedia.org/wiki/PVRTC">PVRTC</a> formats available via this extension. These are:<br />
[page:constant RGB_PVRTC_4BPPV1_Format]: RGB compression in 4-bit mode. One block for each 4×4 pixels.<br />
[page:constant RGB_PVRTC_2BPPV1_Format]: RGB compression in 2-bit mode. One block for each 8×4 pixels.<br />
[page:constant RGBA_PVRTC_4BPPV1_Format]: RGBA compression in 4-bit mode. One block for each 4×4 pixels.<br />
[page:constant RGBA_PVRTC_2BPPV1_Format]: RGBA compression in 2-bit mode. One block for each 8×4 pixels.<br />
</div>

<h2>ETC Compressed Texture Format</h2>
<code>
THREE.RGB_ETC1_Format
</code>
<div>
For use with a [page:CompressedTexture CompressedTexture]'s [page:Texture.format format] property,
these require support for the <a href="https://www.khronos.org/registry/webgl/extensions/WEBGL_compressed_texture_etc1/">WEBGL_compressed_texture_etc1</a>
extension. <br />
According to <a href="http://webglstats.com/">WebglStats</a>, as of February 2016
just over 13% of WebGL enabled devices support this extenstion.<br /><br />
</div>

<h2>Encoding</h2>
<code>
THREE.LinearEncoding
THREE.sRGBEncoding
THREE.GammaEncoding
THREE.RGBEEncoding
THREE.LogLuvEncoding
THREE.RGBM7Encoding
THREE.RGBM16Encoding
THREE.RGBDEncoding
THREE.BasicDepthPacking
THREE.RGBADepthPacking
</code>
<div>
For use with a Texture's [page:Texture.encoding encoding] property.<br /><br />

If the encoding type is changed after the texture has already been used by a material,
you will need to set [page:Material.needsUpdate Material.needsUpdate] to *true* to make the material recompile.<br /><br />

[page:constant LinearEncoding] is the default.
Values other than this are only valid for a material's map, envMap and emissiveMap.
</div>

<h2>Source</h2>
Expand Down
2 changes: 1 addition & 1 deletion docs/api/materials/MeshBasicMaterial.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ <h3>[property:TextureCube envMap]</h3>
<h3>[property:Integer combine]</h3>
<div>How to combine the result of the surface's color with the environment map, if any.</div>

<div>Options are [page:Textures THREE.Multiply] (default), [page:Textures THREE.MixOperation], [page:Textures THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>
<div>Options are [page:Materials THREE.Multiply] (default), [page:Materials THREE.MixOperation], [page:Materials THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>

<h3>[property:Float reflectivity]</h3>
<div>How much the environment map affects the surface; also see "combine".</div>
Expand Down
2 changes: 1 addition & 1 deletion docs/api/materials/MeshLambertMaterial.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ <h3>[property:TextureCube envMap]</h3>
<h3>[property:Integer combine]</h3>
<div>How to combine the result of the surface's color with the environment map, if any.</div>

<div>Options are [page:Textures THREE.Multiply] (default), [page:Textures THREE.MixOperation], [page:Textures THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>
<div>Options are [page:Materials THREE.Multiply] (default), [page:Materials THREE.MixOperation], [page:Materials THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>

<h3>[property:Float reflectivity]</h3>
<div>How much the environment map affects the surface; also see "combine".</div>
Expand Down
2 changes: 1 addition & 1 deletion docs/api/materials/MeshPhongMaterial.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ <h3>[property:TextureCube envMap]</h3>
<h3>[property:Integer combine]</h3>
<div>How to combine the result of the surface's color with the environment map, if any.</div>

<div>Options are [page:Textures THREE.MultiplyOperation] (default), [page:Textures THREE.MixOperation], [page:Textures THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>
<div>Options are [page:Materials THREE.Multiply] (default), [page:Materials THREE.MixOperation], [page:Materials THREE.AddOperation]. If mix is chosen, the reflectivity is used to blend between the two colors.</div>

<h3>[property:Float reflectivity]</h3>
<div>How much the environment map affects the surface; also see "combine".</div>
Expand Down

0 comments on commit a88cf2b

Please sign in to comment.