4、SDK架构初探：核心模块与设计哲学
拿到一个工业相机SDK，很多人第一反应就是翻demo、抄代码。我刚开始也这样，结果项目一复杂，代码就成了一团乱麻。后来我花了点时间把SDK的骨架摸清楚，才发现——搞懂架构，比背API重要十倍。
这一章，我们就来拆解SDK的四个核心模块，聊聊它的设计思路，再看看事件驱动模型到底是怎么回事。
4.1 SDK核心模块：四个支柱
不管哪家厂商的SDK，底层逻辑都差不多。我把它归纳为四个模块：
| 模块 | 核心职责 | 典型API |
|---|---|---|
| 设备枚举 | 发现总线上的相机，获取设备信息 | EnumDevices(), GetDeviceInfo() |
| 连接控制 | 打开/关闭设备，管理会话生命周期 | Open(), Close(), IsConnected() |
| 采集回调 | 启动/停止图像流，注册数据回调 | StartGrabbing(), RegisterImageCallback() |
| 参数配置 | 读写相机属性，如曝光、增益、ROI | SetFloatValue(), GetEnumValue() |
这四个模块，就是SDK的四个支柱。你想想看，任何二次开发，本质上都是在跟这四个东西打交道。
4.1.1 设备枚举：找到你的相机
设备枚举是第一步。SDK会扫描所有可用的总线接口——USB、GigE、CoaXPress等等，然后返回一个设备列表。
我在项目中遇到过一个问题：同一台相机，用USB3.0线连上，枚举出来是“Camera A”；换了一根线，变成了“Camera B”。后来才发现，设备枚举依赖的是硬件序列号，不是物理端口。所以，千万别用端口号来标识相机，要用序列号。
4.1.2 连接控制：打开与关闭的艺术
连接控制看似简单，就是Open和Close。但这里有个坑：资源释放的顺序。
我曾经在一个产线项目里，因为先调了Close()再释放回调资源，导致程序崩溃。原因是回调线程还在跑，但设备句柄已经失效了。正确的做法是：
- 先停止采集（StopGrabbing）
- 再注销回调（UnregisterCallback）
- 最后关闭设备（Close）
这个顺序，我建议你写成代码注释，每次调用前看一眼。
4.1.3 采集回调：数据的生命线
采集回调是SDK里最核心的模块。相机采集到一帧图像后，SDK会通过回调函数把数据交给你。
回调函数是在SDK内部线程里执行的。这意味着：
- 不要在回调里做耗时操作（比如保存图片到硬盘）
- 不要在回调里加锁，容易死锁
- 回调里只做数据拷贝，然后丢到自己的队列里
4.1.4 参数配置：控制相机的每一寸
参数配置模块，说白了就是读写相机寄存器。SDK把它封装成了属性节点（Node）的形式。
常见的参数类型有：
- 整数型： 比如宽度、高度
- 浮点型： 比如曝光时间、增益
- 枚举型： 比如触发模式、像素格式
- 布尔型： 比如是否开启自动曝光
- 字符串型： 比如设备序列号
这里有个容易忽略的点：参数之间有依赖关系。比如，你设置了ROI，那么宽度和高度会自动变化。如果你先设宽度再设ROI，顺序反了，可能就会报错。
4.2 API设计哲学：为什么SDK长这样？
很多人觉得SDK的API设计得很“绕”。其实，它背后有一套设计哲学。
第一，统一性。 不管你是USB相机还是GigE相机，API接口都是一样的。这就是为什么SDK里会有“设备信息”这个结构体——它把不同总线的差异都封装起来了。
第二，异步性。 相机采集是硬件行为，不能阻塞主线程。所以SDK大量使用回调、事件、异步函数。你想想看，如果StartGrabbing()是同步的，那你的程序就得卡在那里等图像回来，多可怕。
第三，容错性。 工业相机经常掉线、断流。SDK的设计会尽量保证：设备断开时，回调能收到错误码，而不是直接崩溃。
4.3 事件驱动模型：SDK的“心脏”
事件驱动模型，是SDK内部运转的核心机制。说白了，就是“有事通知你，没事别打扰”。
SDK内部维护了一个事件循环。当硬件产生数据、发生错误、或者状态变化时，SDK会生成一个事件，然后调用你注册的回调函数。
这个模型的好处很明显：
- 低延迟： 事件一来，立刻处理
- 低资源占用： 没有轮询，CPU不空转
- 解耦： 你的业务逻辑和SDK内部逻辑是分离的
但坏处也有：回调地狱。如果事件太多，回调嵌套太深，代码会变得很难调试。
我建议的做法是：把事件驱动模型和状态机结合起来。比如，定义一个“空闲-采集-错误”的状态机，每个事件触发状态切换，这样逻辑就清晰多了。
4.4 避坑指南：我踩过的那些坑
最后，分享几个我实际项目中踩过的坑，希望能帮你省点时间。
我曾经在回调里直接调用OpenCV的imshow()，结果界面卡死。原因是imshow()需要GUI线程，而回调在SDK线程里。正确做法是把图像数据拷贝出来，通过信号/槽机制发给UI线程。
有一次，我同时枚举4台相机，结果只找到了3台。排查后发现，枚举函数不是线程安全的。多线程环境下，要给枚举操作加锁。
设置曝光时间后，读回来还是旧值。后来发现，有些参数需要先调用“提交”或“应用”接口才会生效。SDK文档里写的是“异步参数”，我一开始没注意。
嗯，这一章的内容就到这里。SDK的架构，说白了就是“硬件-驱动-事件-回调”这条链。搞懂了它，后面的开发就会顺畅很多。