InstancedObjects

基于Three.js的实例化对象管理模块，用于管理大量相似对象的渲染。通过实例化渲染技术，将相同几何体和材质的对象合并为单个绘制调用。

类定义

javascript

class InstanceInfo
class InstancedObject3D extends Object3D
class InstancedMesh extends InstancedObject3D
class InstancedLine extends InstancedObject3D
class InstancedLineSegments extends InstancedObject3D
class InstancedLineLoop extends InstancedObject3D

常量

INSTANCED_OBJECT3D_TYPE

实例化对象类型枚举，定义支持的实例化对象类型。

类型: {Object}
静态: true
只读: true

属性:

MESH {string} - 实例化网格对象
LINE {string} - 实例化线条对象
LINE_SEGMENTS {string} - 实例化线段对象
LINE_LOOP {string} - 实例化线环对象

InstanceInfo

实例信息管理类，用于存储和管理实例化对象的相关信息。

方法:

copy(source) - 复制实例信息
getUniqueId(index) - 获取实例唯一标识符
setInstanceUniqueId(uId) - 添加实例唯一标识符
setInstanceBounding(box3, sphere) - 设置实例包围盒和包围球
getInstanceInfo(index) - 获取实例信息
toJSON() - 转换为JSON格式

构造函数

constructor(geometry, material, count)

创建实例化对象实例，初始化共享几何体、材质和实例数量，并建立实例索引与变换矩阵存储。

参数:

geometry {BufferGeometry} - 共享几何体
material {Material} - 实例材质
count {number} - 实例数量

说明:

InstancedMesh、InstancedLine、InstancedLineSegments、InstancedLineLoop 均基于 InstancedObject3D 的构造逻辑。
推荐通过各类 Create(...) 静态方法创建实例，以自动完成唯一 ID、包围体与加速结构初始化。

静态方法

InstancedMesh.Create(meshArray, callback)

从网格对象数组创建实例化网格，自动计算包围盒和BVH树。

参数:

meshArray {Array<Mesh>} - 网格对象数组
callback {Function} - 回调函数，接收(uniqueId, index)参数

返回值:

{InstancedMesh} 实例化网格对象

InstancedLine.Create(lineArray, callback)

从线条对象数组创建实例化线条。

参数:

lineArray {Array<Line>} - 线条对象数组
callback {Function} - 回调函数

返回值:

{InstancedLine} 实例化线条对象

InstancedLineSegments.Create(lineSegmentsArray, callback)

从线段对象数组创建实例化线段。

参数:

lineSegmentsArray {Array<LineSegments>} - 线段对象数组
callback {Function} - 回调函数

返回值:

{InstancedLineSegments} 实例化线段对象

InstancedLineLoop.Create(lineLoopArray, callback)

从闭合线条对象数组创建实例化闭合线条。

参数:

lineLoopArray {Array<LineLoop>} - 闭合线条对象数组
callback {Function} - 回调函数

返回值:

{InstancedLineLoop} 实例化闭合线条对象

通用方法

以下方法在所有实例化类中通用，继承自InstancedObject3D基类：

方法名	功能描述	参数	返回值
`setColorAt(index, color)`	设置实例颜色	`index` {number}, `color`	-
`setMatrixAt(index, matrix)`	设置实例变换矩阵	`index` {number}, `matrix`	-
`getColorAt(index, color)`	获取实例颜色	`index` {number}, `color`	-
`getMatrixAt(index, matrix)`	获取实例变换矩阵	`index` {number}, `matrix`	-
`getAllInstanceWorldBoundingBox()`	获取所有实例世界包围盒	-
`getAllInstanceWorldBoundingSphere()`	获取所有实例世界包围球	-
`getInstanceGeometry()`	获取实例几何体	-
`raycast(raycaster, intersects, objectType)`	射线检测	`raycaster` {Raycaster}, `intersects` {Array}, `objectType`	-
`getAllInstances()`	获取所有实例对象	-
`getUniqueIDByIndex(index)`	根据索引获取唯一ID	`index`
`setInstanceMatrix(index, transformMatrix)`	设置实例变换矩阵	`index` {number}, `transformMatrix`
`setInstanceVisible(index, boolean)`	设置实例可见性	`index` {number}, `boolean`
`computeBVHTree()`	计算BVH树	-	-
`updateMorphTargets()`	更新变形目标	-	-
`dispose()`	释放资源	-	-
`toJSON()`	转换为JSON格式	-

重写方法

每个类重写了以下方法，提供类型特定的实现：

getInstance()

类名	方法签名	特殊功能
`InstancedMesh`	`getInstance(index, overWriteMaterial, edgesLineMaterial)`	支持边缘线材质，可添加边缘线显示
`InstancedLine`	`getInstance(index, overWriteMaterial)`	基础实现，设置renderOrder=2
`InstancedLineSegments`	`getInstance(index, overWriteMaterial)`	基础实现，设置renderOrder=2
`InstancedLineLoop`	`getInstance(index, overWriteMaterial)`	基础实现，设置renderOrder=2

toJSON()

每个类设置不同的类型标识：

类名	类型标识
`InstancedMesh`	`INSTANCED_OBJECT3D_TYPE.MESH`
`InstancedLine`	`INSTANCED_OBJECT3D_TYPE.LINE`
`InstancedLineSegments`	`INSTANCED_OBJECT3D_TYPE.LINE_SEGMENTS`
`InstancedLineLoop`	`INSTANCED_OBJECT3D_TYPE.LINE_LOOP`

特殊方法

computeLineDistances()

拥有类: InstancedLine, InstancedLineSegments

计算线条距离，为线条几何体计算累积距离，用于线条材质的效果渲染。

示例:

javascript

// 计算线条距离
instancedLine.computeLineDistances();

使用场景

大量相同对象渲染

建筑模型中的重复构件
植被系统中的树木和草地
粒子系统中的粒子对象

渲染优化

减少绘制调用次数
降低GPU负载
提高渲染性能

动态实例管理

动态添加和移除实例
控制实例的可见性
更新实例的变换

InstancedObjects ​

类定义 ​

常量 ​

INSTANCED_OBJECT3D_TYPE ​

InstanceInfo ​

构造函数 ​

constructor(geometry, material, count) ​

静态方法 ​

InstancedMesh.Create(meshArray, callback) ​

InstancedLine.Create(lineArray, callback) ​

InstancedLineSegments.Create(lineSegmentsArray, callback) ​

InstancedLineLoop.Create(lineLoopArray, callback) ​

通用方法 ​

重写方法 ​

getInstance() ​

toJSON() ​

特殊方法 ​

computeLineDistances() ​

使用场景 ​

大量相同对象渲染 ​

渲染优化 ​

动态实例管理 ​

相关链接 ​

InstancedObjects

类定义

常量

INSTANCED_OBJECT3D_TYPE

InstanceInfo

构造函数

constructor(geometry, material, count)

静态方法

InstancedMesh.Create(meshArray, callback)

InstancedLine.Create(lineArray, callback)

InstancedLineSegments.Create(lineSegmentsArray, callback)

InstancedLineLoop.Create(lineLoopArray, callback)

通用方法

重写方法

getInstance()

toJSON()

特殊方法

computeLineDistances()

使用场景

大量相同对象渲染

渲染优化

动态实例管理

相关链接