three.js Object3D

這是Three.js中大部分對象的基類，提供了一系列的屬性和方法來對三維空間中的物體進(jìn)行操縱。請注意，可以通過.add( object )方法來將對象進(jìn)行組合，該方法將對象添加為子對象，但為此最好使用Group（來作為父對象）。

構(gòu)造器

Object3D()

構(gòu)造器中不帶有參數(shù)。

屬性

.animations : AnimationClip

包含對象動畫剪輯的數(shù)組。

.castShadow : Boolean

對象是否被渲染到陰影貼圖中。默認(rèn)值為false。

.children : Array

含有對象的子級的數(shù)組。請參閱Group來了解將手動對象進(jìn)行分組的相關(guān)信息。

.customDepthMaterial : Material

渲染到深度圖時(shí)要使用的自定義深度材質(zhì)。只能在網(wǎng)格上下文中使用。當(dāng)使用 DirectionalLight 或 SpotLight 進(jìn)行陰影投射時(shí)，如果您正在修改頂點(diǎn)著色器中的頂點(diǎn)位置，則必須為適當(dāng)?shù)年幱爸付?nbsp;customDepthMaterial。默認(rèn)是未定義的。

.customDistanceMaterial : Material

與customDepthMaterial相同，但與PointLight一起使用。默認(rèn)值為undefined。

.frustumCulled : Boolean

設(shè)置后，它會在渲染對象之前檢查每一幀對象是否在相機(jī)的視錐體中。如果設(shè)置為 false，即使對象不在相機(jī)的視錐體中，也會在每一幀渲染該對象。默認(rèn)為真。

.id : Integer

只讀 —— 表示該對象實(shí)例ID的唯一數(shù)字。

.isObject3D : Boolean

用于檢查給定對象是否為 Object3D 類型的只讀標(biāo)志。

.layers : Layers

物體的層級關(guān)系。 物體只有和一個正在使用的Camera至少在同一個層時(shí)才可見。使用 Raycaster 時(shí)，此屬性還可用于在光線相交測試中過濾掉不需要的對象。

.matrix : Matrix4

局部變換矩陣。

.matrixAutoUpdate : Boolean

當(dāng)這個屬性設(shè)置了之后，它將計(jì)算每一幀的位移、旋轉(zhuǎn)（四元變換）和縮放矩陣，并重新計(jì)算matrixWorld屬性。默認(rèn)值是Object3D.DefaultMatrixAutoUpdate (true)。

.matrixWorld : Matrix4

物體的世界變換。若這個Object3D沒有父級，則它將和local transform .matrix（局部變換矩陣）相同。

.matrixWorldAutoUpdate : Boolean

默認(rèn)為真。如果設(shè)置，則渲染器會檢查每一幀對象及其子對象是否需要矩陣更新。如果不是，則您必須自己維護(hù)對象及其子項(xiàng)中的所有矩陣。

.matrixWorldNeedsUpdate : Boolean

當(dāng)這個屬性設(shè)置了之后，它將計(jì)算在那一幀中的matrixWorld，并將這個值重置為false。默認(rèn)值為false。

.modelViewMatrix : Matrix4

這個值傳遞給著色器，用于計(jì)算物體的位置。

.name : String

對象的名稱，可選、不必唯一。默認(rèn)值是一個空字符串。

.normalMatrix : Matrix3

這個值傳遞給著色器，用于計(jì)算物體的光照。 它是物體的modelViewMatrix矩陣中，左上角3x3子矩陣的逆的轉(zhuǎn)置矩陣。使用這個特殊矩陣的原因，是只需使用modelViewMatrix就可以得出一個法線（縮放時(shí)）的非單位長度或者非垂直的方向（不規(guī)則縮放時(shí)）。另一方面，modelViewMatrix矩陣中的位移部分和法線的計(jì)算無關(guān)，因此Matrix3就已經(jīng)足夠了。

.onAfterRender : Function

一個可選的回調(diào)函數(shù)，在Object3D渲染之后直接執(zhí)行。 使用以下參數(shù)來調(diào)用此函數(shù)：renderer，scene，camera，geometry，material，group。

請注意，此回調(diào)僅針對可渲染的 3D 對象執(zhí)行。意思是 3D 對象，它們使用幾何體和材料（如網(wǎng)格、線、點(diǎn)或精靈的實(shí)例）定義其視覺外觀。 Object3D、Group 或 Bone 的實(shí)例不可渲染，因此不會為此類對象執(zhí)行此回調(diào)。

.onBeforeRender : Function

一個可選的回調(diào)函數(shù)，在Object3D渲染之前直接執(zhí)行。 使用以下參數(shù)來調(diào)用此函數(shù)：renderer，scene，camera，geometry，material，group。

請注意，此回調(diào)僅針對可渲染的 3D 對象執(zhí)行。意思是 3D 對象，它們使用幾何體和材料（如網(wǎng)格、線、點(diǎn)或精靈的實(shí)例）定義其視覺外觀。 Object3D、Group 或 Bone 的實(shí)例不可渲染，因此不會為此類對象執(zhí)行此回調(diào)。

.parent : Object3D

在scene graph（場景圖）中，一個對象的父級對象。 一個對象最多僅能有一個父級對象。

.position : Vector3

表示對象局部位置的Vector3。默認(rèn)值為(0, 0, 0)。

.quaternion : Quaternion

表示對象局部旋轉(zhuǎn)的Quaternion（四元數(shù)）。

.receiveShadow : Boolean

材質(zhì)是否接收陰影。默認(rèn)值為false。

.renderOrder : Number

這個值將使得scene graph（場景圖）中默認(rèn)的的渲染順序被覆蓋， 即使不透明對象和透明對象保持獨(dú)立順序。 渲染順序是由低到高來排序的，默認(rèn)值為0。

.rotation : Euler

物體的局部旋轉(zhuǎn)，以弧度來表示。（請參閱Euler angles-歐拉角）

.scale : Vector3

物體的局部縮放。默認(rèn)值是Vector3( 1, 1, 1 )。

.up : Vector3

這個屬性由lookAt方法所使用，例如，來決定結(jié)果的朝向。 默認(rèn)值是Object3D.DefaultUp，即( 0, 1, 0 )。

.userData : Object

一個用于存儲Object3D自定義數(shù)據(jù)的對象。 它不應(yīng)當(dāng)包含對函數(shù)的引用，因?yàn)檫@些函數(shù)將不會被克隆。

.uuid : String

該對象實(shí)例的UUID。 這是一個自動生成的值，不應(yīng)當(dāng)對其進(jìn)行修改。

.visible : Boolean

可見性。這個值為true時(shí)，物體將被渲染。默認(rèn)值為true。

靜態(tài)屬性

靜態(tài)屬性和方法由每個類所定義，并非由每個類的實(shí)例所定義。 也就是說，改變Object3D.DefaultUp或Object3D.DefaultMatrixAutoUpdate的值， 將改變每個在此之后由Object3D類（或派生類）創(chuàng)建的實(shí)例中的up和matrixAutoUpdate的值。（已經(jīng)創(chuàng)建好的Object3D不會受到影響）。

.DefaultUp : Vector3

默認(rèn)的物體的up方向，同時(shí)也作為DirectionalLight、HemisphereLight和Spotlight（自頂向下創(chuàng)建的燈光）的默認(rèn)方向。 默認(rèn)設(shè)為( 0, 1, 0 )。

.DefaultMatrixAutoUpdate : Boolean

matrixAutoUpdate的默認(rèn)設(shè)置，用于新創(chuàng)建的Object3D。

方法

EventDispatcher 在該類上可用的所有方法。

.add ( object : Object3D, ... ) : this

添加對象到這個對象的子級，可以添加任意數(shù)量的對象。 當(dāng)前傳入的對象中的父級將在這里被移除，因?yàn)橐粋€對象僅能有一個父級。請參閱Group來查看手動編組對象的相關(guān)信息。

.applyMatrix4 ( matrix : Matrix4 ) : undefined

對當(dāng)前物體應(yīng)用這個變換矩陣，并更新物體的位置、旋轉(zhuǎn)和縮放。

.applyQuaternion ( quaternion : Quaternion ) : this

對當(dāng)前物體應(yīng)用由四元數(shù)所表示的變換。

.attach ( object : Object3D ) : this

將object作為子級來添加到該對象中，同時(shí)保持該object的世界變換。

.clone ( recursive : Boolean ) : Object3D

recursive —— 如果值為true，則該物體的后代也會被克隆。默認(rèn)值為true。返回對象前物體的克隆（以及可選的所有后代）。

.copy ( object : Object3D, recursive : Boolean ) : this

recursive —— 如果值為true，則該物體的后代也會被復(fù)制。默認(rèn)值為true。復(fù)制給定的對象到這個對象中。 請注意，事件監(jiān)聽器和用戶定義的回調(diào)函數(shù)（.onAfterRender 和 .onBeforeRender）不會被復(fù)制。

.getObjectById ( id : Integer ) : Object3D

id —— 標(biāo)識該對象實(shí)例的唯一數(shù)字。從該對象開始，搜索一個對象及其子級，返回第一個帶有匹配id的子對象。請注意，id是按照時(shí)間順序來分配的：1、2、3、……，每增加一個新的對象就自增1。

.getObjectByName ( name : String ) : Object3D

name —— 用于來匹配子物體中Object3D.name屬性的字符串。從該對象開始，搜索一個對象及其子級，返回第一個帶有匹配name的子對象。請注意，大多數(shù)的對象中name默認(rèn)是一個空字符串，要使用這個方法，你將需要手動地設(shè)置name屬性。

.getObjectByProperty ( name : String, value : Any ) : Object3D

name —— 將要用于查找的屬性的名稱。value —— 給定的屬性的值。從該對象開始，搜索一個對象及其子級，返回第一個給定的屬性中包含有匹配的值的子對象。

.getObjectsByProperty ( name : String, value : Any ) : Object3D

name —— 將要用于查找的屬性的名稱。value —— 給定的屬性的值。從此對象開始，搜索一個對象及其子對象，返回包含給定屬性的匹配值的所有子對象。

.getWorldPosition ( target : Vector3 ) : Vector3

target — 結(jié)果將被復(fù)制到這個Vector3中。返回一個表示該物體在世界空間中位置的矢量。

.getWorldQuaternion ( target : Quaternion ) : Quaternion

target — 結(jié)果將被復(fù)制到這個Quaternion中。返回一個表示該物體在世界空間中旋轉(zhuǎn)的四元數(shù)。

.getWorldScale ( target : Vector3 ) : Vector3

target — 結(jié)果將被復(fù)制到這個Vector3中。返回一個包含著該物體在世界空間中各個軸向上所應(yīng)用的縮放因數(shù)的矢量。

.getWorldDirection ( target : Vector3 ) : Vector3

target — 結(jié)果將被復(fù)制到這個Vector3中。返回一個表示該物體在世界空間中Z軸正方向的矢量。

.localToWorld ( vector : Vector3 ) : Vector3

vector - 一個表示在該物體局部空間中位置的向量。將該向量從物體的局部空間轉(zhuǎn)換到世界空間。

.lookAt ( vector : Vector3 ) : undefined.lookAt ( x : Float, y : Float, z : Float ) : undefined

vector - 一個表示世界空間中位置的向量。也可以使用世界空間中x、y和z的位置分量。旋轉(zhuǎn)物體使其在世界空間中面朝一個點(diǎn)。這一方法不支持其父級被旋轉(zhuǎn)過或者被位移過的物體。

.raycast ( raycaster : Raycaster, intersects : Array ) : undefined

抽象（空方法），在一條被投射出的射線與這個物體之間獲得交點(diǎn)。 在一些子類，例如Mesh, Line, and Points實(shí)現(xiàn)了這個方法，以用于光線投射。

.remove ( object : Object3D, ... ) : this

從當(dāng)前對象的子級中移除對象?？梢砸瞥我鈹?shù)量的對象。

.removeFromParent () : this

將此對象從其當(dāng)前父對象中移除。

.rotateOnAxis ( axis : Vector3, angle : Float ) : this

axis —— 一個在局部空間中的標(biāo)準(zhǔn)化向量。angle —— 角度，以弧度來表示。在局部空間中繞著該物體的軸來旋轉(zhuǎn)一個物體，假設(shè)這個軸已被標(biāo)準(zhǔn)化。

.rotateOnWorldAxis ( axis : Vector3, angle : Float ) : this

axis -- 一個在世界空間中的標(biāo)準(zhǔn)化向量。angle -- 角度，以弧度來表示。在世界空間中繞著該物體的軸來旋轉(zhuǎn)一個物體，假設(shè)這個軸已被標(biāo)準(zhǔn)化。 方法假設(shè)該物體沒有旋轉(zhuǎn)過的父級。

.rotateX ( rad : Float ) : this

rad - 將要旋轉(zhuǎn)的角度（以弧度來表示）。繞局部空間的X軸旋轉(zhuǎn)這個物體。

.rotateY ( rad : Float ) : this

rad - 將要旋轉(zhuǎn)的角度（以弧度來表示）。繞局部空間的Y軸旋轉(zhuǎn)這個物體。

.rotateZ ( rad : Float ) : this

rad - 將要旋轉(zhuǎn)的角度（以弧度來表示）。繞局部空間的Z軸旋轉(zhuǎn)這個物體。

.setRotationFromAxisAngle ( axis : Vector3, angle : Float ) : undefined

axis -- 一個在局部空間中的標(biāo)準(zhǔn)化向量。angle -- 角度（以弧度來表示）。調(diào)用.quaternion中的setFromAxisAngle( axis, angle )。

.setRotationFromEuler ( euler : Euler ) : undefined

euler -- 指定了旋轉(zhuǎn)量的歐拉角。調(diào)用.quaternion中的setRotationFromEuler( euler)。

.setRotationFromMatrix ( m : Matrix4 ) : undefined

m -- 通過該矩陣中的旋轉(zhuǎn)分量來旋轉(zhuǎn)四元數(shù)。調(diào)用.quaternion中的setFromRotationMatrix( m)。請注意，這里假設(shè)m上的3x3矩陣是一個純旋轉(zhuǎn)矩陣（即未縮放的矩陣）。

.setRotationFromQuaternion ( q : Quaternion ) : undefined

q -- 標(biāo)準(zhǔn)化的四元數(shù)。將所給的四元數(shù)復(fù)制到.quaternion中。

.toJSON ( meta : Object ) : Object

meta -- 包含有元數(shù)據(jù)的對象，例如該對象的材質(zhì)、紋理或圖片。 將對象轉(zhuǎn)換為 three.js JSON Object/Scene format（three.js JSON 物體/場景格式）。

.translateOnAxis ( axis : Vector3, distance : Float ) : this

axis -- 一個在局部空間中的標(biāo)準(zhǔn)化向量。distance -- 將要平移的距離。在局部空間中沿著一條軸來平移物體，假設(shè)軸已被標(biāo)準(zhǔn)化。

.translateX ( distance : Float ) : this

沿著X軸將平移distance個單位。

.translateY ( distance : Float ) : this

沿著Y軸將平移distance個單位。

.translateZ ( distance : Float ) : this

沿著Z軸將平移distance個單位。

.traverse ( callback : Function ) : undefined

callback - 以一個object3D對象作為第一個參數(shù)的函數(shù)。在對象以及后代中執(zhí)行的回調(diào)函數(shù)。

.traverseVisible ( callback : Function ) : undefined

callback - 以一個object3D對象作為第一個參數(shù)的函數(shù)。類似traverse函數(shù)，但在這里，回調(diào)函數(shù)僅對可見的對象執(zhí)行，不可見對象的后代將不遍歷。

.traverseAncestors ( callback : Function ) : undefined

callback - 以一個object3D對象作為第一個參數(shù)的函數(shù)。在所有的祖先中執(zhí)行回調(diào)函數(shù)。

.updateMatrix () : undefined

更新局部變換。

.updateMatrixWorld ( force : Boolean ) : undefined

更新物體及其后代的全局變換。

.updateWorldMatrix ( updateParents : Boolean, updateChildren : Boolean ) : undefined

updateParents - 遞歸更新祖先的全局變換。updateChildren - 遞歸更新后代的全局變換。更新對象的全局變換。

.worldToLocal ( vector : Vector3 ) : Vector3

vector - 一個表示在世界空間中位置的向量。將該向量從世界空間轉(zhuǎn)換到物體的局部空間。

源代碼

src/core/Object3D.js