javascript
/
three.js
镜像来自 https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461
							<!DOCTYPE html>
<html lang="zh">

<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">
		这是Three.js中大部分对象的基类，提供了一系列的属性和方法来对三维空间中的物体进行操纵。<br /><br />

		请注意，可以通过[page:.add]( object )方法来将对象进行组合，该方法将对象添加为子对象，但为此最好使用[page:Group]（来作为父对象）。
	</p>


	<h2>构造器</h2>


	<h3>[name]()</h3>
	<p>
		构造器中不带有参数。
	</p>


	<h2>属性</h2>

	<h3>[property:AnimationClip animations]</h3>
	<p>Array with object's animation clips.</p>

	<h3>[property:Boolean castShadow]</h3>
	<p>对象是否被渲染到阴影贴图中。默认值为*false*。</p>

	<h3>[property:Object3D children]</h3>
	<p>含有对象的子级的数组。请参阅[page:Group]来了解将手动对象进行分组的相关信息。</p>

	<h3>[property:Material customDepthMaterial]</h3>
	<p>渲染到深度贴图时此材质要使用的自定义深度材质。
		当使用[page:DirectionalLight]或[page:SpotLight]进行阴影投射时，如果您正在（a）修改顶点着色器中的顶点位置，
		（b）使用位移贴图，（c）alphaTest中使用alpha贴图，或（d）alphaTest中使用透明纹理，
		您必须指定customDepthMaterial以得到合适的阴影。默认值*undefined*。
	</p>

	<h3>[property:Material customDistanceMaterial]</h3>
	<p>与[page:.customDepthMaterial customDepthMaterial]相同，但与[page:PointLight]一起使用。默认值为*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>只读 —— 表示该对象实例ID的唯一数字。</p>

	<h3>[property:Layers layers]</h3>
	<p>
		物体的层级关系。
		物体只有和一个正在使用的[page:Camera]至少在同一个层时才可见。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>局部变换矩阵。</p>

	<h3>[property:Boolean matrixAutoUpdate]</h3>
	<p>
		当这个属性设置了之后，它将计算每一帧的位移、旋转（四元变换）和缩放矩阵，并重新计算matrixWorld属性。默认值是[page:Object3D.DefaultMatrixAutoUpdate] (true)。
	</p>

	<h3>[property:Matrix4 matrixWorld]</h3>
	<p>
		物体的世界变换。若这个Object3D没有父级，则它将和local transform [page:.matrix]（局部变换矩阵）相同。
	</p>

	<h3>[property:Boolean matrixWorldNeedsUpdate]</h3>
	<p>
		当这个属性设置了之后，它将计算在那一帧中的matrixWorld，并将这个值重置为false。默认值为*false*。
	</p>

	<h3>[property:Matrix4 modelViewMatrix]</h3>
	<p>这个值传递给着色器，用于计算物体的位置。</p>

	<h3>[property:String name]</h3>
	<p>对象的名称，可选、不必唯一。默认值是一个空字符串。</p>

	<h3>[property:Matrix3 normalMatrix]</h3>
	<p>
		这个值传递给着色器，用于计算物体的光照。
		它是物体的modelViewMatrix矩阵中，左上角3x3子矩阵的逆的转置矩阵。
		<br /><br />
		使用这个特殊矩阵的原因，是只需使用modelViewMatrix就可以得出一个法线（缩放时）的非单位长度或者非垂直的方向（不规则缩放时）。
		<br /><br />
		另一方面，modelViewMatrix矩阵中的位移部分和法线的计算无关，因此Matrix3就已经足够了。
	</p>

	<h3>[property:Function onAfterRender]</h3>
	<p>
		一个可选的回调函数，在Object3D渲染之后直接执行。
		使用以下参数来调用此函数：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 onBeforeRender]</h3>
	<p>
		一个可选的回调函数，在Object3D渲染之前直接执行。
		使用以下参数来调用此函数：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:Object3D parent]</h3>
	<p>在[link:https://en.wikipedia.org/wiki/Scene_graph scene graph]（场景图）中，一个对象的父级对象。
		一个对象最多仅能有一个父级对象。</p>

	<h3>[property:Vector3 position]</h3>
	<p>表示对象局部位置的[page:Vector3]。默认值为(0, 0, 0)。</p>

	<h3>[property:Quaternion quaternion]</h3>
	<p>表示对象局部旋转的[page:Quaternion Quaternion]（四元数）。</p>

	<h3>[property:Boolean receiveShadow]</h3>
	<p>材质是否接收阴影。默认值为*false*。</p>

	<h3>[property:Number renderOrder]</h3>
	<p>
		这个值将使得[link:https://en.wikipedia.org/wiki/Scene_graph scene graph]（场景图）中默认的的渲染顺序被覆盖，
		即使不透明对象和透明对象保持独立顺序。
		渲染顺序是由低到高来排序的，默认值为*0*。
	</p>

	<h3>[property:Euler rotation]</h3>
	<p>
		物体的局部旋转，以弧度来表示。（请参阅[link:https://en.wikipedia.org/wiki/Euler_angles Euler angles]-欧拉角）
	</p>

	<h3>[property:Vector3 scale]</h3>
	<p>
		物体的局部缩放。默认值是[page:Vector3]( 1, 1, 1 )。
	</p>

	<h3>[property:Vector3 up]</h3>
	<p>
		这个属性由[page:.lookAt lookAt]方法所使用，例如，来决定结果的朝向。
		默认值是[page:Object3D.DefaultUp]，即( 0, 1, 0 )。
	</p>

	<h3>[property:Object userData]</h3>
	<p>
		一个用于存储Object3D自定义数据的对象。
		它不应当包含对函数的引用，因为这些函数将不会被克隆。
	</p>

	<h3>[property:String uuid]</h3>
	<p>
		该对象实例的[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID]。
		这是一个自动生成的值，不应当对其进行修改。
	</p>

	<h3>[property:Boolean visible]</h3>
	<p>可见性。这个值为*true*时，物体将被渲染。默认值为*true*。</p>


	<h2>静态属性</h2>
	<p>
		静态属性和方法由每个类所定义，并非由每个类的实例所定义。
		也就是说，改变[page:Object3D.DefaultUp]或[page:Object3D.DefaultMatrixAutoUpdate]的值，
		将改变<b>每个在此之后</b>由Object3D类（或派生类）创建的实例中的[page:.up up]和[page:.matrixAutoUpdate matrixAutoUpdate]的值。（已经创建好的Object3D不会受到影响）。
	</p>

	<h3>[property:Vector3 DefaultUp]</h3>
	<p>
		默认的物体的[page:.up up]方向，同时也作为[page:DirectionalLight]、[page:HemisphereLight]和[page:Spotlight]（自顶向下创建的灯光）的默认方向。
		默认设为( 0, 1, 0 )。
	</p>

	<h3>[property:Boolean DefaultMatrixAutoUpdate]</h3>
	<p>
			[page:.matrixAutoUpdate matrixAutoUpdate]的默认设置，用于新创建的Object3D。<br />

	</p>


	<h2>方法</h2>

	<h3>[page:EventDispatcher EventDispatcher] 方法在这个类上是可用的。</h3>

	<h3>[method:null add]( [param:Object3D object], ... )</h3>
	<p>
		添加<b>对象</b>到这个对象的子级，可以添加任意数量的对象。
		当前传入的对象中的父级将在这里被移除，因为一个对象仅能有一个父级。<br /><br />
		请参阅[page:Group]来查看手动编组对象的相关信息。
	</p>

	<h3>[method:null applyMatrix4]( [param:Matrix4 matrix] )</h3>
	<p>对当前物体应用这个变换矩阵，并更新物体的位置、旋转和缩放。</p>

	<h3>[method:Object3D applyQuaternion]( [param:Quaternion quaternion] )</h3>
	<p>对当前物体应用由四元数所表示的变换。</p>


	<h3>[method:this attach]( [param:Object3D object] )</h3>
	<p>将*object*作为子级来添加到该对象中，同时保持该object的世界变换。</p>

	<h3>[method:Object3D clone]( [param:Boolean recursive] )</h3>
	<p>
		recursive —— 如果值为true，则该物体的后代也会被克隆。默认值为true。<br /><br />

		返回对象前物体的克隆（以及可选的所有后代）。
	</p>

	<h3>[method:this copy]( [param:Object3D object], [param:Boolean recursive] )</h3>
	<p>
		recursive —— 如果值为true，则该物体的后代也会被复制。默认值为true。<br /><br />

		复制给定的对象到这个对象中。

		请注意，事件监听器和用户定义的回调函数（[page:.onAfterRender] 和 [page:.onBeforeRender]）不会被复制。
	</p>

	<h3>[method:Object3D getObjectById]( [param:Integer id] )</h3>
	<p>
		id —— 标识该对象实例的唯一数字。<br /><br />

		从该对象开始，搜索一个对象及其子级，返回第一个带有匹配id的子对象。<br />
		请注意，id是按照时间顺序来分配的：1、2、3、……，每增加一个新的对象就自增1。
	</p>

	<h3>[method:Object3D getObjectByName]( [param:String name] )</h3>
	<p>
		name —— 用于来匹配子物体中Object3D.name属性的字符串。<br /><br />

		从该对象开始，搜索一个对象及其子级，返回第一个带有匹配name的子对象。<br />
		请注意，大多数的对象中name默认是一个空字符串，要使用这个方法，你将需要手动地设置name属性。
	</p>

	<h3>[method:Object3D getObjectByProperty]( [param:String name], [param:Float value] )</h3>
	<p>
		name —— 将要用于查找的属性的名称。<br />
		value —— 给定的属性的值。 <br /><br />
		从该对象开始，搜索一个对象及其子级，返回第一个给定的属性中包含有匹配的值的子对象。
	</p>

	<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
	<p>
		[page:Vector3 target] — 结果将被复制到这个Vector3中。<br /><br />
		返回一个表示该物体在世界空间中位置的矢量。
	</p>

	<h3>[method:Quaternion getWorldQuaternion]( [param:Quaternion target] )</h3>
	<p>
		[page:Quaternion target] — 结果将被复制到这个Quaternion中。<br /><br />
		返回一个表示该物体在世界空间中旋转的四元数。
	</p>

	<h3>[method:Vector3 getWorldScale]( [param:Vector3 target] )</h3>
	<p>
		[page:Vector3 target] — 结果将被复制到这个Vector3中。<br /><br />
		返回一个包含着该物体在世界空间中各个轴向上所应用的缩放因数的矢量。
	</p>

	<h3>[method:Vector3 getWorldDirection]( [param:Vector3 target] )</h3>
	<p>
		[page:Vector3 target] — 结果将被复制到这个Vector3中。 <br /><br />
		返回一个表示该物体在世界空间中Z轴正方向的矢量。
	</p>


	<h3>[method:Vector3 localToWorld]( [param:Vector3 vector] )</h3>
	<p>
		vector - 一个表示在该物体局部空间中位置的向量。<br /><br />

		将该向量从物体的局部空间转换到世界空间。
	</p>

	<h3>[method:null lookAt]( [param:Vector3 vector] )<br />
		[method:null lookAt]( [param:Float x], [param:Float y], [param:Float z] )</h3>
	<p>
		vector - 一个表示世界空间中位置的向量。<br /><br />
		也可以使用世界空间中[page:.x x]、[page:.y y]和[page:.z z]的位置分量。<br /><br />
		旋转物体使其在世界空间中面朝一个点。<br /><br />
		这一方法不支持其父级被旋转过或者被位移过的物体。
	</p>

	<h3>[method:Array raycast]( [param:Raycaster raycaster], [param:Array intersects] )</h3>
	<p>抽象（空方法），在一条被投射出的射线与这个物体之间获得交点。
		在一些子类，例如[page:Mesh], [page:Line], and [page:Points]实现了这个方法，以用于光线投射。
	</p>

	<h3>[method:null remove]( [param:Object3D object], ... )</h3>
	<p>
		从当前对象的子级中移除<b>对象</b>。可以移除任意数量的对象。
	</p>

	<h3>[method:this rotateOnAxis]( [param:Vector3 axis], [param:Float angle] )</h3>
	<p>
		axis —— 一个在局部空间中的标准化向量。<br />
		angle —— 角度，以弧度来表示。<br /><br />
		Rotate the object on 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 -- 一个在世界空间中的标准化向量。<br />
		angle -- 角度，以弧度来表示。<br /><br />

		Rotate the object on an axis in world space. The axis is assumed to be normalized.<br /><br />

		This method does not support objects having rotated parent(s).
	</p>

	<h3>[method:this rotateAroundWorldAxis]( [param:Vector3 point], [param:Vector3 axis], [param:Float angle] )</h3>
	<p>
		point -- The point to rotate around.<br />
		axis -- A normalized vector in world space.<br />
		angle -- The angle in radians.<br /><br />

		Rotate the object around an axis in world space. (The axis passes through point.) The axis is assumed to be normalized.<br /><br/ >

		This method does not support objects having rotated parent(s).
	</p>

	<h3>[method:this rotateX]( [param:Float rad] )</h3>
	<p>
		rad - 将要旋转的角度（以弧度来表示）。<br /><br />
		绕局部空间的X轴旋转这个物体。
	</p>

	<h3>[method:this rotateY]( [param:Float rad] )</h3>
	<p>
		rad - 将要旋转的角度（以弧度来表示）。<br /><br />
		绕局部空间的Y轴旋转这个物体。
	</p>

	<h3>[method:this rotateZ]( [param:Float rad] )</h3>
	<p>
		rad - 将要旋转的角度（以弧度来表示）。<br /><br />
		绕局部空间的Z轴旋转这个物体。
	</p>

	<h3>[method:null setRotationFromAxisAngle]( [param:Vector3 axis], [param:Float angle] )</h3>
	<p>
		axis -- 一个在局部空间中的标准化向量。<br />
		angle -- 角度（以弧度来表示）。<br /><br />

		调用[page:.quaternion]中的[page:Quaternion.setFromAxisAngle setFromAxisAngle]( [page:Float axis], [page:Float angle] )。
	</p>

	<h3>[method:null setRotationFromEuler]( [param:Euler euler] )</h3>
	<p>
		euler -- 指定了旋转量的欧拉角。<br />

		调用[page:.quaternion]中的[page:Quaternion.setRotationFromEuler setRotationFromEuler]( [page:Euler euler])。

	</p>

	<h3>[method:null setRotationFromMatrix]( [param:Matrix4 m] )</h3>
	<p>
		m -- 通过该矩阵中的旋转分量来旋转四元数。<br />

		调用[page:.quaternion]中的[page:Quaternion.setFromRotationMatrix setFromRotationMatrix]( [page:Matrix4 m])。
		<br /><br />

		请注意，这里假设m上的3x3矩阵是一个纯旋转矩阵（即未缩放的矩阵）。
	</p>

	<h3>[method:null setRotationFromQuaternion]( [param:Quaternion q] )</h3>
	<p>
		q -- 标准化的四元数。<br /><br />

		将所给的四元数复制到[page:.quaternion]中。
	</p>

	<h3>[method:Object toJSON]( [param:Object meta] )</h3>
	<p>
		meta -- 包含有元数据的对象，例如该对象的材质、纹理或图片。
		将对象转换为 three.js [link:https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 JSON Object/Scene format]（three.js JSON 物体/场景格式）。
	</p>

	<h3>[method:this translateOnAxis]( [param:Vector3 axis], [param:Float distance] )</h3>
	<p>
		axis -- 一个在局部空间中的标准化向量。<br />
		distance -- 将要平移的距离。<br /><br />
		在局部空间中沿着一条轴来平移物体，假设轴已被标准化。
	</p>

	<h3>[method:this translateX]( [param:Float distance] )</h3>
	<p>沿着X轴将平移*distance*个单位。</p>

	<h3>[method:this translateY]( [param:Float distance] )</h3>
	<p>沿着Y轴将平移*distance*个单位。</p>

	<h3>[method:this translateZ]( [param:Float distance] )</h3>
	<p>沿着Z轴将平移*distance*个单位。</p>

	<h3>[method:null traverse]( [param:Function callback] )</h3>
	<p>

		callback - 以一个object3D对象作为第一个参数的函数。
		<br /><br />

		在对象以及后代中执行的回调函数。
	</p>

	<h3>[method:null traverseVisible]( [param:Function callback] )</h3>
	<p>
			callback - 以一个object3D对象作为第一个参数的函数。
			<br /><br />

		类似traverse函数，但在这里，回调函数仅对可见的对象执行，不可见对象的后代将不遍历。
	</p>

	<h3>[method:null traverseAncestors]( [param:Function callback] )</h3>
	<p>
		callback - 以一个object3D对象作为第一个参数的函数。<br /><br />

		在所有的祖先中执行回调函数。
	</p>

	<h3>[method:null updateMatrix]()</h3>
	<p>更新局部变换。</p>

	<h3>[method:null updateMatrixWorld]( [param:Boolean force] )</h3>
	<p>更新物体及其后代的全局变换。</p>

	<h3>[method:null 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 - 一个表示在世界空间中位置的向量。<br /><br />

		将该向量从世界空间转换到物体的局部空间。
	</p>

	<h2>源代码</h2>

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

</html>