简介：这是一份围绕 OpenGL 影像处理效果展开的可运行工程源码，面向具备一定 C++ 与图形学基础、希望理解 GPU 着色器实践的开发者与学习者，重点演示边缘检测与卡通化两类效果的实现思路。压缩包共 33 个文件，约 918KB，以 14 个 .h 头文件和 11 个 .cpp 源文件为主体，辅以着色器、位图素材、工程配置与说明文档，便于从整体结构上梳理顶点与片段着色、纹理加载和 CPU 端处理的分工。已有 152 人学习，说明该主题在图形学入门、课程实践与实验项目中具有一定参考价值。读者可据此分析边缘检测算法在像素着色器中的落地方式，理解卡通效果涉及的轮廓提取、色彩简化与轮廓强化流程，并借助可调参数开展对比实验，进而掌握 GLSL 着色器编写、GPU 并行计算及实时影像处理的基本方法。
1. 从 CPU 的 40ms 到 GPU 的 2ms：这套 OpenGL 影像处理工程解决的是什么问题
某开发者第一次把边缘检测从内存搬到显卡上，先在 CPU 里跑了一遍 3×3 的 Sobel，1080p 一张图四十多毫秒，切到 OpenGL 之后同样一张图不到两毫秒。提速不是白捡的——真正卡住他两天的是纹理坐标上下颠倒、离屏帧缓冲没切回屏幕、以及 mipmap 没生成导致采样全黑。这份资源就是把我踩过的这些坑整理成的一套完整 OpenGL 影像处理效果工程：图片读入、纹理上传、离屏效果链、屏幕输出整条链路跑通，内置边缘检测、高斯模糊、亮度/对比度/饱和度等常用效果，每个效果是一个独立可插拔的 pass。适合会一点 C++、想搞明白 GPU 图像处理管线怎么搭、想给自己的桌面工具或相机类应用加实时滤镜的人。
2. 工程结构与渲染管线：一张图从磁盘到屏幕要经过几道手
2.1 目录划分与各模块职责
拿到源码先看目录，比直接从main.cpp一行行读要快得多。这套工程按「资源管理 / 渲染目标 / 效果 / 胶水层」四块切分，边界清楚，后面加效果基本不用动前两块。
gl_image_effects/ ├── CMakeLists.txt ├── src/ │ ├── main.cpp # 窗口、事件循环、效果链编排 │ ├── Shader.cpp/.h # GLSL 编译、链接、uniform 缓存 │ ├── Texture.cpp/.h # 图片解码、纹理参数设置 │ ├── RenderTarget.cpp/.h # FBO + 颜色附件纹理的创建与复用 │ └── EffectChain.cpp/.h # pass 串联、双缓冲乒乓 ├── shaders/ │ ├── quad.vert # 全屏四边形顶点着色器（所有 pass 共用） │ ├── sobel.frag # 边缘检测 │ ├── gaussian.frag # 可分离高斯模糊 │ └── color_adjust.frag # 亮度/对比度/饱和度 ├── third_party/ │ ├── glad/ # 函数指针加载 │ └── stb_image.h # 单头文件图片解码 └── assets/ └── sample.jpgShader这一层我一般会做两件事：一是把glGetUniformLocation的结果缓存进std::unordered_map<std::string, GLint>，避免每帧几十次字符串查找；二是编译失败时把 info log 完整打出来，并带上文件名和行号，否则对着 GLSL 报错猜是哪一行，那是真的玄学。RenderTarget只负责 FBO 和它那张颜色纹理的生命周期，跟具体效果无关，所以效果链无论多长，渲染目标的代码都不用改。
EffectChain是整套东西的调度中心。每个效果被抽象成一个结构体，里面有 program、若干 uniform 的名字与当前值、以及是否启用的开关。主循环只跟这个std::vector<Effect>打交道，加效果就是往数组里 push 一项，删效果就是 erase，不改渲染代码。
提示：把「效果」做成数据而不是硬编码的 if-else 分支，是这套工程最值得抄的一处设计。后面要支持预设、要支持拖拽排序、要支持效果开关，全都是现成的。
2.2 双 FBO 离屏渲染：效果链为什么不能直接画到屏幕
新手最容易犯的错是：每加一个效果就glDrawArrays一次画到默认帧缓冲上。这样做的结果是第二个效果读不到第一个效果的输出——你没法在读一张纹理的同时往这张纹理里写，这是未定义行为，驱动会给你一张花屏或者干脆全黑。
正确做法是乒乓双缓冲：准备两个 FBO（各带一张颜色纹理），第 1 个 pass 读纹理 A 写纹理 B，第 2 个 pass 读 B 写 A，以此类推，最后一个 pass 的输出再一次性 blit 到默认帧缓冲。渲染目标的创建代码如下，注意里面那两行GL_CLAMP_TO_EDGE，漏掉的话边缘一圈像素会采样到对侧，做高斯模糊时表现为画面上下左右边框出现一条亮线。
// 创建一个可复用的离屏渲染目标，返回 FBO，颜色纹理通过 outTex 带出 GLuint createRenderTarget(int w, int h, GLuint* outTex) { GLuint fbo = 0, tex = 0; glGenFramebuffers(1, &fbo); glBindFramebuffer(GL_FRAMEBUFFER, fbo); glGenTextures(1, &tex); glBindTexture(GL_TEXTURE_2D, tex); glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, w, h, 0, GL_RGBA, GL_UNSIGNED_BYTE, nullptr); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); // 关键：不夹紧的话，边缘采样会绕到对侧，模糊时边框会出亮边 glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE); glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, tex, 0); if (glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE) { // 尺寸为 0、显存不足、格式不被支持都会走到这里，早失败早排查 fprintf(stderr, "FBO incomplete: %d x %d\n", w, h); } glBindFramebuffer(GL_FRAMEBUFFER, 0); // 一定要切回去，否则后面的绘制全进 FBO *outTex = tex; return fbo; }参数上要注意GL_RGBA8这个内部格式：高版本 GL 用 sized internal format 更规范，配GL_RGBA+GL_UNSIGNED_BYTE作为上传格式。窗口尺寸变化时，两个 FBO 都要跟着glTexImage2D重新分配（或者先glDeleteTextures再重建），只改 viewport 不重建纹理，结果是画面只有左下角一小块有内容。
效果链的调度逻辑本身很短，但顺序和缓冲切换这两个点错了就很难查：
// 效果链：每个 pass 以上一个 FBO 的纹理为输入，写入另一个 FBO void renderChain(const std::vector<Effect>& chain, GLuint fbo[2], GLuint tex[2], int width, int height) { int src = 0; for (size_t i = 0; i < chain.size(); ++i) { if (!chain[i].enabled) continue; // 关掉的效果直接跳过，不浪费一次 pass int dst = 1 - src; glBindFramebuffer(GL_FRAMEBUFFER, fbo[dst]); glViewport(0, 0, width, height); glClear(GL_COLOR_BUFFER_BIT); glUseProgram(chain[i].program); glActiveTexture(GL_TEXTURE0); glBindTexture(GL_TEXTURE_2D, tex[src]); glUniform1i(chain[i].uTexture, 0); // 其余 uniform 由效果自己设置 chain[i].applyUniforms(); glDrawArrays(GL_TRIANGLE_STRIP, 0, 4); src = dst; // 乒乓：这一趟的输出成为下一趟的输入 } // 最后一路回屏 glBindFramebuffer(GL_FRAMEBUFFER, 0); blitToScreen(tex[src]); }src和dst的翻转是这套逻辑的核心，不理解这一行就等于不理解整条管线。另外注意if (!enabled) continue;放在最前面——如果放在切换缓冲之后，被跳过的 pass 会让src停在原地，后面读到的就是上一轮循环残留的内容，这种 bug 表现为「关掉某个效果之后画面反而更奇怪了」。
2.3 全屏四边形与纹理坐标：所有效果共用的一个顶点着色器
整套工程只用一个顶点着色器。因为每个 pass 干的都是「拿一张和屏幕一样大的图，逐像素算个新颜色」，几何部分永远是覆盖整个 NDC 的四边形，两个三角形拼起来，用GL_TRIANGLE_STRIP四次顶点就够。
#version 330 core layout(location = 0) in vec2 aPos; // NDC 坐标，范围 -1 ~ 1 out vec2 vUV; void main() { vUV = aPos * 0.5 + 0.5; // NDC 映射到 0 ~ 1 的纹理坐标 gl_Position = vec4(aPos, 0.0, 1.0); }顶点数据就八个 float，注意 v 的排列方向：
// 顺序必须与 GL_TRIANGLE_STRIP 匹配：左下、右下、左上、右上 const float kQuad[] = { -1.0f, -1.0f, 1.0f, -1.0f, -1.0f, 1.0f, 1.0f, 1.0f, };坐标映射这一行aPos * 0.5 + 0.5是整条链路里最容易出问题的地方。NDC 的 y 轴向上，而为 OpenGL 准备的纹理数据（尤其是从图片加载来的）原点通常被约定在左上，两边一错，画面就上下颠倒。解法不是在这里改映射，而是在加载图片时统一翻转一次（见 4.2 节的stbi_set_flip_vertically_on_load）。我一般坚持「只在导入时翻一次」，而不是在每个 fragment shader 里写1.0 - vUV.y——后者看起来能用，但一旦某天要做逐级输出中间结果对比，方向就会乱套，排查起来是纯粹的血泪经验。
3. 核心效果拆解：边缘检测、高斯模糊与色彩调整的着色器写法
3.1 灰度化加 Sobel：边缘检测的 3×3 邻域怎么取
Sobel 的思路很朴素：对每个像素取它周围 3×3 的邻域，分别算横向梯度 Gx 和纵向梯度 Gy，再取模长当作边缘强度。难点不在数学，在于「周围」怎么取——纹理坐标是 0 到 1 的归一化值，你要偏移一个像素，就得知道一个像素在 UV 空间里占多少，这个值通过 uniform 传进去，等于1.0 / 纹理宽高。
#version 330 core in vec2 vUV; out vec4 fragColor; uniform sampler2D uTexture; uniform vec2 uTexelSize; // (1.0/width, 1.0/height) uniform float uIntensity; // 边缘增益，常见 1.0 ~ 3.0 // 先转灰度再做梯度：彩色图直接算梯度会让不同通道的边缘互相干扰 float luma(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); } void main() { vec2 o = uTexelSize; // 3×3 九宫格采样，命名按方位：t=top b=bottom l=left r=right float tl = luma(texture(uTexture, vUV + vec2(-o.x, o.y)).rgb); float t = luma(texture(uTexture, vUV + vec2( 0.0, o.y)).rgb); float tr = luma(texture(uTexture, vUV + vec2( o.x, o.y)).rgb); float l = luma(texture(uTexture, vUV + vec2(-o.x, 0.0)).rgb); float r = luma(texture(uTexture, vUV + vec2( o.x, 0.0)).rgb); float bl = luma(texture(uTexture, vUV + vec2(-o.x, -o.y)).rgb); float b = luma(texture(uTexture, vUV + vec2( 0.0, -o.y)).rgb); float br = luma(texture(uTexture, vUV + vec2( o.x, -o.y)).rgb); // Sobel 卷积核：[1 2 1] 的加权，中间行/列权重为 2 float gx = -tl - 2.0 * l - bl + tr + 2.0 * r + br; float gy = tl + 2.0 * t + tr - bl - 2.0 * b - br; float edge = length(vec2(gx, gy)) * uIntensity; fragColor = vec4(vec3(clamp(edge, 0.0, 1.0)), 1.0); }几处参数说明。uIntensity用来拉伸对比：自然图像经过 Sobel 后梯度值普遍偏小，直接输出会是一张几乎全黑的图，取 2.0 到 3.0 通常能看清轮廓；做工业检测类的图可能 1.0 就够。length()是欧氏模长，换成abs(gx) + abs(gy)会更快一点、边缘略粗，对实时性要求高的场景可以换。另外这里输出的是灰度边缘图，如果想要「彩底描边」，把fragColor改成原图颜色与边缘强度相乘即可，实现上是多一次采样。
还有一个细节：uTexelSize必须跟着纹理的实际尺寸走，而不是窗口尺寸。中间某个 pass 如果做了降采样（为了性能，模糊经常在半分辨率下做），传错了就会得到一片没有边缘的糊图，这属于典型的「看着像着色器写错了，其实是外部参数不对」。
3.2 可分离高斯模糊：两趟渲染把 O(n²) 摊成 O(n)
二维高斯模糊直接做，N×N 的核每像素要采样 N² 次，5×5 就是 25 次，稍微上到 9×9 就 81 次，1080p 下帧率立刻跪。利用高斯的可分离性拆成横竖两趟，采样次数降到 2N，5×5 从 25 次降到 10 次，半径越大收益越明显。这也是为什么这套工程坚持做成效果链——两趟渲染的中间结果必须能被下一趟读到，单 pass 架构下根本实现不了。
#version 330 core in vec2 vUV; out vec4 fragColor; uniform sampler2D uTexture; uniform vec2 uDirection; // 横向趟传 (1/w, 0)，纵向趟传 (0, 1/h) uniform float uWeights[5]; // 归一化权重，host 侧算好 uniform float uOffsets[5]; // 采样偏移（以像素为单位） void main() { vec3 sum = texture(uTexture, vUV).rgb * uWeights[0]; for (int i = 1; i < 5; ++i) { vec2 delta = uDirection * uOffsets[i]; sum += texture(uTexture, vUV + delta).rgb * uWeights[i]; // 一侧 sum += texture(uTexture, vUV - delta).rgb * uWeights[i]; // 对称另一侧 } fragColor = vec4(sum, 1.0); }权重在 CPU 端算，别在着色器里现场exp，一是浪费，二是有些老驱动对循环里的超越函数优化很差：
// 一维高斯核，返回长度为 2*radius+1 的归一化权重 std::vector<float> gaussianWeights(float sigma, int radius) { std::vector<float> w(2 * radius + 1); float sum = 0.0f; for (int i = -radius; i <= radius; ++i) { float v = std::exp(-(i * i) / (2.0f * sigma * sigma)); w[i + radius] = v; sum += v; } for (auto& v : w) v /= sum; // 不归一化会整体提亮或压暗 return w; }sigma决定模糊的观感：小于 1.0 基本看不出来，1.5 到 3.0 是比较自然的磨皮量级，再大就成马赛克了。radius一般取ceil(3 * sigma)，因为高斯在三个标准差以外的权重已经小到可以直接砍掉，多采样的边际收益接近零。这里还有个性能技巧我常做：模糊在半分辨率下跑，权重和偏移按半分辨率纹理的尺寸算，最后再上采样回全分辨率。肉眼几乎看不出差别，耗时能省下四分之三。代价是细密的纹理（比如织物、头发）会有点糊，要不要用取决于你的效果链后面接的是什么。
3.3 亮度、对比度、饱和度：三个 uniform 一次矩阵式的色彩调整
色彩调整看起来最不起眼，但在实际产品里是用户最常调的一项。实现上没什么玄机，关键是参数的取值区间要设计得符合直觉：亮度用加减（-1 到 1，0 是原样），对比度和饱和度用乘性（1.0 是原样），否则滑杆推到中间不是原图，用户会觉得这功能坏了。
#version 330 core in vec2 vUV; out vec4 fragColor; uniform sampler2D uTexture; uniform float uBrightness; // -1.0 ~ 1.0，0 为原样 uniform float uContrast; // 0.5 ~ 2.0，1.0 为原样 uniform float uSaturation; // 0.0 ~ 2.0，1.0 为原样 void main() { vec3 c = texture(uTexture, vUV).rgb; c += uBrightness; // 亮度：整体平移 c = (c - 0.5) * uContrast + 0.5; // 对比度：以中灰 0.5 为轴心缩放 float g = dot(c, vec3(0.2126, 0.7152, 0.0722)); // 感知亮度权重 c = mix(vec3(g), c, uSaturation); // 饱和度：向灰度插值 // 三件事都可能在区间外，最后统一 clamp，否则高光会溢出成纯白斑 fragColor = vec4(clamp(c, 0.0, 1.0), 1.0); }对比度那行(c - 0.5) * k + 0.5里的 0.5 是轴心，用中灰而不是 0，这样调对比度时整体亮度不会跟着漂。饱和度用mix(灰度, 原色, k)，k 为 0 是全灰、1 是原样、大于 1 是加饱和，比手写c + (c - g) * k少一次乘加而且不会在超范围时出怪色。亮度权重那三个数（0.2126 / 0.7152 / 0.0722）是线性空间的感知系数，和 3.1 节 Sobel 里用的 0.299 / 0.587 / 0.114 不是一套——后者是显示空间的老系数，做边缘检测时差别不大，但做饱和度调整时用错了，红色物体调饱和度会出现明显的偏色。
注意：如果整个工程在 sRGB 空间里直接算，那么亮度加减在暗部会显得迟钝、亮部会过曝。想做得更专业，就先把颜色转到线性空间算完再转回去，代价是多两行 pow。多数轻量工具为了简单不做这步，能不能接受取决于你的目标用户有多挑。
4. 编译与运行：把工程在本机跑通的最小步骤
4.1 依赖与 CMake 配置
依赖一共三项：GLFW 负责窗口和输入，glad 负责加载 OpenGL 函数指针，stb_image 负责解图片。前两个可以走包管理，第三个是单头文件，直接拖进third_party就行。CMake 里最容易翻车的是 glad——它必须作为一个 C 文件参与编译，不能只 include 头文件了事，否则链接阶段会报一堆undefined reference。
cmake_minimum_required(VERSION 3.16) project(gl_image_effects LANGUAGES C CXX) # 注意要带 C，glad.c 是 C 源码 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(glfw3 3.3 REQUIRED) find_package(OpenGL REQUIRED) add_executable(gl_image_effects src/main.cpp src/Shader.cpp src/Texture.cpp src/RenderTarget.cpp src/EffectChain.cpp third_party/glad/src/glad.c # 必须编译进来，只 include 头文件是不够的 ) target_include_directories(gl_image_effects PRIVATE src third_party/glad/include third_party ) target_link_libraries(gl_image_effects PRIVATE glfw OpenGL::GL ${CMAKE_DL_LIBS})编译命令就三步，跑不通时先看第一步 find_package 有没有报找不到 glfw3：
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j ./build/gl_image_effects assets/sample.jpg用 Release 而不是 Debug 很重要。stb_image的解码和着色器编译在 Debug 下都能忍，但如果你后面自己加了逐像素的 CPU 侧循环做对比验证，Debug 下慢十倍是常态，会误判成渲染性能有问题。
4.2 图片加载：三行代码里藏着的两个坑
纹理加载这段代码短，但两个坑几乎是必踩的：上下翻转和行对齐。
#define STB_IMAGE_IMPLEMENTATION #include "stb_image.h" GLuint loadTexture(const char* path) { // 坑 1：图片原点在左上，GL 纹理坐标原点在左下，这里一次性翻正 stbi_set_flip_vertically_on_load(true); int w = 0, h = 0, n = 0; unsigned char* data = stbi_load(path, &w, &h, &n, 4); // 强制 4 通道，省得后面判分支 if (!data) { fprintf(stderr, "load failed: %s\n", path); return 0; } GLuint tex = 0; glGenTextures(1, &tex); glBindTexture(GL_TEXTURE_2D, tex); // 坑 2：宽度不是 4 的倍数时，默认 4 字节对齐会让每行错位 glPixelStorei(GL_UNPACK_ALIGNMENT, 1); glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, w, h, 0, GL_RGBA, GL_UNSIGNED_BYTE, data); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE); stbi_image_free(data); return tex; }第三个参数传4而不是0是有意的：强制四通道输出，后面所有texture().rgb的采样都不用担心三通道纹理在某个驱动上被当成 RGB 还是 BGR。代价是内存多四分之一，对一张 1080p 图完全可以接受。另外注意这里没有调glGenerateMipmap——因为这张纹理只被当作效果链的输入，全程用GL_LINEAR采样，生成 mipmap 纯属浪费。反过来说，如果哪天你把MIN_FILTER改成GL_LINEAR_MIPMAP_LINEAR却忘了生成 mipmap，画面会直接变成全黑，这个现象很有迷惑性（见 5.2）。
4.3 跑起来之后先验哪几件事
程序能启动不算跑通，先按顺序确认四个点，能省掉后面大量瞎猜。
第一，着色器全部编译链接成功，控制台没有 info log 输出。第二，把效果链清空、直接 blit 原纹理到屏幕，画面应该和原图完全一致，方向和颜色都对——这一步过不了，后面所有效果都没有意义。第三，逐个启用效果，每加一个截一张图，确认变化符合预期，边缘检测出来应该是白底黑线的轮廓感，高斯模糊应该是整体柔化且没有边框亮线。第四，拖拽窗口改变尺寸，确认画面跟着缩放且不拉伸变形，这一步会暴露 FBO 没重建的问题。
我一般会在代码里留一个调试开关，把每个 pass 的输出都存成 png，命名带序号。这个习惯看起来笨，但比对着屏幕肉眼比对快了不止一个数量级，尤其是在调边缘检测这种对数值敏感的算子时。
5. 避坑与排查：GLSL 编译、坐标系与性能的翻车现场
5.1 编译链接阶段的坑
现象：链接报一堆undefined reference to glGenFramebuffers之类的符号。原因：glad 的头文件 include 了，但glad.c没有被编译进目标，或者 include 了 glad 头文件之前先 include 了系统自带的 GL 头，导致函数声明被宏替换掉。 解决：CMake 的project()里带上C语言，把glad.c显式加进add_executable；同时保证#include <glad/glad.h>永远在#include <GLFW/glfw3.h>之前，这个顺序反了在部分平台上会直接编译失败。
现象：运行时着色器编译失败，日志只有一行0:1(1): error:，看不出问题。原因：info log 的缓冲区开得太小，或者根本没打印。GLSL 的报错格式是「文件索引:行号(列号)」，文件索引是相对glShaderSource传进去的字符串数组而言的。 解决：log 缓冲区开到 1024 字节起，打印时把源码原文也按行号截一段出来对照；如果用了#include之类的预处理拼接，记得在拼接后的字符串里保留行号。
5.2 画面不对：黑屏、颠倒、边缘发灰
现象：整个窗口全黑，但程序没崩、也没有 GL 错误。原因：常见有三种。一是纹理的MIN_FILTER设成了GL_LINEAR_MIPMAP_LINEAR但没调glGenerateMipmap，采样结果按规范是「不完整纹理」，返回全黑。二是uTexture这个 uniform 没设成 0，默认值虽然是 0，但如果你绑定到了GL_TEXTURE1又没改 uniform，采样就全黑。三是某个 pass 之后忘了glBindFramebuffer(GL_FRAMEBUFFER, 0)，最后的 blit 目标还是那个 FBO，屏幕上当然什么都没有。 解决：按「纹理完整性 → uniform 值 → 帧缓冲绑定」的顺序逐个查，用glGetError加glCheckFramebufferStatus在每步之后打点，比漫无目的地改代码快得多。
现象：画面上下颠倒。原因：图片解码出来的第一行是图像顶部，而 GL 的纹理坐标 v=0 在底部，两边对不上。 解决：统一在loadTexture里调stbi_set_flip_vertically_on_load(true)，全工程只翻这一次。不要在 fragment shader 里写vUV.y = 1.0 - vUV.y，一旦效果链里有某个 pass 拿到的不是原始纹理（比如已经翻过的中间结果），再翻一次就又颠回去了。
现象：边缘检测出来的图几乎全黑，只有极少数地方有一点白。原因：两种可能。一是uTexelSize传的是窗口尺寸的倒数而不是纹理尺寸的倒数，或者干脆传了(1, 1)，邻域偏移大到跨越了半张图，梯度算出来是噪声。二是没做灰度化直接对 rgb 三个通道分别算梯度，颜色通道之间相互抵消。 解决：先把uTexelSize硬编码成vec2(1.0/1920.0, 1.0/1080.0)验证一次，确认逻辑正确再改成 uniform；灰度化那步不要省，dot(c, vec3(0.299, 0.587, 0.114))一行的事。
现象：高斯模糊之后，画面四周出现一圈明显的亮边或者暗边。原因：纹理的 wrap 模式是默认的GL_REPEAT，模糊采样到边界外的坐标时绕回了对侧像素，横向趟会把左边的像素混到右边去。 解决：把参与模糊的纹理 wrap 全部设成GL_CLAMP_TO_EDGE；如果模糊半径很大（超过画面尺寸的 5%），光夹紧还不够，得在边界处按距离衰减权重，或者干脆先给图加一圈 padding。
5.3 性能与资源
现象：加了第五个效果之后帧率从 60 掉到 20。原因：每个 pass 都在全分辨率下跑，五个 pass 就是五次 1080p 的逐像素运算，加上中间纹理的带宽开销。 解决：先确认有没有做「关闭的效果跳过」这个优化；再把模糊这类可以降采样的效果放到半分辨率下跑；最后检查 uniforms 是不是每帧都在重新glGetUniformLocation。真到了这一步还不够，就考虑把能合并的 pass 合成一个 shader，比如亮度、对比度、饱和度三项完全可以塞进一个color_adjust.frag，而不是拆成三个 pass。
现象：连续切换图片几十次之后显存爆掉。原因：每次加载新图都glGenTextures，但没glDeleteTextures旧的那张。GL 对象不会自动回收，glGenTextures拿到的名字只是复用空闲槽位。 解决：把纹理和 FBO 都包一层 RAII，析构时删除；切换图片时复用已有的纹理 ID，用glTexImage2D重新分配内容而不是新建对象。窗口 resize 也是同理，重建 FBO 之前先删旧的。
6. 二次开发：加一个自定义滤镜并验证它真的生效了
6.1 接入一个新效果要改的三处
这套工程加效果的路径很短，我以「色调分离（posterize）」为例走一遍——它把连续的颜色量化成有限几档，做海报风格或者复古感很好用，代码只有三行，适合当模板。
第一处是着色器文件，新建shaders/posterize.frag：
#version 330 core in vec2 vUV; out vec4 fragColor; uniform sampler2D uTexture; uniform float uLevels; // 量化级数，6.0 左右效果比较自然，2.0 会变成版画 void main() { vec4 c = texture(uTexture, vUV); // 先乘级数、四舍五入取整、再除回去，得到阶梯状的颜色分布 c.rgb = floor(c.rgb * uLevels + 0.5) / uLevels; fragColor = c; }第二处是注册到效果链，把 program、名字、uniform 的位置和默认值塞进Effect结构体，push 到数组末尾：
Effect makePosterize(float levels) { Effect e; e.name = "posterize"; e.program = Shader::build("shaders/quad.vert", "shaders/posterize.frag"); e.enabled = true; e.uTexture = glGetUniformLocation(e.program, "uTexture"); e.uLevels = glGetUniformLocation(e.program, "uLevels"); e.applyUniforms = [levels]() { glUniform1f(e.uLevels, levels); }; return e; } chain.push_back(makePosterize(6.0f)); // 放在色彩调整之后，避免量化后再拉伸对比度第三处是 UI 或者配置文件里的开关，如果你只是想验证，把push_back注释掉对比两次就够了。位置顺序值得说一句：posterize 放在色彩调整之后，量化出来的档位是稳定的；放在之前，后面的对比度拉伸会把阶梯重新拉开，看起来就像没生效。
6.2 逐 pass 截图 + 像素差：怎么确认改动是对的
改了效果链之后，最大的风险不是报错，而是「看起来变了但其实错位了一个像素」或者「某些 pass 根本没跑」。我一般会把每个 pass 的输出都存成 png，和改动前的基准图做像素级差分，超过阈值的区域才算有效改动。
# 逐 pass 对比：确认某个 pass 的输出确实变了，且变化范围符合预期 from PIL import Image, ImageChops a = Image.open("out/pass_02.png").convert("RGB") b = Image.open("baseline/pass_02.png").convert("RGB") diff = ImageChops.difference(a, b) # 每个通道的最大差值，用来判断是"整体微调"还是"局部剧变" print("max diff per channel:", diff.getextrema()) # 差异像素占比，用来判断改动范围是否合理（比如只改边缘就不该超过 30%） hist = diff.convert("L").histogram() changed = sum(hist[8:]) / (a.width * a.height) print(f"changed ratio: {changed:.2%}")几个判断经验，都是被坑出来的。如果某个 pass 的changed ratio是 100% 且max diff很大，多半是坐标系翻了或者采样通道错了，不是参数问题。如果是 0%，先确认这个 pass 有没有被enabled = false跳过，再确认它读的纹理是不是上一个 pass 的输出——乒乓缓冲里src和dst弄反了，会出现「效果互相抵消」的假象。如果只有边缘一圈有差异，那基本就是这个 pass 的纹理 wrap 模式不对。
效果链的顺序调整我也建议用这套方式验证。比如把高斯模糊挪到边缘检测前面，边缘会变粗、细节减少，changed ratio会上升但不会到 100%，这个区间是合理的；如果一下子到 100%，说明挪的位置把某个 pass 的输入类型搞错了（比如把灰度图喂给了需要彩色的饱和度调整）。
从那以后我每次给效果链加新东西，都强制先跑一遍「关掉全部效果 → 只开一个 → 全开」的三段对比截图，中间结果全部落盘，不靠肉眼在窗口里看。这套流程多花五分钟，能省掉一整个下午对着黑屏猜哪一行写错了。希望帮到你。
本文还有配套的精品资源，点击获取
