Threejs 源码解析 (Object3D)
版本95
本来想就这么用算了，可是发现好多都不理解，也就起了解析源码的心思，下苦功夫了，以前老版本的有人写过，不过threejs 更新太快，有些变动，并且他只是简单的注释，并未详细的解释，对于我这种刚开始接触的小白来说，数学就是一大硬伤，本来想做个原生的射线拾取，结果看的我一脸懵逼，跳的函数太多，刚开始容易迷路，所有就打算慢慢啃；方法都尽量解释，以便知道这样的方法为什么得这样的结果；
相关连的部分，我会看完再回来更新；
以前大神写的旧版本：https://blog.csdn.net/omni360
Object3d 是所有模型的基类；
import { Quaternion } from '../math/Quaternion.js';
import { Vector3 } from '../math/Vector3.js';
import { Matrix4 } from '../math/Matrix4.js';
import { EventDispatcher } from './EventDispatcher.js';
import { Euler } from '../math/Euler.js';
import { Layers } from './Layers.js';
import { Matrix3 } from '../math/Matrix3.js';
import { _Math } from '../math/Math.js';
/**
* @author mrdoob / http://mrdoob.com/
* @author mikael emtinger / http://gomo.se/
* @author alteredq / http://alteredqualia.com/
* @author WestLangley / http://github.com/WestLangley
* @author elephantatwork / www.elephantatwork.ch
*/
var object3DId = 0;
function Object3D() {
/**
* Object.defineProperty（obj, prop ， descriptior） ：表示新增或者修改一个已经存在的属性，并返回这个对象;
* obj ： 需定义属性的对象
* prop: 需定义或者修改属性的名字
* descriptor : 将被定义或修改的属性的描述符
*/
Object.defineProperty( this, 'id', { value: object3DId ++ } );
this.uuid = _Math.generateUUID();//生成id
this.name = '';
this.type = 'Object3D';
this.parent = null;
this.children = [];
this.up = Object3D.DefaultUp.clone();//初始化以Y轴正方向的向量
var position = new Vector3();
var rotation = new Euler();//初始化欧拉角
var quaternion = new Quaternion();//初始化成四元矩阵
var scale = new Vector3( 1, 1, 1 );
/**
* 给对象rotation属性绑定setFromEuler()方法
* 当rotation属性值更改，调用setFromEuler()方法
*/
function onRotationChange() {
quaternion.setFromEuler( rotation, false );//欧拉角转化成四元数
}
/**
* 给对象quaternion属性绑定setFromQuaternion()方法
* 当quaternion属性值更改，setFromQuaternion()方法
*/
function onQuaternionChange() {
rotation.setFromQuaternion( quaternion, undefined, false );//通过设置四元，旋转得到坐标
}
//绑定监听
rotation.onChange( onRotationChange );
quaternion.onChange( onQuaternionChange );
//定义属性
Object.defineProperties( this, {
position: {
enumerable: true,
value: position
},
rotation: {
enumerable: true,
value: rotation
},
quaternion: {
enumerable: true,
value: quaternion
},
scale: {
enumerable: true,
value: scale
},
modelViewMatrix: {
value: new Matrix4()
},
normalMatrix: {
value: new Matrix3()
}
} );
this.matrix = new Matrix4();//对象变换矩阵
this.matrixWorld = new Matrix4();//对象世界矩阵
this.matrixAutoUpdate = Object3D.DefaultMatrixAutoUpdate;//矩阵自动更新
this.matrixWorldNeedsUpdate = false;//每帧是否重新计算世界矩阵
this.layers = new Layers();//层
this.visible = true;//是否隐藏
this.castShadow = false;//是否生成阴影
this.receiveShadow = false;//是否接受阴影
this.frustumCulled = true;//锥形剔除
this.renderOrder = 0;//渲染命令
this.userData = {};//用户自定义数据
}
Object3D.DefaultUp = new Vector3( 0, 1, 0 );//Object3D 的up方向，用以camera 的up 默认y轴的正方向
Object3D.DefaultMatrixAutoUpdate = true;
//事件
Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ), {
constructor: Object3D,
isObject3D: true,
//在渲染之前
onBeforeRender: function () {},
//在渲染之后
onAfterRender: function () {},
//对变换矩阵的变换，达到缩放，旋转，移动的目的
applyMatrix: function ( matrix ) {
//在现有的矩阵上进行变换，两个矩阵相乘，更新原来的变换矩阵
this.matrix.multiplyMatrices( matrix, this.matrix );
//把变换矩阵分解成 位置，四元，缩放
this.matrix.decompose( this.position, this.quaternion, this.scale );
},
//变换四元数
applyQuaternion: function ( q ) {
this.quaternion.premultiply( q );
return this;
},
//通过四元数的方式旋转任意坐标轴(参数axis)旋转角度(参数angle),最后将结果返回到this.quternion属性中
setRotationFromAxisAngle: function ( axis, angle ) {
// assumes axis is normalized
this.quaternion.setFromAxisAngle( axis, angle );
},
//通过一次欧拉旋转(参数euler)设置四元数旋转,最后将结果返回到this.quternion属性中
setRotationFromEuler: function ( euler ) {
this.quaternion.setFromEuler( euler, true );
},
//利用一个参数m(旋转矩阵),达到旋转变换的目的吧,最后将结果返回到this.quternion属性中
setRotationFromMatrix: function ( m ) {
// assumes the upper 3x3 of m is a pure rotation matrix (i.e, unscaled)
this.quaternion.setFromRotationMatrix( m );
},
//通过规范化的旋转四元数直接应用旋转
setRotationFromQuaternion: function ( q ) {
// assumes q is normalized
this.quaternion.copy( q );
},
/**
* @function
* @desc 通过坐标轴旋转
* @param {THREE.Vector3} axis
* @param {float} angle 弧度
* @return {THREE.Object3D}
*/
rotateOnAxis: function () {
// rotate object on axis in object space
// axis is assumed to be normalized
var q1 = new Quaternion();
return function rotateOnAxis( axis, angle ) {
q1.setFromAxisAngle( axis, angle );
this.quaternion.multiply( q1 );
return this;
};
}(),
/*
* 旋转世界坐标，不旋转父类，与上面方法类似
* */
rotateOnWorldAxis: function () {
// rotate object on axis in world space
// axis is assumed to be normalized
// method assumes no rotated parent
var q1 = new Quaternion();
return function rotateOnWorldAxis( axis, angle ) {
q1.setFromAxisAngle( axis, angle );
this.quaternion.premultiply( q1 );
return this;
};
}(),
/**
* 绕X轴旋转angle度
*/
rotateX: function () {
var v1 = new Vector3( 1, 0, 0 );
return function rotateX( angle ) {
return this.rotateOnAxis( v1, angle );
};
}(),
/**
* 绕Z轴旋转angle度
*/
rotateY: function () {
var v1 = new Vector3( 0, 1, 0 );
return function rotateY( angle ) {
return this.rotateOnAxis( v1, angle );
};
}(),
/**
* 绕Z轴旋转angle度
*/
rotateZ: function () {
var v1 = new Vector3( 0, 0, 1 );
return function rotateZ( angle ) {
return this.rotateOnAxis( v1, angle );
};
}(),
/**
* @function
* @desc 对象延任意坐标轴(参数axis)移动指定距离(参数distance)
* @param {THREE.Vector3} axis 平移轴
* @param {float} distance 平移距离
* @return {THREE.Object3D}
*/
translateOnAxis: function () {
// translate object by distance along axis in object space 对象空间中沿轴的距离转换对象
// axis is assumed to be normalized
var v1 = new Vector3();
return function translateOnAxis( axis, distance ) {
v1.copy( axis ).applyQuaternion( this.quaternion );//平移方向向量乘以当前四元数，乘以四元数是因为，如果物体被选择，那么它自身的轴方向是方向改变的
this.position.add( v1.multiplyScalar( distance ) );//得到最终的移动位置
return this;
};
}(),
/**
* 对象延X轴方向移动距离为（distance）
*/
translateX: function () {
var v1 = new Vector3( 1, 0, 0 );
return function translateX( distance ) {
return this.translateOnAxis( v1, distance );
};
}(),
/**
* 对象延Y轴方向移动距离为（distance）
*/
translateY: function () {
var v1 = new Vector3( 0, 1, 0 );
return function translateY( distance ) {
return this.translateOnAxis( v1, distance );
};
}(),
/**
* 对象延Z轴方向移动距离为（distance）
*/
translateZ: function () {
var v1 = new Vector3( 0, 0, 1 );
return function translateZ( distance ) {
return this.translateOnAxis( v1, distance );
};
}(),
/**
* @desc 将参数vector,从对象坐标空间变换成世界坐标空间
* @param {THREE.Vector3} vector
* @returns {THREE.Vector3}
*/
localToWorld: function ( vector ) {
return vector.applyMatrix4( this.matrixWorld );
},
/**
* @desc 将参数vector,从世界坐标空间变换成对象坐标空间
* @param {THREE.Vector3} vector
* @returns {THREE.Vector3}
*/
worldToLocal: function () {
var m1 = new Matrix4();
return function worldToLocal( vector ) {
return vector.applyMatrix4( m1.getInverse( this.matrixWorld ) );
};
}(),
/**
* 对象看向的位置（vector）
*/
lookAt: function () {
// This method does not support objects with rotated and/or translated parent(s)
var m1 = new Matrix4();
var vector = new Vector3();
return function lookAt( x, y, z ) {
if ( x.isVector3 ) {
vector.copy( x );
} else {
vector.set( x, y, z );
}
if ( this.isCamera ) {
m1.lookAt( this.position, vector, this.up );
} else {
m1.lookAt( vector, this.position, this.up );
}
this.quaternion.setFromRotationMatrix( m1 );
};
}(),
/**
* @desc 对象(参数object),设置为当前对象的子对象
* @param {THREE.Object3D} object
* @returns {THREE.Object3D}
*/
add: function ( object ) {
//arguments 是每个函数都有的，它是函数参数数组， arguments[ i ] 得到参数对象，i的最大值是传了多少个参数
if ( arguments.length > 1 ) {
for ( var i = 0; i < arguments.length; i ++ ) {
this.add( arguments[ i ] );
}
return this;
}
if ( object === this ) {
console.error( "THREE.Object3D.add: object can't be added as a child of itself.", object );
return this;
}
if ( ( object && object.isObject3D ) ) {
if ( object.parent !== null ) {
object.parent.remove( object );
}
object.parent = this;
object.dispatchEvent( { type: 'added' } );
this.children.push( object );
} else {
console.error( "THREE.Object3D.add: object not an instance of THREE.Object3D.", object );
}
return this;
},
/**
* @desc 对象(参数object),从当前对象的子对象列表中删除
* @param {THREE.Object3D} object
*/
remove: function ( object ) {
if ( arguments.length > 1 ) {
for ( var i = 0; i < arguments.length; i ++ ) {
this.remove( arguments[ i ] );
}
return this;
}
var index = this.children.indexOf( object );
if ( index !== - 1 ) {
object.parent = null;
object.dispatchEvent( { type: 'removed' } );
this.children.splice( index, 1 );
}
return this;
},
/**
* @desc 通过id获得子对象
* @param {String} name
* @param {boolean} recursive 默认为false,表示不才查找子对象的子对象
* @returns {THREE.Object3D}
*/
getObjectById: function ( id ) {
return this.getObjectByProperty( 'id', id );
},
getObjectByName: function ( name ) {
return this.getObjectByProperty( 'name', name );
},
getObjectByProperty: function ( name, value ) {
if ( this[ name ] === value ) return this;
for ( var i = 0, l = this.children.length; i < l; i ++ ) {
var child = this.children[ i ];
var object = child.getObjectByProperty( name, value );
if ( object !== undefined ) {
return object;
}
}
return undefined;
},
/**
* @desc 获得世界坐标系下的平移坐标，也就是根据变换矩阵分解得到平移的坐标
* @param {THREE.Vector3} optionalTarget
* @returns {THREE.Vector3}
*/
getWorldPosition: function ( target ) {
if ( target === undefined ) {
console.warn( 'THREE.Object3D: .getWorldPosition() target is now required' );
target = new Vector3();
}
this.updateMatrixWorld( true );
return target.setFromMatrixPosition( this.matrixWorld );
},
/**
* @function
* @desc 获得世界坐标系下的四元数，通过变换矩阵，分解成位置坐标，四元数，缩放，返回四元数
* @param {THREE.Quaternion} optionalTarget
* @return {THREE.Quaternion}
*/
getWorldQuaternion: function () {
var position = new Vector3();
var scale = new Vector3();
return function getWorldQuaternion( target ) {
if ( target === undefined ) {
console.warn( 'THREE.Object3D: .getWorldQuaternion() target is now required' );
target = new Quaternion();
}
this.updateMatrixWorld( true );
this.matrixWorld.decompose( position, target, scale );
return target;
};
}(),
/**
* @function
* @desc 获得世界坐标系下的缩放向量
* @param {THREE.Vector3} optionalTarget
* @return {THREE.Vector3}
*/
getWorldScale: function () {
var position = new Vector3();
var quaternion = new Quaternion();
return function getWorldScale( target ) {
if ( target === undefined ) {
console.warn( 'THREE.Object3D: .getWorldScale() target is now required' );
target = new Vector3();
}
this.updateMatrixWorld( true );
this.matrixWorld.decompose( position, quaternion, target );
return target;
};
}(),
/**
* @function
* @desc 获得世界坐标系下的旋转角
* @param {THREE.Vector3} optionalTarget
* @return {THREE.Vector3}
*/
getWorldDirection: function () {
var quaternion = new Quaternion();
return function getWorldDirection( target ) {
if ( target === undefined ) {
console.warn( 'THREE.Object3D: .getWorldDirection() target is now required' );
target = new Vector3();
}
this.getWorldQuaternion( quaternion );
return target.set( 0, 0, 1 ).applyQuaternion( quaternion );
};
}(),
/**
* @desc 光线跟踪 ，未写代码
*/
raycast: function () {},
/**
* @desc 遍历当前对象以及子对象并且应用callback方法
* @param {requestCallback} callback
*/
traverse: function ( callback ) {
callback( this );
var children = this.children;
for ( var i = 0, l = children.length; i < l; i ++ ) {
children[ i ].traverse( callback );
}
},
/**
* @desc 遍历当前对象以及子对象，当对象可见时并且应用callback方法
* @param {requestCallback} callback
*/
traverseVisible: function ( callback ) {
if ( this.visible === false ) return;
callback( this );
var children = this.children;
for ( var i = 0, l = children.length; i < l; i ++ ) {
children[ i ].traverseVisible( callback );
}
},
traverseAncestors: function ( callback ) {
var parent = this.parent;
if ( parent !== null ) {
callback( parent );
parent.traverseAncestors( callback );
}
},
/**
* @desc 根据位置，四元数，缩放比例更新矩阵，并设置世界矩阵需要更新
*/
updateMatrix: function () {
this.matrix.compose( this.position, this.quaternion, this.scale );
this.matrixWorldNeedsUpdate = true;
},
/**
* @desc 根据位置，四元数，缩放比例更新世界矩阵
* @param {boolean} force 是否强制更新
*/
updateMatrixWorld: function ( force ) {
if ( this.matrixAutoUpdate ) this.updateMatrix();
if ( this.matrixWorldNeedsUpdate || force ) {
if ( this.parent === null ) {
this.matrixWorld.copy( this.matrix );
} else {
this.matrixWorld.multiplyMatrices( this.parent.matrixWorld, this.matrix );
}
this.matrixWorldNeedsUpdate = false;
force = true;
}
// update children
var children = this.children;
for ( var i = 0, l = children.length; i < l; i ++ ) {
children[ i ].updateMatrixWorld( force );
}
},
/**
* Object3D存为json 格式
* @param meta
* @returns {{}}
*/
toJSON: function ( meta ) {
// meta is a string when called from JSON.stringify
var isRootObject = ( meta === undefined || typeof meta === 'string' );
var output = {};
// meta is a hash used to collect geometries, materials.
// not providing it implies that this is the root object
// being serialized.
if ( isRootObject ) {
// initialize meta obj
meta = {
geometries: {},
materials: {},
textures: {},
images: {},
shapes: {}
};
output.metadata = {
version: 4.5,
type: 'Object',
generator: 'Object3D.toJSON'
};
}
// standard Object3D serialization
var object = {};
object.uuid = this.uuid;
object.type = this.type;
if ( this.name !== '' ) object.name = this.name;
if ( this.castShadow === true ) object.castShadow = true;
if ( this.receiveShadow === true ) object.receiveShadow = true;
if ( this.visible === false ) object.visible = false;
if ( this.frustumCulled === false ) object.frustumCulled = false;
if ( this.renderOrder !== 0 ) object.renderOrder = this.renderOrder;
if ( JSON.stringify( this.userData ) !== '{}' ) object.userData = this.userData;
object.layers = this.layers.mask;
object.matrix = this.matrix.toArray();
if ( this.matrixAutoUpdate === false ) object.matrixAutoUpdate = false;
//
function serialize( library, element ) {
if ( library[ element.uuid ] === undefined ) {
library[ element.uuid ] = element.toJSON( meta );
}
return element.uuid;
}
if ( this.isMesh || this.isLine || this.isPoints ) {
object.geometry = serialize( meta.geometries, this.geometry );
var parameters = this.geometry.parameters;
if ( parameters !== undefined && parameters.shapes !== undefined ) {
var shapes = parameters.shapes;
if ( Array.isArray( shapes ) ) {
for ( var i = 0, l = shapes.length; i < l; i ++ ) {
var shape = shapes[ i ];
serialize( meta.shapes, shape );
}
} else {
serialize( meta.shapes, shapes );
}
}
}
if ( this.material !== undefined ) {
if ( Array.isArray( this.material ) ) {
var uuids = [];
for ( var i = 0, l = this.material.length; i < l; i ++ ) {
uuids.push( serialize( meta.materials, this.material[ i ] ) );
}
object.material = uuids;
} else {
object.material = serialize( meta.materials, this.material );
}
}
//
if ( this.children.length > 0 ) {
object.children = [];
for ( var i = 0; i < this.children.length; i ++ ) {
object.children.push( this.children[ i ].toJSON( meta ).object );
}
}
if ( isRootObject ) {
var geometries = extractFromCache( meta.geometries );
var materials = extractFromCache( meta.materials );
var textures = extractFromCache( meta.textures );
var images = extractFromCache( meta.images );
var shapes = extractFromCache( meta.shapes );
if ( geometries.length > 0 ) output.geometries = geometries;
if ( materials.length > 0 ) output.materials = materials;
if ( textures.length > 0 ) output.textures = textures;
if ( images.length > 0 ) output.images = images;
if ( shapes.length > 0 ) output.shapes = shapes;
}
output.object = object;
return output;
// extract data from the cache hash
// remove metadata on each item
// and return as array
function extractFromCache( cache ) {
var values = [];
for ( var key in cache ) {
var data = cache[ key ];
delete data.metadata;
values.push( data );
}
return values;
}
},
/**
* 克隆Object3D
* @param recursive 为true ，克隆其子对象，否则只克隆当前对象，默认为true
*/
clone: function ( recursive ) {
return new this.constructor().copy( this, recursive );
},
/**
* 复制
* @param source
* @param recursive
* @returns {copy}
*/
copy: function ( source, recursive ) {
if ( recursive === undefined ) recursive = true;
this.name = source.name;
this.up.copy( source.up );
this.position.copy( source.position );
this.quaternion.copy( source.quaternion );
this.scale.copy( source.scale );
this.matrix.copy( source.matrix );
this.matrixWorld.copy( source.matrixWorld );
this.matrixAutoUpdate = source.matrixAutoUpdate;
this.matrixWorldNeedsUpdate = source.matrixWorldNeedsUpdate;
this.layers.mask = source.layers.mask;
this.visible = source.visible;
this.castShadow = source.castShadow;
this.receiveShadow = source.receiveShadow;
this.frustumCulled = source.frustumCulled;
this.renderOrder = source.renderOrder;
this.userData = JSON.parse( JSON.stringify( source.userData ) );
if ( recursive === true ) {
for ( var i = 0; i < source.children.length; i ++ ) {
var child = source.children[ i ];
this.add( child.clone() );
}
}
return this;
}
} );
export { Object3D };