[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,96 +2,257 @@
|
||||
id: wiki-2026-0508-instancedmesh-동적-버퍼-확장
|
||||
title: InstancedMesh 동적 버퍼 확장
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-D6CCE0]
|
||||
aliases: [Dynamic InstancedMesh, Resize InstancedMesh, InstancedMesh Growth]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
verification_status: applied
|
||||
tags: [threejs, webgl, webgpu, performance, buffer]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - [[InstancedMesh]] 동적 버퍼 확장"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: TypeScript
|
||||
framework: Three.js r172
|
||||
---
|
||||
|
||||
# [[InstancedMesh 동적 버퍼 확장]]
|
||||
# InstancedMesh 동적 버퍼 확장
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> InstancedMesh 동적 버퍼 확장은 렌더링 중 인스턴스 수가 초기 할당된 용량(Capacity)을 초과할 때, 시스템이 새로운 더 큰 버퍼를 할당하고 기존 데이터를 복사하는 과정을 의미한다 [1]. 이 과정에서 수십 메가바이트 크기의 배열이 빈번하게 생성되고 파괴되어 가비지 컬렉션(GC)을 유발하며, 이는 프레임 지연(스터터링)이나 메모리 할당 오류로 이어진다 [1, 2]. 결과적으로 이러한 성능 병목을 피하기 위해 개발자들은 런타임 확장을 피하고, 최대 예상 인스턴스 수에 맞춘 버퍼 사전 할당이나 객체 풀링 전략을 권장하고 있다 [1, 3].
|
||||
## 매 한 줄
|
||||
> **"매 InstancedMesh 의 capacity 부족 시 GPU buffer 를 reallocate"**. Three.js InstancedMesh 의 `count` 는 fixed allocation. 매 instance 추가가 capacity 초과하면 새 buffer 를 만들고 기존 data 를 copy. 매 amortized O(1) 을 위한 geometric growth 가 정석.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **동적 버퍼 확장의 발생 원리**
|
||||
InstancedMesh는 객체 수가 동적으로 변하는 환경(예: 적들이 수시로 생성되거나 파괴되는 상황)에서 초기 용량을 넘어서면 새로운 버퍼를 동적으로 확장해야 한다 [1]. 이때 기존 데이터를 새롭고 더 큰 버퍼로 복사하는 작업이 필연적으로 수반된다 [1].
|
||||
## 매 핵심
|
||||
|
||||
- **성능 저하 및 메모리 문제**
|
||||
동적 버퍼 확장은 메모리 할당 빈도가 매우 잦아 CPU 부하를 극도로 높이며, 데이터 전송 효율을 떨어뜨린다 [1]. 구형 `[[TypedArray]]` 데이터가 메모리에서 빈번하게 해제되는 과정에서 자바스크립트 가비지 컬렉터(GC)가 작동하여 프레임이 일시적으로 멈추는 현상(Stuttering)이 발생한다 [1]. A-Frame 기반 구현 등 일부 환경에서는 용량 증가 시 이전 InstancedMesh를 깔끔하게 해제(dispose)하지 못해 작은 메모리 누수([[memory]] Leak)가 발생할 우려도 존재한다 [4]. [[Needle Engine]] 환경에서도 버퍼가 동적으로 확장될 때 "[[[Instancing]]] Growing Buffer"라는 로그와 함께 렌더링이 일시적으로 수 초간 멈추는 성능 병목이 관찰되었다 [2].
|
||||
### 매 기본 한계
|
||||
- 매 `new InstancedMesh(geo, mat, count)` 는 매 `count` 만큼 GPU buffer alloc.
|
||||
- 매 `mesh.count` 변경은 draw 만 줄이지 buffer 는 그대로.
|
||||
- 매 capacity 초과 → 매 새 mesh / 새 InstancedBufferAttribute 가 필요.
|
||||
|
||||
- **최적화 및 대안 전략**
|
||||
이러한 성능 하락을 방지하려면 런타임에 동적으로 버퍼를 확장하는 대신, 앱 시작 시점이나 로드 시 최대 예상 인스턴스 수에 맞춰 충분한 크기의 버퍼를 미리 할당(Preallocate)하는 방식이 권장된다 [3, 5]. 또한, 대규모 프로젝트에서는 예측 불가능한 버퍼 확장을 막기 위해 사전에 엄격한 메모리 예산을 수립해야 한다 [1]. 메모리 할당 및 해제의 오버헤드를 최소화하기 위해 한 번 생성된 인스턴스 데이터를 재사용하는 객체 풀링(Object [[Pooling]])이나 링 버퍼(Ring Buffer) 구조를 채택하는 것이 효율적이다 [1].
|
||||
### 매 Strategy
|
||||
- **Geometric growth**: 매 capacity 부족 시 ×1.5 또는 ×2 로 resize.
|
||||
- **Pool & free list**: 매 deletion 후 빈 slot 재사용 (compact 회피).
|
||||
- **Chunked**: 매 fixed-size chunk N 개로 운영 (한 chunk 가득 차면 새 chunk).
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
|
||||
### 매 응용
|
||||
1. **Realtime particle spawn / despawn**.
|
||||
2. **User-placed object editor** (매 추가 무한).
|
||||
3. **Streaming voxel chunk** (매 LOD 별 instance 수 가변).
|
||||
4. **NPC spawn system**.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[InstancedMesh]], [[가비지 컬렉션 ([[Garbage Collection]])]], 객체 풀링 ([[Object Pooling]]), 버퍼 사전 할당 (Buffer Preallocation)
|
||||
- **Projects/Contexts:** [[Needle Engine]], A-Frame (instanced-mesh 컴포넌트), 실시간 웹 그래픽스 최적화
|
||||
- **Contradictions/Notes:** 예측 불가능한 다량의 객체를 렌더링하려면 동적 확장이 필수적인 기능처럼 보이나, 실제 렌더링 환경에서는 이 과정이 프레임 드랍과 메모리 누수 위험 등 높은 리스크를 수반하므로 오히려 고정 용량 할당이나 풀링을 통해 원천적으로 확장을 회피하는 것이 강력히 권장된다 [1, 3, 4].
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-19*
|
||||
### 1. Geometric resize utility
|
||||
```typescript
|
||||
class DynamicInstancedMesh {
|
||||
private mesh: THREE.InstancedMesh;
|
||||
private capacity: number;
|
||||
private size = 0;
|
||||
private freeList: number[] = [];
|
||||
|
||||
---
|
||||
constructor(
|
||||
private geo: THREE.BufferGeometry,
|
||||
private mat: THREE.Material,
|
||||
initialCapacity = 64,
|
||||
private maxCapacity = 1_000_000,
|
||||
) {
|
||||
this.capacity = initialCapacity;
|
||||
this.mesh = this.makeMesh(initialCapacity);
|
||||
}
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
private makeMesh(cap: number): THREE.InstancedMesh {
|
||||
const m = new THREE.InstancedMesh(this.geo, this.mat, cap);
|
||||
m.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
|
||||
m.count = this.size;
|
||||
return m;
|
||||
}
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
add(matrix: THREE.Matrix4): number {
|
||||
let idx: number;
|
||||
if (this.freeList.length > 0) {
|
||||
idx = this.freeList.pop()!;
|
||||
} else {
|
||||
if (this.size >= this.capacity) this.grow();
|
||||
idx = this.size++;
|
||||
}
|
||||
this.mesh.setMatrixAt(idx, matrix);
|
||||
this.mesh.instanceMatrix.needsUpdate = true;
|
||||
this.mesh.count = this.size;
|
||||
return idx;
|
||||
}
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
remove(idx: number) {
|
||||
// 매 zero-scale matrix 로 hide → free list 등록
|
||||
const zero = new THREE.Matrix4().scale(new THREE.Vector3(0, 0, 0));
|
||||
this.mesh.setMatrixAt(idx, zero);
|
||||
this.mesh.instanceMatrix.needsUpdate = true;
|
||||
this.freeList.push(idx);
|
||||
}
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
private grow() {
|
||||
const newCap = Math.min(this.capacity * 2, this.maxCapacity);
|
||||
if (newCap <= this.capacity) throw new Error('Max capacity hit');
|
||||
const newMesh = this.makeMesh(newCap);
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
// 매 기존 matrix 복사
|
||||
const m = new THREE.Matrix4();
|
||||
for (let i = 0; i < this.size; i++) {
|
||||
this.mesh.getMatrixAt(i, m);
|
||||
newMesh.setMatrixAt(i, m);
|
||||
}
|
||||
// 매 color 도 있으면 copy
|
||||
if (this.mesh.instanceColor) {
|
||||
const oldColor = this.mesh.instanceColor.array as Float32Array;
|
||||
const newColor = new Float32Array(newCap * 3);
|
||||
newColor.set(oldColor);
|
||||
newMesh.instanceColor = new THREE.InstancedBufferAttribute(newColor, 3);
|
||||
}
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
// 매 swap
|
||||
const parent = this.mesh.parent;
|
||||
if (parent) {
|
||||
parent.remove(this.mesh);
|
||||
parent.add(newMesh);
|
||||
}
|
||||
this.mesh.dispose(); // 매 매 critical: GPU buffer free
|
||||
this.mesh = newMesh;
|
||||
this.capacity = newCap;
|
||||
console.log(`[DynamicInstancedMesh] grew → ${newCap}`);
|
||||
}
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
get object(): THREE.InstancedMesh { return this.mesh; }
|
||||
get instanceCount(): number { return this.size - this.freeList.length; }
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### 2. Chunked strategy (매 large N 친화적)
|
||||
```typescript
|
||||
class ChunkedInstancedMesh {
|
||||
private chunks: THREE.InstancedMesh[] = [];
|
||||
private group = new THREE.Group();
|
||||
private CHUNK_SIZE = 4096;
|
||||
private currentChunkSize = 0;
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
constructor(private geo: THREE.BufferGeometry, private mat: THREE.Material) {
|
||||
this.addChunk();
|
||||
}
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
private addChunk() {
|
||||
const m = new THREE.InstancedMesh(this.geo, this.mat, this.CHUNK_SIZE);
|
||||
m.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
|
||||
m.count = 0;
|
||||
this.chunks.push(m);
|
||||
this.group.add(m);
|
||||
this.currentChunkSize = 0;
|
||||
}
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
add(matrix: THREE.Matrix4): { chunk: number; idx: number } {
|
||||
if (this.currentChunkSize >= this.CHUNK_SIZE) this.addChunk();
|
||||
const chunkIdx = this.chunks.length - 1;
|
||||
const chunk = this.chunks[chunkIdx];
|
||||
const idx = this.currentChunkSize++;
|
||||
chunk.setMatrixAt(idx, matrix);
|
||||
chunk.count = idx + 1;
|
||||
chunk.instanceMatrix.needsUpdate = true;
|
||||
return { chunk: chunkIdx, idx };
|
||||
}
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
get object(): THREE.Group { return this.group; }
|
||||
}
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### 3. Partial buffer update (updateRange)
|
||||
```typescript
|
||||
// 매 매 frame 일부만 변경 시 매 전체 upload 회피
|
||||
function updateInstanceRange(
|
||||
mesh: THREE.InstancedMesh, startIdx: number, count: number
|
||||
) {
|
||||
mesh.instanceMatrix.updateRange.offset = startIdx * 16; // mat4 = 16 floats
|
||||
mesh.instanceMatrix.updateRange.count = count * 16;
|
||||
mesh.instanceMatrix.needsUpdate = true;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. WebGPU StorageBuffer 동적 grow
|
||||
```typescript
|
||||
import { storage, instanceIndex } from 'three/tsl';
|
||||
|
||||
class GPUDynamicInstances {
|
||||
private buffer: THREE.StorageBufferAttribute;
|
||||
private capacity: number;
|
||||
|
||||
constructor(initial = 1024) {
|
||||
this.capacity = initial;
|
||||
this.buffer = new THREE.StorageBufferAttribute(initial, 16);
|
||||
}
|
||||
|
||||
grow(needed: number) {
|
||||
const newCap = Math.max(this.capacity * 2, needed);
|
||||
const newBuf = new THREE.StorageBufferAttribute(newCap, 16);
|
||||
// 매 GPU-side copy: compute pass 로 old → new
|
||||
// 매 또는 CPU readback 후 재upload (매 비싸지만 단순)
|
||||
newBuf.array.set(this.buffer.array);
|
||||
this.buffer = newBuf;
|
||||
this.capacity = newCap;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Defragment (free list 가 너무 커지면)
|
||||
```typescript
|
||||
defragment(dim: DynamicInstancedMesh) {
|
||||
// 매 freeList sort 후 살아있는 instance 를 앞으로 compact
|
||||
// 매 user-facing index 가 바뀌므로 index map 도 업데이트해야 함
|
||||
// ... (구현은 use case 별 — id↔index 매핑 유지가 매 critical)
|
||||
}
|
||||
```
|
||||
|
||||
### 6. dispose 와 GPU memory 관리
|
||||
```typescript
|
||||
function disposeInstanced(mesh: THREE.InstancedMesh) {
|
||||
mesh.geometry.dispose();
|
||||
if (Array.isArray(mesh.material)) mesh.material.forEach(m => m.dispose());
|
||||
else mesh.material.dispose();
|
||||
mesh.dispose(); // 매 InstancedMesh 자체 buffer
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| 매 instance 수가 천천히 변동 | Geometric grow ×2 |
|
||||
| 매 instance 수 매 frame 격변 | Pre-alloc max + count 조절 |
|
||||
| 매 매우 큰 N + streaming | Chunked (CHUNK_SIZE 4-16k) |
|
||||
| 매 frequent delete | Free list + zero-scale hide |
|
||||
| 매 free list ≥ 30% | Defragment 한 번 |
|
||||
| 매 GPU-driven spawn | WebGPU StorageBuffer + compute |
|
||||
|
||||
**기본값**: 매 generic dynamic case → DynamicInstancedMesh (×2 grow + free list + zero-scale remove).
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[InstancedMesh 최적화]] · [[Three.js]]
|
||||
- 변형: [[BatchedMesh]] · [[GPU Particle Systems]]
|
||||
- 응용: [[Realtime Editors]] · [[Voxel Streaming]]
|
||||
- Adjacent: [[Free List]] · [[Geometric Resize]] · [[Buffer Pool]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: dynamic spawn/despawn 시스템 설계, free list vs chunked 의 trade-off 설명.
|
||||
**언제 X**: 매 specific WebGL driver memory bug.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **매 add 마다 new InstancedMesh**: 매 GPU alloc storm — 반드시 amortize.
|
||||
- **dispose() 빠뜨림**: 매 grow 후 옛 mesh GPU buffer 의 leak.
|
||||
- **Linear grow (+1, +1)**: O(N²) total copy. 매 geometric (×1.5 or ×2) 만 사용.
|
||||
- **remove 후 splice**: 매 모든 후속 idx shift → 비싸다. 매 zero-scale + free list.
|
||||
- **매 free list 만 쓰고 defrag 없음**: 매 hide 된 instance 도 vertex shader 실행 (zero-scale 은 깎임).
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Three.js r172 source `src/objects/InstancedMesh.js`).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — dynamic grow + free list + chunked |
|
||||
|
||||
Reference in New Issue
Block a user