import { Box3 } from "../math/Box3.js"; import { Matrix4 } from "../math/Matrix4.js"; import { Quaternion } from "../math/Quaternion.js"; import { Sphere } from "../math/Sphere.js"; import { Vector2 } from "../math/Vector2.js"; import { Vector3 } from "../math/Vector3.js"; import { BufferAttribute } from "./BufferAttribute.js"; import { EventDispatcher } from "./EventDispatcher.js"; import { GLBufferAttribute } from "./GLBufferAttribute.js"; import { InterleavedBufferAttribute } from "./InterleavedBufferAttribute.js"; export type NormalBufferAttributes = Record; export type NormalOrGLBufferAttributes = Record< string, BufferAttribute | InterleavedBufferAttribute | GLBufferAttribute >; /** * 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. * @remarks * To read and edit data in BufferGeometry attributes, see {@link THREE.BufferAttribute | BufferAttribute} documentation. * @example * ```typescript * 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 ); * ``` * @example * ```typescript * 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 * ] ); * geometry.setAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) ); * * 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 ); * ``` * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry | Mesh with non-indexed faces} * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_indexed | Mesh with indexed faces} * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_lines | Lines} * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_lines_indexed | Indexed Lines} * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_custom_attributes_particles | Particles} * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_rawshader | Raw Shaders} * @see {@link https://threejs.org/docs/index.html#api/en/core/BufferGeometry | Official Documentation} * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/BufferGeometry.js | Source} */ export class BufferGeometry< Attributes extends NormalOrGLBufferAttributes = NormalBufferAttributes, > extends EventDispatcher<{ dispose: {} }> { /** * This creates a new {@link THREE.BufferGeometry | BufferGeometry} object. */ constructor(); /** * Unique number for this {@link THREE.BufferGeometry | BufferGeometry} instance. * @remarks Expects a `Integer` */ id: number; /** * {@link http://en.wikipedia.org/wiki/Universally_unique_identifier | UUID} of this object instance. * @remarks This gets automatically assigned and shouldn't be edited. */ uuid: string; /** * Optional name for this {@link THREE.BufferGeometry | BufferGeometry} instance. * @defaultValue `''` */ name: string; /** * A Read-only _string_ to check if `this` object type. * @remarks Sub-classes will update this value. * @defaultValue `BufferGeometry` */ readonly type: string | "BufferGeometry"; /** * 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 {@link THREE.WebGLRenderer | renderer} assumes that each three contiguous positions represent a single triangle. * @defaultValue `null` */ index: BufferAttribute | null; /** * This hashmap has as id the name of the attribute to be set and as value the {@link THREE.BufferAttribute | buffer} to set it to. Rather than accessing this property directly, * use {@link setAttribute | .setAttribute} and {@link getAttribute | .getAttribute} to access attributes of this geometry. * @defaultValue `{}` */ attributes: Attributes; /** * Hashmap of {@link THREE.BufferAttribute | BufferAttributes} holding details of the geometry's morph targets. * @remarks * Once the geometry has been rendered, the morph attribute data cannot be changed. * You will have to call {@link dispose | .dispose}(), and create a new instance of {@link THREE.BufferGeometry | BufferGeometry}. * @defaultValue `{}` */ morphAttributes: { [name: string]: Array; // TODO Replace for 'Record<>' }; /** * 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. * @defaultValue `false` */ morphTargetsRelative: boolean; /** * 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. * @remarks 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. * @remarks Use {@link addGroup | .addGroup} to add groups, rather than modifying this array directly. * @defaultValue `[]` */ groups: Array<{ /** * Specifies the first element in this draw call – the first vertex for non-indexed geometry, otherwise the first triangle index. * @remarks Expects a `Integer` */ start: number; /** * Specifies how many vertices (or indices) are included. * @remarks Expects a `Integer` */ count: number; /** * Specifies the material array index to use. * @remarks Expects a `Integer` */ materialIndex?: number | undefined; }>; /** * Bounding box for the {@link THREE.BufferGeometry | BufferGeometry}, which can be calculated with {@link computeBoundingBox | .computeBoundingBox()}. * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`. * @defaultValue `null` */ boundingBox: Box3 | null; /** * Bounding sphere for the {@link THREE.BufferGeometry | BufferGeometry}, which can be calculated with {@link computeBoundingSphere | .computeBoundingSphere()}. * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`. * @defaultValue `null` */ boundingSphere: Sphere | null; /** * Determines the part of the geometry to render. This should not be set directly, instead use {@link setDrawRange | .setDrawRange(...)}. * @remarks For non-indexed {@link THREE.BufferGeometry | BufferGeometry}, count is the number of vertices to render. * @remarks For indexed {@link THREE.BufferGeometry | BufferGeometry}, count is the number of indices to render. * @defaultValue `{ start: 0, count: Infinity }` */ drawRange: { start: number; count: number }; /** * 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. * @defaultValue `{}` */ userData: Record; /** * Read-only flag to check if a given object is of type {@link BufferGeometry}. * @remarks This is a _constant_ value * @defaultValue `true` */ readonly isBufferGeometry: true; /** * Return the {@link index | .index} buffer. */ getIndex(): BufferAttribute | null; /** * Set the {@link THREE.BufferGeometry.index | .index} buffer. * @param index */ setIndex(index: BufferAttribute | number[] | null): this; /** * Sets an {@link attributes | attribute} to this geometry with the specified name. * @remarks * Use this rather than the attributes property, because an internal hashmap of {@link attributes | .attributes} is maintained to speed up iterating over attributes. * @param name * @param attribute */ setAttribute(name: K, attribute: Attributes[K]): this; /** * Returns the {@link attributes | attribute} with the specified name. * @param name */ getAttribute(name: K): Attributes[K]; /** * Deletes the {@link attributes | attribute} with the specified name. * @param name */ deleteAttribute(name: keyof Attributes): this; /** * Returns true if the {@link attributes | attribute} with the specified name exists. * @param name */ hasAttribute(name: keyof Attributes): boolean; /** * Adds a group to this geometry * @see the {@link BufferGeometry.groups | groups} property for details. * @param start * @param count * @param materialIndex */ addGroup(start: number, count: number, materialIndex?: number): void; /** * Clears all groups. */ clearGroups(): void; /** * Set the {@link drawRange | .drawRange} property * @remarks For non-indexed BufferGeometry, count is the number of vertices to render * @remarks For indexed BufferGeometry, count is the number of indices to render. * @param start * @param count is the number of vertices or indices to render. Expects a `Integer` */ setDrawRange(start: number, count: number): void; /** * Applies the matrix transform to the geometry. * @param matrix */ applyMatrix4(matrix: Matrix4): this; /** * Applies the rotation represented by the quaternion to the geometry. * @param quaternion */ applyQuaternion(quaternion: Quaternion): this; /** * Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation. * @param angle radians. Expects a `Float` */ rotateX(angle: number): this; /** * Rotate the geometry about the Y axis. * @remarks This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation. * @param angle radians. Expects a `Float` */ rotateY(angle: number): this; /** * Rotate the geometry about the Z axis. * @remarks This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation. * @param angle radians. Expects a `Float` */ rotateZ(angle: number): this; /** * Translate the geometry. * @remarks This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.position | Object3D.position} for typical real-time mesh rotation. * @param x Expects a `Float` * @param y Expects a `Float` * @param z Expects a `Float` */ translate(x: number, y: number, z: number): this; /** * Scale the geometry data. * @remarks This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.scale | Object3D.scale} for typical real-time mesh scaling. * @param x Expects a `Float` * @param y Expects a `Float` * @param z Expects a `Float` */ scale(x: number, y: number, z: number): this; /** * Rotates the geometry to face a point in space. * @remarks This is typically done as a one time operation, and not during a loop. * @remarks Use {@link THREE.Object3D.lookAt | Object3D.lookAt} for typical real-time mesh usage. * @param vector A world vector to look at. */ lookAt(vector: Vector3): this; /** * Center the geometry based on the bounding box. */ center(): this; /** * Sets the attributes for this BufferGeometry from an array of points. * @param points */ setFromPoints(points: Vector3[] | Vector2[]): this; /** * Computes the bounding box of the geometry, and updates the {@link .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. */ computeBoundingBox(): void; /** * Computes the bounding sphere of the geometry, and updates the {@link .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. */ computeBoundingSphere(): void; /** * Calculates and adds a tangent attribute to this geometry. * The computation is only supported for indexed geometries and if position, normal, and uv attributes are defined * @remarks * When using a tangent space normal map, prefer the MikkTSpace algorithm provided by * {@link BufferGeometryUtils.computeMikkTSpaceTangents} instead. */ computeTangents(): void; /** * 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. */ computeVertexNormals(): void; /** * Every normal vector in a geometry will have a magnitude of 1 * @remarks This will correct lighting on the geometry surfaces. */ normalizeNormals(): void; /** * Return a non-index version of an indexed BufferGeometry. */ toNonIndexed(): BufferGeometry; /** * Convert the buffer geometry to three.js {@link https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 | JSON Object/Scene format}. */ toJSON(): {}; /** * Creates a clone of this BufferGeometry */ clone(): this; /** * Copies another BufferGeometry to this BufferGeometry. * @param source */ copy(source: BufferGeometry): this; /** * Frees the GPU-related resources allocated by this instance. * @remarks Call this method whenever this instance is no longer used in your app. */ dispose(): void; }