gitadmin
/
three.js
mirror of https://github.com/mrdoob/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496
							<!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>三维物体所属的动画剪辑数组.</p>

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

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

	<h3>[property:Material customDepthMaterial]</h3>
	<p>在渲染到深度图的时候所用的自定义深度材质。 只能在网格中使用。
	当使用[page:DirectionalLight]（平行光）或者[page:SpotLight]（聚光灯光）生成影子的时候, 如果你调整过顶点着色器中的顶点位置，就需要定义一个自定义深度材质来生成正确的影子。默认为*undefined*.
	</p>

	<h3>[property:Material customDistanceMaterial]</h3>
	<p>与[page:.customDepthMaterial customDepthMaterial]相同，但与[page:PointLight](点光源）一起使用。默认值为*undefined*。
	</p>

	<h3>[property:Boolean frustumCulled]</h3>
	<p>
		当这个设置了的时候，每一帧渲染前都会检测这个物体是不是在相机的视椎体范围内。 如果设置为`false` 物体不管是不是在相机的视椎体范围内都会渲染。默认为`true`。
	</p>

	<h3>[property:Integer id]</h3>
	<p>只读 —— 表示该对象实例ID的唯一数字。</p>

		<h3>[property:Boolean isObject3D]</h3>
		<p>
			查看所给对象是不是[name]类型的只读标记.
		</p>

	<h3>[property:Layers layers]</h3>
	<p>
		物体的层级关系。
		物体只有和一个正在使用的[page:Camera]至少在同一个层时才可见。当使用[page:Raycaster]进行射线检测的时候此项属性可以用于过滤不参与检测的物体.
	</p>

	<h3>[property:Matrix4 matrix]</h3>
	<p>局部变换矩阵。</p>

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

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

	<h3>[property:Boolean matrixWorldAutoUpdate]</h3>
	<p>
	默认为 true. 当设置的时候，渲染器在每一帧都会检查物体自身以及它的自带是否需要更新世界变换矩阵。
	如果不需要的话它自身以及它的子代的所有世界变换矩阵都需要你来维护。
	</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>
	注意此回调函数只会在*可渲染*的3D物体上执行。可渲染的3D物体指的是那种拥有视觉表现的、定义了几何体与材质的物体，例如像是[page:Mesh]、[page:Line]、[page:Points] 或者[page:Sprite]。
	[page:Object3D]、 [page:Group] 或者 [page:Bone] 这些是不可渲染的物体，因此此回调函数不会在这样的物体上执行。
	</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>
		注意此回调函数只会在*可渲染*的3D物体上执行。可渲染的3D物体指的是那种拥有视觉表现的、定义了几何体与材质的物体，例如像是[page:Mesh]、[page:Line]、[page:Points] 或者[page:Sprite]。
		[page:Object3D]、 [page:Group] 或者 [page:Bone] 这些是不可渲染的物体，因此此回调函数不会在这样的物体上执行。
	</p>

	<h3>[property:Function onBeforeRender]</h3>
	<p>
		一个可选的回调函数，在Object3D渲染之前直接执行。
		使用以下参数来调用此函数：renderer，scene，camera，geometry，material，group。
	</p>
	<p>
	注意此回调函数只会在*可渲染*的3D物体上执行。可渲染的3D物体指的是那种拥有视觉表现的、定义了几何体与材质的物体，例如像是[page:Mesh]、[page:Line]、[page:Points] 或者[page:Sprite]。
	[page:Object3D]、 [page:Group] 或者 [page:Bone] 这些是不可渲染的物体，因此此回调函数不会在这样的物体上执行。
	</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>
		注意此回调函数只会在*可渲染*的3D物体上执行。可渲染的3D物体指的是那种拥有视觉表现的、定义了几何体与材质的物体，例如像是[page:Mesh]、[page:Line]、[page:Points] 或者[page:Sprite]。
		[page:Object3D]、 [page:Group] 或者 [page:Bone] 这些是不可渲染的物体，因此此回调函数不会在这样的物体上执行。
	</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.DEFAULT_UP]，即( 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.DEFAULT_UP]或[page:Object3D.DEFAULT_MATRIX_AUTO_UPDATE]的值，
		将改变<b>每个在此之后</b>由Object3D类（或派生类）创建的实例中的[page:.up up]和[page:.matrixAutoUpdate matrixAutoUpdate]的值。（已经创建好的Object3D不会受到影响）。
	</p>

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

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

	</p>

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

	<h2>方法</h2>

	<p>[page:EventDispatcher EventDispatcher] 在该类上可用的所有方法。</p>

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

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

	<h3>[method:this 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:Any value] )</h3>
	<p>
		name —— 将要用于查找的属性的名称。<br />
		value —— 给定的属性的值。 <br /><br />
		从该对象开始，搜索一个对象及其子级，返回第一个给定的属性中包含有匹配的值的子对象。
	</p>

	<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
	<p>
		name —— 将要用于查找的属性的名称。<br />
		value —— 给定的属性的值。 <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 />
		从此对象开始，搜索一个对象及其子对象，返回包含给定属性的匹配值的所有子对象。
	</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:undefined lookAt]( [param:Vector3 vector] )<br />
		[method:undefined 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:undefined raycast]( [param:Raycaster raycaster], [param:Array intersects] )</h3>
	<p>抽象（空方法），在一条被投射出的射线与这个物体之间获得交点。
		在一些子类，例如[page:Mesh], [page:Line], and [page:Points]实现了这个方法，以用于光线投射。
	</p>

	<h3>[method:this remove]( [param:Object3D object], ... )</h3>
	<p>
		从当前对象的子级中移除<b>对象</b>。可以移除任意数量的对象。
	</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 —— 一个在局部空间中的标准化向量。<br />
		angle —— 角度，以弧度来表示。<br /><br />
		在局部空间中绕着该物体的轴来旋转一个物体，假设这个轴已被标准化。
	</p>

	<h3>[method:this rotateOnWorldAxis]( [param:Vector3 axis], [param:Float angle] )</h3>
	<p>
		axis -- 一个在世界空间中的标准化向量。<br />
		angle -- 角度，以弧度来表示。<br /><br />

		在世界空间中绕着该物体的轴来旋转一个物体，假设这个轴已被标准化。
		方法假设该物体没有旋转过的父级。
	</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:undefined 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:undefined setRotationFromEuler]( [param:Euler euler] )</h3>
	<p>
		euler -- 指定了旋转量的欧拉角。<br />

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

	</p>

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

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

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

	<h3>[method:undefined 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:undefined traverse]( [param:Function callback] )</h3>
	<p>

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

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

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

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

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

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

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

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

	<h3>[method:undefined updateWorldMatrix]( [param:Boolean updateParents], [param:Boolean updateChildren] )</h3>
	<p>
		updateParents - 递归更新物体的所有祖先的全局变换.<br />
		updateChildren - 递归更新物体的所有后代的全局变换.<br /><br />

		更新物体的全局变换。
	</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>