Texture.html 10.9 KB
Newer Older
M
Mr.doob 已提交
1 2 3 4
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
M
Mr.doob 已提交
5
		<base href="../../../" />
M
Mr.doob 已提交
6 7 8 9 10 11 12
		<script src="list.js"></script>
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>[name]</h1>

13
		<p class="desc">Create a texture to apply to a surface or as a reflection or refraction map.</p>
M
Mr.doob 已提交
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32


		<h2>Constructor</h2>

		<h3>[name]( image, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, encoding )</h3>

		<h2>Example</h2>

		<code>
		// load a texture, set wrap mode to repeat
		var texture = new THREE.TextureLoader().load( "textures/water.jpg" );
		texture.wrapS = THREE.RepeatWrapping;
		texture.wrapT = THREE.RepeatWrapping;
		texture.repeat.set( 4, 4 );
		</code>

		<h2>Properties</h2>

		<h3>[property:Integer id]</h3>
33
		<p>
M
Mr.doob 已提交
34
		Readonly - unique number for this texture instance.
35
		</p>
M
Mr.doob 已提交
36 37

		<h3>[property:String uuid]</h3>
38
		<p>
M
Mr.doob 已提交
39 40
		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
		This gets automatically assigned, so this shouldn't be edited.
41
		</p>
M
Mr.doob 已提交
42 43

		<h3>[property:String name]</h3>
44
		<p>
M
Mr.doob 已提交
45
		Optional name of the object (doesn't need to be unique). Default is an empty string.
46
		</p>
M
Mr.doob 已提交
47 48

		<h3>[property:Image image]</h3>
49
		<p>
M
Mr.doob 已提交
50 51 52 53 54 55
		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.
56
		</p>
M
Mr.doob 已提交
57

58 59 60 61 62 63 64
		<h3>[property:Boolean isTexture]</h3>
		<p>
			Used to check whether this or derived classes are Textures. Default is *true*.<br /><br />

			You should not change this, as it is used internally for optimisation.
		</p>

M
Mr.doob 已提交
65
		<h3>[property:array mipmaps]</h3>
66
		<p>
M
Mr.doob 已提交
67
		Array of user-specified mipmaps (optional).
68
		</p>
M
Mr.doob 已提交
69

70
		<h3>[property:number mapping]</h3>
71
		<p>
M
Mr.doob 已提交
72 73 74 75
		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.
76
		</p>
M
Mr.doob 已提交
77 78

		<h3>[property:number wrapS]</h3>
79
		<p>
M
Mr.doob 已提交
80 81 82 83
		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.
84
		</p>
M
Mr.doob 已提交
85 86

		<h3>[property:number wrapT]</h3>
87
		<p>
M
Mr.doob 已提交
88 89 90 91 92 93 94
		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.
95
		</p>
M
Mr.doob 已提交
96 97

		<h3>[property:number magFilter]</h3>
98
		<p>
M
Mr.doob 已提交
99 100 101 102
		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.
103
		</p>
M
Mr.doob 已提交
104 105

		<h3>[property:number minFilter]</h3>
106
		<p>
M
Mr.doob 已提交
107 108 109 110
		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.
111
		</p>
M
Mr.doob 已提交
112 113

		<h3>[property:number anisotropy]</h3>
114
		<p>
M
Mr.doob 已提交
115 116 117 118
		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.
119
		</p>
M
Mr.doob 已提交
120 121

		<h3>[property:number format]</h3>
122
		<p>
M
Mr.doob 已提交
123 124 125 126
		The default is [page:Textures THREE.RGBAFormat], although the [page:TextureLoader TextureLoader] will automatically
		set this to [page:Textures THREE.RGBFormat] for JPG images. <br /><br />

		See the [page:Textures texture constants] page for details of other formats.
127
		</p>
M
Mr.doob 已提交
128 129

		<h3>[property:number type]</h3>
130
		<p>
M
Mr.doob 已提交
131 132 133 134
		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.
135
		</p>
M
Mr.doob 已提交
136 137

		<h3>[property:Vector2 offset]</h3>
138
		<p>
M
Mr.doob 已提交
139
		How much a single repetition of the texture is offset from the beginning, in each direction U and V.
140
		Typical range is *0.0* to *1.0*.  _Note:_ The offset property is a convenience modifier and only affects
M
Mr.doob 已提交
141
		the Texture's application to the first set of UVs on a model.  If the Texture is used as a map requiring
142
		additional UV sets (e.g. the aoMap or lightMap of most stock materials), those UVs must be manually
M
Mr.doob 已提交
143
		assigned to achieve the desired offset.
144
		</p>
M
Mr.doob 已提交
145 146

		<h3>[property:Vector2 repeat]</h3>
147
		<p>
148 149 150 151
		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.  _Note:_ The repeat property is a convenience modifier and only affects
M
Mr.doob 已提交
152
		the Texture's application to the first set of UVs on a model.  If the Texture is used as a map requiring
153
		additional UV sets (e.g. the aoMap or lightMap of most stock materials), those UVs must be manually
M
Mr.doob 已提交
154
		assigned to achieve the desired repetiton.
155
		</p>
M
Mr.doob 已提交
156 157

		<h3>[property:number rotation]</h3>
158
		<p>
M
Mauro Ghini 已提交
159
		How much the texture is rotated around the center point, in radians. Positive values are counter-clockwise. Default is *0*.
160
		</p>
M
Mr.doob 已提交
161 162

		<h3>[property:Vector2 center]</h3>
163
		<p>
W
WestLangley 已提交
164
		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.
165
		</p>
M
Mr.doob 已提交
166 167

		<h3>[property:boolean matrixAutoUpdate]</h3>
168
		<p>
W
WestLangley 已提交
169 170
		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.
M
Mr.doob 已提交
171
		Set this to false if you are specifying the uv-transform matrix directly.
172
		</p>
M
Mr.doob 已提交
173 174

		<h3>[property:Matrix3 matrix]</h3>
175
		<p>
W
WestLangley 已提交
176 177 178
		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.
M
Michael Blix 已提交
179
		Default is the identity matrix.
180
		</p>
M
Mr.doob 已提交
181 182

		<h3>[property:boolean generateMipmaps]</h3>
183
		<p>
M
Mr.doob 已提交
184 185
		Whether to generate mipmaps (if possible) for a texture. True by default. Set this to false if you are
		creating mipmaps manually.
186
		</p>
M
Mr.doob 已提交
187 188

		<h3>[property:boolean premultiplyAlpha]</h3>
189
		<p>
190 191
		If set to *true*, the alpha channel, if present, is multiplied into the color channels when the texture is uploaded to the GPU. Defaut is *false*.<br /><br />

192 193
		Note that this property has no effect for [link:https://developer.mozilla.org/de/docs/Web/API/ImageBitmap ImageBitmap].
		You need to configure on bitmap creation instead. See [page:ImageBitmapLoader].
194
		</p>
M
Mr.doob 已提交
195 196

		<h3>[property:boolean flipY]</h3>
197
		<p>
198 199
		If set to *true*, the texture is flipped along the vertical axis when uploaded to the GPU. Default is *true*.<br /><br />

200 201
		Note that this property has no effect for [link:https://developer.mozilla.org/de/docs/Web/API/ImageBitmap ImageBitmap].
		You need to configure on bitmap creation instead. See [page:ImageBitmapLoader].
202
		</p>
M
Mr.doob 已提交
203 204

		<h3>[property:number unpackAlignment]</h3>
205
		<p>
M
Mr.doob 已提交
206 207 208
		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).
M
Mugen87 已提交
209
		See [link:http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPixelStorei.xml glPixelStorei]
M
Mr.doob 已提交
210
		for more information.
211
		</p>
M
Mr.doob 已提交
212 213

		<h3>[property:number encoding]</h3>
214
		<p>
M
Mr.doob 已提交
215 216 217
		[page:Textures THREE.LinearEncoding] is the default.
		See the [page:Textures texture constants] page for details of other formats.<br /><br />

M
Magnuz Binder 已提交
218
		Note that if this value is changed on a texture after the material has been used,
M
Mr.doob 已提交
219
		it is necessary to trigger a Material.needsUpdate for this value to be realized in the shader.
220
		</p>
M
Mr.doob 已提交
221 222

		<h3>[property:Integer version]</h3>
223
		<p>
M
Mr.doob 已提交
224
		This starts at *0* and counts how many times [property:Boolean needsUpdate] is set to *true*.
225
		</p>
M
Mr.doob 已提交
226 227

		<h3>[property:Function onUpdate]</h3>
228
		<p>
M
Mr.doob 已提交
229 230
		A callback function, called when the texture is updated (e.g., when needsUpdate has been set to true
		and then the texture is used).
231
		</p>
M
Mr.doob 已提交
232 233

		<h3>[property:Boolean needsUpdate]</h3>
234
		<p>
M
Mr.doob 已提交
235
		Set this to *true* to trigger an update next time the texture is used. Particularly important for setting the wrap mode.
236
		</p>
M
Mr.doob 已提交
237 238 239 240 241 242


		<h2>Methods</h2>

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

W
WestLangley 已提交
243 244 245 246 247 248
		<h3>[method:null 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>

249
		<h3>[method:Texture clone]()</h3>
250
		<p>
M
Mr.doob 已提交
251
		Make copy of the texture. Note this is not a "deep copy", the image is shared.
252
		</p>
M
Mr.doob 已提交
253

254
		<h3>[method:Texture toJSON]( [param:Object meta] )</h3>
255
		<p>
M
Mr.doob 已提交
256 257
		meta -- optional object containing metadata.<br />
		Convert the material to three.js JSON format.
258
		</p>
M
Mr.doob 已提交
259 260

		<h3>[method:null dispose]()</h3>
261
		<p>
M
Mr.doob 已提交
262
		Call [page:EventDispatcher EventDispatcher].dispatchEvent with a 'dispose' event type.
263
		</p>
M
Mr.doob 已提交
264

M
Mr.doob 已提交
265
		<h3>[method:Vector2 transformUv]( [param:Vector2 uv] )</h3>
266
		<p>
W
WestLangley 已提交
267
		Transform the uv based on the value of this texture's [page:Texture.offset .offset], [page:Texture.repeat .repeat],
M
Mr.doob 已提交
268
		[page:Texture.wrapS .wrapS], [page:Texture.wrapT .wrapT] and [page:Texture.flipY .flipY] properties.
269
		</p>
M
Mr.doob 已提交
270 271 272 273 274 275

		<h2>Source</h2>

		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
	</body>
</html>