2nd/10_Wiki/Topics/Frontend/Instancing.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-instancing	Instancing	10_Wiki/Topics	verified	self	GPU instancing instanced rendering drawInstanced	none	A	0.95	applied	graphics gpu webgl webgpu threejs performance		2026-05-10	pending	language framework GLSL/WGSL Three.js/WebGPU

Instancing

매 한 줄

"매 동일 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 지원.

매 핵심

매 왜 빠른가

• Draw call overhead 제거: 매 CPU→GPU command 1번 만.
• Vertex buffer reuse: 매 base mesh 1개, instance attr 만 streaming.
• GPU parallelism: 매 instance 가 각 SM/CU 에 분산.

매 per-instance attribute 종류

• Transform matrix (mat4) — 매 가장 흔함.
• Color / tint (vec4)
• Texture index / atlas UV offset
• Animation frame (skinned crowd)

매 응용

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.

💻 패턴

Three.js InstancedMesh

import * as THREE from "three";

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);

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);

Per-instance color

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),
);

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 );");
};

Update single instance (game troop move)

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);

WebGPU instanced draw

// 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);
}`;

// JS — drawIndexedIndirect 또는 draw with instanceCount
pass.draw(vertexCount, instanceCount, 0, 0);

GPU frustum culling (compute → instanced draw)

@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)

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 패턴