You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
321 lines
12 KiB
321 lines
12 KiB
<!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">
|
|
Create a texture to apply to a surface or as a reflection or refraction map.
|
|
</p>
|
|
|
|
<p>
|
|
Note: After the initial use of a texture, its dimensions, format, and type cannot be changed. Instead, call [page:.dispose]() on the texture and instantiate a new one.
|
|
</p>
|
|
|
|
<h2>Code Example</h2>
|
|
|
|
<code>
|
|
// load a texture, set wrap mode to repeat
|
|
const texture = new THREE.TextureLoader().load( "textures/water.jpg" );
|
|
texture.wrapS = THREE.RepeatWrapping;
|
|
texture.wrapT = THREE.RepeatWrapping;
|
|
texture.repeat.set( 4, 4 );
|
|
</code>
|
|
|
|
<h2>Constructor</h2>
|
|
|
|
<h3>[name]( image, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, encoding )</h3>
|
|
|
|
<h2>Properties</h2>
|
|
|
|
<h3>[property:Integer id]</h3>
|
|
<p>
|
|
Readonly - unique number for this texture instance.
|
|
</p>
|
|
|
|
<h3>[property:Boolean isTexture]</h3>
|
|
<p>
|
|
Read-only flag to check if a given object is of type [name].
|
|
</p>
|
|
|
|
<h3>[property:String uuid]</h3>
|
|
<p>
|
|
[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
|
|
This gets automatically assigned, so this shouldn't be edited.
|
|
</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:Image image]</h3>
|
|
<p>
|
|
An image object, typically created using the [page:TextureLoader.load] method.
|
|
This can be any image (e.g., PNG, JPG, GIF, DDS) or video (e.g., MP4, OGG/OGV) type supported by three.js.<br /><br />
|
|
|
|
To use video as a texture you need to have a playing HTML5
|
|
video element as a source for your texture image and continuously update this texture
|
|
as long as video is playing - the [page:VideoTexture VideoTexture] class handles this automatically.
|
|
</p>
|
|
|
|
<h3>[property:Array mipmaps]</h3>
|
|
<p>
|
|
Array of user-specified mipmaps (optional).
|
|
</p>
|
|
|
|
<h3>[property:number mapping]</h3>
|
|
<p>
|
|
How the image is applied to the object. An object type of [page:Textures THREE.UVMapping] is the default,
|
|
where the U,V coordinates are used to apply the map.<br />
|
|
|
|
See the [page:Textures texture constants] page for other mapping types.
|
|
</p>
|
|
|
|
<h3>[property:number wrapS]</h3>
|
|
<p>
|
|
This defines how the texture is wrapped horizontally and corresponds to *U* in UV mapping.<br />
|
|
The default is [page:Textures THREE.ClampToEdgeWrapping], where the edge is clamped to the outer edge texels.
|
|
The other two choices are [page:Textures THREE.RepeatWrapping] and [page:Textures THREE.MirroredRepeatWrapping].
|
|
See the [page:Textures texture constants] page for details.
|
|
</p>
|
|
|
|
<h3>[property:number wrapT]</h3>
|
|
<p>
|
|
This defines how the texture is wrapped vertically and corresponds to *V* in UV mapping.<br />
|
|
The same choices are available as for [property:number wrapS].<br /><br />
|
|
|
|
NOTE: tiling of images in textures only functions if image dimensions are powers of two
|
|
(2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, ...) in terms of pixels.
|
|
Individual dimensions need not be equal, but each must be a power of two.
|
|
This is a limitation of WebGL, not three.js.
|
|
</p>
|
|
|
|
<h3>[property:number magFilter]</h3>
|
|
<p>
|
|
How the texture is sampled when a texel covers more than one pixel. The default is
|
|
[page:Textures THREE.LinearFilter], which takes the four closest texels and bilinearly interpolates among them.
|
|
The other option is [page:Textures THREE.NearestFilter], which uses the value of the closest texel.<br />
|
|
See the [page:Textures texture constants] page for details.
|
|
</p>
|
|
|
|
<h3>[property:number minFilter]</h3>
|
|
<p>
|
|
How the texture is sampled when a texel covers less than one pixel. The default is
|
|
[page:Textures THREE.LinearMipmapLinearFilter], which uses mipmapping and a trilinear filter. <br /><br />
|
|
|
|
See the [page:Textures texture constants] page for all possible choices.
|
|
</p>
|
|
|
|
<h3>[property:number anisotropy]</h3>
|
|
<p>
|
|
The number of samples taken along the axis through the pixel that has the highest density of texels.
|
|
By default, this value is 1. A higher value gives a less blurry result than a basic mipmap,
|
|
at the cost of more texture samples being used. Use [page:WebGLRenderer.capabilities renderer.capabilities.getMaxAnisotropy]() to
|
|
find the maximum valid anisotropy value for the GPU; this value is usually a power of 2.
|
|
</p>
|
|
|
|
<h3>[property:number format]</h3>
|
|
<p>
|
|
The default is [page:Textures THREE.RGBAFormat].<br /><br />
|
|
|
|
See the [page:Textures texture constants] page for details of other formats.
|
|
</p>
|
|
|
|
<h3>[property:String internalFormat]</h3>
|
|
<p>
|
|
The default value is obtained using a combination of [page:Texture.format .format] and
|
|
[page:Texture.type .type].<br />
|
|
|
|
The GPU format allows the developer to specify how the data is going to be
|
|
stored on the GPU.<br /><br />
|
|
|
|
See the [page:Textures texture constants] page for details regarding all supported internal formats.
|
|
</p>
|
|
|
|
<h3>[property:number type]</h3>
|
|
<p>
|
|
This must correspond to the [page:Texture.format .format]. The default is [page:Textures THREE.UnsignedByteType],
|
|
which will be used for most texture formats.<br /><br />
|
|
|
|
See the [page:Textures texture constants] page for details of other formats.
|
|
</p>
|
|
|
|
<h3>[property:Vector2 offset]</h3>
|
|
<p>
|
|
How much a single repetition of the texture is offset from the beginning, in each direction U and V.
|
|
Typical range is `0.0` to `1.0`.
|
|
</p>
|
|
<p>
|
|
The below texture types share the `first` uv channel in the engine. The offset (and repeat) setting is evaluated according to
|
|
the following priorities and then shared by those textures:
|
|
<ol>
|
|
<li>color map</li>
|
|
<li>specular map</li>
|
|
<li>displacement map</li>
|
|
<li>normal map</li>
|
|
<li>bump map</li>
|
|
<li>roughness map</li>
|
|
<li>metalness map</li>
|
|
<li>alpha map</li>
|
|
<li>emissive map</li>
|
|
<li>clearcoat map</li>
|
|
<li>clearcoat normal map</li>
|
|
<li>clearcoat roughnessMap map</li>
|
|
</ol>
|
|
</p>
|
|
<p>
|
|
The below texture types share the `second` uv channel in the engine. The offset (and repeat) setting is evaluated according to
|
|
the following priorities and then shared by those textures:
|
|
<ol>
|
|
<li>ao map</li>
|
|
<li>light map</li>
|
|
</ol>
|
|
</p>
|
|
|
|
<h3>[property:Vector2 repeat]</h3>
|
|
<p>
|
|
How many times the texture is repeated across the surface, in each direction U and V. If repeat is set
|
|
greater than 1 in either direction, the corresponding Wrap parameter should also be set to
|
|
[page:Textures THREE.RepeatWrapping] or [page:Textures THREE.MirroredRepeatWrapping] to achieve the desired
|
|
tiling effect. Setting different repeat values for textures is restricted in the same way like [page:.offset].
|
|
</p>
|
|
|
|
<h3>[property:number rotation]</h3>
|
|
<p>
|
|
How much the texture is rotated around the center point, in radians. Positive values are counter-clockwise. Default is `0`.
|
|
</p>
|
|
|
|
<h3>[property:Vector2 center]</h3>
|
|
<p>
|
|
The point around which rotation occurs. A value of (0.5, 0.5) corresponds to the center of the texture. Default is (0, 0), the lower left.
|
|
</p>
|
|
|
|
<h3>[property:Boolean matrixAutoUpdate]</h3>
|
|
<p>
|
|
Whether to update the texture's uv-transform [page:Texture.matrix .matrix] from the texture properties [page:Texture.offset .offset], [page:Texture.repeat .repeat],
|
|
[page:Texture.rotation .rotation], and [page:Texture.center .center]. True by default.
|
|
Set this to false if you are specifying the uv-transform matrix directly.
|
|
</p>
|
|
|
|
<h3>[property:Matrix3 matrix]</h3>
|
|
<p>
|
|
The uv-transform matrix for the texture. Updated by the renderer from the texture properties [page:Texture.offset .offset], [page:Texture.repeat .repeat],
|
|
[page:Texture.rotation .rotation], and [page:Texture.center .center] when the texture's [page:Texture.matrixAutoUpdate .matrixAutoUpdate] property is true.
|
|
When [page:Texture.matrixAutoUpdate .matrixAutoUpdate] property is false, this matrix may be set manually.
|
|
Default is the identity matrix.
|
|
</p>
|
|
|
|
<h3>[property:Boolean generateMipmaps]</h3>
|
|
<p>
|
|
Whether to generate mipmaps (if possible) for a texture. True by default. Set this to false if you are
|
|
creating mipmaps manually.
|
|
</p>
|
|
|
|
<h3>[property:Boolean premultiplyAlpha]</h3>
|
|
<p>
|
|
If set to `true`, the alpha channel, if present, is multiplied into the color channels when the texture is uploaded to the GPU. Default is `false`.<br /><br />
|
|
|
|
Note that this property has no effect for [link:https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap ImageBitmap].
|
|
You need to configure on bitmap creation instead. See [page:ImageBitmapLoader].
|
|
</p>
|
|
|
|
<h3>[property:Boolean flipY]</h3>
|
|
<p>
|
|
If set to `true`, the texture is flipped along the vertical axis when uploaded to the GPU. Default is `true`.<br /><br />
|
|
|
|
Note that this property has no effect for [link:https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap ImageBitmap].
|
|
You need to configure on bitmap creation instead. See [page:ImageBitmapLoader].
|
|
</p>
|
|
|
|
<h3>[property:number unpackAlignment]</h3>
|
|
<p>
|
|
4 by default. Specifies the alignment requirements for the start of each pixel row in memory.
|
|
The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes),
|
|
4 (word-alignment), and 8 (rows start on double-word boundaries).
|
|
See [link:http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPixelStorei.xml glPixelStorei]
|
|
for more information.
|
|
</p>
|
|
|
|
<h3>[property:number encoding]</h3>
|
|
<p>
|
|
[page:Textures THREE.LinearEncoding] is the default.
|
|
See the [page:Textures texture constants] page for details of other formats.<br /><br />
|
|
|
|
Note that if this value is changed on a texture after the material has been used,
|
|
it is necessary to trigger a Material.needsUpdate for this value to be realized in the shader.
|
|
</p>
|
|
|
|
<h3>[property:Integer version]</h3>
|
|
<p>
|
|
This starts at `0` and counts how many times [page:Texture.needsUpdate .needsUpdate] is set to `true`.
|
|
</p>
|
|
|
|
<h3>[property:Function onUpdate]</h3>
|
|
<p>
|
|
A callback function, called when the texture is updated (e.g., when needsUpdate has been set to true
|
|
and then the texture is used).
|
|
</p>
|
|
|
|
<h3>[property:Boolean needsUpdate]</h3>
|
|
<p>
|
|
Set this to `true` to trigger an update next time the texture is used. Particularly important for setting the wrap mode.
|
|
</p>
|
|
|
|
<h3>[property:Object userData]</h3>
|
|
<p>
|
|
An object that can be used to store custom data about the texture. It should not hold
|
|
references to functions as these will not be cloned.
|
|
</p>
|
|
|
|
<h3>[property:Source source]</h3>
|
|
<p>
|
|
The data definition of a texture. A reference to the data source can be shared across textures.
|
|
This is often useful in context of spritesheets where multiple textures render the same data but with different texture transformations.
|
|
</p>
|
|
|
|
<h2>Methods</h2>
|
|
|
|
<p>[page:EventDispatcher EventDispatcher] methods are available on this class.</p>
|
|
|
|
<h3>[method:undefined updateMatrix]()</h3>
|
|
<p>
|
|
Update the texture's uv-transform [page:Texture.matrix .matrix] from the texture properties [page:Texture.offset .offset], [page:Texture.repeat .repeat],
|
|
[page:Texture.rotation .rotation], and [page:Texture.center .center].
|
|
</p>
|
|
|
|
<h3>[method:Texture clone]()</h3>
|
|
<p>
|
|
Make copy of the texture. Note this is not a "deep copy", the image is shared.
|
|
Besides, cloning a texture does not automatically mark it for a texture upload. You have to set [page:Texture.needsUpdate .needsUpdate] to true as soon as its image property (the data source) is fully loaded or ready.
|
|
</p>
|
|
|
|
<h3>[method:Object toJSON]( [param:Object meta] )</h3>
|
|
<p>
|
|
meta -- optional object containing metadata.<br />
|
|
Convert the texture to three.js [link:https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 JSON Object/Scene format].
|
|
</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>
|
|
|
|
<h3>[method:Vector2 transformUv]( [param:Vector2 uv] )</h3>
|
|
<p>
|
|
Transform the uv based on the value of this texture's [page:Texture.offset .offset], [page:Texture.repeat .repeat],
|
|
[page:Texture.wrapS .wrapS], [page:Texture.wrapT .wrapT] and [page:Texture.flipY .flipY] properties.
|
|
</p>
|
|
|
|
<h2>Source</h2>
|
|
|
|
<p>
|
|
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
|
|
</p>
|
|
</body>
|
|
</html>
|
|
|