shader-fundamentals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shader Fundamentals

着色器基础知识

GLSL (OpenGL Shading Language) runs on the GPU. Vertex shaders transform geometry; fragment shaders color pixels.

GLSL（OpenGL Shading Language）运行在GPU上。Vertex shader负责变换几何体；Fragment shader负责为像素上色。

Quick Start

快速入门

glsl

// Vertex Shader
uniform mat4 projectionMatrix;
uniform mat4 modelViewMatrix;

attribute vec3 position;
attribute vec2 uv;

varying vec2 vUv;

void main() {
  vUv = uv;
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

// Fragment Shader
uniform float uTime;
varying vec2 vUv;

void main() {
  vec3 color = vec3(vUv, sin(uTime) * 0.5 + 0.5);
  gl_FragColor = vec4(color, 1.0);
}

glsl

// Vertex Shader
uniform mat4 projectionMatrix;
uniform mat4 modelViewMatrix;

attribute vec3 position;
attribute vec2 uv;

varying vec2 vUv;

void main() {
  vUv = uv;
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

// Fragment Shader
uniform float uTime;
varying vec2 vUv;

void main() {
  vec3 color = vec3(vUv, sin(uTime) * 0.5 + 0.5);
  gl_FragColor = vec4(color, 1.0);
}

Graphics Pipeline

图形渲染管线

Vertex Data → [Vertex Shader] → Primitives → Rasterization → [Fragment Shader] → Pixels
     ↑              ↑                                              ↑
 attributes    transforms                                    per-pixel color

Stage	Runs Per	Purpose
Vertex Shader	Vertex	Transform positions, pass data to fragment
Fragment Shader	Pixel	Calculate final color

Vertex Data → [Vertex Shader] → Primitives → Rasterization → [Fragment Shader] → Pixels
     ↑              ↑                                              ↑
 attributes    几何变换                                    逐像素上色

阶段	执行频率	用途
Vertex Shader	每个顶点	变换位置，向片元着色器传递数据
Fragment Shader	每个像素	计算最终像素颜色

Data Types

数据类型

Scalars

标量

glsl

bool b = true;
int i = 42;
float f = 3.14;

glsl

bool b = true;
int i = 42;
float f = 3.14;

Vectors

向量

glsl

vec2 v2 = vec2(1.0, 2.0);
vec3 v3 = vec3(1.0, 2.0, 3.0);
vec4 v4 = vec4(1.0, 2.0, 3.0, 4.0);

// Integer vectors
ivec2 iv2 = ivec2(1, 2);
ivec3 iv3 = ivec3(1, 2, 3);

// Boolean vectors
bvec2 bv2 = bvec2(true, false);

glsl

vec2 v2 = vec2(1.0, 2.0);
vec3 v3 = vec3(1.0, 2.0, 3.0);
vec4 v4 = vec4(1.0, 2.0, 3.0, 4.0);

// Integer vectors
ivec2 iv2 = ivec2(1, 2);
ivec3 iv3 = ivec3(1, 2, 3);

// Boolean vectors
bvec2 bv2 = bvec2(true, false);

Swizzling

分量重组（Swizzling）

glsl

vec4 color = vec4(1.0, 0.5, 0.2, 1.0);

vec3 rgb = color.rgb;      // (1.0, 0.5, 0.2)
vec2 rg = color.rg;        // (1.0, 0.5)
float r = color.r;         // 1.0

// Reorder
vec3 bgr = color.bgr;      // (0.2, 0.5, 1.0)

// Duplicate
vec3 rrr = color.rrr;      // (1.0, 1.0, 1.0)

// Position aliases (xyzw = rgba = stpq)
vec3 pos = v4.xyz;
vec2 uv = v4.st;

glsl

vec4 color = vec4(1.0, 0.5, 0.2, 1.0);

vec3 rgb = color.rgb;      // (1.0, 0.5, 0.2)
vec2 rg = color.rg;        // (1.0, 0.5)
float r = color.r;         // 1.0

// 重排
vec3 bgr = color.bgr;      // (0.2, 0.5, 1.0)

// 复制
vec3 rrr = color.rrr;      // (1.0, 1.0, 1.0)

// 位置别名（xyzw = rgba = stpq）
vec3 pos = v4.xyz;
vec2 uv = v4.st;

Matrices

矩阵

glsl

mat2 m2;  // 2x2
mat3 m3;  // 3x3
mat4 m4;  // 4x4

// Access columns
vec4 col0 = m4[0];

// Access element
float val = m4[1][2];  // column 1, row 2

glsl

mat2 m2;  // 2x2
mat3 m3;  // 3x3
mat4 m4;  // 4x4

// 访问列
vec4 col0 = m4[0];

// 访问元素
float val = m4[1][2];  // 第1列，第2行

Samplers

采样器

glsl

uniform sampler2D uTexture;      // 2D texture
uniform samplerCube uCubemap;    // Cube map

// Sample texture
vec4 texColor = texture2D(uTexture, vUv);
vec4 cubeColor = textureCube(uCubemap, direction);

glsl

uniform sampler2D uTexture;      // 2D纹理
uniform samplerCube uCubemap;    // 立方体贴图

// 采样纹理
vec4 texColor = texture2D(uTexture, vUv);
vec4 cubeColor = textureCube(uCubemap, direction);

Variable Qualifiers

变量限定符

Uniforms (CPU → GPU, constant per draw)

Uniforms（CPU → GPU，每次绘制保持恒定）

glsl

// Set from JavaScript, same for all vertices/fragments
uniform float uTime;
uniform vec3 uColor;
uniform mat4 uModelMatrix;
uniform sampler2D uTexture;

glsl

// 从JavaScript设置，对所有顶点/片元相同
uniform float uTime;
uniform vec3 uColor;
uniform mat4 uModelMatrix;
uniform sampler2D uTexture;

Attributes (Per-vertex data)

Attributes（逐顶点数据）

glsl

// Only in vertex shader
attribute vec3 position;    // Built-in: vertex position
attribute vec3 normal;      // Built-in: vertex normal
attribute vec2 uv;          // Built-in: texture coordinates
attribute vec3 color;       // Built-in: vertex color

// Custom attributes
attribute float aScale;
attribute vec3 aOffset;

glsl

// 仅在Vertex shader中可用
attribute vec3 position;    // 内置：顶点位置
attribute vec3 normal;      // 内置：顶点法线
attribute vec2 uv;          // 内置：纹理坐标
attribute vec3 color;       // 内置：顶点颜色

// 自定义Attribute
attribute float aScale;
attribute vec3 aOffset;

Varyings (Vertex → Fragment, interpolated)

Varyings（Vertex → Fragment，插值传递）

glsl

// Vertex shader: write
varying vec2 vUv;
varying vec3 vNormal;

void main() {
  vUv = uv;
  vNormal = normal;
}

// Fragment shader: read (interpolated across triangle)
varying vec2 vUv;
varying vec3 vNormal;

void main() {
  // vUv is interpolated between triangle vertices
}

glsl

// Vertex shader：写入
varying vec2 vUv;
varying vec3 vNormal;

void main() {
  vUv = uv;
  vNormal = normal;
}

// Fragment shader：读取（在三角形内插值）
varying vec2 vUv;
varying vec3 vNormal;

void main() {
  // vUv是三角形顶点间的插值结果
}

Built-in Variables

内置变量

Vertex Shader

glsl

// Output (must write)
vec4 gl_Position;       // Clip-space position

// Output (optional)
float gl_PointSize;     // Point sprite size (for gl.POINTS)

glsl

// 输出（必须赋值）
vec4 gl_Position;       // 裁剪空间位置

// 输出（可选）
float gl_PointSize;     // 点精灵大小（用于gl.POINTS）

Fragment Shader

glsl

// Input
vec4 gl_FragCoord;      // Window-space position (pixel coordinates)
bool gl_FrontFacing;    // True if front face
vec2 gl_PointCoord;     // Point sprite coordinates [0,1]

// Output
vec4 gl_FragColor;      // Final pixel color

glsl

// 输入
vec4 gl_FragCoord;      // 窗口空间位置（像素坐标）
bool gl_FrontFacing;    // 若为正面则为true
vec2 gl_PointCoord;     // 点精灵坐标 [0,1]

// 输出
vec4 gl_FragColor;      // 最终像素颜色

Coordinate Spaces

坐标系

Local/Object Space
      ↓ modelMatrix
World Space
      ↓ viewMatrix
View/Eye/Camera Space
      ↓ projectionMatrix
Clip Space (-1 to 1)
      ↓ perspective divide
NDC (Normalized Device Coordinates)
      ↓ viewport transform
Screen Space (pixels)

局部/对象空间
      ↓ modelMatrix
世界空间
      ↓ viewMatrix
视图/相机空间
      ↓ projectionMatrix
裁剪空间（-1 到 1）
      ↓ 透视除法
NDC（标准化设备坐标）
      ↓ 视口变换
屏幕空间（像素）

Common Matrices (Three.js/R3F)

常用矩阵（Three.js/R3F）

glsl

uniform mat4 modelMatrix;       // Local → World
uniform mat4 viewMatrix;        // World → View
uniform mat4 projectionMatrix;  // View → Clip
uniform mat4 modelViewMatrix;   // Local → View (modelMatrix * viewMatrix)
uniform mat3 normalMatrix;      // For transforming normals

uniform vec3 cameraPosition;    // Camera world position

glsl

uniform mat4 modelMatrix;       // 局部 → 世界
uniform mat4 viewMatrix;        // 世界 → 视图
uniform mat4 projectionMatrix;  // 视图 → 裁剪
uniform mat4 modelViewMatrix;   // 局部 → 视图（modelMatrix * viewMatrix）
uniform mat3 normalMatrix;      // 用于变换法线

uniform vec3 cameraPosition;    // 相机世界位置

Standard Vertex Transform

标准顶点变换

glsl

void main() {
  // Full transform chain
  vec4 worldPosition = modelMatrix * vec4(position, 1.0);
  vec4 viewPosition = viewMatrix * worldPosition;
  vec4 clipPosition = projectionMatrix * viewPosition;
  gl_Position = clipPosition;
  
  // Or combined (more efficient)
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

glsl

void main() {
  // 完整变换链
  vec4 worldPosition = modelMatrix * vec4(position, 1.0);
  vec4 viewPosition = viewMatrix * worldPosition;
  vec4 clipPosition = projectionMatrix * viewPosition;
  gl_Position = clipPosition;
  
  // 或合并写法（更高效）
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

Built-in Functions

内置函数

Math

数学函数

glsl

// Trigonometry
sin(x), cos(x), tan(x)
asin(x), acos(x), atan(x)
atan(y, x)  // atan2

// Exponential
pow(x, y)   // x^y
exp(x)      // e^x
log(x)      // ln(x)
sqrt(x)     // √x
inversesqrt(x)  // 1/√x

// Common
abs(x)
sign(x)     // -1, 0, or 1
floor(x)
ceil(x)
fract(x)    // x - floor(x)
mod(x, y)   // x % y (floating point)
min(x, y)
max(x, y)
clamp(x, min, max)
mix(a, b, t)  // Linear interpolation: a*(1-t) + b*t
step(edge, x) // 0 if x < edge, else 1
smoothstep(e0, e1, x)  // Smooth Hermite interpolation

glsl

// 三角函数
sin(x), cos(x), tan(x)
asin(x), acos(x), atan(x)
atan(y, x)  // atan2

// 指数函数
pow(x, y)   // x^y
exp(x)      // e^x
log(x)      // ln(x)
sqrt(x)     // √x
inversesqrt(x)  // 1/√x

// 常用函数
abs(x)
sign(x)     // -1、0 或 1
floor(x)
ceil(x)
fract(x)    // x - floor(x)
mod(x, y)   // x % y（浮点型）
min(x, y)
max(x, y)
clamp(x, min, max)
mix(a, b, t)  // 线性插值：a*(1-t) + b*t
step(edge, x) // 若x < edge则为0，否则为1
smoothstep(e0, e1, x)  // 平滑埃尔米特插值

Vector

向量函数

glsl

length(v)        // Vector magnitude
distance(a, b)   // length(a - b)
dot(a, b)        // Dot product
cross(a, b)      // Cross product (vec3 only)
normalize(v)     // Unit vector
reflect(I, N)    // Reflection vector
refract(I, N, eta)  // Refraction vector
faceforward(N, I, Nref)  // Flip normal if needed

glsl

length(v)        // 向量模长
distance(a, b)   // length(a - b)
dot(a, b)        // 点积
cross(a, b)      // 叉积（仅vec3）
normalize(v)     // 单位向量
reflect(I, N)    // 反射向量
refract(I, N, eta)  // 折射向量
faceforward(N, I, Nref)  // 按需翻转法线

Common Patterns

常见模式

UV Coordinates

UV坐标

glsl

// vUv ranges from (0,0) at bottom-left to (1,1) at top-right
varying vec2 vUv;

void main() {
  // Center UVs: -0.5 to 0.5
  vec2 centered = vUv - 0.5;
  
  // Aspect-corrected (assuming you pass uResolution)
  vec2 uv = vUv;
  uv.x *= uResolution.x / uResolution.y;
  
  // Tiling
  vec2 tiled = fract(vUv * 4.0);  // 4x4 tiles
  
  // Polar coordinates
  float angle = atan(centered.y, centered.x);
  float radius = length(centered);
}

glsl

// vUv范围从左下角(0,0)到右上角(1,1)
varying vec2 vUv;

void main() {
  // 居中UV：-0.5 到 0.5
  vec2 centered = vUv - 0.5;
  
  // 宽高比校正（假设已传入uResolution）
  vec2 uv = vUv;
  uv.x *= uResolution.x / uResolution.y;
  
  // 平铺
  vec2 tiled = fract(vUv * 4.0);  // 4x4平铺
  
  // 极坐标
  float angle = atan(centered.y, centered.x);
  float radius = length(centered);
}

Color Operations

颜色操作

glsl

// Grayscale (perceptual weights)
float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));

// Contrast
color = (color - 0.5) * contrast + 0.5;

// Brightness
color += brightness;

// Saturation
float gray = dot(color, vec3(0.299, 0.587, 0.114));
color = mix(vec3(gray), color, saturation);

// Gamma correction
color = pow(color, vec3(1.0 / 2.2));  // Linear to sRGB
color = pow(color, vec3(2.2));         // sRGB to linear

glsl

// 灰度转换（感知权重）
float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));

// 对比度调整
color = (color - 0.5) * contrast + 0.5;

// 亮度调整
color += brightness;

// 饱和度调整
float gray = dot(color, vec3(0.299, 0.587, 0.114));
color = mix(vec3(gray), color, saturation);

// Gamma校正
color = pow(color, vec3(1.0 / 2.2));  // 线性转sRGB
color = pow(color, vec3(2.2));         // sRGB转线性

Smooth Transitions

平滑过渡

glsl

// Hard edge
float mask = step(0.5, value);

// Soft edge
float mask = smoothstep(0.4, 0.6, value);

// Anti-aliased edge (screen-space)
float mask = smoothstep(-fwidth(value), fwidth(value), value);

glsl

// 硬边缘
float mask = step(0.5, value);

// 软边缘
float mask = smoothstep(0.4, 0.6, value);

// 抗锯齿边缘（屏幕空间）
float mask = smoothstep(-fwidth(value), fwidth(value), value);

Debugging

调试

Visualize Values

可视化数值

glsl

// Show UVs as color
gl_FragColor = vec4(vUv, 0.0, 1.0);

// Show normals
gl_FragColor = vec4(vNormal * 0.5 + 0.5, 1.0);

// Show depth
float depth = gl_FragCoord.z;
gl_FragColor = vec4(vec3(depth), 1.0);

// Show value range (red=negative, green=positive)
gl_FragColor = vec4(max(0.0, value), max(0.0, -value), 0.0, 1.0);

glsl

// 将UV显示为颜色
gl_FragColor = vec4(vUv, 0.0, 1.0);

// 显示法线
gl_FragColor = vec4(vNormal * 0.5 + 0.5, 1.0);

// 显示深度
float depth = gl_FragCoord.z;
gl_FragColor = vec4(vec3(depth), 1.0);

// 显示数值范围（红色=负值，绿色=正值）
gl_FragColor = vec4(max(0.0, value), max(0.0, -value), 0.0, 1.0);

Common Errors

常见错误

Issue	Likely Cause
Black screen	gl_Position not set, or NaN values
Uniform not updating	Wrong name or type mismatch
Texture black	Texture not loaded, wrong UV
Flickering	Z-fighting, precision issues
Faceted look	Normals not interpolated

问题	可能原因
黑屏	未设置gl_Position，或存在NaN值
Uniform未更新	名称错误或类型不匹配
纹理显示为黑色	纹理未加载，或UV错误
闪烁	Z轴冲突，精度问题
棱角外观	法线未插值

Precision

精度

glsl

// Declare precision (required in fragment shader for WebGL 1)
precision highp float;
precision mediump float;
precision lowp float;

Precision	Range	Use Case
highp	~10^38	Positions, matrices
mediump	~10^14	UVs, colors
lowp	~2	Simple flags

glsl

// 声明精度（WebGL 1中Fragment shader必填）
precision highp float;
precision mediump float;
precision lowp float;

精度	范围	适用场景
highp	~10^38	位置、矩阵
mediump	~10^14	UV、颜色
lowp	~2	简单标志

File Structure

文件结构

shader-fundamentals/
├── SKILL.md
├── references/
│   ├── glsl-types.md         # Complete type reference
│   ├── builtin-functions.md  # All built-in functions
│   └── coordinate-spaces.md  # Transform pipeline
└── scripts/
    └── templates/
        ├── basic.glsl        # Starter template
        └── fullscreen.glsl   # Fullscreen quad shader

shader-fundamentals/
├── SKILL.md
├── references/
│   ├── glsl-types.md         # 完整类型参考
│   ├── builtin-functions.md  # 所有内置函数
│   └── coordinate-spaces.md  # 变换管线
└── scripts/
    └── templates/
        ├── basic.glsl        # 入门模板
        └── fullscreen.glsl   # 全屏四边形着色器

Reference

参考资料

```
references/glsl-types.md
```
— Complete data type reference
```
references/builtin-functions.md
```
— All GLSL built-in functions
```
references/coordinate-spaces.md
```
— Transform pipeline deep-dive

```
references/glsl-types.md
```
— 完整数据类型参考
```
references/builtin-functions.md
```
— 所有GLSL内置函数
```
references/coordinate-spaces.md
```
— 变换管线深度解析