gitadmin
/
three.js
mirror of https://github.com/mrdoob/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
							<!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, colorSpace )
		</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:Integer channel]</h3>
		<p>
			Lets you select the uv attribute to map the texture to. `0` for `uv`,
			`1` for `uv1`, `2` for `uv2` and `3` for `uv3`.
		</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>

		<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.
		</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:string colorSpace]</h3>
		<p>
			[page:Textures THREE.NoColorSpace] is the default. Textures containing color data should be
			annotated with [page:Textures THREE.SRGBColorSpace] or
			[page:Textures THREE.LinearSRGBColorSpace].
		</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.
			Default is an empty object `{}`.
		</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>