当前位置：首页 > news >正文

BufferAttribute

news 来源：原创 2025/5/11 10:44:43

BufferAttribute

3D虚拟工厂在线体验

描述

BufferAttribute 是 Three.js 中用于高效管理几何体属性数据的核心类，其主要特点包括：

数据存储
专为存储 BufferGeometry 的各种属性设计，包括：顶点位置（position）、法线向量（normal）、颜色值（color）、UV坐标（uv）、面片索引（index）、自定义属性（如实例化数据）
GPU优化
采用类型化数组（TypedArray）存储数据，通过连续内存布局实现：显存高效传输、适合WebGL底层渲染管线、支持静态/动态数据更新策略
矢量处理
数据按矢量单元存储（通过itemSize定义维度）、所有方法中的index参数会自动乘以矢量长度定位数据
- 推荐配套方法：
```
// 快速读取矢量数据
const vec = new THREE.Vector3().fromBufferAttribute(attribute, index)
```

构造函数

参数	类型	可选	描述
`array`	TypedArray	否	必须是TypedArray类型，包含`itemSize * numVertices`个元素
`itemSize`	Integer	否	每个顶点的数据维度（如位置/法线为3，UV为2）
`normalized`	Boolean	是	是否将整数类型数据归一化到GLSL范围（如UInt16Array→[0,1]）

属性

属性	类型	读写	默认值	描述
核心属性
`.array`	`TypedArray`	读写	-	存储原始数据的类型化数组。必须使用 `TypedArray` 类型（如 `Float32Array`）；数据长度必须为 `itemSize * 顶点数` 的整数倍
`.count`	`Integer`	只读	自动计算	`array.length / itemSize` 的结果
`.itemSize`	`Integer`	读写	必填	每个元素的组件数（如位置=3，颜色=4）
`.normalized`	`Boolean`	读写	`false`	是否将整数数据归一化到GLSL范围
配置属性
`.name`	`String`	读写	`''`	属性实例的自定义标识名
`.usage`	`THREE.Usage`	读写	`THREE.StaticDrawUsage`	定义GPU内存使用策略
`.gpuType`	`Number`	读写	`THREE.FloatType`	着色器数据类型（仅整数数组有效）
状态控制
`.needsUpdate`	`Boolean`	读写	`false`	设为`true`时触发GPU数据更新
`.version`	`Integer`	读写	`0`	数据版本号（修改时自动递增）
`.updateRange`	`Object`	读写	`{offset:0, count:-1}`	局部更新范围配置。更新前10个顶点数据： attribute.updateRange = { offset: 0, count: 10 }attribute.needsUpdate = true
系统属性
`.isBufferAttribute`	`Boolean`	只读	`true`	类型标识符
`.onUploadCallback`	`Function`	读写	`null`	GPU上传完成回调函数

方法

方法	参数	返回值	描述
矩阵变换
`.applyMatrix3(m)`	`m: THREE.Matrix3`	`this`	应用3x3矩阵变换到每个向量
`.applyMatrix4(m)`	`m: THREE.Matrix4`	`this`	应用4x4矩阵变换到每个向量
`.applyNormalMatrix(m)`	`m: THREE.Matrix3`	`this`	应用法线矩阵变换到每个法向量
`.transformDirection(m)`	`m: THREE.Matrix4`	`this`	仅旋转向量（保持方向性）
数据操作
`.set(value, offset)`	`value: Array/TypedArray`, `offset: Integer`	`this`	批量填充数据
`.copyArray(array)`	`array: Array/TypedArray`	`this`	复制整个数组内容
`.copyAt(index1, attr, index2)`	`index1: Integer`, `attr: BufferAttribute`, `index2: Integer`	`this`	复制单个向量
组件访问
`.getComponent(index, component)`	`index: Integer`, `component: Integer`	`Number`	获取指定分量
`.getX(index)`	`index: Integer`	`Number`	获取X分量
`.getY(index)`	`index: Integer`	`Number`	获取Y分量
`.getZ(index)`	`index: Integer`	`Number`	获取Z分量
`.getW(index)`	`index: Integer`	`Number`	获取W分量
组件设置
`.setComponent(index, component, value)`	`index: Integer`, `component: Integer`, `value: Number`	`this`	设置指定分量
`.setX(index, value)`	`index: Integer`, `value: Number`	`this`	设置X分量
`.setY(index, value)`	`index: Integer`, `value: Number`	`this`	设置Y分量
`.setZ(index, value)`	`index: Integer`, `value: Number`	`this`	设置Z分量
`.setW(index, value)`	`index: Integer`, `value: Number`	`this`	设置W分量
批量设置
`.setXY(index, x, y)`	`index: Integer`, `x: Number`, `y: Number`	`this`	设置XY分量
`.setXYZ(index, x, y, z)`	`index: Integer`, `x: Number`, `y: Number`, `z: Number`	`this`	设置XYZ分量
`.setXYZW(index, x, y, z, w)`	`index: Integer`, `x: Number`, `y: Number`, `z: Number`, `w: Number`	`this`	设置XYZW分量
内存管理
`.clone()`	-	`BufferAttribute`	创建数据副本
`.onUpload(callback)`	`callback: Function`	`this`	上传GPU回调
`.setUsage(value)`	`value: THREE.Usage`	`this`	设置内存使用策略
更新控制
`.addUpdateRange(start, count)`	`start: Integer`, `count: Integer`	`this`	添加局部更新范围
`.clearUpdateRanges()`	-	`this`	清除所有更新范围

示例

  // 1. 创建顶点数据（x,y,z 坐标）const positions = new Float32Array([0, 0, 0,  // 顶点11, 0, 0,  // 顶点20, 1, 0   // 顶点3]);// 2. 创建BufferAttributeconst positionAttribute = new THREE.BufferAttribute(positions, 3); // 3表示每个顶点3个分量(x,y,z)// 3. 添加到几何体const geometry = new THREE.BufferGeometry();geometry.setAttribute('position', positionAttribute);// 4. 创建材质和网格const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });const mesh = new THREE.Mesh(geometry, material);scene.add(mesh); // 在场景中渲染一个红色三角形