如果你做过 iOS 端的图像处理，GPUImage 这个名字肯定不会陌生。GPUImage3 是这个开源图像处理框架的第三代实现，它最明显的变化就是把原来的 OpenGL ES 全部换成了 Metal，并且用 Swift 重写了一遍。更重要的是，GPUImage3 不是对老代码的简单翻译，而是按照 Metal 的资源管理模式重新设计了一套图像处理链路。这篇文章我想以“整个框架理解”为切入点，聊聊它对外的核心抽象、内部的渲染流程、自定义滤镜的关键写法，以及我在实际项目中踩过的坑。适合两类人看：一类是想搞懂框架内部机理，另一类是准备在项目里用它做实时相机滤镜或图片特效，希望少走弯路的人。
1. 从OpenGL到Metal：GPUImage3到底改了什么
1.1 三代框架的演进逻辑
最早的 GPUImage 基于 OpenGL ES 2.0，用 Objective-C 编写。它的设计思路是把图像处理抽象成“源、滤镜、目标”三级结构，每个滤镜背后对应一个 OpenGL 的 FBO（帧缓冲对象）。当时这套设计非常流行，因为 OpenGL ES 2.0 的可编程管线刚普及，图像处理正好可以用 GLSL 片段着色器表达。后来 GPUImage 的新版本转向了 Metal，同时改用 Swift，这就是 GPUImage3 的起点。
老项目如果要迁移到 GPUImage3，不要指望改个 import 就能跑起来。两者的 API 差异很大，因为底层运行时完全不同。Metal 不再像 OpenGL ES 那样是一个全身状态机，它把渲染过程显式拆分成：命令队列（MTLCommandQueue）、命令缓冲（MTLCommandBuffer）、渲染命令编码器（MTLRenderCommandEncoder）和资源（MTLTexture、MTLBuffer）。GPUImage3 里的每一个滤镜节点，本质上就是“一次渲染过程”，或者叫一个 render pass。
我在旧项目上第一次跑 GPUImage3 时最直观的感觉是，帧回调不再像 OpenGL 时代那样频繁处理 GLContext 切换，CPU 侧只需要把渲染指令和参数按顺序提交到命令队列，剩下的执行交给 GPU。这也是现代 iOS 图形开发的主流趋势：CPU 负责组织，GPU 负责算。
1.2 Metal带来的思维转变
要理解 GPUImage3，先得理解一个关键转变：整个框架不再围绕“OpenGL 纹理对象”工作，而是围绕“Metal 纹理资源 + 渲染指令”工作。Metal 里，一个 MTLTexture 是 GPU 上的图像数据，一个 MTLRenderPassDescriptor 描述了一次渲染的目标和加载行为，而 MTLRenderCommandEncoder 则是实际发出绘制命令的地方。
GPUImage3 把这三样东西封装进了自己的结构里。每个滤镜节点拿到上游的图像数据后，会创建或复用一张目标纹理，然后通过片段着色器对源纹理做采样，把结果写入目标纹理。源纹理和目标纹理可能指向同一张纹理，也可能不是，具体看内部是否做了 read-read 兼容。这个机制听起来简单，但整个框架的复杂点恰恰在于：如何管理这条链上所有纹理的生命周期，以及如何让多个滤镜节点像流水线一样连接起来。
所以，我的建议是学习 GPUImage3 时不要先去查它的类列表，而是先画一张图：输入端是什么对象，输出端是什么对象，中间滤镜靠什么连接。想清楚这张图，后面的代码都是围绕它展开的。
2. 框架核心抽象：一张图和一条链
2.1 ImageSource、ImageConsumer与ImageProcessingOperation
GPUImage3 里最基础的抽象不是某个类，而是两个协议：ImageSource 和 ImageConsumer。凡是能产生图像的节点，都遵循 ImageSource；凡是能接收图像的节点，都遵循 ImageConsumer。两个协议之间通过 addTarget 建立联系，GPU 图像数据就从源流向消费者。
滤镜作为中间节点，需要同时遵循这两个协议。框架里用 ImageProcessingOperation 协议把这两个能力组合起来。这样做的好处是：输入源、滤镜、输出目标都不需要继承同一个基类，任何对象只要实现协议就能挂到链上。我在代码里经常为了测试某个滤镜，直接把 PictureInput 接到 RawDataOutput，不需要额外写胶水代码，就是因为这套协议抽象非常干净。
从源码视觉看，核心连接机制是这样的：ImageSource 内部保存了一个 targets 容器，对外提供 addTarget、removeTarget 方法；当源节点生成了新的纹理，它会调用 targets 里每个 consumer 的 newTextureAvailable(_:from:) 方法。消费者收到纹理后，如果它自己还是源节点，就再往后转发给下一级。整个过程相当于把每个节点串成一条责任链。
2.2 Texture包装层：旋转与时间戳处理
GPU 上的 MTLTexture 只是一块像素资源，它不携带方向信息。但真实项目中，相机传上来的画面方向、前置摄像头镜像、用户手持角度等都会影响最终成像。GPUImage3 在 MTLTexture 外面包了一层 Texture，除了保存 texture 本体，还记录了 rotation 和 timestamp 等信息。
这个设计很有必要。图像接入链之后，每个节点都依据 Texture.rotation 来调整坐标采样。如果你自行封装输入源，只传 MTLTexture 不传 rotation，很容易出现画面旋转 90 度或上下颠倒。我自己最初写一个 CameraInput 接入链时，就因为没有设置正确的 orientation，导致输出到 RenderView 的画面是横着的，排查半天才发现不是滤镜问题，而是纹理方向没传对。
Texture 层还承担了统一格式约定的作用。它内部定义了自己的像素格式和颜色空间相关逻辑，让 GPUImage3 的内置滤镜不需要过度关心来自不同源的纹理格式差异。这个封装虽然简单，但属于框架中最容易被忽视的功臣。
2.3 滤镜链的构建与 target 容器
多数人使用 GPUImage3 时，会直接用自定义运算符来串链，例如 pictureInput --> saturation --> blur --> renderView。这个运算符最终会调用 addTarget，在源节点上注册消费者。如果你看源码，会发现 addTarget 的调用时机往往在下一帧处理前注册，而纹理推送发生在 newTextureAvailable 被调用的那一刻。
我特别想强调 target 容器的实现细节：一个源节点可以同时连接多个消费者，也就意味着同一帧纹理可以被多个分支消费。这在做对比测试时很实用：一路接到屏幕实时预览，另一路接到 RawDataOutput 做分析。但因为每条分支都会创建新的 render pass，GPU 负载也会相应增加，不能随便加分支。
从执行顺序上看，GPUImage3 的处理链基本上是串行调用每个消费者的 newTextureAvailable。也就是说，对同一帧而言，滤镜 A 处理完，图像数据同步传送给滤镜 B，然后 B 再处理。GPUCommandBuffer 的提交虽然发生在同一帧内，但 GPU 会有序执行这些 render encoder。理解了这一点，你就不会在调试时奇怪“为什么滤镜链里某一个节点会阻塞整条链”。
2.4 RenderContext：统一的Metal环境
GPUImage3 里的 RenderContext 是一个全局上下文对象，负责创建 MTLDevice、MTLCommandQueue，并加载默认 Metal library。几乎所有输入源、滤镜和输出目标都会用到它。这是框架里特别重要、却容易被新手忽略的一个类。
为什么需要一个全局上下文？因为 Metal 对象创建是有代价的，尤其是 MTLRenderPipelineState。它由着色器函数和渲染目标格式组合生成，一旦变量不符就要重新编译。如果每个滤镜各自创建 MTLDevice，或者每次都去编译 pipeline，性能会非常难看。GPUImage3 通过 RenderContext 统一环境，让多个滤镜可以共享 pipeline 缓存和命令队列。
在调用框架前，你需要确认自己的 Metal library 能被 GPUImage3 找到。GPUImage3 内置的着色器在一个 .metal 文件里，随框架一起编译；你自己的自定义滤镜 shader 可以写在项目目标里，通过库索引加载。如果你在自定义滤镜初始化时找不到函数，先检查 RenderContext 的 library 到底加载了哪个 Metal library。
3. 核心模块逐个拆解
3.1 输入源：PictureInput、CameraInput与MovieInput
输入源是所有处理链的起点。最常用的是 PictureInput，它接收 UIImage、CGImage 或者 CVPixelBuffer，在初始化时把这些数据转换成 MTLTexture。PictureInput 适合静态图片处理以及单元测试，使用起来很直接：创建对象，addTarget，然后调用 processImage。
实时相机场景对应的是 CameraInput，它封装了相机采集逻辑，并在每一帧捕获时把 CVPixelBuffer 转换为 Texture，然后广播给所有消费者。CameraInput 对内存处理比较敏感，因为它每秒钟要产生几十帧数据。GPUImage3 内部对 CVPixelBuffer 和 MetalTexture 之间的转换做了优化，但你还是应该在 AVCaptureVideoDataOutput 的代理回调里注意是否持有过久，否则内存会涨。
MovieInput 则面向视频文件，解码后一帧帧喂给处理链。它适合离线视频滤镜导出。从协议角度看，这三个输入源都只需要实现 ImageSource，所以你可以把 PictureInput 和 CameraInput 接到同一条滤镜链上，代码上完全一致。
3.2 滤镜节点：BasicOperation的封装逻辑
滤镜是框架中最核心的部分。GPUImage3 提供了一套基础类 BasicOperation，它封装了一个 vertex 函数、一个 fragment 函数、纹理输入绑定、uniform 更新和 render pass 的执行。继承 BasicOperation 后，你只需要指定 fragment 函数名，然后在 init 里给 uniform 设置初始值即可。
BasicOperation 内部做的事大致是：接收上游纹理后，把它绑定为 fragment 函数的 texture(0)，然后使用一个覆盖全屏的三角形或者矩形作为几何体，执行绘制。片段着色器对输入纹理逐像素采样，输出到目标纹理。由于它使用全屏几何体，不同尺寸的输入纹理都能被正确处理，你不需要关心图像分辨率的变化。
这种封装带来的最大价值是，自定义一个滤镜的代码量很小。一个简单的对比度调节滤镜，核心可能只有十几行 Swift 和一小段 Metal shader。这对做特效试错非常有帮助——想调滤镜参数，只需要改 uniform，不用碰渲染逻辑。
3.3 组合滤镜：OperationGroup与滤镜复用
实际开发中，很多效果不是单独一个滤镜能完成的。比如“复古感”可能要合并色彩调整、暗角、噪点多个步骤。GPUImage3 提供了 OperationGroup 或类似的容器概念，让你把一组滤镜包装成一个整体。
它的实现思路并不复杂：在容器内部维护一条子链，外部只暴露一个输入源和一个输出消费者。当你把容器挂到大处理链里，它对外表现就像单个滤镜。子链内部的中间纹理只在容器内部流转，外部无法感知。这样既实现了逻辑复用，又避免为了一个复合效果就污染主链的节点数量。
我用 OperationGroup 封装过一套“人像滤镜组”，把磨皮、饱和度、高光阴影统一放在一起。好处是主链只需一个节点，后续如果要调整整体强度，只需在组内做一个参数透传接口就行。如果不用容器，相同功能就得在 app 层维护一堆散落的滤镜对象，后期很难管理。
3.4 输出目标：RenderView、PictureOutput、RawDataOutput与MovieOutput
处理链的终点是输出目标。RenderView 继承自 MTKView，它实现了 ImageConsumer，可以直接把上游纹理渲染到屏幕。它内部会把纹理和目标 drawable 关联起来，等当前帧的渲染指令完成后呈现在窗口上。
如果你想保存处理结果，PictureOutput 会在 finalTexture 可用时回调一个 UIImage 或闭包。这种输出适合离屏渲染场景，比如批量处理图片。需要注意，不要在回调里直接调用 UIKit 的同步 UI 操作，否则可能阻塞 GPU 编码线程。
RawDataOutput 则是把 GPU 纹理像素读回 CPU 的对象。它适用于机器学习推理或生成原始像素字节。但同步读取 texture 的 getBytes 会打断 CPU 与 GPU 的并行流水线，非常耗时。我建议在非实时场景使用，并尽量降低回读频率，或者异步等待 GPU 工作完成后再读取。
MovieOutput 用于把处理链实时写入视频文件，通常跟 CameraInput 配对使用，完成直播或录制特效视频。
4. 实操：从零搭一条完整处理链
4.1 最小工程搭建
我在新工程里搭 GPUImage3 时，会先只连一条最简单的链：从 PictureInput 到 PictureOutput，确保框架安装和上下文初始化没问题。步骤大概是这样：
- 用包管理工具把 GPUImage3 引入项目。
- 创建一个 RenderContext 实例，或者直接使用框架预设的共享上下文。
- 创建 PictureInput，传入测试图片。
- 创建饱和度滤镜 HeightSaturationAdjustment（示例写法，以实际版本为准），设置一个初始参数。
- 创建 PictureOutput，设置回调，在回调里拿到生成图片。
- 用 addTarget 把 PictureInput、滤镜、PictureOutput 串起来。
- 调用 PictureInput 的 processImage 触发处理。
这段流程虽然简单，但能够验证整个框架是否正常工作。如果图片能正常输出，后面再换 CameraInput 或者 RenderView 也不会出太大问题。我在实际项目中，凡是遇到莫名其妙的黑屏，都会先回到这条最小链路做隔离，效率比瞎猜高很多。
4.2 自定义一个对比度滤镜
以对比度滤镜为例，虽然框架内置了类似的，但我们自己实现一遍能加深理解。代码如下：
import GPUImage3 final class ContrastFilter: BasicOperation { var contrast: Float = 1.0 { didSet { uniformSettings["contrast"] = contrast } } init() { super.init(fragmentFunctionName: "contrastFragment", numberOfInputs: 1) uniformSettings["contrast"] = 1.0 } }对应的 Metal 着色器片段如下：
#include <metal_stdlib> using namespace metal; struct VertexOutput { float4 position [[position]]; float2 texCoord; }; fragment half4 contrastFragment(VertexOutput in [[stage_in]], texture2d<half> sourceTexture [[texture(0)]], constant float &contrast [[buffer(0)]]) { constexpr sampler s(coord::normalized, address::clamp_to_edge, filter::linear); half4 color = sourceTexture.sample(s, in.texCoord); color.rgb = clamp((color.rgb - half3(0.5)) * contrast + half3(0.5), 0.0h, 1.0h); return color; }这里需要解释几个细节。顶点着色器由框架提供，所以你只写片段着色器就行了。sourceTexture 使用 texture(0)，对应第一个输入。contrast 使用 buffer(0)，这是 GPUImage3 约定好的 uniform 存储位置。BasicOperation 会把 uniformSettings 里的值写入这个 buffer，所以 Swift 侧只要更新 uniformSettings["contrast"]，Metal 侧就能读到最新值。片段着色器里做了一个标准对比度映射：先减 0.5，乘强度，再加 0.5，最后 clamp 到合法范围。
我在自定义滤镜时最容易犯的错是忘记把 numberOfInputs 改大，导致多个纹理输入时只能采样到第一张。如果你要做双输入，比如 lookup 滤镜，必须先把 numberOfInputs 设置为 2，然后在片段着色器里用 texture(1) 采样第二张纹理。
4.3 多滤镜串联与观察帧耗时
多条滤镜链的代码和单条类似，只是 addTarget 会连接更多节点。我建议每条链画出一个清晰的 DAG，尤其当存在分支时，要思考 GPU 工作负载的变化。举个例子：
let pictureInput = PictureInput(image: image) let colorFilter = SaturationAdjustment() let blurFilter = GaussianBlur() let output = RawDataOutput() pictureInput.addTarget(colorFilter) colorFilter.addTarget(blurFilter) blurFilter.addTarget(output) pictureInput.processImage()每多一个滤镜，就意味着多一次纹理的写出和写入。10 个滤镜组成的链，GPU 可能要处理超过 10 个全屏三角形 pass。用 Instruments 的 Metal Diagnostics 或者 Xcode 的图形调试器可以看到每个 pass 的耗时时序。我自己的经验是，当帧耗时主要卡在 fragment 阶段时，优先考虑减少滤镜数量或者合并着色器，而不是盲目降低纹理分辨率。
4.4 实时相机滤镜链一例
相机实时滤镜链一般是这样的：CameraInput 采集画面，经过滤镜链，最后连到 RenderView。关键点在于相机的视频方向设置。在启动相机采集时，你要根据设备方向调整。GPUImage3 的纹理方向信息会跟随每一帧传给后续节点，所以只要 CameraInput 提供了正确方向，RenderView 就能正常显示。
我还习惯把相机前后切换的镜像逻辑放在输入源层级处理，而不是滤镜层。因为镜像开关本质上影响的是纹理方向，放到输入源处理会让滤镜统一不用关心前置后置差异。如果你发现切换前置摄像头后画面整体反转，检查是否有类似 mirror 的参数需要设置。
实时链路中不要在主线程做重活。CameraInput 的回调可能来自相机队列，如果你在这条队列里同步等待 GPU 读取或者发生锁等待，视频帧率会很差。建议回调里只做纹理转换和 addTarget 转发这类短操作，耗时计算放异步队列。
5. 常见问题与排查技巧实录
5.1 画面全黑的常见原因
黑屏是 GPUImage3 新手遇到最多的问题。原因往往不是框架坏了，而是输出目标没有真正收到纹理。排查顺序我从经验上排一下：先确认 RenderView 是否成功连到了链的末端；再确认输入源确实调用了 processImage；再看滤镜是否设置了有效的 fragment 函数名；最后检查渲染上下文是否在正确的 Metal library 中能找到着色器。
我曾经碰到过一次黑屏，就是因为自定义 shader 编译失败，但错误信息没有被明显抛出来。BasicOperation 初始化和渲染时并不会每帧都检查 pipeline 是否创建成功。你需要在初始化后立即访问相关属性，或者打开框架的日志输出，否则黑屏只表现为一片空白，非常难查。
5.2 纹理方向与镜像处理
纹理方向问题不会导致崩溃，但会让画面“翻转 90 度”或“镜像”。这类问题绝大多数出在 Texture.rotation 上。如果你自定义输入源，要从 CVPixelBuffer 创建 Texture 时显式记录方向；如果你只是使用内置 CameraInput，则要设置好相机输出的图像方向。
另外注意 GPUImage3 滤镜链里的旋转是累积的。如果滤镜 A 把图像旋转 90 度，滤镜 B 不知道，继续按照自身逻辑采样，结果可能又转 90 度。所以我在写自定义滤镜时，会统一在片段着色器里根据传入的 texCoord 处理旋转，而不是修改底层纹理。
5.3 性能突然卡顿和内存升高
性能问题的第一嫌疑是中间纹理的过度分配。每张纹理在 GPU 上都占据着显存，滤镜链越长，同一时刻被保存的纹理越多。如果你发现处理链的内存占用随着运行时间只升不降，可能是某个输入源每帧都创建了新 Texture，而没有走缓存池。
第二个嫌疑是 RawDataOutput 的同步回读。GPU 的并行属性会被 getBytes 打断，因为你必须等待 GPU 写入完成才能拷贝数据。避免在每一帧都调用 read 外，还可以只对关键帧做回读，比如用户按下快门的瞬间。
如果内存没有上涨但帧率下降，可能不是内存，而是你在相机回调里做了耗时的 CPU 逻辑。用 Instruments 的 Time Profiler 能看到具体是哪个方法占用高。我遇到过最夸张的一次是回调里写日志，结果每帧都磁盘 IO，整个链路直接卡成幻灯片。
5.4 线程安全与生命周期
GPUImage3 的链在回调线程中被持续调用，所以要注意不要在后续节点里随意使用 UIKit 控件，除非你保证回调也在主线程。部分框架版本会在主线程渲染视图，但不会自动帮你切换队列。
还有一个常见的生命周期坑：处理链持有输入源，输入源持有目标，如果形成一个 retain cycle，对象永远不会释放。我在某个版本遇到过相机不停止导致 App 内存一直涨的情况，后来确认是 AVCaptureSession 没有在控制器释放时停掉。建议在 viewWillDisappear 或 deinit 里显式调用输入源的停止方法，并断开 addTarget。
5.5 问题速查表
| 症状 | 常见原因 | 排查与解决办法 |
|---|---|---|
| 画面全黑 | 链没连到底，或 shader 编译失败 | 从末端往前检查 addTarget，查看编译日志 |
| 画面旋转或镜像 | Texture.rotation 错误 | 设置输入源方向，避免滤镜层二次旋转 |
| 帧率低 | 滤镜链过长，回读频繁 | 合并着色器，减少 RawDataOutput 回读 |
| 内存持续上涨 | 输入源未释放，纹理未复用 | 停止相机，断开链，检查对象释放 |
| 自定义滤镜无效果 | uniform 更新时机不对 | 在 init 中注册默认值，每次参数变化更新 uniformSettings |
| 自定义 shader 没生效 | Metal library 加载错 | 确认 RenderContext 的 library 包含自定义函数 |
6. 性能优化进阶：让滤镜链更快
6.1 减少中间纹理：能合并就合并
如果你只是想在图片上应用多个特效，最直接的性能优化是写一个组合 shader，把多个片段操作放在同一个 fragment 函数里完成。这样一张中间纹理都不需要，render pass 直接从一次变成一次。比如饱和度、对比度、亮度都可以在一个 shader 里同时作用。
我在一次测试里，把七层滤镜合成的链改成一个单独 shader，帧时间几乎减少了一半。代价是代码复用性下降，因为组合逻辑写死在一个 shader 里。我的建议是开发阶段保持独立滤镜便于调参，到性能调优阶段再把稳定方案合并成一个专用滤镜。
6.2 在自定义节点里灵活使用Metal能力
GPUImage3 并不会限制你只能用 BasicOperation。只要符合协议，你完全可以写一个自定义节点，内部用零散的 Metal API 完成计算，比如调用系统内置的能力或自定义计算管线。这也意味着你可以把 Metal 的强项，比如 compute kernel，集成到 GPUImage3 的处理链里，做一些传统 fragment shader 比较难写的效果，例如直方图统计或者 gaussian pyramid。
这种做法适合对 Metal 比较熟的人。它的好处是绕开框架的高层封装，直接在节点中控制 MTLComputeCommandEncoder，同时仍享受外层链的纹理流转。我做过一个基于计算着色器的局部模糊节点，性能比同等的 fragment shader 更好，因为计算管道可以更灵活地处理相邻像素。
6.3 减少纹理尺寸
当你的处理目标是屏幕展示，而输入源是 4000x3000 的大图时，把链上每一帧都处理这么大并不划算。首先考虑在输入层做缩放，比如 PictureInput 初始化时就把图片缩放到目标尺寸。或者在相机预览时采用更低的 videoResolution 配置。
我遇到的实际场景是图片美化功能：原图可能很大，但预览区只有几百 pt。处理链如果从大图开始，不仅显存占用高，时间开销也大。合理做法是先缩略图预览，真正导出时再用大图跑一次完整链。这里要注意，链上每个滤镜的 uniform 参数，比如 blur radius，要根据分辨率做适配，不能直接共用直线式数值。
6.4 合理利用异步渲染
渲染线程与主线程分离是 Metal 的天然优势。GPUImage3 的很多操作已经异步化，但你的代码里容易破坏它的地方在于：在主线程同步等待 PictureOutput 回调，或者在 CameraInput 回调里调用了主线程更新。想要帧率高，就让链接收帧的逻辑保持非阻塞。
我建议把 PictureOutput 的回调放到自定义队列，拿到结果后集中更新 UI。CameraInput 的回调里尽量不做业务决策。只要你让 GPUImage3 的链保持“接收帧、编码指令、提交”的节奏，大部分性能问题都能避免。
7. 我对框架整体理解的一点收尾
我自己最开始学习 GPUImage3 时，总想一口气看完所有类，结果是越看越乱。后来换了个角度，把整个框架拆成“输入源—滤镜链—输出目标”这根主心神，再去理解每一个类在其中扮演的角色，瞬间清晰很多。GPUImage3 真正核心的并不是某个具体滤镜，而是那套允许任意对象接入同一链路的协议设计，以及背后对 Metal 渲染管线的封装。
在实际使用中，我还有一个习惯：拿到需求后先把处理流程画成一个图，标出哪些节点是输入源、哪些是滤镜、哪些是分支、哪些是输出。画完图再写代码，基本不会出现结构混乱。GPUImage3 的框架虽然涉及不少 Metal 概念，但只要理解了“纹理从哪儿来、render pass 在哪儿发生、结果往哪儿去”这三个问题，剩下的都是查 API 和调参数的事。希望这篇拆解能帮你少踩几个坑，尤其是黑屏和方向问题，这些都是我亲测最浪费时间的地方。
