123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635 |
- <!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">
- This is the base class for most objects in three.js and provides a set of
- properties and methods 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.
- </p>
- <h2>Constructor</h2>
- <h3>[name]()</h3>
- <p>The constructor takes no arguments.</p>
- <h2>Properties</h2>
- <h3>[property:AnimationClip animations]</h3>
- <p>Array with object's animation clips.</p>
- <h3>[property:Boolean castShadow]</h3>
- <p>Whether the object gets rendered into shadow map. Default is `false`.</p>
- <h3>[property:Array children]</h3>
- <p>
- Array with object's children. See [page:Group] for info on manually
- grouping objects.
- </p>
- <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 modifying vertex
- positions in the vertex shader you must specify a customDepthMaterial for
- proper shadows. Default is `undefined`.
- </p>
- <h3>[property:Material customDistanceMaterial]</h3>
- <p>
- Same as [page:.customDepthMaterial customDepthMaterial], but used with
- [page:PointLight]. Default is `undefined`.
- </p>
- <h3>[property:Boolean frustumCulled]</h3>
- <p>
- When this is set, it checks every frame if the object is in the frustum of
- the camera before rendering the object. If set to `false` the object gets
- rendered every frame even if it is not in the frustum of the camera.
- Default is `true`.
- </p>
- <h3>[property:Integer id]</h3>
- <p>readonly – Unique number for this object instance.</p>
- <h3>[property:Boolean isObject3D]</h3>
- <p>Read-only flag to check if a given object is of type [name].</p>
- <h3>[property:Layers layers]</h3>
- <p>
- 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. This property
- can also be used to filter out unwanted objects in ray-intersection tests
- when using [page:Raycaster].
- </p>
- <h3>[property:Matrix4 matrix]</h3>
- <p>The local transform matrix.</p>
- <h3>[property:Boolean matrixAutoUpdate]</h3>
- <p>
- When this is set, it calculates the matrix of position, (rotation or
- quaternion) and scale every frame and also recalculates the matrixWorld
- property. Default is [page:Object3D.DEFAULT_MATRIX_AUTO_UPDATE] (true).
- </p>
- <h3>[property:Matrix4 matrixWorld]</h3>
- <p>
- The global transform of the object. If the Object3D has no parent, then
- it's identical to the local transform [page:.matrix].
- </p>
- <h3>[property:Boolean matrixWorldAutoUpdate]</h3>
- <p>
- If set, then the renderer checks every frame if the object and its
- children need matrix updates. When it isn't, then you have to maintain all
- matrices in the object and its children yourself. Default is
- [page:Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE] (true).
- </p>
- <h3>[property:Boolean matrixWorldNeedsUpdate]</h3>
- <p>
- When this is set, it calculates the matrixWorld in that frame and resets
- this property to false. Default is `false`.
- </p>
- <h3>[property:Matrix4 modelViewMatrix]</h3>
- <p>
- This is passed to the shader and used to calculate the position of the
- object.
- </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:Matrix3 normalMatrix]</h3>
- <p>
- 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.
- </p>
- <h3>[property:Function onAfterRender]</h3>
- <p>
- An optional callback that is executed immediately after a 3D object is
- rendered. This function is called with the following parameters: renderer,
- scene, camera, geometry, material, group.
- </p>
- <p>
- Please notice that this callback is only executed for `renderable` 3D
- objects. Meaning 3D objects which define their visual appearance with
- geometries and materials like instances of [page:Mesh], [page:Line],
- [page:Points] or [page:Sprite]. Instances of [page:Object3D], [page:Group]
- or [page:Bone] are not renderable and thus this callback is not executed
- for such objects.
- </p>
- <h3>[property:Function onAfterShadow]</h3>
- <p>
- An optional callback that is executed immediately after a 3D object is
- rendered to a shadow map. This function is called with the following parameters: renderer,
- scene, camera, shadowCamera, geometry, depthMaterial, group.
- </p>
- <p>
- Please notice that this callback is only executed for `renderable` 3D
- objects. Meaning 3D objects which define their visual appearance with
- geometries and materials like instances of [page:Mesh], [page:Line],
- [page:Points] or [page:Sprite]. Instances of [page:Object3D], [page:Group]
- or [page:Bone] are not renderable and thus this callback is not executed
- for such objects.
- </p>
- <h3>[property:Function onBeforeRender]</h3>
- <p>
- An optional callback that is executed immediately before a 3D object is
- rendered. This function is called with the following parameters: renderer,
- scene, camera, geometry, material, group.
- </p>
- <p>
- Please notice that this callback is only executed for `renderable` 3D
- objects. Meaning 3D objects which define their visual appearance with
- geometries and materials like instances of [page:Mesh], [page:Line],
- [page:Points] or [page:Sprite]. Instances of [page:Object3D], [page:Group]
- or [page:Bone] are not renderable and thus this callback is not executed
- for such objects.
- </p>
- <h3>[property:Function onBeforeShadow]</h3>
- <p>
- An optional callback that is executed immediately before a 3D object is
- rendered to a shadow map. This function is called with the following parameters: renderer,
- scene, camera, shadowCamera, geometry, depthMaterial, group.
- </p>
- <p>
- Please notice that this callback is only executed for `renderable` 3D
- objects. Meaning 3D objects which define their visual appearance with
- geometries and materials like instances of [page:Mesh], [page:Line],
- [page:Points] or [page:Sprite]. Instances of [page:Object3D], [page:Group]
- or [page:Bone] are not renderable and thus this callback is not executed
- for such objects.
- </p>
- <h3>[property:Object3D parent]</h3>
- <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>
- <h3>[property:Vector3 position]</h3>
- <p>
- A [page:Vector3] representing the object's local position. Default is `(0,
- 0, 0)`.
- </p>
- <h3>[property:Quaternion quaternion]</h3>
- <p>Object's local rotation as a [page:Quaternion Quaternion].</p>
- <h3>[property:Boolean receiveShadow]</h3>
- <p>Whether the material receives shadows. Default is `false`.</p>
- <h3>[property:Number renderOrder]</h3>
- <p>
- This value allows the default rendering order of
- [link:https://en.wikipedia.org/wiki/Scene_graph scene graph] 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.
- Sorting is from lowest to highest renderOrder. Default value is `0`.
- </p>
- <h3>[property:Euler rotation]</h3>
- <p>
- Object's local rotation (see
- [link:https://en.wikipedia.org/wiki/Euler_angles Euler angles]), in
- radians.
- </p>
- <h3>[property:Vector3 scale]</h3>
- <p>The object's local scale. Default is [page:Vector3]( 1, 1, 1 ).</p>
- <h3>[property:Vector3 up]</h3>
- <p>
- This is used by the [page:.lookAt lookAt] method, for example, to
- determine the orientation of the result.<br />
- Default is [page:Object3D.DEFAULT_UP] - that is, `( 0, 1, 0 )`.
- </p>
- <h3>[property:Object userData]</h3>
- <p>
- An object that can be used to store custom data about the Object3D. It
- should not hold references to functions as these will not be cloned.
- Default is an empty object `{}`.
- </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:Boolean visible]</h3>
- <p>Object gets rendered if `true`. Default is `true`.</p>
- <h2>Static Properties</h2>
- <p>
- Static properties and methods are defined per class rather than per
- instance of that class. This means that changing
- [page:Object3D.DEFAULT_UP] or [page:Object3D.DEFAULT_MATRIX_AUTO_UPDATE]
- will change the values of [page:.up up] and [page:.matrixAutoUpdate matrixAutoUpdate] for `every` instance of Object3D (or derived classes)
- created after the change has been made (already created Object3Ds will not
- be affected).
- </p>
- <h3>[property:Vector3 DEFAULT_UP]</h3>
- <p>
- 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 />
- Set to ( 0, 1, 0 ) by default.
- </p>
- <h3>[property:Boolean DEFAULT_MATRIX_AUTO_UPDATE]</h3>
- <p>
- The default setting for [page:.matrixAutoUpdate matrixAutoUpdate] for
- newly created Object3Ds.<br />
- </p>
- <h3>[property:Boolean DEFAULT_MATRIX_WORLD_AUTO_UPDATE]</h3>
- <p>
- The default setting for [page:.matrixWorldAutoUpdate
- matrixWorldAutoUpdate] for newly created Object3Ds.<br />
- </p>
- <h2>Methods</h2>
- <p>
- [page:EventDispatcher EventDispatcher] methods are available on this
- class.
- </p>
- <h3>[method:this add]( [param:Object3D object], ... )</h3>
- <p>
- Adds `object` as child of this object. An arbitrary number of objects may
- be added. Any current parent on an object passed in here will be removed,
- since an object can have at most one parent.<br /><br />
- See [page:Group] for info on manually grouping objects.
- </p>
- <h3>[method:undefined applyMatrix4]( [param:Matrix4 matrix] )</h3>
- <p>
- Applies the matrix transform to the object and updates the object's
- position, rotation and scale.
- </p>
- <h3>[method:this applyQuaternion]( [param:Quaternion quaternion] )</h3>
- <p>Applies the rotation represented by the quaternion to the object.</p>
- <h3>[method:this attach]( [param:Object3D object] )</h3>
- <p>
- Adds `object` as a child of this, while maintaining the object's world
- transform.<br /><br />
- Note: This method does not support scene graphs having
- non-uniformly-scaled nodes(s).
- </p>
-
- <h3>[method:this clear]()</h3>
- <p>Removes all child objects.</p>
- <h3>[method:Object3D clone]( [param:Boolean recursive] )</h3>
- <p>
- recursive -- if true, descendants of the object are also cloned. Default
- is true.<br /><br />
- Returns a clone of this object and optionally all descendants.
- </p>
- <h3>[method:this copy]( [param:Object3D object], [param:Boolean recursive] )</h3>
- <p>
- recursive -- If set to `true`, descendants of the object are copied next to the existing ones.
- If set to `false`, descendants are left unchanged. Default is `true`.<br /><br />
- Copies the given object into this object. Note: Event listeners and
- user-defined callbacks ([page:.onAfterRender] and [page:.onBeforeRender])
- are not copied.
- </p>
- <h3>[method:Object3D getObjectById]( [param:Integer id] )</h3>
- <p>
- id -- Unique number of the object instance<br /><br />
- Searches through an object and its children, starting with the object
- itself, 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.
- </p>
- <h3>[method:Object3D getObjectByName]( [param:String name] )</h3>
- <p>
- name -- String to match to the children's Object3D.name property.
- <br /><br />
- Searches through an object and its children, starting with the object
- itself, and returns the first with a matching name.<br />
- Note that for most objects the name is an empty string by default. You
- will have to set it manually to make use of this method.
- </p>
- <h3>[method:Object3D getObjectByProperty]( [param:String name], [param:Any value] )</h3>
- <p>
- name -- the property name to search for. <br />
- value -- value of the given property. <br /><br />
- Searches through an object and its children, starting with the object
- itself, and returns the first with a property that matches the value
- given.
- </p>
- <h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
- <p>
- name -- the property name to search for. <br />
- value -- value of the given property. <br />
- optionalTarget -- (optional) target to set the result.
- Otherwise a new Array is instantiated. If set, you must clear this
- array prior to each call (i.e., array.length = 0;). <br /><br />
- Searches through an object and its children, starting with the object
- itself, and returns all the objects with a property that matches the value
- given.
- </p>
- <h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
- <p>
- [page:Vector3 target] — the result will be copied into this Vector3.
- <br /><br />
- Returns a vector representing the position of the object in world space.
- </p>
- <h3>[method:Quaternion getWorldQuaternion]( [param:Quaternion target] )</h3>
- <p>
- [page:Quaternion target] — the result will be copied into this Quaternion.
- <br /><br />
- Returns a quaternion representing the rotation of the object in world
- space.
- </p>
- <h3>[method:Vector3 getWorldScale]( [param:Vector3 target] )</h3>
- <p>
- [page:Vector3 target] — the result will be copied into this Vector3.
- <br /><br />
- Returns a vector of the scaling factors applied to the object for each
- axis in world space.
- </p>
- <h3>[method:Vector3 getWorldDirection]( [param:Vector3 target] )</h3>
- <p>
- [page:Vector3 target] — the result will be copied into this Vector3.
- <br /><br />
- Returns a vector representing the direction of object's positive z-axis in
- world space.
- </p>
- <h3>[method:Vector3 localToWorld]( [param:Vector3 vector] )</h3>
- <p>
- vector - A vector representing a position in this object's local space.<br /><br />
- Converts the vector from this object's local space to world space.
- </p>
- <h3>[method:undefined lookAt]( [param:Vector3 vector] )<br />
- [method:undefined lookAt]( [param:Float x], [param:Float y], [param:Float z] )
- </h3>
- <p>
- vector - A vector representing a position in world space.<br /><br />
- 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 />
- This method does not support objects having non-uniformly-scaled
- parent(s).
- </p>
- <h3>[method:undefined raycast]( [param:Raycaster raycaster], [param:Array intersects] )</h3>
- <p>
- 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.
- </p>
- <h3>[method:this remove]( [param:Object3D object], ... )</h3>
- <p>
- Removes `object` as child of this object. An arbitrary number of objects
- may be removed.
- </p>
- <h3>[method:this removeFromParent]()</h3>
- <p>Removes this object from its current parent.</p>
- <h3>[method:this rotateOnAxis]( [param:Vector3 axis], [param:Float angle] )</h3>
- <p>
- axis -- A normalized vector in object space. <br />
- angle -- The angle in radians.<br /><br />
- Rotate an object along an axis in object space. The axis is assumed to be
- normalized.
- </p>
- <h3>[method:this rotateOnWorldAxis]( [param:Vector3 axis], [param:Float angle])</h3>
- <p>
- 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.
- </p>
- <h3>[method:this rotateX]( [param:Float rad] )</h3>
- <p>
- rad - the angle to rotate in radians.<br /><br />
- Rotates the object around x axis in local space.
- </p>
- <h3>[method:this rotateY]( [param:Float rad] )</h3>
- <p>
- rad - the angle to rotate in radians.<br /><br />
- Rotates the object around y axis in local space.
- </p>
- <h3>[method:this rotateZ]( [param:Float rad] )</h3>
- <p>
- rad - the angle to rotate in radians.<br /><br />
- Rotates the object around z axis in local space.
- </p>
- <h3>[method:undefined setRotationFromAxisAngle]( [param:Vector3 axis], [param:Float angle] )</h3>
- <p>
- axis -- A normalized vector in object space. <br />
- angle -- angle in radians<br /><br />
- Calls [page:Quaternion.setFromAxisAngle setFromAxisAngle]( [page:Float axis], [page:Float angle] ) on the [page:.quaternion].
- </p>
- <h3>[method:undefined setRotationFromEuler]( [param:Euler euler] )</h3>
- <p>
- euler -- Euler angle specifying rotation amount.<br />
- Calls [page:Quaternion.setRotationFromEuler setRotationFromEuler](
- [page:Euler euler]) on the [page:.quaternion].
- </p>
- <h3>[method:undefined setRotationFromMatrix]( [param:Matrix4 m] )</h3>
- <p>
- 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).
- </p>
- <h3>[method:undefined setRotationFromQuaternion]( [param:Quaternion q] )</h3>
- <p>
- q -- normalized Quaternion.<br /><br />
- Copy the given quaternion into [page:.quaternion].
- </p>
- <h3>[method:Object toJSON]( [param:Object meta] )</h3>
- <p>
- meta -- object containing metadata such as materials, textures or images
- for the object.<br />
- Convert the object to three.js
- [link:https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 JSON Object/Scene format].
- </p>
- <h3>[method:this translateOnAxis]( [param:Vector3 axis], [param:Float distance] )</h3>
- <p>
- axis -- A normalized vector in object space.<br />
- 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.
- </p>
- <h3>[method:this translateX]( [param:Float distance] )</h3>
- <p>Translates object along x axis in object space by `distance` units.</p>
- <h3>[method:this translateY]( [param:Float distance] )</h3>
- <p>Translates object along y axis in object space by `distance` units.</p>
- <h3>[method:this translateZ]( [param:Float distance] )</h3>
- <p>Translates object along z axis in object space by `distance` units.</p>
- <h3>[method:undefined traverse]( [param:Function callback] )</h3>
- <p>
- callback - A function with as first argument an object3D object.<br /><br />
- Executes the callback on this object and all descendants.<br />
- Note: Modifying the scene graph inside the callback is discouraged.
- </p>
- <h3>[method:undefined traverseVisible]( [param:Function callback] )</h3>
- <p>
- 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.<br />
- Note: Modifying the scene graph inside the callback is discouraged.
- </p>
- <h3>[method:undefined traverseAncestors]( [param:Function callback] )</h3>
- <p>
- callback - A function with as first argument an object3D object.<br /><br />
- Executes the callback on all ancestors.<br />
- Note: Modifying the scene graph inside the callback is discouraged.
- </p>
- <h3>[method:undefined updateMatrix]()</h3>
- <p>Updates the local transform.</p>
- <h3>[method:undefined updateMatrixWorld]( [param:Boolean force] )</h3>
- <p>
- force - A boolean that can be used to bypass
- [page:.matrixWorldAutoUpdate], to recalculate the world matrix of the
- object and descendants on the current frame. Useful if you cannot wait for
- the renderer to update it on the next frame (assuming
- [page:.matrixWorldAutoUpdate] set to `true`).<br /><br />
- Updates the global transform of the object and its descendants if the
- world matrix needs update ([page:.matrixWorldNeedsUpdate] set to true) or
- if the `force` parameter is set to `true`.
- </p>
- <h3>[method:undefined updateWorldMatrix]( [param:Boolean updateParents], [param:Boolean updateChildren] )</h3>
- <p>
- updateParents - recursively updates global transform of ancestors.<br />
- updateChildren - recursively updates global transform of descendants.<br /><br />
- Updates the global transform of the object.
- </p>
- <h3>[method:Vector3 worldToLocal]( [param:Vector3 vector] )</h3>
- <p>
- vector - A vector representing a position in world space.<br /><br />
- Converts the vector from world space to this object's local space.
- </p>
- <h2>Events</h2>
- <h3>added</h3>
- <p>
- Fires when the object has been added to its parent object.
- </p>
- <h3>removed</h3>
- <p>
- Fires when the object has been removed from its parent object.
- </p>
- <h3>childadded</h3>
- <p>
- Fires when a new child object has been added.
- </p>
- <h3>childremoved</h3>
- <p>
- Fires when a new child object has been removed.
- </p>
- <h2>Source</h2>
- <p>
- [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
- </p>
- </body>
- </html>
|