@lijuhong1981/three.instancedsprite 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/.claude/settings.local.json +7 -0
  2. package/API.md +514 -0
  3. package/README.md +55 -0
  4. package/index.js +5 -0
  5. package/package.json +41 -0
  6. package/src/InstancedSprite.js +345 -0
  7. package/src/InstancedSpriteCollection.js +226 -0
  8. package/src/InstancedSpriteMaterial.js +134 -0
  9. package/src/InstancedSpriteMesh.js +406 -0
  10. package/src/InstancedSpriteNodeMaterial.js +148 -0
package/.claude/settings.local.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "permissions": {
3
+ "allow": [
4
+ "Bash(node --check src/InstancedSpriteNodeMaterial.js)"
5
+ ]
6
+ }
7
+ }
package/API.md ADDED
@@ -0,0 +1,514 @@
1
+ ## Classes
2
+
3
+ <dl>
4
+ <dt><a href="#InstancedSprite">InstancedSprite</a></dt>
5
+ <dd><p>InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有属性</p>
6
+ <ul>
7
+ <li>InstancedSprite跟Sprite不同，它只是一个数据集合对象，并不继承自Object3D，不能直接加入到Scene中</li>
8
+ <li>但它可以作为属性Module使用，修改InstancedSprite的属性会自动更新至GPU中</li>
9
+ </ul>
10
+ </dd>
11
+ <dt><a href="#InstancedSpriteCollection">InstancedSpriteCollection</a> ⇐ <code>Object3D</code></dt>
12
+ <dd><p>InstancedSpriteCollection类，批量管理InstancedSprite实例</p>
13
+ <ul>
14
+ <li>继承自Object3D</li>
15
+ <li>根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，</li>
16
+ <li>管理InstancedSprite与InstancedSpriteMesh实例</li>
17
+ </ul>
18
+ </dd>
19
+ <dt><a href="#InstancedSpriteMaterial">InstancedSpriteMaterial</a> ⇐ <code>ShaderMaterial</code></dt>
20
+ <dd><p>InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性</p>
21
+ </dd>
22
+ <dt><a href="#InstancedSpriteMesh">InstancedSpriteMesh</a> ⇐ <code>Mesh</code></dt>
23
+ <dd><p>InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件</p>
24
+ </dd>
25
+ </dl>
26
+
27
+ ## Constants
28
+
29
+ <dl>
30
+ <dt><a href="#imageLoader">imageLoader</a></dt>
31
+ <dd></dd>
32
+ </dl>
33
+
34
+ ## Typedefs
35
+
36
+ <dl>
37
+ <dt><a href="#InstancedSpriteOptions">InstancedSpriteOptions</a> : <code>object</code></dt>
38
+ <dd><p>InstancedSprite 对象配置项选项</p>
39
+ </dd>
40
+ </dl>
41
+
42
+ <a name="InstancedSprite"></a>
43
+
44
+ ## InstancedSprite
45
+ InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有属性
46
+
47
+ * InstancedSprite跟Sprite不同，它只是一个数据集合对象，并不继承自Object3D，不能直接加入到Scene中
48
+ * 但它可以作为属性Module使用，修改InstancedSprite的属性会自动更新至GPU中
49
+
50
+ **Kind**: global class
51
+
52
+ * [InstancedSprite](#InstancedSprite)
53
+ * [new InstancedSprite(options, collection)](#new_InstancedSprite_new)
54
+ * [.type](#InstancedSprite+type) : <code>string</code>
55
+ * [.uuid](#InstancedSprite+uuid) : <code>string</code>
56
+ * [.show](#InstancedSprite+show) : <code>boolean</code>
57
+ * [.position](#InstancedSprite+position) : <code>Vector3</code>
58
+ * [.scale](#InstancedSprite+scale) : <code>number</code>
59
+ * [.rotation](#InstancedSprite+rotation) : <code>number</code>
60
+ * [.sizeAttenuation](#InstancedSprite+sizeAttenuation) : <code>boolean</code>
61
+ * [.center](#InstancedSprite+center) : <code>Vector2</code>
62
+ * [.color](#InstancedSprite+color) : <code>Color</code>
63
+ * [.opacity](#InstancedSprite+opacity) : <code>number</code>
64
+ * [.imageSize](#InstancedSprite+imageSize) : <code>Vector2</code>
65
+ * [.isInstancedSprite](#InstancedSprite+isInstancedSprite) : <code>boolean</code>
66
+ * [.visible](#InstancedSprite+visible) : <code>boolean</code>
67
+ * [.rotationDegrees](#InstancedSprite+rotationDegrees) : <code>number</code>
68
+ * [.image](#InstancedSprite+image) : <code>string</code> \| <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code>
69
+ * [.imageId](#InstancedSprite+imageId) : <code>string</code>
70
+ * [.imageWidth](#InstancedSprite+imageWidth) : <code>number</code>
71
+ * [.imageHeight](#InstancedSprite+imageHeight) : <code>number</code>
72
+ * [.geometry](#InstancedSprite+geometry) : <code>InstancedBufferGeometry</code>
73
+ * [.material](#InstancedSprite+material) : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)
74
+ * [.setValues(options)](#InstancedSprite+setValues) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
75
+ * [.remove()](#InstancedSprite+remove) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
76
+ * [.raycast(raycaster, intersects, modelViewMatrix)](#InstancedSprite+raycast)
77
+
78
+ <a name="new_InstancedSprite_new"></a>
79
+
80
+ ### new InstancedSprite(options, collection)
81
+
82
+ | Param | Type | Description |
83
+ | --- | --- | --- |
84
+ | options | [<code>InstancedSpriteOptions</code>](#InstancedSpriteOptions) | 初始化配置项 |
85
+ | collection | [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection) | 所属InstancedSpriteCollection实例，必填 |
86
+
87
+ <a name="InstancedSprite+type"></a>
88
+
89
+ ### instancedSprite.type : <code>string</code>
90
+ 对象类型标识
91
+
92
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
93
+ **Read only**: true
94
+ <a name="InstancedSprite+uuid"></a>
95
+
96
+ ### instancedSprite.uuid : <code>string</code>
97
+ 当前InstancedSprite的唯一标识id
98
+
99
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
100
+ **Read only**: true
101
+ <a name="InstancedSprite+show"></a>
102
+
103
+ ### instancedSprite.show : <code>boolean</code>
104
+ 是否显示
105
+
106
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
107
+ <a name="InstancedSprite+position"></a>
108
+
109
+ ### instancedSprite.position : <code>Vector3</code>
110
+ 世界坐标位置
111
+
112
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
113
+ <a name="InstancedSprite+scale"></a>
114
+
115
+ ### instancedSprite.scale : <code>number</code>
116
+ 缩放
117
+
118
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
119
+ <a name="InstancedSprite+rotation"></a>
120
+
121
+ ### instancedSprite.rotation : <code>number</code>
122
+ 旋转（弧度）
123
+
124
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
125
+ <a name="InstancedSprite+sizeAttenuation"></a>
126
+
127
+ ### instancedSprite.sizeAttenuation : <code>boolean</code>
128
+ 尺寸是否跟随相机深度变化
129
+
130
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
131
+ <a name="InstancedSprite+center"></a>
132
+
133
+ ### instancedSprite.center : <code>Vector2</code>
134
+ 锚点中心（0-1）
135
+
136
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
137
+ <a name="InstancedSprite+color"></a>
138
+
139
+ ### instancedSprite.color : <code>Color</code>
140
+ 颜色
141
+
142
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
143
+ <a name="InstancedSprite+opacity"></a>
144
+
145
+ ### instancedSprite.opacity : <code>number</code>
146
+ 不透明度（0-1）
147
+
148
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
149
+ <a name="InstancedSprite+imageSize"></a>
150
+
151
+ ### instancedSprite.imageSize : <code>Vector2</code>
152
+ 图片尺寸（像素），图片加载完成后可用
153
+
154
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
155
+ **Read only**: true
156
+ <a name="InstancedSprite+isInstancedSprite"></a>
157
+
158
+ ### instancedSprite.isInstancedSprite : <code>boolean</code>
159
+ InstancedSprite对象标识
160
+
161
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
162
+ **Read only**: true
163
+ <a name="InstancedSprite+visible"></a>
164
+
165
+ ### instancedSprite.visible : <code>boolean</code>
166
+ 是否可见，等同于show
167
+
168
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
169
+ <a name="InstancedSprite+rotationDegrees"></a>
170
+
171
+ ### instancedSprite.rotationDegrees : <code>number</code>
172
+ 旋转（角度）
173
+
174
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
175
+ <a name="InstancedSprite+image"></a>
176
+
177
+ ### instancedSprite.image : <code>string</code> \| <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code>
178
+ 图片资源，可以是URL字符串、HTMLImageElement或HTMLCanvasElement
179
+
180
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
181
+ <a name="InstancedSprite+imageId"></a>
182
+
183
+ ### instancedSprite.imageId : <code>string</code>
184
+ 图片ID，图片加载完成后可用，通常为图片URL或生成的UUID
185
+
186
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
187
+ **Read only**: true
188
+ <a name="InstancedSprite+imageWidth"></a>
189
+
190
+ ### instancedSprite.imageWidth : <code>number</code>
191
+ 图片像素宽度，图片加载完成后可用
192
+
193
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
194
+ **Read only**: true
195
+ <a name="InstancedSprite+imageHeight"></a>
196
+
197
+ ### instancedSprite.imageHeight : <code>number</code>
198
+ 图片像素高度，图片加载完成后可用
199
+
200
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
201
+ **Read only**: true
202
+ <a name="InstancedSprite+geometry"></a>
203
+
204
+ ### instancedSprite.geometry : <code>InstancedBufferGeometry</code>
205
+ InstancedSprite对象的几何体属性
206
+
207
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
208
+ **Read only**: true
209
+ <a name="InstancedSprite+material"></a>
210
+
211
+ ### instancedSprite.material : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)
212
+ InstancedSprite对象的材质属性
213
+
214
+ **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)
215
+ **Read only**: true
216
+ <a name="InstancedSprite+setValues"></a>
217
+
218
+ ### instancedSprite.setValues(options) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
219
+ 设置参数
220
+
221
+ **Kind**: instance method of [<code>InstancedSprite</code>](#InstancedSprite)
222
+
223
+ | Param | Type |
224
+ | --- | --- |
225
+ | options | [<code>InstancedSpriteOptions</code>](#InstancedSpriteOptions) |
226
+
227
+ <a name="InstancedSprite+remove"></a>
228
+
229
+ ### instancedSprite.remove() ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
230
+ 从Mesh中移除该InstancedSprite对象
231
+
232
+ **Kind**: instance method of [<code>InstancedSprite</code>](#InstancedSprite)
233
+ <a name="InstancedSprite+raycast"></a>
234
+
235
+ ### instancedSprite.raycast(raycaster, intersects, modelViewMatrix)
236
+ Computes intersection points between a casted ray and this sprite.
237
+
238
+ **Kind**: instance method of [<code>InstancedSprite</code>](#InstancedSprite)
239
+
240
+ | Param | Type | Description |
241
+ | --- | --- | --- |
242
+ | raycaster | <code>Raycaster</code> | The raycaster. |
243
+ | intersects | <code>Array.&lt;Object&gt;</code> | The target array that holds the intersection points. |
244
+ | modelViewMatrix | <code>Matrix4</code> | |
245
+
246
+ <a name="InstancedSpriteCollection"></a>
247
+
248
+ ## InstancedSpriteCollection ⇐ <code>Object3D</code>
249
+ InstancedSpriteCollection类，批量管理InstancedSprite实例
250
+
251
+ * 继承自Object3D
252
+ * 根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，
253
+ * 管理InstancedSprite与InstancedSpriteMesh实例
254
+
255
+ **Kind**: global class
256
+ **Extends**: <code>Object3D</code>
257
+
258
+ * [InstancedSpriteCollection](#InstancedSpriteCollection) ⇐ <code>Object3D</code>
259
+ * [.type](#InstancedSpriteCollection+type) : <code>string</code>
260
+ * [.isInstancedSpriteCollection](#InstancedSpriteCollection+isInstancedSpriteCollection) : <code>boolean</code>
261
+ * [.depthTest](#InstancedSpriteCollection+depthTest) : <code>boolean</code>
262
+ * [.instancedSprites](#InstancedSpriteCollection+instancedSprites) : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
263
+ * [.size](#InstancedSpriteCollection+size) : <code>number</code>
264
+ * [._setImage(source, sprite)](#InstancedSpriteCollection+_setImage)
265
+ * [.get(index)](#InstancedSpriteCollection+get) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
266
+ * [.getByUuid(uuid)](#InstancedSpriteCollection+getByUuid) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
267
+ * [.add()](#InstancedSpriteCollection+add) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
268
+ * [.remove(sprite)](#InstancedSpriteCollection+remove) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
269
+ * [.forEach(callback)](#InstancedSpriteCollection+forEach) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
270
+ * [.raycast(raycaster, intersects)](#InstancedSpriteCollection+raycast)
271
+
272
+ <a name="InstancedSpriteCollection+type"></a>
273
+
274
+ ### instancedSpriteCollection.type : <code>string</code>
275
+ 对象类型标识
276
+
277
+ **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
278
+ **Read only**: true
279
+ <a name="InstancedSpriteCollection+isInstancedSpriteCollection"></a>
280
+
281
+ ### instancedSpriteCollection.isInstancedSpriteCollection : <code>boolean</code>
282
+ InstancedSpriteCollection对象标识
283
+
284
+ **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
285
+ **Read only**: true
286
+ <a name="InstancedSpriteCollection+depthTest"></a>
287
+
288
+ ### instancedSpriteCollection.depthTest : <code>boolean</code>
289
+ 深度测试开关，默认为true，开启后会进行深度测试以正确处理遮挡关系，但可能会有性能影响；如果关闭则所有InstancedSprite都会被渲染在最前面，适合需要始终显示的UI元素等场景
290
+
291
+ **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
292
+ **Default**: <code>true</code>
293
+ <a name="InstancedSpriteCollection+instancedSprites"></a>
294
+
295
+ ### instancedSpriteCollection.instancedSprites : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
296
+ InstancedSprite实例数组
297
+
298
+ **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
299
+ **Read only**: true
300
+ <a name="InstancedSpriteCollection+size"></a>
301
+
302
+ ### instancedSpriteCollection.size : <code>number</code>
303
+ InstancedSprite实例数量
304
+
305
+ **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
306
+ **Read only**: true
307
+ <a name="InstancedSpriteCollection+_setImage"></a>
308
+
309
+ ### instancedSpriteCollection.\_setImage(source, sprite)
310
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
311
+
312
+ | Param | Type |
313
+ | --- | --- |
314
+ | source | <code>string</code> \| <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code> |
315
+ | sprite | [<code>InstancedSprite</code>](#InstancedSprite) |
316
+
317
+ <a name="InstancedSpriteCollection+get"></a>
318
+
319
+ ### instancedSpriteCollection.get(index) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
320
+ 根据索引获取InstancedSprite实例
321
+
322
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
323
+
324
+ | Param | Type |
325
+ | --- | --- |
326
+ | index | <code>number</code> |
327
+
328
+ <a name="InstancedSpriteCollection+getByUuid"></a>
329
+
330
+ ### instancedSpriteCollection.getByUuid(uuid) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
331
+ 根据uuid获取InstancedSprite实例
332
+
333
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
334
+
335
+ | Param | Type |
336
+ | --- | --- |
337
+ | uuid | <code>string</code> |
338
+
339
+ <a name="InstancedSpriteCollection+add"></a>
340
+
341
+ ### instancedSpriteCollection.add() ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
342
+ 添加InstancedSprite
343
+
344
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
345
+ <a name="InstancedSpriteCollection+remove"></a>
346
+
347
+ ### instancedSpriteCollection.remove(sprite) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
348
+ 移除InstancedSprite
349
+
350
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
351
+
352
+ | Param | Type |
353
+ | --- | --- |
354
+ | sprite | [<code>InstancedSprite</code>](#InstancedSprite) |
355
+
356
+ <a name="InstancedSpriteCollection+forEach"></a>
357
+
358
+ ### instancedSpriteCollection.forEach(callback) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
359
+ 遍历所有的InstancedSprite
360
+
361
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
362
+
363
+ | Param | Type |
364
+ | --- | --- |
365
+ | callback | <code>function</code> |
366
+
367
+ <a name="InstancedSpriteCollection+raycast"></a>
368
+
369
+ ### instancedSpriteCollection.raycast(raycaster, intersects)
370
+ Computes intersection points between a casted ray and this sprite.
371
+
372
+ **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
373
+
374
+ | Param | Type | Description |
375
+ | --- | --- | --- |
376
+ | raycaster | <code>Raycaster</code> | The raycaster. |
377
+ | intersects | <code>Array.&lt;Object&gt;</code> | The target array that holds the intersection points. |
378
+
379
+ <a name="InstancedSpriteMaterial"></a>
380
+
381
+ ## InstancedSpriteMaterial ⇐ <code>ShaderMaterial</code>
382
+ InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性
383
+
384
+ **Kind**: global class
385
+ **Extends**: <code>ShaderMaterial</code>
386
+ <a name="InstancedSpriteMaterial+texture"></a>
387
+
388
+ ### instancedSpriteMaterial.texture : <code>Texture</code>
389
+ 图片纹理
390
+
391
+ **Kind**: instance property of [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)
392
+ <a name="InstancedSpriteMesh"></a>
393
+
394
+ ## InstancedSpriteMesh ⇐ <code>Mesh</code>
395
+ InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件
396
+
397
+ **Kind**: global class
398
+ **Extends**: <code>Mesh</code>
399
+
400
+ * [InstancedSpriteMesh](#InstancedSpriteMesh) ⇐ <code>Mesh</code>
401
+ * [new InstancedSpriteMesh(collection, texture)](#new_InstancedSpriteMesh_new)
402
+ * [.type](#InstancedSpriteMesh+type) : <code>string</code>
403
+ * [.isInstancedSpriteMesh](#InstancedSpriteMesh+isInstancedSpriteMesh) : <code>boolean</code>
404
+ * [.depthTest](#InstancedSpriteMesh+depthTest) : <code>boolean</code>
405
+ * [.instancedSprites](#InstancedSpriteMesh+instancedSprites) : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
406
+ * [.add(sprite)](#InstancedSpriteMesh+add) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
407
+ * [.remove(sprite)](#InstancedSpriteMesh+remove) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
408
+ * [.clear()](#InstancedSpriteMesh+clear) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
409
+ * [.raycast(raycaster, intersects)](#InstancedSpriteMesh+raycast)
410
+
411
+ <a name="new_InstancedSpriteMesh_new"></a>
412
+
413
+ ### new InstancedSpriteMesh(collection, texture)
414
+
415
+ | Param | Type | Description |
416
+ | --- | --- | --- |
417
+ | collection | [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection) | 所属的InstancedSpriteCollection实例，必填 |
418
+ | texture | <code>Texture</code> | 材质图像纹理，必填 |
419
+
420
+ <a name="InstancedSpriteMesh+type"></a>
421
+
422
+ ### instancedSpriteMesh.type : <code>string</code>
423
+ 对象类型标识
424
+
425
+ **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
426
+ **Read only**: true
427
+ <a name="InstancedSpriteMesh+isInstancedSpriteMesh"></a>
428
+
429
+ ### instancedSpriteMesh.isInstancedSpriteMesh : <code>boolean</code>
430
+ InstancedSpriteMesh对象标识
431
+
432
+ **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
433
+ **Read only**: true
434
+ <a name="InstancedSpriteMesh+depthTest"></a>
435
+
436
+ ### instancedSpriteMesh.depthTest : <code>boolean</code>
437
+ 深度测试开关，默认为true，开启后会进行深度测试以正确处理遮挡关系，但可能会有性能影响；如果关闭则所有InstancedSprite都会被渲染在最前面，适合需要始终显示的UI元素等场景
438
+
439
+ **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
440
+ **Default**: <code>true</code>
441
+ <a name="InstancedSpriteMesh+instancedSprites"></a>
442
+
443
+ ### instancedSpriteMesh.instancedSprites : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
444
+ InstancedSprite对象数组
445
+
446
+ **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
447
+ **Read only**: true
448
+ <a name="InstancedSpriteMesh+add"></a>
449
+
450
+ ### instancedSpriteMesh.add(sprite) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
451
+ 添加一个InstancedSprite
452
+
453
+ **Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
454
+
455
+ | Param | Type | Description |
456
+ | --- | --- | --- |
457
+ | sprite | [<code>InstancedSprite</code>](#InstancedSprite) | 要添加的InstancedSprite实例 |
458
+
459
+ <a name="InstancedSpriteMesh+remove"></a>
460
+
461
+ ### instancedSpriteMesh.remove(sprite) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
462
+ 移除一个InstancedSprite
463
+
464
+ **Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
465
+
466
+ | Param | Type | Description |
467
+ | --- | --- | --- |
468
+ | sprite | [<code>InstancedSprite</code>](#InstancedSprite) | 要移除的InstancedSprite实例 |
469
+
470
+ <a name="InstancedSpriteMesh+clear"></a>
471
+
472
+ ### instancedSpriteMesh.clear() ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
473
+ 移除所有InstancedSprite
474
+
475
+ **Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
476
+ <a name="InstancedSpriteMesh+raycast"></a>
477
+
478
+ ### instancedSpriteMesh.raycast(raycaster, intersects)
479
+ Computes intersection points between a casted ray and this sprite.
480
+
481
+ **Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
482
+
483
+ | Param | Type | Description |
484
+ | --- | --- | --- |
485
+ | raycaster | <code>Raycaster</code> | The raycaster. |
486
+ | intersects | <code>Array.&lt;Object&gt;</code> | The target array that holds the intersection points. |
487
+
488
+ <a name="imageLoader"></a>
489
+
490
+ ## imageLoader
491
+ **Kind**: global constant
492
+ **Import**: InstancedSpriteCollection from "./InstancedSpriteCollection.js";
493
+ **Import**: InstancedSpriteMesh from "./InstancedSpriteMesh.js";
494
+ **Import**: InstancedSpriteMaterial from "./InstancedSpriteMaterial.js";
495
+ <a name="InstancedSpriteOptions"></a>
496
+
497
+ ## InstancedSpriteOptions : <code>object</code>
498
+ InstancedSprite 对象配置项选项
499
+
500
+ **Kind**: global typedef
501
+ **Properties**
502
+
503
+ | Name | Type | Default | Description |
504
+ | --- | --- | --- | --- |
505
+ | [show] | <code>boolean</code> | <code>true</code> | 是否显示 |
506
+ | [position] | <code>Vector3</code> \| <code>Array.&lt;number&gt;</code> | <code>(0,0,0)</code> | 位置（世界空间） |
507
+ | [scale] | <code>number</code> | <code>1</code> | 缩放 |
508
+ | [rotation] | <code>number</code> | <code>0</code> | 旋转（弧度） |
509
+ | [sizeAttenuation] | <code>boolean</code> | <code>true</code> | 尺寸是否跟随相机深度变化 |
510
+ | [center] | <code>Vector2</code> \| <code>Array.&lt;number&gt;</code> | <code>(0.5,0.5)</code> | 锚点中心（0-1） |
511
+ | [color] | <code>Color</code> \| <code>number</code> \| <code>string</code> | <code>0xffffff</code> | 颜色 |
512
+ | [opacity] | <code>number</code> | <code>1</code> | 不透明度（0-1） |
513
+ | [image] | <code>string</code> \| <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code> | | 图片资源 |
514
+
package/README.md ADDED
@@ -0,0 +1,55 @@
1
+ # InstancedSprite
2
+
3
+ three自带的Sprite并不支持GPU实例化渲染，当遇到需要在场景中大量展示标签的情况时就会出现帧率下降的问题，所以开发了这个InstancedSprite，以InstancedBufferGeometry+自定义ShaderMaterial的形式实例化渲染InstancedSprite对象，极大的提高了大批量标签展示时的渲染效率。
4
+
5
+ ## 安装
6
+
7
+ ```bash
8
+ npm install @lijuhong1981/three.instancedsprite
9
+ ```
10
+
11
+ ## 使用
12
+
13
+ ```js
14
+ import { InstancedSpriteCollection } from "@lijuhong1981/instancedsprite";
15
+ ...
16
+ // 初始化
17
+ const collection = new InstancedSpriteCollection();
18
+ // 如果使用的是WebGPURenderer，请添加参数true，以启用TSL的NodeMaterial
19
+ // const collection = new InstancedSpriteCollection(true);
20
+ ...
21
+ // 动画帧更新
22
+ const onAnimate = () => {
23
+ window.requestAnimationFrame(onAnimate);
24
+ ...
25
+ // 每帧更新
26
+ collection.update();
27
+ };
28
+ // 添加
29
+ const sprite = collection.add(
30
+ {
31
+ position: [100, 100, 100], //位置
32
+ rotation: 0, //旋转
33
+ scale: 1.0, //缩放
34
+ sizeAttenuation: false, //尺寸跟随相机深度变化
35
+ center: [0.5, 0], //中心锚点
36
+ color: 0xff0000, //颜色
37
+ opacity: 0.5, //不透明度
38
+ image: './res/icon.png', //图像地址，相同的image会分配到同一个Mesh下一次性渲染
39
+ }
40
+ );
41
+ // 移除
42
+ sprite.remove();
43
+ // 或
44
+ // collection.remove(sprite);
45
+ // 清空
46
+ collection.clear();
47
+ // 射线检测
48
+ raycaster.setFromCamera(ndc, camera)
49
+ const intersects = raycaster.intersectObject(collection);
50
+ if (intersects.length > 0) {
51
+ const pickedSprite = intersects[0].object; //拾取到的InstancedSprite对象
52
+ }
53
+ ```
54
+
55
+ ## [API文档](./API.md)
package/index.js ADDED
@@ -0,0 +1,5 @@
1
+ export * from "./src/InstancedSprite.js";
2
+ export * from "./src/InstancedSpriteCollection.js";
3
+ export * from "./src/InstancedSpriteMaterial.js";
4
+ export * from "./src/InstancedSpriteMesh.js";
5
+ export * from "./src/InstancedSpriteNodeMaterial.js";
package/package.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "@lijuhong1981/three.instancedsprite",
3
+ "version": "1.0.0",
4
+ "description": "",
5
+ "type": "module",
6
+ "module": "index.js",
7
+ "main": "index.js",
8
+ "publishConfig": {
9
+ "access": "public"
10
+ },
11
+ "scripts": {
12
+ "test": "echo \"Error: no test specified\" && exit 1",
13
+ "docs": "jsdoc2md --files src/*.js > API.md"
14
+ },
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/lijuhong1981/threeInstancedSprite.git"
18
+ },
19
+ "keywords": [
20
+ "three",
21
+ "instanced",
22
+ "sprite",
23
+ "billboard",
24
+ "webgl",
25
+ "webgpu"
26
+ ],
27
+ "author": "",
28
+ "license": "ISC",
29
+ "bugs": {
30
+ "url": "https://github.com/lijuhong1981/threeInstancedSprite/issues"
31
+ },
32
+ "homepage": "https://github.com/lijuhong1981/threeInstancedSprite#readme",
33
+ "dependencies": {
34
+ "@lijuhong1981/jslibs": "^1.4.25",
35
+ "@lijuhong1981/three.utils": "^1.0.3",
36
+ "three": ">=0.171.0"
37
+ },
38
+ "devDependencies": {
39
+ "jsdoc-to-markdown": "^9.1.3"
40
+ }
41
+ }