javascript
/
three.js
mirror of https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
							<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<base href="../../" />
		<script src="list.js"></script>
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>[name]</h1>

		<div class="desc">
		<p>
		This class is an efficient alternative to [page:Geometry], because it stores all data, including
		vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers; this
		reduces the cost of passing all this data to the GPU.<br />
		This also makes BufferGeometry harder to work with than [page:Geometry]; rather than accessing
		position data as [page:Vector3] objects, color data as [page:Color] objects, and so on, you have to
		access the raw data from the appropriate [page:BufferAttribute attribute buffer]. This makes
		BufferGeometry best-suited for static objects where you don't need to manipulate the geometry much
		after instantiating it.
		</p>

		<h2>Example</h2>
		<code>
		var 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.
		var vertices = new Float32Array( [
			-1.0, -1.0,  1.0,
			 1.0, -1.0,  1.0,
			 1.0,  1.0,  1.0,

			 1.0,  1.0,  1.0,
			-1.0,  1.0,  1.0,
			-1.0, -1.0,  1.0
		] );

		// itemSize = 3 because there are 3 values (components) per vertex
		geometry.addAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );
		var material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
		var mesh = new THREE.Mesh( geometry, material );
		</code>
		<div>
			[example:webgl_buffergeometry Complex mesh with non-indexed faces]<br />
			[example:webgl_buffergeometry_uint Complex 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]
		</div>


		<h2>Accessing Attributes</h2>
		<p>
		WebGL stores data associated with individual vertices of a geometry in <em>attributes</em>.
		Examples include the position of the vertex, the normal vector for the vertex, the vertex color,
		and so on. When using [page:Geometry], the [page:WebGLRenderer renderer] takes care of wrapping
		up this information into typed array buffers and sending this data to the shader. With
		BufferGeometry, all of this data is stored in buffers associated with individual attributes.
		This means that to get the position data associated with a vertex (for instance), you must call
		[page:.getAttribute] to access the 'position' [page:BufferAttribute attribute], then access the individual
		x, y, and z coordinates of the position.
		</p>
		<p>
		The following attributes are set by various members of this class:
		</p>
		<h3>[page:BufferAttribute position] (itemSize: 3)</h3>
		<div>
		Stores the x, y, and z coordinates of each vertex in this geometry. Set by [page:.fromGeometry]().
		</div>

		<h3>[page:BufferAttribute normal] (itemSize: 3)</h3>
		<div>
		Stores the x, y, and z components of the face or vertex normal vector of each vertex in this geometry.
		Set by [page:.fromGeometry]().
		</div>

		<h3>[page:BufferAttribute color] (itemSize: 3)</h3>
		<div>
		Stores the red, green, and blue channels of vertex color of each vertex in this geometry.
		Set by [page:.fromGeometry]().
		</div>

		<h3>[page:BufferAttribute index] (itemSize: 1)</h3>
		Allows for vertices to be re-used across multiple triangles; this is called using "indexed triangles" and
		works much the same as it does in [page:Geometry]: 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.
		</div>
		<p>
		In addition to the the built-in attributes, you can set your own custom attributes using the addAttribute method. With [page:Geometry], these attributes are set and stored on the [page:Material]. In BufferGeometry, the attributes are stored with the geometry itself. Note that you still need to set the attributes information on the material as well, but the value of each attribute is stored in the BufferGeometry.
		</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:Hashmap attributes]</h3>
		<div>
		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 addAttribute and getAttribute to access attributes of this geometry.
		</div>

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

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

		<h3>[property:Object drawRange]</h3>
		<div>
			Used to determine what part of the geometry should be rendered. This should not
			be set directly, instead use [page:.setDrawRange].<br />
			Default is
			<code>
				{ start: 0, count: Infinity }
			</code>
		</div>

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

			Each group is an object of the form:
			<code>{ start: Integer, count: Integer, materialIndex: Integer }</code>
			where start specifies the index of the first vertex in this draw call, count specifies
			how many vertices are included, and materialIndex specifies the [page:MultiMaterial] index to use.<br /><br />

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


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

		<h3>[property:Array drawcalls]</h3>
		<div>
		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.
		</div> -->


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

		<h3>[property:BufferAttribute index]</h3>
		<div>
			See "Accessing Attributes" section above for a description of this property.
			Default is *null*.
		</div>

		<h3>[property:Boolean isBufferGeometry]</h3>
		<div>
			Used to check whether this or derived classes are BufferGeometries. Default is *true*.<br /><br />

			You should not change this, as it used internally for optimisation.
		</div>

		<h3>[property:Integer MaxIndex]</h3>
		<div>Maximum number of vertices allowed, set to *65535*.</div>

		<h3>[property:Object morphAttributes]</h3>
		<div>
			Hashmap of [page:BufferAttribute]s holding details of the geometry's [page:Geometry.morphTargets morphTargets].
		</div>

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

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

		<h2>Methods</h2>

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

		<h3>[property:null addAttribute]( [page:String name], [page:BufferAttribute attribute] )</h3>
		<div>
		Adds 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.
		</div>

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


		<h3>[method:null applyMatrix]( [page:Matrix4 matrix] )</h3>
		<div>Bakes matrix transform directly into vertex coordinates.</div>

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

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

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

		<h3>[method:null clearGroups]( )</h3>
		<div>Clears all groups.</div>

		<h3>[method:null computeBoundingBox]()</h3>
		<div>
		Computes bounding box of the geometry, updating [page:.boundingBox] attribute.<br />
		Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
		</div>

		<h3>[method:null computeBoundingSphere]()</h3>
		<div>
		Computes bounding sphere of the geometry, updating [page:.boundingSphere] attribute.<br />
		Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
		</div>

		<h3>[method:null computeVertexNormals]()</h3>
		<div>Computes vertex normals by averaging face normals.</div>

		<h3>[method:null dispose]()</h3>
		<div>
		Disposes the object from memory. <br />
		You need to call this when you want the bufferGeometry removed while the application is running.
		</div>

		<h3>[method:BufferGeometry fromDirectGeometry]( [page:Geometry] )</h3>
		<div>
			Populates this BufferGeometry with data from a [page:DirectGeometry] object.<br /><br />

			Note: [page:DirectGeometry] is mainly used as an intermediary object for converting between [page:Geometry]
			and BufferGeometry.
		</div>

		<h3>[method:BufferGeometry fromGeometry]( [page:Geometry] )</h3>
		<div>Populates this BufferGeometry with data from a [page:Geometry] object.</div>

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

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

		<h3>[method:BufferGeometry lookAt] ( [page:Vector3 vector] )</h3>
		<div>
		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.
		</div>

		<h3>[method:null merge]( [page:BufferGeometry bufferGeometry], [page:Integer offset] )</h3>
		<div>Merge in another BufferGeometry with an optional offset of where to start merging in.</div>

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

		<h3>[method:BufferAttribute removeAttribute]( [page:String name] )</h3>
		<div>Removes the [page:BufferAttribute attribute] with the specified name.</div>

		<h3>[method:BufferGeometry rotateX] ( [page:Float radians] )</h3>
		<div>
		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.
		</div>

		<h3>[method:BufferGeometry rotateY] ( [page:Float radians] )</h3>
		<div>
		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.
		</div>

		<h3>[method:BufferGeometry rotateZ] ( [page:Float radians] )</h3>
		<div>
		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.
		</div>

		<h3>[method:BufferGeometry scale] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
		<div>
		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.
		</div>

		<h3>[method:null setIndex] ( [page:BufferAttribute index] )</h3>
		<div>Set the [page:.index] buffer.</div>

		<h3>[method:null setDrawRange] ( [page:Integer start], [page:Integer count] )</h3>
		<div>Set the [page:.drawRange] buffer. See that property for details.</div>

		<h3>[method:BufferGeometry setFromObject] ( [page:Object3D object] )</h3>
		<div>Sets the attributes for this BufferGeometry from an [page:Object3D].</div>

		<h3>[method:Object toJSON]()</h3>
		<div>Returns a JSON object representation of the BufferGeometry.</div>

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

		<h3>[method:BufferGeometry translate] ( [page:Float x], [page:Float y], [page:Float z] )</h3>
		<div>
		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.
		</div>

		<h3>[method:BufferGeometry updateFromObject] ( [page:Object3D object] )</h3>
		<div>Updates the attributes for this BufferGeometry from an [page:Object3D].</div>


		<h2>Source</h2>

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