[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,323 @@
+---
+id: game-shader-patterns
+title: Shader 패턴 — Vertex / Fragment / WGSL
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [game, shader, glsl, wgsl, vibe-coding]
+tech_stack: { language: "GLSL / WGSL", applicable_to: ["Game", "Frontend"] }
+applied_in: []
+aliases: [shader, GLSL, WGSL, vertex shader, fragment shader, post-processing]
+---
+
+# Shader Patterns
+
+> GPU 의 작은 program. **Vertex (위치 변형) + Fragment (색)**. WebGPU = WGSL, OpenGL/WebGL = GLSL. Effect / 사후 처리 강력.
+
+## 📖 핵심 개념
+- Vertex shader: 각 vertex 변형.
+- Fragment (pixel) shader: 각 pixel 색 결정.
+- Uniform: CPU → GPU 변수.
+- Attribute: vertex 별 data.
+
+## 💻 코드 패턴
+
+### 단순 fragment (GLSL)
+```glsl
+// fragment.glsl
+precision mediump float;
+varying vec2 vUv;
+uniform float uTime;
+
+void main() {
+  vec3 color = vec3(
+    sin(uTime + vUv.x * 6.28) * 0.5 + 0.5,
+    sin(uTime + vUv.y * 6.28 + 2.09) * 0.5 + 0.5,
+    sin(uTime + vUv.x * 6.28 + 4.18) * 0.5 + 0.5
+  );
+  gl_FragColor = vec4(color, 1.0);
+}
+```
+
+### Three.js + GLSL
+```ts
+const material = new THREE.ShaderMaterial({
+  vertexShader: `
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+  fragmentShader: `
+    varying vec2 vUv;
+    uniform float uTime;
+    void main() {
+      gl_FragColor = vec4(vUv, sin(uTime) * 0.5 + 0.5, 1.0);
+    }
+  `,
+  uniforms: { uTime: { value: 0 } },
+});
+
+// 매 frame
+material.uniforms.uTime.value = clock.getElapsedTime();
+```
+
+### WGSL (WebGPU)
+```wgsl
+struct VertexInput {
+  @location(0) position: vec3f,
+  @location(1) uv: vec2f,
+}
+
+struct VertexOutput {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+}
+
+struct Uniforms {
+  time: f32,
+}
+
+@group(0) @binding(0) var<uniform> u: Uniforms;
+
+@vertex
+fn vs(input: VertexInput) -> VertexOutput {
+  var out: VertexOutput;
+  out.position = vec4f(input.position, 1.0);
+  out.uv = input.uv;
+  return out;
+}
+
+@fragment
+fn fs(input: VertexOutput) -> @location(0) vec4f {
+  let color = vec3f(
+    sin(u.time + input.uv.x * 6.28) * 0.5 + 0.5,
+    sin(u.time + input.uv.y * 6.28) * 0.5 + 0.5,
+    1.0
+  );
+  return vec4f(color, 1.0);
+}
+```
+
+### 자주 쓰는 함수 (GLSL/WGSL)
+```glsl
+// Smoothstep — 부드러운 편향
+float t = smoothstep(0.4, 0.6, dist);
+
+// Mix — 보간
+vec3 c = mix(red, blue, t);
+
+// Distance
+float d = length(uv - vec2(0.5, 0.5));
+
+// Step
+float v = step(0.5, x);  // x < 0.5 ? 0 : 1
+
+// Noise (snoise / perlin)
+// 라이브러리 또는 직접 구현
+```
+
+### Pattern: 원
+```glsl
+void main() {
+  vec2 uv = vUv - 0.5;
+  float d = length(uv);
+  float circle = smoothstep(0.3, 0.29, d);
+  gl_FragColor = vec4(vec3(circle), 1.0);
+}
+```
+
+### Pattern: gradient
+```glsl
+gl_FragColor = vec4(mix(vec3(1, 0, 0), vec3(0, 0, 1), vUv.y), 1.0);
+```
+
+### Pattern: noise
+```glsl
+// Simple hash noise
+float hash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+
+float noise(vec2 p) {
+  vec2 i = floor(p), f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(hash(i), hash(i + vec2(1, 0)), u.x),
+    mix(hash(i + vec2(0, 1)), hash(i + vec2(1, 1)), u.x),
+    u.y
+  );
+}
+
+void main() {
+  float n = noise(vUv * 10.0 + uTime);
+  gl_FragColor = vec4(vec3(n), 1.0);
+}
+```
+
+### Post-processing (Three.js)
+```ts
+import { EffectComposer, RenderPass, ShaderPass } from 'three/examples/jsm/Addons.js';
+
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+
+const myPass = new ShaderPass({
+  uniforms: { tDiffuse: { value: null }, uTime: { value: 0 } },
+  vertexShader: ...,
+  fragmentShader: `
+    uniform sampler2D tDiffuse;
+    uniform float uTime;
+    varying vec2 vUv;
+    void main() {
+      vec4 color = texture2D(tDiffuse, vUv);
+      // pixelate
+      vec2 pixelated = floor(vUv * 100.0) / 100.0;
+      color = texture2D(tDiffuse, pixelated);
+      gl_FragColor = color;
+    }
+  `,
+});
+composer.addPass(myPass);
+```
+
+### Vertex displacement (wave)
+```glsl
+// vertex
+uniform float uTime;
+varying vec2 vUv;
+
+void main() {
+  vUv = uv;
+  vec3 pos = position;
+  pos.y += sin(pos.x * 5.0 + uTime) * 0.1;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
+}
+```
+
+### Texture
+```glsl
+uniform sampler2D uTexture;
+varying vec2 vUv;
+
+void main() {
+  vec4 color = texture2D(uTexture, vUv);
+  // tint
+  color.rgb *= vec3(1.0, 0.5, 0.8);
+  gl_FragColor = color;
+}
+```
+
+### React Three Fiber + custom material
+```tsx
+import { extend } from '@react-three/fiber';
+import { shaderMaterial } from '@react-three/drei';
+
+const MyMaterial = shaderMaterial(
+  { uTime: 0, uColor: new THREE.Color('hotpink') },
+  vertexShader,
+  fragmentShader
+);
+extend({ MyMaterial });
+
+function Mesh() {
+  const ref = useRef<any>();
+  useFrame((_, dt) => { ref.current.uTime += dt; });
+  
+  return (
+    <mesh>
+      <boxGeometry />
+      <myMaterial ref={ref} />
+    </mesh>
+  );
+}
+```
+
+### Compute shader (WebGPU only)
+```wgsl
+@group(0) @binding(0) var<storage, read> input: array<f32>;
+@group(0) @binding(1) var<storage, read_write> output: array<f32>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3u) {
+  let i = id.x;
+  output[i] = input[i] * 2.0;
+}
+```
+
+→ Particle simulation / image processing.
+
+### Performance
+```
+- Texture lookup 비싸 — minimize.
+- Branch (if) 가능한 한 적게 — uniform branch 는 OK, dynamic branch 비싼.
+- Precision: highp (vertex) / mediump (fragment) 보통 OK.
+- mipmaps 사용 (texture).
+- Dependent texture lookup 피하기.
+- Discard 비싸 — alpha test 알 됨.
+```
+
+### 디버그
+```
+Spector.js (browser extension): WebGL/WebGPU frame capture.
+Renderdoc: native graphics debugger.
+GLSL Lint (vscode): syntax 검사.
+
+Print debug:
+gl_FragColor = vec4(vec3(myValue), 1.0);
+// 색으로 값 시각화.
+```
+
+### Shadertoy / The Book of Shaders
+- shadertoy.com — 영감.
+- thebookofshaders.com — 학습.
+- 공유된 shader 가 사실상 라이브러리.
+
+### Common shader effects
+```
+- Glitch / chromatic aberration
+- Bloom
+- DOF (depth of field)
+- Outline
+- Toon / cel shading
+- Water / wave
+- Fire / smoke
+- Motion blur
+- Pixelation
+- Gaussian blur
+- Edge detection
+```
+
+## 🤔 의사결정 기준
+| 작업 | 도구 |
+|---|---|
+| 일반 web shader | Three.js + GLSL |
+| Modern + WebGPU | R3F + WGSL |
+| 2D effect | PixiJS filter |
+| Image processing | WebGPU compute |
+| Native game | Unity/Unreal shader graph |
+| Quick prototype | Shadertoy |
+
+## ❌ 안티패턴
+- **Branch heavy 모든 fragment**: 느림. lookup texture.
+- **Texture 매 frame upload**: cache.
+- **High precision 모든 곳**: mediump 충분.
+- **uniform 매 draw 변경**: dirty flag.
+- **Discard 큰 사용**: alpha test 또는 sort.
+- **Compile 매 frame**: cache.
+- **Shader 큰 size**: 중복 로직 — function 분리.
+
+## 🤖 LLM 활용 힌트
+- 공유 shader (Shadertoy) → 자체 변형.
+- WebGPU = WGSL (modern).
+- R3F + drei `shaderMaterial` 가 가장 단순.
+- Spector.js 가 디버그.
+
+## 🔗 관련 문서
+- [[Frontend_Three_R3F]]
+- [[Frontend_WebGPU_Patterns]]
+- [[Game_Loop_ECS]]