chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문

2026-06-12 16:37:41 +09:00
parent a97fc7be07
commit 89fb05a28a
781 changed files with 138546 additions and 47 deletions
@@ -0,0 +1,169 @@
+---
+id: wiki-2026-0508-threejs-webgpu-파티클-예제
+title: Threejs WebGPU 파티클 예제
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Three.js WebGPU Particles, TSL Particles]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [threejs, webgpu, particles, tsl, gpgpu]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: javascript
+  framework: three.js
+---
+
+# Threejs WebGPU 파티클 예제
+
+## 매 한 줄
+> **"매 GPU compute shader 의 millions-of-particles 의 60fps"**. Three.js r170+ 의 WebGPURenderer 의 TSL (Three Shader Language) 의 compute node 의 particle position/velocity 의 GPU buffer 의 simulate. 매 2026 standard: WebGPU 의 baseline browser support (Chrome/Edge/Safari 17.4+/Firefox 127+) 의 production 의 reach.
+
+## 매 핵심
+
+### 매 architecture
+- **Storage buffer**: 매 particle position/velocity 의 GPU memory 의 persist — 매 CPU readback 의 X.
+- **Compute pass**: 매 frame 의 start 의 simulation step 의 dispatch.
+- **Render pass**: 매 same buffer 의 vertex attribute 의 read — instanced point / mesh.
+- **TSL**: 매 JS-authored shader graph 의 WGSL 의 compile — 매 backend portability (WebGPU + WebGL fallback).
+
+### 매 핵심 node
+- `storage()`: 매 mutable GPU buffer.
+- `Fn()`: 매 reusable shader function.
+- `instanceIndex`: 매 compute thread id.
+- `attribute()`: 매 vertex attribute read.
+- `uniform()`: 매 per-frame CPU-set value.
+
+### 매 응용
+1. Galaxy / nebula simulation 의 web demo.
+2. GPGPU fluid (SPH, FLIP) 의 art piece.
+3. Real-time crowd / flock (boid) 의 100k+ agent.
+4. Data viz 의 millions-of-points scatter.
+
+## 💻 패턴
+
+### Setup WebGPURenderer
+```javascript
+import * as THREE from 'three/webgpu';
+import { Fn, storage, instanceIndex, uniform, vec3, sin, cos, time } from 'three/tsl';
+
+const renderer = new THREE.WebGPURenderer({ antialias: true });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(window.innerWidth, window.innerHeight);
+await renderer.init();
+document.body.appendChild(renderer.domElement);
+```
+
+### Allocate particle buffers
+```javascript
+const COUNT = 500_000;
+const positionBuffer = storage(new THREE.StorageInstancedBufferAttribute(COUNT, 3), 'vec3', COUNT);
+const velocityBuffer = storage(new THREE.StorageInstancedBufferAttribute(COUNT, 3), 'vec3', COUNT);
+```
+
+### Init compute (one-time)
+```javascript
+const initCompute = Fn(() => {
+  const i = instanceIndex;
+  const angle = i.toFloat().mul(0.001);
+  positionBuffer.element(i).assign(vec3(cos(angle).mul(50), 0, sin(angle).mul(50)));
+  velocityBuffer.element(i).assign(vec3(0));
+})().compute(COUNT);
+
+await renderer.computeAsync(initCompute);
+```
+
+### Per-frame simulation
+```javascript
+const dt = uniform(0.016);
+const simCompute = Fn(() => {
+  const i = instanceIndex;
+  const pos = positionBuffer.element(i);
+  const vel = velocityBuffer.element(i);
+  const gravity = pos.normalize().negate().mul(9.8);
+  vel.addAssign(gravity.mul(dt));
+  pos.addAssign(vel.mul(dt));
+})().compute(COUNT);
+```
+
+### Render as instanced points
+```javascript
+const material = new THREE.SpriteNodeMaterial();
+material.positionNode = positionBuffer.toAttribute();
+material.colorNode = velocityBuffer.toAttribute().length().mul(0.1);
+
+const mesh = new THREE.InstancedMesh(new THREE.PlaneGeometry(0.05), material, COUNT);
+scene.add(mesh);
+```
+
+### Animation loop
+```javascript
+renderer.setAnimationLoop(async () => {
+  dt.value = clock.getDelta();
+  await renderer.computeAsync(simCompute);
+  await renderer.renderAsync(scene, camera);
+});
+```
+
+### Curl noise flow field
+```javascript
+import { mx_noise_vec3 } from 'three/tsl';
+
+const flowCompute = Fn(() => {
+  const i = instanceIndex;
+  const pos = positionBuffer.element(i);
+  const noise = mx_noise_vec3(pos.mul(0.1).add(time.mul(0.5)));
+  velocityBuffer.element(i).assign(noise.mul(2));
+  pos.addAssign(velocityBuffer.element(i).mul(dt));
+})().compute(COUNT);
+```
+
+### WebGL fallback
+```javascript
+const renderer = WebGPU.isAvailable()
+  ? new THREE.WebGPURenderer()
+  : new THREE.WebGLRenderer();
+// 매 TSL 의 same code 의 WebGL backend 의 transpile (compute X 의 limit 의 case 의 GPGPUComputationRenderer 의 fallback)
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| <10k particle, simple motion | CPU 의 BufferGeometry update |
+| 10k–100k, WebGL2 only | GPGPUComputationRenderer (ping-pong texture) |
+| 100k–10M, modern browser | WebGPURenderer + TSL compute |
+| Physics-accurate fluid | WebGPU compute + custom WGSL |
+| Cross-browser 의 require, IE/legacy | Canvas2D 또는 WebGL1 fallback |
+
+**기본값**: 매 2026 의 new project 의 WebGPURenderer + TSL — 매 WebGL fallback 의 automatic.
+
+## 🔗 Graph
+- 부모: [[Three.js]] · [[WebGPU]]
+- 변형: [[GPGPU]] · [[TSL Three Shader Language]]
+- 응용: [[Particle System]]
+- Adjacent: [[Compute Shader]] · [[Instanced Rendering]]
+
+## 🤖 LLM 활용
+**언제**: 매 100k+ particle 의 60fps 의 require, 매 modern browser 의 target.
+**언제 X**: 매 static scene, low count, 또는 mobile-Safari-pre-17.4 의 fallback 의 critical.
+
+## ❌ 안티패턴
+- **CPU position update**: 매 frame 의 millions-of-vertex 의 GPU upload 의 PCIe bottleneck.
+- **Compute pass 의 매 frame 의 buffer recreate**: 매 GC pressure 의 stutter — 매 reuse.
+- **`renderer.compute()` sync wait**: 매 main thread 의 block — 매 `computeAsync` 의 use.
+- **Float32 over-precision**: 매 WebGPU 의 f16 storage 의 bandwidth halve 의 opportunity 의 miss.
+- **TSL 의 raw WGSL 의 mix 의 unnecessary**: 매 portability 의 break.
+
+## 🧪 검증 / 중복
+- Verified (Three.js r170+ docs, threejs.org/examples webgpu_compute_particles).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — TSL compute, instanced render, WebGL fallback |