webglFramework/Thirdparty/three.js-master/docs/api/core/Object3D.html

   1 <!DOCTYPE html>
   2 <html lang="en">
   3         <head>
   4                 <meta charset="utf-8" />
   5                 <base href="../../" />
   6                 <script src="list.js"></script>
   7                 <script src="page.js"></script>
   8                 <link type="text/css" rel="stylesheet" href="page.css" />
   9         </head>
  10         <body>
  11                 <h1>[name]</h1>
  12
  13                 <div class="desc">
  14                         This is the base class for most objects in three.js and provides a set of properties and methods
  15                         for manipulating objects in 3D space.<br /><br />
  16
  17                         Note that this can be used for grouping objects via the [page:.add]( object ) method
  18                         which adds the object as a child, however it is better to use [page:Group] for this.
  19                 </div>
  20
  21
  22                 <h2>Constructor</h2>
  23
  24
  25                 <h3>[name]()</h3>
  26                 <div>
  27                 The constructor takes no arguments.
  28                 </div>
  29
  30
  31                 <h2>Properties</h2>
  32
  33                 <h3>[property:Boolean castShadow]</h3>
  34                 <div>Whether the object gets rendered into shadow map. Default is *false*.</div>
  35
  36                 <h3>[property:Object3D children]</h3>
  37                 <div>Array with object's children. See [page:Group] for info on manually grouping objects.</div>
  38
  39                 <h3>[property:Boolean frustumCulled]</h3>
  40                 <div>
  41                 When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
  42                 Otherwise the object gets renderered every frame even if it isn't visible. Default is *true*.
  43                 </div>
  44
  45                 <h3>[property:Integer id]</h3>
  46                 <div>readonly – Unique number for this object instance.</div>
  47
  48                 <h3>[property:Boolean isObject]</h3>
  49                 <div>
  50                         Used to check whether this or derived classes are Object3Ds. Default is *true*.<br /><br />
  51
  52                         You should not change this, as it is used internally for optimisation.
  53                 </div>
  54
  55                 <h3>[property:Layers layers]</h3>
  56                 <div>
  57                 The layer membership of the object. The object is only visible if it has at least one
  58                 layer in common with the [page:Camera] in use.
  59                 </div>
  60
  61                 <h3>[property:Matrix4 matrix]</h3>
  62                 <div>The local transform matrix.</div>
  63
  64                 <h3>[property:Boolean matrixAutoUpdate]</h3>
  65                 <div>
  66                 When this is set, it calculates the matrix of position, (rotation or quaternion) and
  67                 scale every frame and also recalculates the matrixWorld property. Default is [page:Object3D.DefaultMatrixAutoUpdate] (true).
  68                 </div>
  69
  70                 <h3>[property:Matrix4 matrixWorld]</h3>
  71                 <div>
  72                 The global transform of the object. If the Object3D has no parent, then it's identical to
  73                 the local transform [page:.matrix].
  74                 </div>
  75
  76                 <h3>[property:Boolean matrixWorldNeedsUpdate]</h3>
  77                 <div>
  78                 When this is set, it calculates the matrixWorld in that frame and resets this property
  79                  to false. Default is *false*.
  80                 </div>
  81
  82                 <h3>[property:Matrix4 modelViewMatrix]</h3>
  83                 <div>This is passed to the shader and used to calculate the position of the object.</div>
  84
  85                 <h3>[property:String name]</h3>
  86                 <div>Optional name of the object (doesn't need to be unique). Default is an empty string.</div>
  87
  88                 <h3>[property:Matrix3 normalMatrix]</h3>
  89                 <div>
  90                 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 />
  91
  92                 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 />
  93
  94                 On the other hand the translation part of the modelViewMatrix is not relevant for the calculation of normals. Thus a Matrix3 is sufficient.
  95                 </div>
  96
  97                 <h3>[property:function onAfterRender]</h3>
  98                 <div>
  99                 An optional callback that is executed immediately after the Object3D is rendered.
 100                 This function is called with the following parameters: renderer, scene, camera, geometry,
 101                 material, group.
 102                 </div>
 103
 104                 <h3>[property:function onBeforeRender]</h3>
 105                 <div>
 106                 An optional callback that is executed immediately before the Object3D is rendered.
 107                 This function is called with the following parameters: renderer, scene, camera, geometry,
 108                 material, group.
 109                 </div>
 110
 111                 <h3>[property:Object3D parent]</h3>
 112                 <div>Object's parent in the [link:https://en.wikipedia.org/wiki/Scene_graph scene graph].</div>
 113
 114                 <h3>[property:Vector3 position]</h3>
 115                 <div>The object's local position.</div>
 116
 117                 <h3>[property:Quaternion quaternion]</h3>
 118                 <div>Object's local rotation as a [page:Quaternion Quaternion].</div>
 119
 120                 <h3>[property:Boolean receiveShadow]</h3>
 121                 <div>Whether the material receives shadows. Default is *false*.</div>
 122
 123                 <h3>[property:Number renderOrder]</h3>
 124                 <div>
 125                 This value allows the default rendering order of [link:https://en.wikipedia.org/wiki/Scene_graph scene graph]
 126                 objects to be overridden although opaque and transparent objects remain sorted independently.
 127                 Sorting is from lowest to highest renderOrder. Default value is *0*.
 128                 </div>
 129
 130                 <h3>[property:Euler rotation]</h3>
 131                 <div>
 132                 Object's local rotation (see [link:https://en.wikipedia.org/wiki/Euler_angles Euler angles]), in radians.
 133                 </div>
 134
 135                 <h3>[property:Vector3 scale]</h3>
 136                 <div>
 137                 The object's local [property:Vector3 scale]. Default is [page:Vector3]( 1, 1, 1 ).
 138                 </div>
 139
 140                 <h3>[property:Vector3 up]</h3>
 141                 <div>
 142                 This is used by the [page:.lookAt lookAt] method, for example, to determine the orientation of the result.<br />
 143                 Default is [page:Object3D.DefaultUp] - that is, ( 0, 1, 0 ).
 144                 </div>
 145
 146                 <h3>[property:object userData]</h3>
 147                 <div>
 148                 An object that can be used to store custom data about the Object3D. It should not hold
 149                 references to functions as these will not be cloned.
 150                 </div>
 151
 152                 <h3>[property:String uuid]</h3>
 153                 <div>
 154                 [link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this object instance.
 155                 This gets automatically assigned, so this shouldn't be edited.
 156                 </div>
 157
 158                 <h3>[property:Boolean visible]</h3>
 159                 <div>Object gets rendered if *true*. Default is *true*.</div>
 160
 161
 162
 163
 164                 <h2>Static Properties</h2>
 165                 <div>
 166                         Static properties and methods are defined per class rather than per instance of that class.
 167                         This means that changing [page:Object3D.DefaultUp] or [page:Object3D.DefaultMatrixAutoUpdate]
 168                         will change the values of [page:.up up] and [page:.matrixAutoUpdate matrixAutoUpdate] for
 169                         <em>every</em>  instance of Object3D (or derived classes)       created after the change has
 170                         been made (already created Object3Ds will not be affected).
 171                 </div>
 172
 173                 <h3>[property:Vector3 DefaultUp]</h3>
 174                 <div>
 175                         The default [page:.up up] direction for objects, also used as the default position for [page:DirectionalLight],
 176                         [page:HemisphereLight] and [page:Spotlight] (which creates lights shining from the top down).<br />
 177                         Set to ( 0, 1, 0 ) by default.
 178                 </div>
 179
 180                 <h3>[property:Vector3 DefaultMatrixAutoUpdate]</h3>
 181                 <div>
 182                         The default setting for [page:.matrixAutoUpdate matrixAutoUpdate] for newly created Object3Ds.<br />
 183
 184                 </div>
 185
 186
 187                 <h2>Methods</h2>
 188
 189                 <h3>[page:EventDispatcher EventDispatcher] methods are available on this class.</h3>
 190
 191                 <h3>[method:null add]( [page:Object3D object], ... )</h3>
 192                 <div>
 193                 Adds *object* as child of this object. An arbitrary number of objects may be added.<br /><br />
 194
 195                 See [page:Group] for info on manually grouping objects.
 196                 </div>
 197
 198                 <h3>[method:null applyMatrix]( [page:Matrix4 matrix] )</h3>
 199                 <div>Applies the matrix transform to the object and updates the object's position, rotation and scale.</div>
 200
 201                 <h3>[method:Object3D applyQuaternion]( [page:Quaternion quaternion] )</h3>
 202                 <div>Applies the rotation represented by the quaternion to the object.</div>
 203
 204                 <h3>[method:Object3D clone]( [page:Boolean recursive] )</h3>
 205                 <div>
 206                 recursive -- if true, descendants of the object are also cloned. Default is true.<br /><br />
 207
 208                 Returns a clone of this object and optionally all descendants.
 209                 </div>
 210
 211                 <h3>[method:Object3D copy]( [page:Object3D object], [page:Boolean recursive] )</h3>
 212                 <div>
 213                 recursive -- if true, descendants of the object are also copied. Default is true.<br /><br />
 214
 215                 Copy the given object into this object.
 216                 </div>
 217
 218                 <h3>[method:Object3D getObjectById]( [page:Integer id] )</h3>
 219                 <div>
 220                 id -- Unique number of the object instance<br /><br />
 221
 222                 Searches through the object's children and returns the first with a matching id.<br />
 223                 Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
 224                 </div>
 225
 226                 <h3>[method:Object3D getObjectByName]( [page:String name] )</h3>
 227                 <div>
 228                 name -- String to match to the children's Object3D.name property. <br /><br />
 229
 230                 Searches through the object's children and returns the first with a matching name.<br />
 231                 Note that for most objects the [property:name] is an empty string by default. You will
 232                 have to set it manually to make use of this method.
 233                 </div>
 234
 235                 <h3>[method:Object3D getObjectByProperty]( [page:String name], [page:Float value] )</h3>
 236                 <div>
 237                 name -- the property name to search for. <br />
 238                 value -- value of the given property. <br /><br />
 239
 240                 Searches through the object's children and returns the first with a property that matches the value given.
 241                 </div>
 242
 243                 <h3>[method:Vector3 getWorldPosition]( [page:Vector3 optionalTarget] )</h3>
 244                 <div>
 245                 optionalTarget — (optional) target to set the result. Otherwise, a new [page:Vector3] is instantiated. <br /><br />
 246
 247                 Returns a vector representing the position of the object in world space.
 248                 </div>
 249
 250                 <h3>[method:Quaternion getWorldQuaternion]( [page:Quaternion optionalTarget] )</h3>
 251                 <div>
 252                 optionalTarget — (optional) if specified, the result will be copied into this Quaternion,
 253                 otherwise a new Quaternion will be created. <br /><br />
 254
 255                 Returns a quaternion representing the rotation of the object in world space.
 256                 </div>
 257
 258                 <h3>[method:Euler getWorldRotation]( [page:Euler optionalTarget] )</h3>
 259                 <div>
 260                 optionalTarget — (optional) if specified, the result will be copied into this Euler,
 261                 otherwise a new Euler will be created. <br /><br />
 262
 263                 Returns the euler angles representing the rotation of the object in world space.
 264                 </div>
 265
 266                 <h3>[method:Vector3 getWorldScale]( [page:Vector3 optionalTarget] )</h3>
 267                 <div>
 268                 [page:Vector3 optionalTarget] — (optional) if specified, the result will be copied into this Vector3,
 269                 otherwise a new Vector3 will be created. <br /><br />
 270
 271                 Returns a vector of the scaling factors applied to the object for each axis in world space.
 272                 </div>
 273
 274                 <h3>[method:Vector3 getWorldDirection]( [page:Vector3 optionalTarget] )</h3>
 275                 <div>
 276                 [page:Vector3 optionalTarget] — (optional) if specified, the result will be copied into this Vector3,
 277                 otherwise a new Vector3 will be created. <br /><br />
 278
 279                 Returns a vector representing the direction of object's positive z-axis in world space.
 280                 </div>
 281
 282
 283                 <h3>[method:Vector3 localToWorld]( [page:Vector3 vector] )</h3>
 284                 <div>
 285                 vector - A vector representing a position in local (object) space.<br /><br />
 286
 287                 Converts the vector from local space to world space.
 288                 </div>
 289
 290                 <h3>[method:null lookAt]( [page:Vector3 vector] )</h3>
 291                 <div>
 292                 vector - A vector representing a position in world space.<br /><br />
 293
 294                 Rotates the object to face a point in world space.
 295                 </div>
 296
 297                 <h3>[method:Array raycast]( [page:Raycaster raycaster], [page:Array intersects] )</h3>
 298                 <div>
 299                 Abstract (empty) method to get intersections between a casted ray and this object.
 300                 Subclasses such as [page:Mesh], [page:Line], and [page:Points] implement this method in order
 301                 to use raycasting.
 302                 </div>
 303
 304                 <h3>[method:null remove]( [page:Object3D object], ... )</h3>
 305                 <div>
 306                 Removes *object* as child of this object. An arbitrary number of objects may be removed.
 307                 </div>
 308
 309                 <h3>[method:Object3D rotateOnAxis]( [page:Vector3 axis], [page:Float angle] )</h3>
 310                 <div>
 311                 axis -- A normalized vector in object space. <br />
 312                 angle -- The angle in radians.<br /><br />
 313
 314                 Rotate an object along an axis in object space. The axis is assumed to be normalized.
 315                 </div>
 316
 317                 <h3>[method:null rotateX]( [page:Float rad] )</h3>
 318                 <div>
 319                 rad - the angle to rotate in radians.<br /><br />
 320
 321                 Rotates the object around x axis in local space.
 322                 </div>
 323
 324                 <h3>[method:null rotateY]( [page:Float rad] )</h3>
 325                 <div>
 326                 rad - the angle to rotate in radians.<br /><br />
 327
 328                 Rotates the object around y axis in local space.
 329                 </div>
 330
 331                 <h3>[method:null rotateZ]( [page:Float rad] )</h3>
 332                 <div>
 333                 rad - the angle to rotate in radians.<br /><br />
 334
 335                 Rotates the object around z axis in local space.
 336                 </div>
 337
 338                 <h3>[method:null setRotationFromAxisAngle]( [page:Vector3 axis], [page:Float angle] )</h3>
 339                 <div>
 340                         axis -- A normalized vector in object space. <br />
 341                         angle -- angle in radians<br /><br />
 342
 343                         Calls [page:Quaternion.setFromAxisAngle setFromAxisAngle]( [page:Float axis], [page:Float angle] )
 344                         on the [page:.quaternion].
 345                 </div>
 346
 347                 <h3>[method:null setRotationFromEuler]( [page:Euler euler] )</h3>
 348                 <div>
 349                         euler -- Euler angle specifying rotation amount.<br />
 350
 351                         Calls [page:Quaternion.setRotationFromEuler setRotationFromEuler]( [page:Euler euler])
 352                         on the [page:.quaternion].
 353                 </div>
 354
 355                 <h3>[method:null setRotationFromMatrix]( [page:Matrix4 m] )</h3>
 356                 <div>
 357                         m -- rotate the quaternion by the rotation component of the matrix.<br />
 358
 359                         Calls [page:Quaternion.setFromRotationMatrix setFromRotationMatrix]( [page:Matrix4 m])
 360                         on the [page:.quaternion].<br /><br />
 361
 362                         Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).
 363                 </div>
 364
 365                 <h3>[method:null setRotationFromQuaternion]( [page:Quaternion q] )</h3>
 366                 <div>
 367                         q -- normalized Quaternion.<br /><br />
 368
 369                         Copy the given quaternion into [page:.quaternion].
 370                 </div>
 371
 372                 <h3>[method:null toJSON]( [page:Quaternion q] )</h3>
 373                 <div>
 374                         Convert the object to JSON format.
 375                 </div>
 376
 377                 <h3>[method:Object3D translateOnAxis]( [page:Vector3 axis], [page:Float distance] )</h3>
 378                 <div>
 379                 axis -- A normalized vector in object space.<br />
 380                 distance -- The distance to translate.<br /><br />
 381
 382                 Translate an object by distance along an axis in object space. The axis is assumed to be normalized.
 383                 </div>
 384
 385                 <h3>[method:null translateX]( [page:Float distance] )</h3>
 386                 <div>Translates object along x axis by *distance* units.</div>
 387
 388                 <h3>[method:null translateY]( [page:Float distance] )</h3>
 389                 <div>Translates object along y axis by *distance* units.</div>
 390
 391                 <h3>[method:null translateZ]( [page:Float distance] )</h3>
 392                 <div>Translates object along z axis by *distance* units.</div>
 393
 394                 <h3>[method:null traverse]( [page:Function callback] )</h3>
 395                 <div>
 396                 callback - A function with as first argument an object3D object.<br /><br />
 397
 398                 Executes the callback on this object and all descendants.
 399                 </div>
 400
 401                 <h3>[method:null traverseVisible]( [page:Function callback] )</h3>
 402                 <div>
 403                 callback - A function with as first argument an object3D object.<br /><br />
 404
 405                 Like traverse, but the callback will only be executed for visible objects.
 406                 Descendants of invisible objects are not traversed.
 407                 </div>
 408
 409                 <h3>[method:null traverseAncestors]( [page:Function callback] )</h3>
 410                 <div>
 411                 callback - A function with as first argument an object3D object.<br /><br />
 412
 413                 Executes the callback on all ancestors.
 414                 </div>
 415
 416                 <h3>[method:null updateMatrix]()</h3>
 417                 <div>Update the local transform.</div>
 418
 419                 <h3>[method:null updateMatrixWorld]( [page:Boolean force] )</h3>
 420                 <div>Update the global transform of the object and its children.</div>
 421
 422
 423                 <h3>[method:Vector3 worldToLocal]( [page:Vector3 vector] )</h3>
 424                 <div>
 425                 vector - A world vector.<br /><br />
 426
 427                 Updates the vector from world space to local space.
 428                 </div>
 429
 430                 <h2>Source</h2>
 431
 432                 [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
 433         </body>
 434 </html>