Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved documentation for docs / Texture #10012

Merged
merged 2 commits into from
Nov 4, 2016
Merged

Improved documentation for docs / Texture #10012

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a1efe46
Improved documentation for docs / Texture
looeee Nov 4, 2016
9210f7b
Removed duplicate needsUpate
looeee Nov 4, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 107 additions & 39 deletions docs/api/textures/Texture.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,128 +31,196 @@ <h2>Properties</h2>

<h3>[property:Integer id]</h3>
<div>
Unique number for this texture instance.
Readonly - unique number for this texture instance.
</div>

<h3>[property:Image image]</h3>
<h3>[property:String uuid]</h3>
<div>
An Image object, typically created using the ImageUtils or [page:ImageLoader ImageLoader] classes. The Image object can include an image (e.g., PNG, JPG, GIF, DDS), video (e.g., MP4, OGG/OGV), or set of six images for a cube map. 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.
[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
This gets automatically assigned, so this shouldn't be edited.
</div>

<h3>[property:object mapping]</h3>
<h3>[property:String name]</h3>
<div>
How the image is applied to the object. An object type of THREE.UVMapping is the default, where the U,V coordinates are used to apply the map, and a single texture is expected. The other types are THREE.CubeReflectionMapping, for cube maps used as a reflection map; THREE.CubeRefractionMapping, refraction mapping; and THREE.SphericalReflectionMapping, a spherical reflection map projection.
Optional name of the object (doesn't need to be unique). Default is an empty string.
</div>

<h3>[property:number wrapS]</h3>
<h3>[property:Image image]</h3>
<div>
The default is THREE.ClampToEdgeWrapping, where the edge is clamped to the outer edge texels. The other two choices are THREE.RepeatWrapping and THREE.MirroredRepeatWrapping.
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.<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.
</div>

<h3>[property:number wrapT]</h3>
<h3>[property:string sourceFile]</h3>
<div>
The default is THREE.ClampToEdgeWrapping, where the edge is clamped to the outer edge texels. The other two choices are THREE.RepeatWrapping and THREE.MirroredRepeatWrapping.
This property is currently unused.
</div>

<h3>[property:array mipmaps]</h3>
<div>
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.
Array of user-specified mipmaps (optional).
</div>

<h3>[property:number magFilter]</h3>
<h3>[property:object mapping]</h3>
<div>
How the texture is sampled when a texel covers more than one pixel. The default is THREE.LinearFilter, which takes the four closest texels and bilinearly interpolates among them. The other option is THREE.NearestFilter, which uses the value of the closest texel.
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.
</div>

<h3>[property:number minFilter]</h3>
<h3>[property:number wrapS]</h3>
<div>
How the texture is sampled when a texel covers less than one pixel. The default is THREE.LinearMipMapLinearFilter, which uses mipmapping and a trilinear filter. Other choices are THREE.NearestFilter, THREE.NearestMipMapNearestFilter, THREE.NearestMipMapLinearFilter, THREE.LinearFilter, and THREE.LinearMipMapNearestFilter. These vary whether the nearest texel or nearest four texels are retrieved on the nearest mipmap or nearest two mipmaps. Interpolation occurs among the samples retrieved.
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.
</div>

<h3>[property:number format]</h3>
<h3>[property:number wrapT]</h3>
<div>
The default is THREE.RGBAFormat for the texture. Other formats are: THREE.AlphaFormat, THREE.RGBFormat, THREE.LuminanceFormat, and THREE.LuminanceAlphaFormat. There are also compressed texture formats, if the S3TC extension is supported: THREE.RGB_S3TC_DXT1_Format, THREE.RGBA_S3TC_DXT1_Format, THREE.RGBA_S3TC_DXT3_Format, and THREE.RGBA_S3TC_DXT5_Format.
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.
</div>

<h3>[property:number type]</h3>
<h3>[property:number magFilter]</h3>
<div>
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.
</div>

<h3>[property:number minFilter]</h3>
<div>
The default is THREE.UnsignedByteType. Other valid types (as WebGL allows) are THREE.ByteType, THREE.ShortType, THREE.UnsignedShortType, THREE.IntType, THREE.UnsignedIntType, THREE.FloatType, THREE.UnsignedShort4444Type, THREE.UnsignedShort5551Type, and THREE.UnsignedShort565Type.
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.
</div>

<h3>[property:number anisotropy]</h3>
<div>
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 renderer.getMaxAnisotropy() to find the maximum valid anisotropy value for the GPU; this value is usually a power of 2.
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.getMaxAnisotropy renderer.getMaxAnisotropy]() to
find the maximum valid anisotropy value for the GPU; this value is usually a power of 2.
</div>

<h3>[property:boolean needsUpdate]</h3>
<h3>[property:number format]</h3>
<div>
If a texture is changed after creation, set this flag to true so that the texture is properly set up. Particularly important for setting the wrap mode.
The default is [page:Textures THREE.RGBAFormat], although the [page:TextureLoader TextureLoader] will automatically
et this to [page:Textures THREE.RGBFormat] for JPG images. <br /><br />

See the [page:Textures texture constants] page for details of other formats.
</div>

<h3>[property:Vector2 repeat]</h3>
<h3>[property:number type]</h3>
<div>
How many times the texture is repeated across the surface, in each direction U and V.
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.
</div>

<h3>[property:Vector2 offset]</h3>
<div>
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.
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*.
</div>

<h3>[property:string name]</h3>
<h3>[property:Vector2 repeat]</h3>
<div>
Given name of the texture, empty string by default.
How many times the texture is repeated across the surface, in each direction U and V.
</div>

<h3>[property:boolean generateMipmaps]</h3>
<div>
Whether to generate mipmaps (if possible) for a texture. True by default.
Whether to generate mipmaps (if possible) for a texture. True by default. Set this to false if you are
creating mipmaps manually.
</div>

<h3>[property:boolean premultiplyAlpha]</h3>
<div>
False by default, which is the norm for PNG images. Set to true if the RGB values have
been stored premultiplied by alpha.
</div>

<h3>[property:boolean flipY]</h3>
<div>
True by default. Flips the image's Y axis to match the WebGL texture coordinate space.
</div>

<h3>[property:array mipmaps]</h3>
<h3>[property:number unpackAlignment]</h3>
<div>
Array of user-specified mipmaps (optional).
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 <a href="http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPixelStorei.xml">glPixelStorei</a>
for more information.
</div>

<h3>[property:number unpackAlignment]</h3>
<h3>[property:number encoding]</h3>
<div>
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 <a href="http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPixelStorei.xml">glPixelStorei</a> for more information.
[page:Textures THREE.LinearEncoding] is the default.
See the [page:Textures texture constants] page for details of other formats.<br /><br />

Note that ff 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.
</div>

<h3>[property:boolean premultiplyAlpha]</h3>
<h3>[property:Integer version]</h3>
<div>
False by default, which is the norm for PNG images. Set to true if the RGB values have been stored premultiplied by alpha.
This starts at *0* and counts how many times [property:Boolean needsUpdate] is set to *true*.
</div>

<h3>[property:number encoding]</h3>
<h3>[property:Function onUpdate]</h3>
<div>
Set to THREE.LinearEncoding by default, but supports sRGB, RGBE, RGBM, RGBD, LogLuv and Gamma corrected encodings. IMPORTANT: 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.
A callback function, called when the texture is updated (e.g., when needsUpdate has been set to true
and then the texture is used).
</div>

<h3>[property:object onUpdate]</h3>
<h3>[property:Boolean needsUpdate]</h3>
<div>
A callback function, called when the texture is updated (e.g., when needsUpdate has been set to true and then the texture is used).
Set this to *true* to trigger an update next time the texture is used. Particularly important for setting the wrap mode.
</div>


<h2>Methods</h2>

<h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>

<h3>[method:Material clone]( [page:Texture texture] )</h3>
<h3>[method:Texture clone]( [page:Texture texture] )</h3>
<div>
Make copy of texture. Note this is not a "deep copy", the image is shared.
Make copy of the texture. Note this is not a "deep copy", the image is shared.
</div>

<h3>[method:Texture toJSON]( meta )</h3>
<div>
meta -- optional object containing metadata.<br />
Convert the material to Three JSON format.
</div>

<h3>[method:null dispose]()</h3>
<div>
Call [page:EventDispatcher EventDispatcher].dispatchEvent with a 'dispose' event type.
</div>

<h3>[method:null transformUv]( uv )</h3>
<div>
Transform the uv based on the value of this texture's [page:Texture.repeat .repeat], [page:Texture.offset .offset],
[page:Texture.wrapS .wrapS], [page:Texture.wrapT .wrapT] and [page:Texture.flipY .flipY] properties.
</div>

<h2>Source</h2>

[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
Expand Down