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


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365
							<!DOCTYPE html>
<html lang="en">
	<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>
			A representation of mesh, line, or point geometry. Includes vertex
			positions, face indices, normals, colors, UVs, and custom attributes
			within buffers, reducing the cost of passing all this data to the GPU.
		</p>
		<p>
			To read and edit data in BufferGeometry attributes, see
			[page:BufferAttribute] documentation.
		</p>

		<h2>Code Example</h2>

		<code>
		const geometry = new THREE.BufferGeometry();

		// create a simple square shape. We duplicate the top left and bottom right
		// vertices because each vertex needs to appear once per triangle.
		const vertices = new Float32Array( [
			-1.0, -1.0,  1.0, // v0
			 1.0, -1.0,  1.0, // v1
			 1.0,  1.0,  1.0, // v2

			 1.0,  1.0,  1.0, // v3
			-1.0,  1.0,  1.0, // v4
			-1.0, -1.0,  1.0  // v5
		] );

		// itemSize = 3 because there are 3 values (components) per vertex
		geometry.setAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );
		const material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
		const mesh = new THREE.Mesh( geometry, material );
		</code>

		<h2>Code Example (Index)</h2>

		<code>
		const geometry = new THREE.BufferGeometry();

		const vertices = new Float32Array( [
			-1.0, -1.0,  1.0, // v0
			 1.0, -1.0,  1.0, // v1
			 1.0,  1.0,  1.0, // v2
			-1.0,  1.0,  1.0, // v3
		] );

		const indices = [
			0, 1, 2,
			2, 3, 0,
		];

		geometry.setIndex( indices );
		geometry.setAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );

		const material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
		const mesh = new THREE.Mesh( geometry, material );
		</code>

		<h2>Examples</h2>
		<p>
			[example:webgl_buffergeometry Mesh with non-indexed faces]<br />
			[example:webgl_buffergeometry_indexed Mesh with indexed faces]<br />
			[example:webgl_buffergeometry_lines Lines]<br />
			[example:webgl_buffergeometry_lines_indexed Indexed Lines]<br />
			[example:webgl_buffergeometry_custom_attributes_particles Particles]<br />
			[example:webgl_buffergeometry_rawshader Raw Shaders]
		</p>

		<h2>Constructor</h2>

		<h3>[name]()</h3>
		<div>
			This creates a new [name]. It also sets several properties to a default
			value.
		</div>

		<h2>Properties</h2>

		<h3>[property:Object attributes]</h3>
		<p>
			This hashmap has as id the name of the attribute to be set and as value
			the [page:BufferAttribute buffer] to set it to. Rather than accessing this
			property directly, use [page:.setAttribute] and [page:.getAttribute] to
			access attributes of this geometry.
		</p>

		<h3>[property:Box3 boundingBox]</h3>
		<p>
			Bounding box for the bufferGeometry, which can be calculated with
			[page:.computeBoundingBox](). Default is `null`.
		</p>

		<h3>[property:Sphere boundingSphere]</h3>
		<p>
			Bounding sphere for the bufferGeometry, which can be calculated with
			[page:.computeBoundingSphere](). Default is `null`.
		</p>

		<h3>[property:Object drawRange]</h3>
		<p>
			Determines the part of the geometry to render. This should not be set
			directly, instead use [page:.setDrawRange]. Default is
			<code>
			{ start: 0, count: Infinity }
			</code>
			For non-indexed BufferGeometry, count is the number of vertices to render.
			For indexed BufferGeometry, count is the number of indices to render.
		</p>

		<h3>[property:Array groups]</h3>
		<p>
			Split the geometry into groups, each of which will be rendered in a
			separate WebGL draw call. This allows an array of materials to be used
			with the geometry.<br /><br />

			Each group is an object of the form:
			<code>
			{ start: Integer, count: Integer, materialIndex: Integer }
			</code>
			where start specifies the first element in this draw call – the first
			vertex for non-indexed geometry, otherwise the first triangle index. Count
			specifies how many vertices (or indices) are included, and materialIndex
			specifies the material array index to use.<br /><br />

			Use [page:.addGroup] to add groups, rather than modifying this array
			directly.<br /><br />

			Every vertex and index must belong to exactly one group — groups must not
			share vertices or indices, and must not leave vertices or indices unused.
		</p>

		<!-- Note: groups used to be called drawCalls

		<h3>[property:Array drawcalls]</h3>
		<p>
		For geometries that use indexed triangles, this Array can be used to split the object
		into multiple WebGL draw calls. Each draw call will draw some subset of the vertices
		in this geometry using the configured [page:Material shader]. This may be necessary if,
		for instance, you have more than 65535 vertices in your object.
		</p> -->

		<h3>[property:Integer id]</h3>
		<p>Unique number for this bufferGeometry instance.</p>

		<h3>[property:BufferAttribute index]</h3>
		<p>
			Allows for vertices to be re-used across multiple triangles; this is
			called using "indexed triangles". Each triangle is associated with the
			indices of three vertices. This attribute therefore stores the index of
			each vertex for each triangular face. If this attribute is not set, the
			[page:WebGLRenderer renderer] assumes that each three contiguous positions
			represent a single triangle. Default is `null`.
		</p>

		<h3>[property:Boolean isBufferGeometry]</h3>
		<p>Read-only flag to check if a given object is of type [name].</p>

		<h3>[property:Object morphAttributes]</h3>
		<p>
			Hashmap of [page:BufferAttribute]s holding details of the geometry's morph
			targets.<br />
			Note: Once the geometry has been rendered, the morph attribute data cannot
			be changed. You will have to call [page:.dispose](), and create a new
			instance of [name].
		</p>

		<h3>[property:Boolean morphTargetsRelative]</h3>
		<p>
			Used to control the morph target behavior; when set to true, the morph
			target data is treated as relative offsets, rather than as absolute
			positions/normals. Default is `false`.
		</p>

		<h3>[property:String name]</h3>
		<p>
			Optional name for this bufferGeometry instance. Default is an empty
			string.
		</p>

		<h3>[property:Object userData]</h3>
		<p>
			An object that can be used to store custom data about the BufferGeometry.
			It should not hold references to functions as these will not be cloned.
			Default is an empty object `{}`.
		</p>

		<h3>[property:String uuid]</h3>
		<p>
			[link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of
			this object instance. This gets automatically assigned and shouldn't be
			edited.
		</p>

		<h2>Methods</h2>

		<p>
			[page:EventDispatcher EventDispatcher] methods are available on this
			class.
		</p>

		<h3>[method:undefined addGroup]( [param:Integer start], [param:Integer count], [param:Integer materialIndex] )</h3>
		<p>
			Adds a group to this geometry; see the [page:BufferGeometry.groups groups]
			property for details.
		</p>

		<h3>[method:this applyMatrix4]( [param:Matrix4 matrix] )</h3>
		<p>Applies the matrix transform to the geometry.</p>

		<h3>[method:this applyQuaternion]( [param:Quaternion quaternion] )</h3>
		<p>Applies the rotation represented by the quaternion to the geometry.</p>

		<h3>[method:this center] ()</h3>
		<p>Center the geometry based on the bounding box.</p>

		<h3>[method:undefined clearGroups]( )</h3>
		<p>Clears all groups.</p>

		<h3>[method:BufferGeometry clone]()</h3>
		<p>Creates a clone of this BufferGeometry.</p>

		<h3>[method:undefined computeBoundingBox]()</h3>
		<p>
			Computes the bounding box of the geometry, and updates the [page:.boundingBox] attribute.
			The bounding box is not computed by the engine; it must be computed by your app.
			You may need to recompute the bounding box if the geometry vertices are modified.
		</p>

		<h3>[method:undefined computeBoundingSphere]()</h3>
		<p>
			Computes the bounding sphere of the geometry, and updates the [page:.boundingSphere] attribute.
			The engine automatically computes the bounding sphere when it is needed, e.g., for ray casting or view frustum culling.
			You may need to recompute the bounding sphere if the geometry vertices are modified.
		</p>

		<h3>[method:undefined computeTangents]()</h3>
		<p>
			Calculates and adds a tangent attribute to this geometry.<br />
			The computation is only supported for indexed geometries and if position,
			normal, and uv attributes are defined. When using a tangent space normal
			map, prefer the MikkTSpace algorithm provided by
			[page:BufferGeometryUtils.computeMikkTSpaceTangents] instead.
		</p>

		<h3>[method:undefined computeVertexNormals]()</h3>
		<p>Computes vertex normals for the given vertex data. For indexed geometries, the method sets each vertex normal to be the average of the face normals of the faces that share that vertex.
		For non-indexed geometries, vertices are not shared, and the method sets each vertex normal to be the same as the face normal.</p>

		<h3>[method:this copy]( [param:BufferGeometry bufferGeometry] )</h3>
		<p>Copies another BufferGeometry to this BufferGeometry.</p>

		<h3>[method:BufferAttribute deleteAttribute]( [param:String name] )</h3>
		<p>Deletes the [page:BufferAttribute attribute] with the specified name.</p>

		<h3>[method:undefined dispose]()</h3>
		<p>
			Frees the GPU-related resources allocated by this instance. Call this
			method whenever this instance is no longer used in your app.
		</p>

		<h3>[method:BufferAttribute getAttribute]( [param:String name] )</h3>
		<p>Returns the [page:BufferAttribute attribute] with the specified name.</p>

		<h3>[method:BufferAttribute getIndex] ()</h3>
		<p>Return the [page:.index] buffer.</p>

		<h3>[method:Boolean hasAttribute]( [param:String name] )</h3>
		<p>Returns `true` if the attribute with the specified name exists.</p>

		<h3>[method:this lookAt] ( [param:Vector3 vector] )</h3>
		<p>
			vector - A world vector to look at.<br /><br />

			Rotates the geometry to face a point in space. This is typically done as a
			one time operation, and not during a loop. Use [page:Object3D.lookAt] for
			typical real-time mesh usage.
		</p>

		<h3>[method:undefined normalizeNormals]()</h3>
		<p>
			Every normal vector in a geometry will have a magnitude of `1`. This will
			correct lighting on the geometry surfaces.
		</p>

		<h3>[method:this rotateX] ( [param:Float radians] )</h3>
		<p>
			Rotate the geometry about the X axis. This is typically done as a one time
			operation, and not during a loop. Use [page:Object3D.rotation] for typical
			real-time mesh rotation.
		</p>

		<h3>[method:this rotateY] ( [param:Float radians] )</h3>
		<p>
			Rotate the geometry about the Y axis. This is typically done as a one time
			operation, and not during a loop. Use [page:Object3D.rotation] for typical
			real-time mesh rotation.
		</p>

		<h3>[method:this rotateZ] ( [param:Float radians] )</h3>
		<p>
			Rotate the geometry about the Z axis. This is typically done as a one time
			operation, and not during a loop. Use [page:Object3D.rotation] for typical
			real-time mesh rotation.
		</p>

		<h3>[method:this scale] ( [param:Float x], [param:Float y], [param:Float z] )</h3>
		<p>
			Scale the geometry data. This is typically done as a one time operation,
			and not during a loop. Use [page:Object3D.scale] for typical real-time
			mesh scaling.
		</p>

		<h3>[method:this setAttribute]( [param:String name], [param:BufferAttribute attribute] )</h3>
		<p>
			Sets an attribute to this geometry. Use this rather than the attributes
			property, because an internal hashmap of [page:.attributes] is maintained
			to speed up iterating over attributes.
		</p>

		<h3>[method:undefined setDrawRange] ( [param:Integer start], [param:Integer count] )</h3>
		<p>
			Set the [page:.drawRange] property. For non-indexed BufferGeometry, count
			is the number of vertices to render. For indexed BufferGeometry, count is
			the number of indices to render.
		</p>

		<h3>[method:this setFromPoints] ( [param:Array points] )</h3>
		<p>Sets the attributes for this BufferGeometry from an array of points.</p>

		<h3>[method:this setIndex] ( [param:BufferAttribute index] )</h3>
		<p>Set the [page:.index] buffer.</p>

		<h3>[method:Object toJSON]()</h3>
		<p>
			Convert the buffer geometry to three.js
			[link:https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 JSON Object/Scene format].
		</p>

		<h3>[method:BufferGeometry toNonIndexed]()</h3>
		<p>Return a non-index version of an indexed BufferGeometry.</p>

		<h3>[method:this translate] ( [param:Float x], [param:Float y], [param:Float z] )</h3>
		<p>
			Translate the geometry. This is typically done as a one time operation,
			and not during a loop. Use [page:Object3D.position] for typical real-time
			mesh translation.
		</p>

		<h2>Source</h2>

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