[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,96 +2,177 @@
|
||||
id: wiki-2026-0508-instancing
|
||||
title: Instancing
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-2752BF]
|
||||
aliases: [GPU instancing, instanced rendering, drawInstanced]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
confidence_score: 0.95
|
||||
verification_status: applied
|
||||
tags: [graphics, gpu, webgl, webgpu, threejs, performance]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - Instancing"
|
||||
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: GLSL/WGSL
|
||||
framework: Three.js/WebGPU
|
||||
---
|
||||
|
||||
# [[Instancing|Instancing]]
|
||||
# Instancing
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 인스턴싱(Instancing)은 웹 그래픽스 렌더링 및 UI 디자인 소프트웨어에서 성능을 최적화하기 위해 동일한 객체를 효율적으로 반복 처리하는 기법입니다. [[WebGL|WebGL]]이나 WebGPU 환경에서는 단일 드로우 콜(Draw Call)로 동일한 메쉬나 형태를 대량으로 그려내어 CPU 및 GPU 오버헤드를 줄이는 핵심 기술로 사용됩니다 [1, 2]. 반면 [[Figma|Figma]]와 같은 디자인 도구에서는 원본 컴포넌트의 복제본을 의미하며, 인스턴스 내부의 구조적 최적화 여부가 소프트웨어 성능에 직접적인 영향을 미칩니다 [3, 4].
|
||||
## 매 한 줄
|
||||
> **"매 동일 mesh 를 N 번 그릴 때 single draw call 로 묶는 GPU 기법 — 매 per-instance attribute (transform, color) 만 다르게"**. 매 thousands → millions of objects 가 60fps 로 가능. 매 grass, particles, crowd, foliage 의 핵심. WebGL 2 / WebGPU / Vulkan / Metal 모두 native 지원.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **웹 그래픽스 렌더링 최적화 (WebGL & WebGPU):**
|
||||
- **드로우 콜(Draw Call) 감소:** WebGL 애플리케이션에서 성능을 극대화하는 가장 중요한 비결은 드로우 콜 횟수를 최소화하는 것입니다 [5]. 동일한 메쉬를 여러 번 호출하여 그리는 대신 인스턴싱 기법을 사용하면 대량의 메쉬를 단일 함수 호출로 렌더링할 수 있어 성능 오버헤드를 크게 줄일 수 있습니다 [1].
|
||||
- **WebGPU를 활용한 가우시안 렌더링 (WebSplatter):** WebGPU 기반의 [[3D_Gaussian_Splatting|3D Gaussian Splatting]] 프레임워크인 WebSplatter는 래스터화 단계에서 인스턴스화된 드로우 콜(instanced draw call)을 통해 각 가우시안을 단일 쿼드(두 개의 삼각형)로 제출하여 렌더링합니다 [2]. 렌더 패스(Render pass) 내부에서 `passEncoder.draw(vertexCount, instanceCount)` 명령을 호출하여, 지정된 정점 및 인스턴스 수만큼 버텍스 셰이더와 프래그먼트 셰이더의 실행을 트리거합니다 [6].
|
||||
- **관련 WebGL 확장 기능:** WebGL 생태계에서는 이와 같은 인스턴싱을 지원하기 위해 `[[ANGLE|ANGLE]]_instanced_arrays`라는 확장(Extension) 기능을 제공합니다 [7].
|
||||
## 매 핵심
|
||||
|
||||
- **디자인 시스템 및 UI 도구(Figma)에서의 인스턴스:**
|
||||
- **성능 저하의 원인:** 대규모 디자인 파일에서 복잡한 중첩 구조를 가진 컴포넌트를 사용할 때, 인스턴스 내부에 불필요하게 포함된 숨겨진 레이어(hidden layers)는 파일의 렌더링과 업데이트 속도를 크게 늦출 수 있습니다 [3, 8, 9].
|
||||
- **인스턴스 최적화 방안:** 구조 컴포넌트의 사용을 줄이고, 대신 별도의 변형(variants) 개수를 늘려 인스턴스 내의 숨겨진 레이어들을 제거하면 프로토타입 동작이 눈에 띄게 부드러워지며 성능이 크게 향상됩니다 [4, 10].
|
||||
### 매 왜 빠른가
|
||||
- **Draw call overhead 제거**: 매 CPU→GPU command 1번 만.
|
||||
- **Vertex buffer reuse**: 매 base mesh 1개, instance attr 만 streaming.
|
||||
- **GPU parallelism**: 매 instance 가 각 SM/CU 에 분산.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Graphics & Performance 분야의 자동 자산화 수행.
|
||||
### 매 per-instance attribute 종류
|
||||
- **Transform matrix** (mat4) — 매 가장 흔함.
|
||||
- **Color / tint** (vec4)
|
||||
- **Texture index** / atlas UV offset
|
||||
- **Animation frame** (skinned crowd)
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** Draw Calls, [[WebGL|WebGL]], [[WebGPU|WebGPU]], Gaussian Splatting
|
||||
- **Projects/Contexts:** [[Wonderland Engine|Wonderland Engine]], WebSplatter, [[Figma|Figma]]
|
||||
- **Contradictions/Notes:** 주어진 소스 데이터 내에서 '인스턴스(Instancing)'라는 용어는 3D 그래픽스 하드웨어 가속을 위한 렌더링 효율화 기법(WebGL/WebGPU)과, 디자인 도구 내에서 원본 객체를 복제해 사용하는 개체 단위(Figma)라는 두 가지 상이한 맥락에서 설명되고 있습니다.
|
||||
### 매 응용
|
||||
1. Three.js `InstancedMesh` — 매 50k tree, 100k particle.
|
||||
2. Unreal HISM / Niagara, Unity GPU Instancer.
|
||||
3. WebGPU compute-driven instancing — 매 frustum culling on GPU.
|
||||
4. Game KvK map — 매 thousands of city/troop sprite.
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-19*
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
### Three.js InstancedMesh
|
||||
```javascript
|
||||
import * as THREE from "three";
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
const geometry = new THREE.BoxGeometry(1, 1, 1);
|
||||
const material = new THREE.MeshStandardMaterial({ color: 0x44aa88 });
|
||||
const count = 10000;
|
||||
const mesh = new THREE.InstancedMesh(geometry, material, count);
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
const m = new THREE.Matrix4();
|
||||
for (let i = 0; i < count; i++) {
|
||||
m.setPosition(
|
||||
(Math.random() - 0.5) * 100,
|
||||
0,
|
||||
(Math.random() - 0.5) * 100,
|
||||
);
|
||||
mesh.setMatrixAt(i, m);
|
||||
}
|
||||
mesh.instanceMatrix.needsUpdate = true;
|
||||
scene.add(mesh);
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Per-instance color
|
||||
```javascript
|
||||
const colors = new Float32Array(count * 3);
|
||||
for (let i = 0; i < count; i++) {
|
||||
colors[i * 3] = Math.random();
|
||||
colors[i * 3 + 1] = Math.random();
|
||||
colors[i * 3 + 2] = Math.random();
|
||||
}
|
||||
geometry.setAttribute(
|
||||
"instanceColor",
|
||||
new THREE.InstancedBufferAttribute(colors, 3),
|
||||
);
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
material.onBeforeCompile = (shader) => {
|
||||
shader.vertexShader = shader.vertexShader
|
||||
.replace("#include <common>", "#include <common>\nattribute vec3 instanceColor; varying vec3 vColor;")
|
||||
.replace("#include <begin_vertex>", "#include <begin_vertex>\nvColor = instanceColor;");
|
||||
shader.fragmentShader = shader.fragmentShader
|
||||
.replace("#include <common>", "#include <common>\nvarying vec3 vColor;")
|
||||
.replace("vec4 diffuseColor = vec4( diffuse, opacity );", "vec4 diffuseColor = vec4( diffuse * vColor, opacity );");
|
||||
};
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Update single instance (game troop move)
|
||||
```javascript
|
||||
function updateTroop(idx: number, x: number, z: number) {
|
||||
m.setPosition(x, 0, z);
|
||||
mesh.setMatrixAt(idx, m);
|
||||
mesh.instanceMatrix.needsUpdate = true; // 매 dirty flag
|
||||
}
|
||||
// 매 N 변경 시 partial range update (Three r150+)
|
||||
mesh.instanceMatrix.addUpdateRange(start * 16, count * 16);
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### WebGPU instanced draw
|
||||
```javascript
|
||||
// WGSL vertex shader
|
||||
const wgsl = `
|
||||
struct Instance { @location(3) m0: vec4f, @location(4) m1: vec4f, @location(5) m2: vec4f, @location(6) m3: vec4f };
|
||||
@vertex fn vs(@location(0) pos: vec3f, instance: Instance) -> @builtin(position) vec4f {
|
||||
let model = mat4x4f(instance.m0, instance.m1, instance.m2, instance.m3);
|
||||
return uniforms.viewProj * model * vec4f(pos, 1.0);
|
||||
}`;
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
// JS — drawIndexedIndirect 또는 draw with instanceCount
|
||||
pass.draw(vertexCount, instanceCount, 0, 0);
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### GPU frustum culling (compute → instanced draw)
|
||||
```wgsl
|
||||
@compute @workgroup_size(64)
|
||||
fn cull(@builtin(global_invocation_id) gid: vec3u) {
|
||||
let idx = gid.x;
|
||||
if (idx >= arrayLength(&instances)) { return; }
|
||||
let m = instances[idx];
|
||||
if (inFrustum(m.bbox)) {
|
||||
let out = atomicAdd(&visibleCount, 1u);
|
||||
visibleInstances[out] = m;
|
||||
}
|
||||
}
|
||||
// 매 visibleInstances + visibleCount → drawIndirect
|
||||
```
|
||||
|
||||
### Foliage with wind (vertex shader animation)
|
||||
```glsl
|
||||
attribute mat4 instanceMatrix;
|
||||
uniform float uTime;
|
||||
void main() {
|
||||
vec3 p = position;
|
||||
float wind = sin(uTime + instanceMatrix[3].x * 0.1) * 0.1 * p.y;
|
||||
p.x += wind;
|
||||
gl_Position = projectionMatrix * viewMatrix * instanceMatrix * vec4(p, 1.0);
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Same mesh, ≥100 copies | InstancedMesh |
|
||||
| Different meshes, similar | BatchedMesh (Three r155+) |
|
||||
| Dynamic count + culling | GPU compute culling + drawIndirect |
|
||||
| Skinned crowd | Texture-baked anim + instancing |
|
||||
| Just 10 copies | 매 그냥 N draw — 매 instancing overhead 작음 |
|
||||
|
||||
**기본값**: ≥100 copies of same mesh → InstancedMesh.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[GPU Rendering]] · [[Draw Call Optimization]]
|
||||
- 변형: [[BatchedMesh]] · [[Indirect Drawing]] · [[Mesh Shader]]
|
||||
- 응용: [[Three.js]] · [[WebGPU]] · [[Unity GPU Instancer]]
|
||||
- Adjacent: [[Frustum Culling]] · [[LOD]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: large-scale rendering 설계, particle / foliage / crowd 구현.
|
||||
**언제 X**: 매 single object, 매 매우 다른 mesh — 매 instancing overhead 정당화 X.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **needsUpdate = true on every frame**: 매 모든 instance 변경 안 했어도 전체 upload — 매 partial update range 사용.
|
||||
- **instancing for unique meshes**: 매 효과 X — 매 BatchedMesh 또는 multi-draw indirect.
|
||||
- **CPU-side culling per instance**: 매 GPU compute 가 더 빠름 (10k+).
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Three.js docs, WebGPU spec, Real-Time Rendering 4th ed.).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — Three.js + WebGPU instancing 패턴 |
|
||||
|
||||
Reference in New Issue
Block a user