[name]

该类是 three.js 中大多数对象的基类。它提供了一组属性和方法用于在 3D 空间下对对象进行操作。

注意,通过 [page:.add]( object ) 方法,该类可以被应用于成组的对象。然而更好的方式是使用 [page:Group]。

构造函数

[name]()

构造函数没有任何参数。

属性

[property:Boolean castShadow]

当前物体是否需要在阴影图 (shadow map)中被渲染,默认值为 *false*。

[property:Object3D children]

子物体的队列。将对象成组的方法详见 [page:Group]。

[property:Boolean frustumCulled]

当该值被设置时,在每帧渲染该物体前,都会检查物体是否在视锥内。 否则,物体在每帧时都会被渲染,即使物体不可见。默认值为 *true*。

[property:Integer id]

只读 – 当前物体唯一标识符。

[property:Boolean isObject3D]

用于判断当前类或其派生类是 Object3D 对象。默认值为 *true*。

该值被用于内部优化,不应该被更改。

[property:Layers layers]

当前物体所属图层信息。只有当该物体与摄像机至少共享一个图层时,该物体才可见。

[property:Matrix4 matrix]

局部空间下的转移矩阵。

[property:Boolean matrixAutoUpdate]

当设置该值时,对象会重新计算 matrixWorld 属性值,计算位置矩阵、旋转矩阵,并且在每帧都进行缩放。 默认值 [page:Object3D.DefaultMatrixAutoUpdate] 为 true。

[property:Matrix4 matrixWorld]

对象的全局变换矩阵。如果 Object3D 没有父对象,则该矩阵与局部变换矩阵 [page:.matrix] 相同。

[property:Boolean matrixWorldNeedsUpdate]

当该值设置时,对象会在这帧重新计算 matrixWorld,且将该值设置为 false。默认值为 *false*。

[property:Matrix4 modelViewMatrix]

该值被传递给着色器,用于计算对象的坐标。

[property:String name]

对象的可选别名(无需全局唯一)。默认值为空字符串。

[property:Matrix3 normalMatrix]

该值传递给着色器用于计算对向的光照。该矩阵等价于 modelViewMatrix 的左上 3x3 子矩阵的逆矩阵的转置。 需要该矩阵的原因如下,如果单纯使用 modelViewMatrix 会导致法向量在对象缩放时长度未归一化或方向不垂直。

This is passed to the shader and used to calculate lighting for the object.

另外 modelViewMatrix 中的位移信息在法向量计算时并不相关。因而,normalMatrix 使用 Matrix3 矩阵足矣。

[property:function onAfterRender]

可选的回调函数,在每次 Object3D 对象渲染后会被立刻调用。 该函数参数列表如下:renderer, scene, camera, geometry, material, group。

[property:function onBeforeRender]

可选的回调函数,在每次 Object3D 对象渲染前会被调用。 该函数参数列表如下:renderer, scene, camera, geometry, material, group。

[property:Object3D parent]

对象的父对象 [link:https://en.wikipedia.org/wiki/Scene_graph scene graph]。每个对象最多可以有一个父对象。

[property:Vector3 position]

[page:Vector3] 向量,用于表示对象的局部坐标系下的位置。默认值为 (0, 0, 0)。

[property:Quaternion quaternion]

对象的本地旋转四元组 [page:Quaternion Quaternion]。

[property:Boolean receiveShadow]

判断当前材质是否接收阴影。默认值是 *false*。

[property:Number renderOrder]

该值允许对象的默认渲染顺序 [link:https://en.wikipedia.org/wiki/Scene_graph scene graph] 被修改。 但不透明和透明物体依然分开进行渲染排序。渲染顺序的排序是从最低到最高。renderOrder 的默认值为 *0*。

[property:Euler rotation]

物体本地坐标系下的旋转信息 (see [link:https://en.wikipedia.org/wiki/Euler_angles Euler angles]),度量单位为弧度。

[property:Vector3 scale]

物体本地坐标系下的缩放信息。默认值是 [page:Vector3]( 1, 1, 1 )。

[property:Vector3 up]

该值被用于 [page:.lookAt lookAt] 方法。例如,用于判断对象朝向。
默认值 [page:Object3D.DefaultUp] 为 ( 0, 1, 0 )。

[property:object userData]

用于存储 Object3D 的定制化数据的对象。该对象不应该保存任何函数的引用,这些值在对象被克隆时不会被拷贝。

[property:String uuid]

当前对象实例的 [link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID]。 该值会被自动赋值。不应该被修改。

[property:Boolean visible]

如果该值为 *true*,则对象会被显示。默认值为 *true*。

静态属性

不同于非静态属性和方法是按照对象定义的,静态属性和方法是按类定义的,即同一个类的不同实例间是共享静态属性及方法的。 这意味着改变 [page:Object3D.DefaultUp] 或 [page:Object3D.DefaultMatrixAutoUpdate],将会改变在这之后创建的 每个 Object3D 实例(或其派生类的示例)的 [page:.up up] 和 [page:.matrixAutoUpdate matrixAutoUpdate] 的值。已经被创建的 Object3D 实例不受影响。

[property:Vector3 DefaultUp]

当前对象的默认的 [page:.up up] 方向,同样被用于 [page:DirectionalLight]、[page:HemisphereLight]、和 [page:Spotlight](光线方向从上至下) 的默认空间位置。
默认值为 ( 0, 1, 0 ) 。

[property:Vector3 DefaultMatrixAutoUpdate]

新创建的 Object3D 的 [page:.matrixAutoUpdate matrixAutoUpdate] 的默认值。

方法

[page:EventDispatcher EventDispatcher] 可用于此类的方法。

[method:null add]( [param:Object3D object], ... )

将参数指定的 *object* 添加到当前对象。参数指定的对象会被添加一个随机数。由于每个对象只能有一个父对象, 在被设置新的父对象后,参数对象的原父对象将会被移除,并有当前对象替代。

手动将对象成组详情见 [page:Group]。

[method:null applyMatrix]( [param:Matrix4 matrix] )

将参数指定的矩阵应用于对象,并且依据矩阵对对象进行位移、旋转和缩放。

[method:Object3D applyQuaternion]( [param:Quaternion quaternion] )

将参数指定的四元数应用于对象,并对对象进行旋转。

[method:Object3D clone]( [param:Boolean recursive] )

recursive -- 如果为 true, 连同子对象一起克隆。默认值为 true.

返回该对象的克隆,并且依据参数可能同时返回子对象的克隆。

[method:this copy]( [param:Object3D object], [param:Boolean recursive] )

recursive -- 如果为 true, 参数指定的对象连同子对象一起被复制。默认值为 true.

将指定对象拷贝到当前对象。

[method:Object3D getObjectById]( [param:Integer id] )

id -- 对象实例的唯一数字标识符。

搜索对象的所有子对象,并返回第一个 id 与参数匹配的对象。
注意,对象的 id 按照时间顺序依次生生成:1,2,3,...每有一个新物体被创建则 id 增加 1。

[method:Object3D getObjectByName]( [param:String name] )

name -- 匹配子对象 Object3D.name 属性的字符串。

搜索对象的所有子对象,并返回第一个 Object3D.name 属性与参数匹配的对象。
注意,对于大多数对象来说对象名称保持默认值,是一个空的字符串。需要你手动设置才会有意义。

[method:Object3D getObjectByProperty]( [param:String name], [param:Float value] )

name -- 要检索的属性的名称。
value -- 要匹配的属性的值。

搜索对象的子对象返回第一个属性名和属性值都匹配的对象。

[method:Vector3 getWorldPosition]( [param:Vector3 target] )

[page:Vector3 target] — 结果将被复制到这个三维矢量中。

返回一个代表对象全局坐标的三维矢量。

[method:Quaternion getWorldQuaternion]( [param:Quaternion target] )

[page:Quaternion target] — 结果将被复制到这个四元数中.

返回代表对象全局旋转的四元数。

[method:Vector3 getWorldScale]( [param:Vector3 target] )

[page:Vector3 target] — 结果将被复制到这个三维矢量中。

返回代表对象每个轴向的全局缩放参数的三维矢量。

[method:Vector3 getWorldDirection]( [param:Vector3 target] )

[page:Vector3 target] — 结果将被复制到这个三维矢量中。

返回代表对象全局坐标系下 z 轴朝向的三维矢量。

[method:Vector3 localToWorld]( [param:Vector3 vector] )

vector - 代表本地(局部)坐标位置的三维矢量。

将参数指定的本地坐标矢量转换为全局坐标。

[method:null lookAt]( [param:Vector3 vector] )
[method:null lookAt]( [param:Float x], [param:Float y], [param:Float z] )

vector - 代表全局坐标位置的三维矢量。

另外, 参数可以由全局坐标的第一维 ([page:.x x]), 第二维([page:.y y]) 和 第三维([page:.z z])组成的参数列表代替。

旋转物体使得其朝向参数指定的全局坐标。

该方法旋转仅旋转对象及子对象,不会影响父对象的旋转或位移。

[method:Array raycast]( [param:Raycaster raycaster], [param:Array intersects] )

抽象(空)方法,用于获取射线与对象的碰撞信息。 为使用射线检测,[page:Mesh], [page:Line], [page:Points] 子类实现了该方法。

[method:null remove]( [param:Object3D object], ... )

将当前对象下,参数指定的子对象进行删除。该方法可能删除任意多个对象。

[method:this rotateOnAxis]( [param:Vector3 axis], [param:Float angle] )

axis -- 局部坐标系下的归一化向量。
angle -- 以弧度代表的角度信息。

在局部坐标系下按照参数给定向量对物体进行旋转。参数 axis 为归一化的向量。

[method:this rotateOnWorldAxis]( [param:Vector3 axis], [param:Float angle] )

axis -- 全局坐标系下的归一化向量。
angle -- 以弧度代表的角度信息。

在全局坐标系下按照参数给定向量对物体进行旋转。参数 axis 为归一化的向量。 该方法不会影响父对象旋转。

[method:this rotateX]( [param:Float rad] )

rad - 以弧度代表的旋转角度信息。

在局部坐标系下根据参数,绕 x 轴旋转物体。

[method:this rotateY]( [param:Float rad] )

rad - 以弧度代表的旋转角度信息。

在局部坐标系下根据参数,绕 x 轴旋转物体。

[method:this rotateZ]( [param:Float rad] )

rad - 以弧度代表的旋转角度信息。

在局部坐标系下根据参数,绕 x 轴旋转物体。

[method:null setRotationFromAxisAngle]( [param:Vector3 axis], [param:Float angle] )

axis -- 局部坐标系下的归一化向量。
angle -- 以弧度代表的角度信息。

该方法将会在 [page:.quaternion] 中,调用 [page:Quaternion.setFromAxisAngle setFromAxisAngle]( [page:Float axis], [page:Float angle] )。

[method:null setRotationFromEuler]( [param:Euler euler] )

euler -- 以欧拉角代表的旋转角度信息。
该方法将会在 [page:.quaternion] 中,调用 [page:Quaternion.setRotationFromEuler setRotationFromEuler]( [page:Euler euler])。

[method:null setRotationFromMatrix]( [param:Matrix4 m] )

m -- 按照参数给定矩阵旋转对象四元数。
该方法将会在 [page:.quaternion] 中,调用 [page:Quaternion.setFromRotationMatrix setFromRotationMatrix]( [page:Matrix4 m])。

注意,该方法假设参数 m 矩阵的左上 3x3 表示非缩放的旋转信息。

[method:null setRotationFromQuaternion]( [param:Quaternion q] )

q -- 归一化的四元数。

将参数指定四元数拷贝到 [page:.quaternion]。

[method:null toJSON]( [param:Quaternion q] )

将对象转化为 JSON 格式。

[method:this translateOnAxis]( [param:Vector3 axis], [param:Float distance] )

axis -- 局部坐标系下的归一化向量。
distance -- 需要被位移的距离。

将物体沿参数给定方向移动指定距离。假设方向向量已经被归一化。

[method:this translateX]( [param:Float distance] )

将对象沿 X 轴移动参数 *distance* 指定距离。

[method:this translateY]( [param:Float distance] )

将对象沿 Y 轴移动参数 *distance* 指定距离。

[method:this translateZ]( [param:Float distance] )

将对象沿 Z 轴移动参数 *distance* 指定距离。

[method:null traverse]( [param:Function callback] )

callback - 回调函数,第一个参数为 Object3D 对象。

在该对象及所有子对象上执行该函数。

[method:null traverseVisible]( [param:Function callback] )

callback - 回调函数,第一个参数为 Object3D 对象。

如同 traverse 函数,该函数只会在可见的对象及子对象上被调用。

[method:null traverseAncestors]( [param:Function callback] )

callback - 回调函数,第一个参数为 Object3D 对象。

在父对象及所有祖先上被调用。

[method:null updateMatrix]()

更新局部变换矩阵。

[method:null updateMatrixWorld]( [param:Boolean force] )

更新当前对象及子对象的全局变换信息。

[method:Vector3 worldToLocal]( [param:Vector3 vector] )

vector - 全局坐标向量。

将参数给定坐标从全局坐标转换为局部坐标。

资源

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