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

13
		<p class="desc">
L
Lewy Blue 已提交
14
			This is the base class for most objects in three.js and provides a set of properties and methods
L
looeee 已提交
15 16 17 18
			for manipulating objects in 3D space.<br /><br />

			Note that this can be used for grouping objects via the [page:.add]( object ) method
			which adds the object as a child, however it is better to use [page:Group] for this.
19
		</p>
20 21 22 23


		<h2>Constructor</h2>

C
cjshannon 已提交
24

25
		<h3>[name]()</h3>
26
		<p>
G
Greg Tatum 已提交
27
		The constructor takes no arguments.
28
		</p>
29 30 31 32


		<h2>Properties</h2>

L
looeee 已提交
33
		<h3>[property:Boolean castShadow]</h3>
34
		<p>Whether the object gets rendered into shadow map. Default is *false*.</p>
35

L
looeee 已提交
36
		<h3>[property:Object3D children]</h3>
37
		<p>Array with object's children. See [page:Group] for info on manually grouping objects.</p>
38

39 40 41 42 43 44 45 46 47 48
		<h3>[property:Material customDepthMaterial]</h3>
		<p>
		Custom depth material to be used when rendering to the depth map. Can only be used in context of meshes.
		When shadow-casting with a [page:DirectionalLight] or [page:SpotLight], if you are (a) modifying vertex positions in the vertex shader,
		(b) using a displacement map, (c) using an alpha map with alphaTest, or (d) using a transparent texture with alphaTest,
		you must specify a customDepthMaterial for proper shadows. Default is *undefined*.
		</p>

		<h3>[property:Material customDistanceMaterial]</h3>
		<p>
49
		Same as [page:.customDepthMaterial customDepthMaterial], but used with [page:PointLight]. Default is *undefined*.
50 51
		</p>

L
looeee 已提交
52
		<h3>[property:Boolean frustumCulled]</h3>
53
		<p>
L
looeee 已提交
54
		When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
55
		Otherwise the object gets rendered every frame even if it isn't visible. Default is *true*.
56
		</p>
M
Mr.doob 已提交
57

L
looeee 已提交
58
		<h3>[property:Integer id]</h3>
59
		<p>readonly – Unique number for this object instance.</p>
M
Mr.doob 已提交
60

G
Gerdon Abbink 已提交
61
		<h3>[property:Boolean isObject3D]</h3>
62
		<p>
L
looeee 已提交
63
			Used to check whether this or derived classes are Object3Ds. Default is *true*.<br /><br />
64

J
Jing Ma 已提交
65
			You should not change this, as it is used internally for optimisation.
66
		</p>
67

L
looeee 已提交
68
		<h3>[property:Layers layers]</h3>
69
		<p>
L
looeee 已提交
70 71
		The layer membership of the object. The object is only visible if it has at least one
		layer in common with the [page:Camera] in use.
72
		</p>
73

L
looeee 已提交
74
		<h3>[property:Matrix4 matrix]</h3>
75
		<p>The local transform matrix.</p>
76

L
looeee 已提交
77
		<h3>[property:Boolean matrixAutoUpdate]</h3>
78
		<p>
L
looeee 已提交
79
		When this is set, it calculates the matrix of position, (rotation or quaternion) and
80
		scale every frame and also recalculates the matrixWorld property. Default is [page:Object3D.DefaultMatrixAutoUpdate] (true).
81
		</p>
82

L
looeee 已提交
83
		<h3>[property:Matrix4 matrixWorld]</h3>
84
		<p>
J
Jing Ma 已提交
85
		The global transform of the object. If the Object3D has no parent, then it's identical to
L
looeee 已提交
86
		the local transform [page:.matrix].
87
		</p>
88

L
looeee 已提交
89
		<h3>[property:Boolean matrixWorldNeedsUpdate]</h3>
90
		<p>
L
looeee 已提交
91 92
		When this is set, it calculates the matrixWorld in that frame and resets this property
		 to false. Default is *false*.
93
		</p>
94

L
looeee 已提交
95
		<h3>[property:Matrix4 modelViewMatrix]</h3>
96
		<p>This is passed to the shader and used to calculate the position of the object.</p>
97

L
looeee 已提交
98
		<h3>[property:String name]</h3>
99
		<p>Optional name of the object (doesn't need to be unique). Default is an empty string.</p>
L
looeee 已提交
100 101

		<h3>[property:Matrix3 normalMatrix]</h3>
102
		<p>
103 104 105 106 107
		This is passed to the shader and used to calculate lighting for the object. It is the transpose of the inverse of the upper left 3x3 sub-matrix of this object's modelViewMatrix.<br /><br />

		The reason for this special matrix is that simply using the modelViewMatrix could result in a non-unit length of normals (on scaling) or in a non-perpendicular direction (on non-uniform scaling).<br /><br />

		On the other hand the translation part of the modelViewMatrix is not relevant for the calculation of normals. Thus a Matrix3 is sufficient.
108
		</p>
L
looeee 已提交
109

110
		<h3>[property:Function onAfterRender]</h3>
111
		<p>
L
looeee 已提交
112 113 114
		An optional callback that is executed immediately after the Object3D is rendered.
		This function is called with the following parameters: renderer, scene, camera, geometry,
		material, group.
115
		</p>
L
looeee 已提交
116

117
		<h3>[property:Function onBeforeRender]</h3>
118
		<p>
L
looeee 已提交
119 120 121
		An optional callback that is executed immediately before the Object3D is rendered.
		This function is called with the following parameters: renderer, scene, camera, geometry,
		material, group.
122
		</p>
123

L
looeee 已提交
124
		<h3>[property:Object3D parent]</h3>
125 126
		<p>Object's parent in the [link:https://en.wikipedia.org/wiki/Scene_graph scene graph]. An object can have at most
		one parent.</p>
L
looeee 已提交
127 128

		<h3>[property:Vector3 position]</h3>
129
		<p>A [page:Vector3] representing the object's local position. Default is (0, 0, 0).</p>
L
looeee 已提交
130 131

		<h3>[property:Quaternion quaternion]</h3>
132
		<p>Object's local rotation as a [page:Quaternion Quaternion].</p>
L
looeee 已提交
133

134
		<h3>[property:Boolean receiveShadow]</h3>
135
		<p>Whether the material receives shadows. Default is *false*.</p>
136

L
looeee 已提交
137
		<h3>[property:Number renderOrder]</h3>
138
		<p>
L
looeee 已提交
139
		This value allows the default rendering order of [link:https://en.wikipedia.org/wiki/Scene_graph scene graph]
140 141
		objects to be overridden although opaque and transparent objects remain sorted independently. When this property
		is set for an instance of [page:Group Group], all descendants objects will be sorted and rendered together.
L
looeee 已提交
142
		Sorting is from lowest to highest renderOrder. Default value is *0*.
143
		</p>
144

L
looeee 已提交
145
		<h3>[property:Euler rotation]</h3>
146
		<p>
L
looeee 已提交
147
		Object's local rotation (see [link:https://en.wikipedia.org/wiki/Euler_angles Euler angles]), in radians.
148
		</p>
149

L
looeee 已提交
150
		<h3>[property:Vector3 scale]</h3>
151 152 153
		<p>
		The object's local scale. Default is [page:Vector3]( 1, 1, 1 ).
		</p>
154

L
looeee 已提交
155
		<h3>[property:Vector3 up]</h3>
156
		<p>
L
Lewy Blue 已提交
157 158
		This is used by the [page:.lookAt lookAt] method, for example, to determine the orientation of the result.<br />
		Default is [page:Object3D.DefaultUp] - that is, ( 0, 1, 0 ).
159
		</p>
L
looeee 已提交
160

161
		<h3>[property:Object userData]</h3>
162
		<p>
J
Jing Ma 已提交
163
		An object that can be used to store custom data about the Object3D. It should not hold
L
looeee 已提交
164
		references to functions as these will not be cloned.
165
		</p>
C
cjshannon 已提交
166

L
looeee 已提交
167
		<h3>[property:String uuid]</h3>
168
		<p>
L
looeee 已提交
169 170
		[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
		This gets automatically assigned, so this shouldn't be edited.
171
		</p>
172

L
looeee 已提交
173
		<h3>[property:Boolean visible]</h3>
174
		<p>Object gets rendered if *true*. Default is *true*.</p>
L
looeee 已提交
175 176 177



178

179
		<h2>Static Properties</h2>
180
		<p>
181 182 183 184 185
			Static properties and methods are defined per class rather than per instance of that class.
			This means that changing [page:Object3D.DefaultUp] or [page:Object3D.DefaultMatrixAutoUpdate]
			will change the values of [page:.up up] and [page:.matrixAutoUpdate matrixAutoUpdate] for
			<em>every</em>	instance of Object3D (or derived classes)	created after the change has
			been made (already created Object3Ds will not be affected).
186
		</p>
187 188

		<h3>[property:Vector3 DefaultUp]</h3>
189
		<p>
190 191
			The default [page:.up up] direction for objects, also used as the default position for [page:DirectionalLight],
			[page:HemisphereLight] and [page:Spotlight] (which creates lights shining from the top down).<br />
J
Jing Ma 已提交
192
			Set to ( 0, 1, 0 ) by default.
193
		</p>
194 195

		<h3>[property:Vector3 DefaultMatrixAutoUpdate]</h3>
196
		<p>
J
Jing Ma 已提交
197
			The default setting for [page:.matrixAutoUpdate matrixAutoUpdate] for newly created Object3Ds.<br />
C
cjshannon 已提交
198

199
		</p>
A
aardgoose 已提交
200

201

202
		<h2>Methods</h2>
203

G
Greg Tatum 已提交
204
		<h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>
205

206
		<h3>[method:this add]( [param:Object3D object], ... )</h3>
207
		<p>
208
		Adds *object* as child of this object. An arbitrary number of objects may be added. Any current parent on an
209
		object passed in here will be removed, since an object can have at most one parent.<br /><br />
210

L
looeee 已提交
211
		See [page:Group] for info on manually grouping objects.
212
		</p>
213

214
		<h3>[method:null applyMatrix]( [param:Matrix4 matrix] )</h3>
215
		<p>Applies the matrix transform to the object and updates the object's position, rotation and scale.</p>
W
WestLangley 已提交
216

217
		<h3>[method:this applyQuaternion]( [param:Quaternion quaternion] )</h3>
218
		<p>Applies the rotation represented by the quaternion to the object.</p>
L
looeee 已提交
219

220
		<h3>[method:Object3D clone]( [param:Boolean recursive] )</h3>
221
		<p>
L
looeee 已提交
222 223
		recursive -- if true, descendants of the object are also cloned. Default is true.<br /><br />

J
Jing Ma 已提交
224
		Returns a clone of this object and optionally all descendants.
225
		</p>
L
looeee 已提交
226

227
		<h3>[method:this copy]( [param:Object3D object], [param:Boolean recursive] )</h3>
228
		<p>
L
looeee 已提交
229 230 231
		recursive -- if true, descendants of the object are also copied. Default is true.<br /><br />

		Copy the given object into this object.
232

M
Mr.doob 已提交
233
		Note: event listeners and user-defined callbacks ([page:.onAfterRender] and [page:.onBeforeRender]) are not copied.
234
		</p>
235

236
		<h3>[method:Object3D getObjectById]( [param:Integer id] )</h3>
237
		<p>
L
looeee 已提交
238 239 240 241
		id -- Unique number of the object instance<br /><br />

		Searches through the object's children and returns the first with a matching id.<br />
		Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
242
		</p>
L
looeee 已提交
243

244
		<h3>[method:Object3D getObjectByName]( [param:String name] )</h3>
245
		<p>
J
Jing Ma 已提交
246
		name -- String to match to the children's Object3D.name property. <br /><br />
L
looeee 已提交
247 248

		Searches through the object's children and returns the first with a matching name.<br />
249
		Note that for most objects the name is an empty string by default. You will
L
looeee 已提交
250
		have to set it manually to make use of this method.
251
		</p>
252

253
		<h3>[method:Object3D getObjectByProperty]( [param:String name], [param:Float value] )</h3>
254
		<p>
L
looeee 已提交
255 256 257
		name -- the property name to search for. <br />
		value -- value of the given property. <br /><br />

J
Jing Ma 已提交
258
		Searches through the object's children and returns the first with a property that matches the value given.
259
		</p>
L
looeee 已提交
260

M
Mr.doob 已提交
261
		<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
262
		<p>
W
WestLangley 已提交
263
		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
L
looeee 已提交
264 265

		Returns a vector representing the position of the object in world space.
266
		</p>
267

M
Mr.doob 已提交
268
		<h3>[method:Quaternion getWorldQuaternion]( [param:Quaternion target] )</h3>
269
		<p>
W
WestLangley 已提交
270
		[page:Quaternion target] — the result will be copied into this Quaternion. <br /><br />
L
looeee 已提交
271 272

		Returns a quaternion representing the rotation of the object in world space.
273
		</p>
L
looeee 已提交
274

M
Mr.doob 已提交
275
		<h3>[method:Vector3 getWorldScale]( [param:Vector3 target] )</h3>
276
		<p>
W
WestLangley 已提交
277
		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
L
looeee 已提交
278 279

		Returns a vector of the scaling factors applied to the object for each axis in world space.
280
		</p>
L
looeee 已提交
281

M
Mr.doob 已提交
282
		<h3>[method:Vector3 getWorldDirection]( [param:Vector3 target] )</h3>
283
		<p>
W
WestLangley 已提交
284
		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />
L
looeee 已提交
285 286

		Returns a vector representing the direction of object's positive z-axis in world space.
287
		</p>
288

L
looeee 已提交
289

290
		<h3>[method:Vector3 localToWorld]( [param:Vector3 vector] )</h3>
291
		<p>
T
Tentone 已提交
292
		vector - A vector representing a position in local (object) space.<br /><br />
293

L
looeee 已提交
294
		Converts the vector from local space to world space.
295
		</p>
296

L
linbingquan 已提交
297
		<h3>[method:null lookAt]( [param:Vector3 vector] )<br />
298
		[method:null lookAt]( [param:Float x], [param:Float y], [param:Float z] )</h3>
299
		<p>
L
looeee 已提交
300
		vector - A vector representing a position in world space.<br /><br />
W
WestLangley 已提交
301 302 303 304
		Optionally, the [page:.x x], [page:.y y] and [page:.z z] components of the world space position.<br /><br />

		Rotates the object to face a point in world space.<br /><br />

W
WestLangley 已提交
305
		This method does not support objects having non-uniformly-scaled parent(s).
306
		</p>
L
looeee 已提交
307

308
		<h3>[method:Array raycast]( [param:Raycaster raycaster], [param:Array intersects] )</h3>
309
		<p>
L
looeee 已提交
310 311 312
		Abstract (empty) method to get intersections between a casted ray and this object.
		Subclasses such as [page:Mesh], [page:Line], and [page:Points] implement this method in order
		to use raycasting.
313
		</p>
314

315
		<h3>[method:this remove]( [param:Object3D object], ... )</h3>
316
		<p>
317
		Removes *object* as child of this object. An arbitrary number of objects may be removed.
318
		</p>
319

320
		<h3>[method:this rotateOnAxis]( [param:Vector3 axis], [param:Float angle] )</h3>
321
		<p>
L
looeee 已提交
322 323
		axis -- A normalized vector in object space. <br />
		angle -- The angle in radians.<br /><br />
324

L
looeee 已提交
325
		Rotate an object along an axis in object space. The axis is assumed to be normalized.
326
		</p>
327

328
		<h3>[method:this rotateOnWorldAxis]( [param:Vector3 axis], [param:Float angle] )</h3>
329
		<p>
330 331 332 333 334
		axis -- A normalized vector in world space. <br />
		angle -- The angle in radians.<br /><br />

		Rotate an object along an axis in world space. The axis is assumed to be normalized.
		Method Assumes no rotated parent.
335
		</p>
336

337
		<h3>[method:this rotateX]( [param:Float rad] )</h3>
338
		<p>
L
looeee 已提交
339
		rad - the angle to rotate in radians.<br /><br />
340

L
looeee 已提交
341
		Rotates the object around x axis in local space.
342
		</p>
343

344
		<h3>[method:this rotateY]( [param:Float rad] )</h3>
345
		<p>
L
looeee 已提交
346
		rad - the angle to rotate in radians.<br /><br />
347

L
looeee 已提交
348
		Rotates the object around y axis in local space.
349
		</p>
350

351
		<h3>[method:this rotateZ]( [param:Float rad] )</h3>
352
		<p>
L
looeee 已提交
353
		rad - the angle to rotate in radians.<br /><br />
C
cjshannon 已提交
354

L
looeee 已提交
355
		Rotates the object around z axis in local space.
356
		</p>
357

358
		<h3>[method:null setRotationFromAxisAngle]( [param:Vector3 axis], [param:Float angle] )</h3>
359
		<p>
L
looeee 已提交
360 361
			axis -- A normalized vector in object space. <br />
			angle -- angle in radians<br /><br />
362

L
looeee 已提交
363 364
			Calls [page:Quaternion.setFromAxisAngle setFromAxisAngle]( [page:Float axis], [page:Float angle] )
			on the [page:.quaternion].
365
		</p>
366

367
		<h3>[method:null setRotationFromEuler]( [param:Euler euler] )</h3>
368
		<p>
L
looeee 已提交
369
			euler -- Euler angle specifying rotation amount.<br />
370

L
looeee 已提交
371 372
			Calls [page:Quaternion.setRotationFromEuler setRotationFromEuler]( [page:Euler euler])
			on the [page:.quaternion].
373
		</p>
L
looeee 已提交
374

375
		<h3>[method:null setRotationFromMatrix]( [param:Matrix4 m] )</h3>
376
		<p>
L
looeee 已提交
377 378 379 380 381 382
			m -- rotate the quaternion by the rotation component of the matrix.<br />

			Calls [page:Quaternion.setFromRotationMatrix setFromRotationMatrix]( [page:Matrix4 m])
			on the [page:.quaternion].<br /><br />

			Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).
383
		</p>
384

385
		<h3>[method:null setRotationFromQuaternion]( [param:Quaternion q] )</h3>
386
		<p>
L
looeee 已提交
387 388 389
			q -- normalized Quaternion.<br /><br />

			Copy the given quaternion into [page:.quaternion].
390
		</p>
L
looeee 已提交
391

392
		<h3>[method:null toJSON]( [param:Quaternion q] )</h3>
393
		<p>
L
looeee 已提交
394
			Convert the object to JSON format.
395
		</p>
396

397
		<h3>[method:this translateOnAxis]( [param:Vector3 axis], [param:Float distance] )</h3>
398
		<p>
G
Greg Tatum 已提交
399
		axis -- A normalized vector in object space.<br />
L
looeee 已提交
400 401 402
		distance -- The distance to translate.<br /><br />

		Translate an object by distance along an axis in object space. The axis is assumed to be normalized.
403
		</p>
L
looeee 已提交
404

405
		<h3>[method:this translateX]( [param:Float distance] )</h3>
H
haolly 已提交
406
		<p>Translates object along x axis in object space by *distance* units.</p>
L
looeee 已提交
407

408
		<h3>[method:this translateY]( [param:Float distance] )</h3>
H
haolly 已提交
409
		<p>Translates object along y axis in object space by *distance* units.</p>
L
looeee 已提交
410

411
		<h3>[method:this translateZ]( [param:Float distance] )</h3>
H
haolly 已提交
412
		<p>Translates object along z axis in object space by *distance* units.</p>
L
looeee 已提交
413

414
		<h3>[method:null traverse]( [param:Function callback] )</h3>
415
		<p>
L
looeee 已提交
416 417 418
		callback - A function with as first argument an object3D object.<br /><br />

		Executes the callback on this object and all descendants.
419
		</p>
420

421
		<h3>[method:null traverseVisible]( [param:Function callback] )</h3>
422
		<p>
L
looeee 已提交
423 424 425 426
		callback - A function with as first argument an object3D object.<br /><br />

		Like traverse, but the callback will only be executed for visible objects.
		Descendants of invisible objects are not traversed.
427
		</p>
L
looeee 已提交
428

429
		<h3>[method:null traverseAncestors]( [param:Function callback] )</h3>
430
		<p>
L
looeee 已提交
431 432 433
		callback - A function with as first argument an object3D object.<br /><br />

		Executes the callback on all ancestors.
434
		</p>
C
cjshannon 已提交
435

L
looeee 已提交
436
		<h3>[method:null updateMatrix]()</h3>
437
		<p>Update the local transform.</p>
L
looeee 已提交
438

439
		<h3>[method:null updateMatrixWorld]( [param:Boolean force] )</h3>
440
		<p>Update the global transform of the object and its children.</p>
L
looeee 已提交
441 442


443
		<h3>[method:Vector3 worldToLocal]( [param:Vector3 vector] )</h3>
444
		<p>
L
looeee 已提交
445 446 447
		vector - A world vector.<br /><br />

		Updates the vector from world space to local space.
448
		</p>
449

450 451 452 453 454
		<h2>Source</h2>

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