[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,96 +2,175 @@
|
||||
id: wiki-2026-0508-webgl-api
|
||||
title: WebGL API
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-32752F]
|
||||
aliases: [WebGL, WebGL API, WebGL 1.0, WebGL 2.0]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
verification_status: applied
|
||||
tags: [webgl, graphics, gpu, gles]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - [[WebGL|WebGL]] API"
|
||||
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: JavaScript/GLSL
|
||||
framework: Web Platform
|
||||
---
|
||||
|
||||
# [[WebGL API|WebGL API]]
|
||||
# WebGL API
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> WebGL(Web Graphics Library)은 웹 브라우저의 HTML5 `<canvas>` 요소 내에서 하드웨어 가속을 통해 실시간 3D 및 2D 그래픽을 렌더링하기 위한 저수준(low-level) 크로스 플랫폼 애플리케이션 프로그래밍 인터페이스(API)입니다 [1-3]. [[OpenGL ES|OpenGL ES]] 2.0을 기반으로 구축되었으며, 자바스크립트([[JavaScript|JavaScript]]) 코드를 GPU 명령어로 변환하여 그래픽 처리 장치(GPU)에서 직접 실행되도록 설계되었습니다 [2, 4]. 2011년에 도입된 이후 웹 기반 3D 그래픽의 핵심 기반으로 사용되어 왔으나, 단일 스레드 실행 및 전역 상태 머신 모델과 같은 아키텍처의 한계로 인해 CPU 병목 현상이 발생하는 등 최신 하드웨어 성능을 온전히 끌어내기에는 제약이 존재합니다 [4-7].
|
||||
## 매 한 줄
|
||||
> **"매 OpenGL ES 의 web — canvas 의 GPU draw"**. WebGL 매 OpenGL ES 2.0 (WebGL1) / ES 3.0 (WebGL2) binding 의 browser. 2026 매 WebGPU rising 매 WebGL 매 still ubiquitous — fallback / wide compatibility 의 사용.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **작동 방식 및 렌더링 파이프라인:**
|
||||
WebGL은 프로그래머 친화적이라기보다는 빠른 하드웨어 렌더링을 위해 최적화된 저수준 API로, 하드웨어 회로의 스위치를 직접 조작하는 것과 같은 역할을 수행합니다 [3]. 렌더링을 위해서는 HTML 캔버스 요소에서 WebGL 컨텍스트(`gl`)를 가져오고, 정점 셰이더([[Vertex Shader|Vertex Shader]])와 단편 셰이더(fragment shader)를 컴파일하여 렌더링 프로그램으로 링크해야 합니다 [8]. 이후 GPU 메모리에 버퍼 객체를 생성하여 모델 데이터를 복사하고, 자바스크립트 코드에서 `drawArrays()` 등과 같은 명령을 호출하여 화면에 그래픽을 그립니다 [8-10].
|
||||
## 매 핵심
|
||||
|
||||
* **성능 최적화 및 브라우저 오버헤드:**
|
||||
WebGL은 브라우저 환경에서 실행되므로 보안을 위한 유효성 검사와 자바스크립트 호출을 변환하는 마샬링(marshalling) 과정에서 네이티브 환경 대비 오버헤드가 발생합니다 [11]. 컨텍스트 스위칭과 CPU-자바스크립트 프로그램 및 GPU 간의 데이터 통신은 렌더링 속도를 저하시키는 주된 원인입니다 [12, 13]. 따라서 고성능을 얻으려면 `getError()`, `get[[Parameter|Parameter]]()` 같이 비용이 큰 호출을 피하고, 배치(Batching)나 인스턴싱(Instancing) 기술을 활용해 드로우 콜([[Draw Call|Draw Call]]) 횟수를 최소화해야 합니다 [10, 14]. 더불어 예측할 수 없는 가비지 컬렉션([[Garbage Collection|Garbage Collection]])으로 인한 렌더링 끊김을 막기 위해 가비지를 생성하지 않는 엄격한 자바스크립트 작성 방식이 요구됩니다 [15, 16].
|
||||
### 매 pipeline
|
||||
- **Vertex shader**: per-vertex transform — clip space.
|
||||
- **Rasterizer**: triangles → fragments.
|
||||
- **Fragment shader**: per-pixel color.
|
||||
- **Framebuffer**: render target — default canvas / FBO offscreen.
|
||||
|
||||
* **아키텍처의 구조적 한계:**
|
||||
WebGL의 핵심적인 문제는 기반이 되는 아키텍처가 2011년 GPU 설계(OpenGL ES 2.0)에 머물러 있어 최신 그래픽 하드웨어의 기능을 충분히 활용할 수 없다는 점입니다 [4, 17]. 첫째, 단일 스레드 실행 모델로 인해 모든 드로우 콜과 상태 변경이 순차적으로 처리되어, GPU가 작업을 기다리는 동안 CPU에 과부하(병목 현상)가 발생합니다 [5, 7]. 둘째, 전역 상태 머신(global [[State|State]] machine)에 의존하므로 드로우 콜마다 매개변수를 개별적으로 설정해야 하며, 이 과정에서 CPU 측의 반복적인 상태 유효성 검사가 수반됩니다 [6, 18]. 셋째, 컴퓨트 셰이더(Compute Shader)를 지원하지 않아 입자 시스템이나 물리 시뮬레이션 같은 대규모 병렬 연산 작업조차 렌더링 오버헤드로 병목을 겪고 있는 CPU에서 수행해야 합니다 [19]. 이러한 한계들로 인해 오늘날 웹 산업에서는 멀티 스레드 명령 생성 및 컴퓨트 셰이더를 지원하는 차세대 API인 [[WebGPU|WebGPU]]로의 전환이 활발히 진행 중입니다 [20-23].
|
||||
### 매 핵심 objects
|
||||
- **Buffer** (`ARRAY_BUFFER`, `ELEMENT_ARRAY_BUFFER`): vertex / index data.
|
||||
- **Texture** (2D / cube / 3D-WebGL2 / array-WebGL2).
|
||||
- **Program**: vertex + fragment shader linked.
|
||||
- **VAO** (WebGL2): vertex attribute state.
|
||||
- **UBO** (WebGL2): uniform block — efficient bulk uniform.
|
||||
- **Framebuffer / Renderbuffer**: offscreen render targets.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Graphics & Performance 분야의 자동 자산화 수행.
|
||||
### 매 응용
|
||||
1. **3D libraries**: Three.js / Babylon.js / PlayCanvas.
|
||||
2. **2D accelerated**: PixiJS / Konva.
|
||||
3. **Data viz**: deck.gl / Mapbox GL / regl.
|
||||
4. **Games / interactive**: itch.io HTML5 / Unity WebGL build.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** OpenGL ES 2.0, [[GPU|GPU]], HTML5 Canvas, WebGPU, [[JavaScript|JavaScript]]
|
||||
- **Projects/Contexts:** Three.js, [[WebGLRenderingContext|WebGLRenderingContext]]
|
||||
- **Contradictions/Notes:** 소스에 따르면 WebGL은 단일 스레드 실행과 컴퓨트 셰이더 미지원 등의 구조적 단점 때문에 성능에 민감하고 대규모 연산이 필요한 최신 3D 경험에서는 한계가 명확하여 WebGPU로 대체되고 있습니다 [7, 19, 23]. 하지만 보편적이고 폭넓은 브라우저 호환성이 필요한 프로덕션 환경(모든 기기에서 동작해야 하는 경우)에서는 WebGPU의 지원이 아직 완벽하지 않기 때문에 여전히 WebGL이 가장 안전하고 적절한 선택(또는 폴백)으로 간주됩니다 [24-26].
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-19*
|
||||
### 매 minimal triangle
|
||||
```js
|
||||
const canvas = document.querySelector('canvas');
|
||||
const gl = canvas.getContext('webgl2');
|
||||
|
||||
---
|
||||
const vs = `#version 300 es
|
||||
in vec2 a_pos;
|
||||
void main() { gl_Position = vec4(a_pos, 0.0, 1.0); }`;
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
const fs = `#version 300 es
|
||||
precision highp float;
|
||||
out vec4 fragColor;
|
||||
void main() { fragColor = vec4(1.0, 0.5, 0.2, 1.0); }`;
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
function compile(type, src) {
|
||||
const s = gl.createShader(type);
|
||||
gl.shaderSource(s, src); gl.compileShader(s);
|
||||
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) throw gl.getShaderInfoLog(s);
|
||||
return s;
|
||||
}
|
||||
const prog = gl.createProgram();
|
||||
gl.attachShader(prog, compile(gl.VERTEX_SHADER, vs));
|
||||
gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
|
||||
gl.linkProgram(prog);
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
const vao = gl.createVertexArray();
|
||||
gl.bindVertexArray(vao);
|
||||
const vbo = gl.createBuffer();
|
||||
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
|
||||
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([0, 0.5, -0.5, -0.5, 0.5, -0.5]), gl.STATIC_DRAW);
|
||||
const loc = gl.getAttribLocation(prog, 'a_pos');
|
||||
gl.enableVertexAttribArray(loc);
|
||||
gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
|
||||
|
||||
## 🧪 검증 상태 (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
|
||||
gl.useProgram(prog);
|
||||
gl.drawArrays(gl.TRIANGLES, 0, 3);
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Texture upload
|
||||
```js
|
||||
const tex = gl.createTexture();
|
||||
gl.bindTexture(gl.TEXTURE_2D, tex);
|
||||
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, w, h, 0, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
|
||||
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
|
||||
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
|
||||
gl.generateMipmap(gl.TEXTURE_2D);
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Instanced rendering (WebGL2)
|
||||
```js
|
||||
gl.vertexAttribDivisor(instanceLoc, 1); // advance per instance
|
||||
gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, 10000); // 10k instances 1 draw call
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Uniform Buffer Object (WebGL2)
|
||||
```js
|
||||
const ubo = gl.createBuffer();
|
||||
gl.bindBuffer(gl.UNIFORM_BUFFER, ubo);
|
||||
gl.bufferData(gl.UNIFORM_BUFFER, mat4Buffer, gl.DYNAMIC_DRAW);
|
||||
const idx = gl.getUniformBlockIndex(prog, 'Camera');
|
||||
gl.uniformBlockBinding(prog, idx, 0);
|
||||
gl.bindBufferBase(gl.UNIFORM_BUFFER, 0, ubo);
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### Framebuffer (offscreen / render-to-texture)
|
||||
```js
|
||||
const fbo = gl.createFramebuffer();
|
||||
gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
|
||||
const tex = gl.createTexture();
|
||||
gl.bindTexture(gl.TEXTURE_2D, tex);
|
||||
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, w, h, 0, gl.RGBA, gl.HALF_FLOAT, null);
|
||||
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
|
||||
// 매 render → tex, then post-process
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Transform Feedback (WebGL2 GPU compute-ish)
|
||||
```js
|
||||
gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 0, outBuf);
|
||||
gl.beginTransformFeedback(gl.POINTS);
|
||||
gl.drawArrays(gl.POINTS, 0, particleCount);
|
||||
gl.endTransformFeedback();
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Context loss handling
|
||||
```js
|
||||
canvas.addEventListener('webglcontextlost', (e) => { e.preventDefault(); });
|
||||
canvas.addEventListener('webglcontextrestored', () => { rebuildResources(); });
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | WebGL vs WebGPU |
|
||||
|---|---|
|
||||
| 2026 wide compatibility | WebGL2 — Safari iOS / older Android |
|
||||
| Compute shader | WebGPU |
|
||||
| Multi-pass complex | WebGPU 매 cleaner state model |
|
||||
| Existing Three.js / Babylon | WebGL2 fallback + WebGPU primary |
|
||||
| Simple 2D accel | WebGL2 / 2D canvas |
|
||||
| AAA-grade graphics | WebGPU |
|
||||
|
||||
**기본값**: Three.js with WebGPURenderer + WebGL2 fallback.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[GPU Graphics APIs]] · [[OpenGL ES]]
|
||||
- 변형: [[WebGL2 (WebGL 20)]] · [[WebGPU]]
|
||||
- 응용: [[Threejs]] · [[Babylon.js]] · [[PixiJS]] · [[Mapbox GL]]
|
||||
- Adjacent: [[GLSL]] · [[Canvas API]] · [[OffscreenCanvas]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: cross-browser 3D / 2D GPU accel / data viz / WebGPU 의 fallback.
|
||||
**언제 X**: heavy compute (no compute shader in WebGL) / cutting-edge graphics — WebGPU 사용.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **State thrash**: bind/unbind every draw — batch by program/texture.
|
||||
- **Sync readback**: `readPixels` 매 GPU stall — use PBO async (WebGL2).
|
||||
- **No VAO**: re-binding attributes every draw — VAO 매 cache.
|
||||
- **Uniform per draw call**: UBO 의 bulk update / instancing.
|
||||
- **Premultiply confusion**: alpha blending 의 incorrect — `UNPACK_PREMULTIPLY_ALPHA_WEBGL`.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Khronos WebGL 1.0/2.0 spec / MDN WebGL API).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — pipeline, VAO, UBO, FBO, instancing, transform feedback |
|
||||
|
||||
Reference in New Issue
Block a user