简介面向佳能相机二次开发的Windows开发者资源基于官方EDSDK封装出统一的C语言接口涵盖初始化与反初始化、拍照与录像、实时取景预览、自动对焦与调焦、属性读取设置以及事件回调等常用能力可有效降低直接调用官方SDK的复杂度减少底层适配工作适用于工业检测、视频采集、摄影自动化控制等场景。压缩包共14个文件其中6个h头文件声明对外接口4个dll与2个lib构成运行和链接环境另有2个c文件给出封装实现及调用示例整体约866KB便于快速集成到开发工程。已有600人学习下载。通过这套封装开发者可直接使用HalfShutterAFC、TakePicture、StartVideo、DownloadEvfImage、AutoFocus等现成接口免去重复编写相机事件回调与属性控制逻辑的麻烦并可根据需要自行扩展是接入佳能单反/微单时较为轻量的参考实现也便于学习EDSDK调用流程。1. 封装的边界为什么需要再包一层 EDSDK工位上一台工控机拖四台佳能相机做视觉采集上位机一半 C 一半 Python。直接把官方 EDSDK 的 EdsCamera 对象、事件回调和内存流接口铺到业务代码里结果就是线程打架、内存释放时机不清楚、换台机身就要重调一遍。我拆过几套相机控制工程多数人的问题不是不会调 EDSDK而是要反复重写初始化、回调分发、文件落地这些琐碎逻辑。这个工程把 C 接口的 EDSDK 再包一层对外只留 Init、TakePicture、StartLiveView 这类精简 API回调统一收敛成函数指针数组按相机索引分发。适合做视觉采集、自动化测试台和摄影器材控制的二次开发把这层封装设计好迭代效率能差出一倍以上。2. EDSDK 事件模型与回调分发封装2.1 三类事件回调的注册时机EDSDK 是典型的事件驱动模型相机上的属性变更、文件生成、快门动作都会触发回调。官方提供了三组注册接口EdsSetPropertyEventHandler、EdsSetObjectEventHandler、EdsSetStateEventHandler分别对应属性事件、对象事件和状态事件。原始接口的回调参数里既有 EdsObject 又有事件 ID业务层每次都要做一次类型转换和相机对象匹配这是重复代码最集中的地方。这次接口封装的核心不是把 C 转成 C而是把事件接口封装成可替换的回调槽。工程里定义了三个函数指针数组每个数组按相机索引 MAX_CAMERA 分配槽位回调注册时把相机索引作为 EdsVoid* inContext 传进去SDK 触发时直接从 context 还原索引省掉对象比对。typedef void (*PROPERTYEVENT_CALLBACK)(EdsUInt32 inEvent, EdsUInt32 inPropertyID, EdsUInt32 inParam); typedef void (*OBJECTEVENT_CALLBACK)(EdsUInt32 inEvent); typedef void (*STATEEVENT_CALLBACK)(EdsUInt32 inEvent, EdsUInt32 inParam); static PROPERTYEVENT_CALLBACK g_property_callback[MAX_CAMERA]; static OBJECTEVENT_CALLBACK g_object_callback[MAX_CAMERA]; static STATEEVENT_CALLBACK g_state_callback[MAX_CAMERA]; static EdsError EDSCALLBACK propertyEventHandler( EdsObject inObject, EdsUInt32 inEvent, EdsUInt32 inPropertyID, EdsUInt32 inParam, EdsVoid* inContext) { (void)inObject; // 回调里不再做对象匹配 EdsUInt16 index (EdsUInt16)(EdsIntPtr)inContext; // 从 context 还原相机索引 if (g_property_callback[index] ! NULL) g_property_callback[index](inEvent, inPropertyID, inParam); return EDS_ERR_OK; }context 传索引的做法比遍历相机列表做匹配快也避免了在回调里调用 EdsGetChildAtIndex 这种非线程安全的函数。注意回调是在 EDSDK 内部线程执行的外部函数指针里不要做文件写入、UI 刷新这类耗时操作只做标记和入队。同样逻辑的 objectEventHandler 和 stateEventHandler 分别绑到 g_object_callback 和 g_state_callback 上注册时机放在 Init 函数完成相机枚举之后。2.2 事件队列化与 GetEvent 轮询EDSDK 的线程模型要求应用侧周期调用 EdsGetEvent() 来驱动内部事件循环否则回调会饥饿甚至丢失事件。封装层把这一步收敛成公开的 GetEvent() API内部先调 EdsGetEvent()再把队列里堆积的用户事件分发出去。队列用环形缓冲实现避免回调线程里动态分配内存。#define EVENT_QUEUE_SIZE 256 static EdsUInt32 g_event_queue[EVENT_QUEUE_SIZE]; static volatile int g_event_head 0, g_event_tail 0; static void EnqueueEvent(EdsUInt32 inEvent, EdsUInt32 inParam) { int next (g_event_tail 1) % EVENT_QUEUE_SIZE; if (next g_event_head) return; // 队列满丢弃事件 g_event_queue[g_event_tail] (inEvent 16) | (inParam 0xFFFF); g_event_tail next; } EDSDK_API EdsError GetEvent() { EdsError err EdsGetEvent(); // 驱动 EDSDK 内部事件循环 while (g_event_head ! g_event_tail) { EdsUInt32 packed g_event_queue[g_event_head]; g_event_head (g_event_head 1) % EVENT_QUEUE_SIZE; // 解包后分发到用户注册的 callback DispatchEvent((EdsUInt32)(packed 16), (EdsUInt32)(packed 0xFFFF)); } return err; }队列满时选择丢弃而不是阻塞是因为 EDSDK 回调线程不能长时间挂起丢一个属性刷新的中间态不影响最终状态文件生成这类关键事件靠后续的查询兜底。GetEvent 必须在主控制循环里每 10ms 调用一次和相机通信频率保持一致调用间隔超过 100ms 时连拍场景会明显丢事件。2.3 三类事件的典型处理场景事件类型触发场景常用处理kEdsCameraEvent_PropertyChanged光圈、ISO、白平衡变化刷新属性缓存同步上层 UIkEdsCameraEvent_ObjectCreated拍摄或录像完成文件落在相机存储置位文件就绪信号触发下载kEdsCameraEvent_Shutdown相机休眠、断电或 USB 断开标记掉线执行清理流程事件分发封装好后上层业务只需要填三个函数指针不需要感知 EDSDK 的线程模型。这个设计对 Python 侧尤其友好ctypes 只认 C 函数指针C 回调转 Python 回调只需要一层 trampoline。3. 拍照、录像与实时预览命令封装与状态机3.1 两段式快门与对焦触发EDSDK 的快门命令通过 kEdsCameraCommand_ShutterButton 发送参数有 Halfway 和 Completely 两个状态。半按用于触发自动对焦和测光完全按下才真正曝光。封装层把半按收敛成 HalfShutterAFC把完整拍照流程收敛成 TakePicture两者组合可以应对大部分机型的对焦延迟问题。EDSDK_API EdsError HalfShutterAFC(EdsUInt16 index) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 半按快门触发 AF 与测光不曝光 return EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Halfway); } EDSDK_API EdsError TakePicture(EdsUInt16 index, char** path) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 先半按让机身完成对焦和测光停顿由调用方控制 EdsError err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Halfway); if (err ! EDS_ERR_OK) return err; // 完全按下触发曝光 err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Completely); if (err ! EDS_ERR_OK) return err; // 释放快门回到取景状态 err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_OFF); if (err ! EDS_ERR_OK) return err; // 等待 ObjectCreated 事件后回收文件并回填 path return WaitAndDownloadFile(index, path); }半按到全按之间必须有间隔实测大多数单反在 100ms 之内完成对焦会返回 EDS_ERR_DEVICE_BUSY建议在外部循环里控制半按持续时间。TakePictureNoAF 的实现就是把前半段 Halfway 去掉直接发 Completely适合已经锁焦的连拍场景。WaitAndDownloadFile 内部用 kEdsCameraEvent_ObjectCreated 作为同步信号事件没到就轮询超时超时时间建议 5s超过 10s 基本可以判定相机卡写存储卡。拍照命令映射关系如下封装 API底层命令/属性关键参数HalfShutterAFCkEdsCameraCommand_ShutterButtonHalfwayTakePictureHalfway → Completely → OFF两段式触发TakePictureNoAFCompletely → OFF跳过对焦直接拍StartVideokEdsCameraCommand_MovieStart需先处于录像模式StopVideokEdsCameraCommand_MovieStop停止后等文件事件3.2 录像命令与文件回收延迟录像的 StartVideo 和 StopVideo 在 EDSDK 里也是命令而非属性但前置条件是相机必须处于录像模式。很多人在非录像模式下直接发 MovieStart 得到 EDS_ERR_DEVICE_BUSY原因就是漏了模式切换。正确的顺序是先调 SetDevMode 切到录像模式等待属性事件稳定再发 MovieStart。停止录像后文件回收比拍照慢因为相机需要封口 MP4 容器普遍要等 1 到 2 秒。StopVideo 内部不要立刻拉流而是开启一个 3 秒的超时窗口等待 ObjectCreated。文件回收阶段用 EdsCreateFileStream 创建本地文件流参数要带 kEdsFileCreateDisposition_CreateAlways否则重复文件名会直接报错。3.3 实时预览与内存流生命周期实时预览走的是独立通道StartLiveView 先设置 kEdsPropID_Evf_Mode 为 1然后周期性调 DownloadEvfImage 拉一帧 YCbCr 数据。和拍照文件下载不同预览帧不需要落地成文件直接用内存流承接避免频繁创建临时文件。EDSDK_API EdsError DownloadEvfImage(EdsUInt16 index, void** pointer, EdsUInt64* length) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; EdsStream stream NULL; EdsError err EdsCreateMemoryStream(0, stream); // 0 表示先分配 0 字节按需增长 if (err ! EDS_ERR_OK) return err; err EdsGetEvfImage(camera, stream); // 拉取当前取景器图像 if (err EDS_ERR_OK) { EdsGetPointer(stream, pointer); // 拿到内存流内部缓冲区指针 EdsGetLength(stream, length); // 拿到有效数据长度 } else { EdsRelease(stream); } return err; }这里有个明显的坑EdsGetPointer 返回的是流内部的缓冲区地址不是拷贝出来的独立内存。调用方用完这个指针后必须由封装层负责释放 stream而且释放顺序有讲究先释放 stream 再使用 pointer 就是悬垂指针。工程里的做法是约定 caller 只读不释放下一次 DownloadEvfImage 调用时内部先释放上一帧的流保证同时只有一帧流存活。拉取预览帧的间隔控制在 33ms 到 50ms 之间太快会导致相机端 Buffer 溢出返回 EDS_ERR_OBJECT_NOTREADY。4. 属性读写与模式切换从 EdsPropertyID 到业务语义4.1 通用属性读写的实现EDSDK 的属性接口比较原始读属性前要先查属性大小再调 EdsGetPropertyData 按字节拷贝。不同属性的数据宽度还不一致光圈是浮点编码ISO 和色温是整数白平衡是枚举。把这些细节压平成一个 GetProperty是提升使用体验的关键一步。EDSDK_API EdsError GetProperty(EdsUInt16 index, EdsPropertyID propertyID, EdsUInt32* data) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 第一步查询目标属性的字节大小 EdsUInt32 size 0; EdsError err EdsGetPropertySize(camera, kEdsPropID_PropertySize, 0, propertyID, size); if (err ! EDS_ERR_OK) return err; // 不支持或当前模式不可用 // 第二步按查询结果读取实际数据统一放到 4 字节容器里 return EdsGetPropertyData(camera, propertyID, 0, size, data); }EdssGetPropertySize 的第一个参数传 kEdsPropID_PropertySize 是 EDSDK 的标准技巧表示查询的是第二个参数那个属性的尺寸。如果属性当前不可用函数会返回 EDS_ERR_PROPERTIES_UNAVAILABLE这个错误不应该被当作致命错误很多属性在录像模式下是只读的。SetProperty 的对称实现要先看属性是否可写可以先用 kEdsPropID_PropertySize 查一遍能查到大小再写能少踩一半的通信超时。4.2 模式切换与派生语义直接暴露 EdsPropertyID 给业务层的后果是每个调用方都要记住一堆 0x000000xx 的宏所以封装层基于基础属性接口派生了四个语义明确的接口。SetDevMode 切换拍照与录像模式SetMovieAEMode 控制录像时的自动曝光模式SetAFMode 配置对焦模式剩下的属性走通用的 SetProperty。EDSDK_API EdsError SetDevMode(EdsUInt16 index, eCameraMode mode) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 拍照/录像切换在多数机型上是一条命令而非属性 EdsUInt32 cmd (mode kCameraMode_Movie) ? kEdsCameraCommand_MovieSelectSwON // 切换到录像模式 : kEdsCameraCommand_MovieSelectSwOFF; // 切回拍照模式 EdsError err EdsSendCommand(camera, cmd, 0); if (err ! EDS_ERR_OK) { // 部分无反相机没有这条命令回退到 SaveTo 属性切换 return EdsSetPropertyData(camera, kEdsPropID_SaveTo, 0, sizeof(EdsUInt32), (EdsUInt32){ mode kCameraMode_Movie ? 1 : 0 }); } return err; }eCameraMode 是封装层自己定义的枚举值和按键指令对齐调用方不用去理解 MovieSelectSwON 和 OFF 的区别。切换模式后要等 kEdsCameraEvent_PropertyChanged 事件确认切换完成立刻拉取属性列表会拿到切换前的值这是模式切换最隐蔽的时序问题。SetMovieAEMode 和 SetAFMode 的底层实现都走通用的 SetPropertyData但枚举值域是独立的SetMovieAEMode 在非录像模式下调用会返回属性不可用调用方需要先确认当前设备模式。派生接口底层实现值域与说明SetDevModeMovieSelectSwON / MovieSelectSwOFF先切换模式再发录像命令GetDevMode内部模式缓存由 PropertyChanged 事件维护SetMovieAEModekEdsPropID_MovieAEProgram / Tv / Av / ManualSetAFModekEdsPropID_AFModeOneShot / AI Servo / ManualSetPropertyEdsSetPropertyData光圈、ISO、白平衡等4.3 属性缓存与事件回推属性回调触发的时机比属性写入晚几十毫秒如果上层同步读属性很可能拿到旧值。封装层在这个增强接口封装里做了一层属性缓存SetProperty 时先写缓存再发指令PropertyChanged 事件到达后用事件里的属性 ID 更新缓存并调用回调函数通知业务层。GetProperty 优先返回缓存缓存缺失时才走底层读取。缓存要区分相机索引每个 index 独立维护一份属性表。机身参数、镜头参数混在一个表里时会互相覆盖特别是焦距和光圈这类随镜头变化的属性建议按 kEdsPropID_LensID 分组存属性 ID 冲突时以最后一次事件为准每个属性再带一个时间戳读取时超过 5 秒未更新的缓存强制走真实通信。5. 多相机索引、内存释放与稳定性验证技巧5.1 索引到相机的两层映射Init(EdsUInt16 index) 里的 index 不是 USB 端口号而是 EDSDK 枚举出的相机序号。封装层只维护一个静态数组 g_camera[MAX_CAMERA]Init 时用 EdsGetCameraList 拿到相机列表再按 index 取出对应对象。枚举顺序不保证和 USB 口顺序一致同一台相机的枚举位置会随开机顺序变化所以工程里必须把相机的 kEdsPropID_ProductName 和序列号也拉出来缓存上层按序列号分配业务槽位。static EdsCamera* g_camera[MAX_CAMERA]; EDSDK_API EdsError Init(EdsUInt16 index) { if (index MAX_CAMERA) return EDS_ERR_DEVICE_NOT_FOUND; EdsCameraList list NULL; EdsError err EdsGetCameraList(list); // 枚举当前连接的相机列表 if (err ! EDS_ERR_OK) return err; err EdsGetChildAtIndex(list, index, g_camera[index]); // 按索引取相机对象 if (err EDS_ERR_OK) { EdsInitializeSDK(); // 初始化 SDK重复调用是安全的 err CreateCameraSession(index); // 打开会话并注册回调 } return err; }UnInit 的对称逻辑要先把事件回调置空再终止会话最后才调用 EdsTerminateSDK。顺序反了会在 SDK 释放后收到回调产生野指针。断线重连的场景里旧索引不能直接复用要先调 EdsGetCameraList 重新枚举再用序列号匹配新索引匹配上以后把索引映射表更新掉。5.2 文件路径与内存释放的约定TakePicture 和 StopVideo 的 char** path 是封装层 malloc 出来的调用方用完后必须 free。文件名规则由封装层统一生成格式是 IMG_YYYYMMDD_HHMMSS_%02d.CR2%02d 是相机索引。不要直接把 EDSDK 返回的设备文件名透传出去不同相机的命名规则差异太大统一格式可以省掉后续解析的麻烦。录像文件同理封装层只负责把相机存储卡上的文件下载完落盘后回填路径。5.3 无真机时的桩验证没有相机在手边时把 EdsSendCommand 和 EdsGetPropertyData 打桩成可替换的函数指针上层代码跑在 mock 层上。桩函数预置一套属性表拍照命令直接触发一个假的 ObjectCreated 事件让 WaitAndDownloadFile 的完整流程跑通。真机上容易出问题的都是文件下载逻辑写一个最小测试程序只做拍照和取图连续跑 200 次确认无内存泄漏比在业务里排查快得多。文件路径生成逻辑最好单独抽成纯函数输入时间戳索引输出路径用普通单测覆盖再把真机回收文件的下载调用单独验证路径拼接的坑基本就堵死了。本文还有配套的精品资源点击获取
EDSDK相机控制二次开发：回调封装与多相机管理实践
简介面向佳能相机二次开发的Windows开发者资源基于官方EDSDK封装出统一的C语言接口涵盖初始化与反初始化、拍照与录像、实时取景预览、自动对焦与调焦、属性读取设置以及事件回调等常用能力可有效降低直接调用官方SDK的复杂度减少底层适配工作适用于工业检测、视频采集、摄影自动化控制等场景。压缩包共14个文件其中6个h头文件声明对外接口4个dll与2个lib构成运行和链接环境另有2个c文件给出封装实现及调用示例整体约866KB便于快速集成到开发工程。已有600人学习下载。通过这套封装开发者可直接使用HalfShutterAFC、TakePicture、StartVideo、DownloadEvfImage、AutoFocus等现成接口免去重复编写相机事件回调与属性控制逻辑的麻烦并可根据需要自行扩展是接入佳能单反/微单时较为轻量的参考实现也便于学习EDSDK调用流程。1. 封装的边界为什么需要再包一层 EDSDK工位上一台工控机拖四台佳能相机做视觉采集上位机一半 C 一半 Python。直接把官方 EDSDK 的 EdsCamera 对象、事件回调和内存流接口铺到业务代码里结果就是线程打架、内存释放时机不清楚、换台机身就要重调一遍。我拆过几套相机控制工程多数人的问题不是不会调 EDSDK而是要反复重写初始化、回调分发、文件落地这些琐碎逻辑。这个工程把 C 接口的 EDSDK 再包一层对外只留 Init、TakePicture、StartLiveView 这类精简 API回调统一收敛成函数指针数组按相机索引分发。适合做视觉采集、自动化测试台和摄影器材控制的二次开发把这层封装设计好迭代效率能差出一倍以上。2. EDSDK 事件模型与回调分发封装2.1 三类事件回调的注册时机EDSDK 是典型的事件驱动模型相机上的属性变更、文件生成、快门动作都会触发回调。官方提供了三组注册接口EdsSetPropertyEventHandler、EdsSetObjectEventHandler、EdsSetStateEventHandler分别对应属性事件、对象事件和状态事件。原始接口的回调参数里既有 EdsObject 又有事件 ID业务层每次都要做一次类型转换和相机对象匹配这是重复代码最集中的地方。这次接口封装的核心不是把 C 转成 C而是把事件接口封装成可替换的回调槽。工程里定义了三个函数指针数组每个数组按相机索引 MAX_CAMERA 分配槽位回调注册时把相机索引作为 EdsVoid* inContext 传进去SDK 触发时直接从 context 还原索引省掉对象比对。typedef void (*PROPERTYEVENT_CALLBACK)(EdsUInt32 inEvent, EdsUInt32 inPropertyID, EdsUInt32 inParam); typedef void (*OBJECTEVENT_CALLBACK)(EdsUInt32 inEvent); typedef void (*STATEEVENT_CALLBACK)(EdsUInt32 inEvent, EdsUInt32 inParam); static PROPERTYEVENT_CALLBACK g_property_callback[MAX_CAMERA]; static OBJECTEVENT_CALLBACK g_object_callback[MAX_CAMERA]; static STATEEVENT_CALLBACK g_state_callback[MAX_CAMERA]; static EdsError EDSCALLBACK propertyEventHandler( EdsObject inObject, EdsUInt32 inEvent, EdsUInt32 inPropertyID, EdsUInt32 inParam, EdsVoid* inContext) { (void)inObject; // 回调里不再做对象匹配 EdsUInt16 index (EdsUInt16)(EdsIntPtr)inContext; // 从 context 还原相机索引 if (g_property_callback[index] ! NULL) g_property_callback[index](inEvent, inPropertyID, inParam); return EDS_ERR_OK; }context 传索引的做法比遍历相机列表做匹配快也避免了在回调里调用 EdsGetChildAtIndex 这种非线程安全的函数。注意回调是在 EDSDK 内部线程执行的外部函数指针里不要做文件写入、UI 刷新这类耗时操作只做标记和入队。同样逻辑的 objectEventHandler 和 stateEventHandler 分别绑到 g_object_callback 和 g_state_callback 上注册时机放在 Init 函数完成相机枚举之后。2.2 事件队列化与 GetEvent 轮询EDSDK 的线程模型要求应用侧周期调用 EdsGetEvent() 来驱动内部事件循环否则回调会饥饿甚至丢失事件。封装层把这一步收敛成公开的 GetEvent() API内部先调 EdsGetEvent()再把队列里堆积的用户事件分发出去。队列用环形缓冲实现避免回调线程里动态分配内存。#define EVENT_QUEUE_SIZE 256 static EdsUInt32 g_event_queue[EVENT_QUEUE_SIZE]; static volatile int g_event_head 0, g_event_tail 0; static void EnqueueEvent(EdsUInt32 inEvent, EdsUInt32 inParam) { int next (g_event_tail 1) % EVENT_QUEUE_SIZE; if (next g_event_head) return; // 队列满丢弃事件 g_event_queue[g_event_tail] (inEvent 16) | (inParam 0xFFFF); g_event_tail next; } EDSDK_API EdsError GetEvent() { EdsError err EdsGetEvent(); // 驱动 EDSDK 内部事件循环 while (g_event_head ! g_event_tail) { EdsUInt32 packed g_event_queue[g_event_head]; g_event_head (g_event_head 1) % EVENT_QUEUE_SIZE; // 解包后分发到用户注册的 callback DispatchEvent((EdsUInt32)(packed 16), (EdsUInt32)(packed 0xFFFF)); } return err; }队列满时选择丢弃而不是阻塞是因为 EDSDK 回调线程不能长时间挂起丢一个属性刷新的中间态不影响最终状态文件生成这类关键事件靠后续的查询兜底。GetEvent 必须在主控制循环里每 10ms 调用一次和相机通信频率保持一致调用间隔超过 100ms 时连拍场景会明显丢事件。2.3 三类事件的典型处理场景事件类型触发场景常用处理kEdsCameraEvent_PropertyChanged光圈、ISO、白平衡变化刷新属性缓存同步上层 UIkEdsCameraEvent_ObjectCreated拍摄或录像完成文件落在相机存储置位文件就绪信号触发下载kEdsCameraEvent_Shutdown相机休眠、断电或 USB 断开标记掉线执行清理流程事件分发封装好后上层业务只需要填三个函数指针不需要感知 EDSDK 的线程模型。这个设计对 Python 侧尤其友好ctypes 只认 C 函数指针C 回调转 Python 回调只需要一层 trampoline。3. 拍照、录像与实时预览命令封装与状态机3.1 两段式快门与对焦触发EDSDK 的快门命令通过 kEdsCameraCommand_ShutterButton 发送参数有 Halfway 和 Completely 两个状态。半按用于触发自动对焦和测光完全按下才真正曝光。封装层把半按收敛成 HalfShutterAFC把完整拍照流程收敛成 TakePicture两者组合可以应对大部分机型的对焦延迟问题。EDSDK_API EdsError HalfShutterAFC(EdsUInt16 index) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 半按快门触发 AF 与测光不曝光 return EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Halfway); } EDSDK_API EdsError TakePicture(EdsUInt16 index, char** path) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 先半按让机身完成对焦和测光停顿由调用方控制 EdsError err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Halfway); if (err ! EDS_ERR_OK) return err; // 完全按下触发曝光 err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_Completely); if (err ! EDS_ERR_OK) return err; // 释放快门回到取景状态 err EdsSendCommand(camera, kEdsCameraCommand_ShutterButton, kEdsCameraCommand_ShutterButton_OFF); if (err ! EDS_ERR_OK) return err; // 等待 ObjectCreated 事件后回收文件并回填 path return WaitAndDownloadFile(index, path); }半按到全按之间必须有间隔实测大多数单反在 100ms 之内完成对焦会返回 EDS_ERR_DEVICE_BUSY建议在外部循环里控制半按持续时间。TakePictureNoAF 的实现就是把前半段 Halfway 去掉直接发 Completely适合已经锁焦的连拍场景。WaitAndDownloadFile 内部用 kEdsCameraEvent_ObjectCreated 作为同步信号事件没到就轮询超时超时时间建议 5s超过 10s 基本可以判定相机卡写存储卡。拍照命令映射关系如下封装 API底层命令/属性关键参数HalfShutterAFCkEdsCameraCommand_ShutterButtonHalfwayTakePictureHalfway → Completely → OFF两段式触发TakePictureNoAFCompletely → OFF跳过对焦直接拍StartVideokEdsCameraCommand_MovieStart需先处于录像模式StopVideokEdsCameraCommand_MovieStop停止后等文件事件3.2 录像命令与文件回收延迟录像的 StartVideo 和 StopVideo 在 EDSDK 里也是命令而非属性但前置条件是相机必须处于录像模式。很多人在非录像模式下直接发 MovieStart 得到 EDS_ERR_DEVICE_BUSY原因就是漏了模式切换。正确的顺序是先调 SetDevMode 切到录像模式等待属性事件稳定再发 MovieStart。停止录像后文件回收比拍照慢因为相机需要封口 MP4 容器普遍要等 1 到 2 秒。StopVideo 内部不要立刻拉流而是开启一个 3 秒的超时窗口等待 ObjectCreated。文件回收阶段用 EdsCreateFileStream 创建本地文件流参数要带 kEdsFileCreateDisposition_CreateAlways否则重复文件名会直接报错。3.3 实时预览与内存流生命周期实时预览走的是独立通道StartLiveView 先设置 kEdsPropID_Evf_Mode 为 1然后周期性调 DownloadEvfImage 拉一帧 YCbCr 数据。和拍照文件下载不同预览帧不需要落地成文件直接用内存流承接避免频繁创建临时文件。EDSDK_API EdsError DownloadEvfImage(EdsUInt16 index, void** pointer, EdsUInt64* length) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; EdsStream stream NULL; EdsError err EdsCreateMemoryStream(0, stream); // 0 表示先分配 0 字节按需增长 if (err ! EDS_ERR_OK) return err; err EdsGetEvfImage(camera, stream); // 拉取当前取景器图像 if (err EDS_ERR_OK) { EdsGetPointer(stream, pointer); // 拿到内存流内部缓冲区指针 EdsGetLength(stream, length); // 拿到有效数据长度 } else { EdsRelease(stream); } return err; }这里有个明显的坑EdsGetPointer 返回的是流内部的缓冲区地址不是拷贝出来的独立内存。调用方用完这个指针后必须由封装层负责释放 stream而且释放顺序有讲究先释放 stream 再使用 pointer 就是悬垂指针。工程里的做法是约定 caller 只读不释放下一次 DownloadEvfImage 调用时内部先释放上一帧的流保证同时只有一帧流存活。拉取预览帧的间隔控制在 33ms 到 50ms 之间太快会导致相机端 Buffer 溢出返回 EDS_ERR_OBJECT_NOTREADY。4. 属性读写与模式切换从 EdsPropertyID 到业务语义4.1 通用属性读写的实现EDSDK 的属性接口比较原始读属性前要先查属性大小再调 EdsGetPropertyData 按字节拷贝。不同属性的数据宽度还不一致光圈是浮点编码ISO 和色温是整数白平衡是枚举。把这些细节压平成一个 GetProperty是提升使用体验的关键一步。EDSDK_API EdsError GetProperty(EdsUInt16 index, EdsPropertyID propertyID, EdsUInt32* data) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 第一步查询目标属性的字节大小 EdsUInt32 size 0; EdsError err EdsGetPropertySize(camera, kEdsPropID_PropertySize, 0, propertyID, size); if (err ! EDS_ERR_OK) return err; // 不支持或当前模式不可用 // 第二步按查询结果读取实际数据统一放到 4 字节容器里 return EdsGetPropertyData(camera, propertyID, 0, size, data); }EdssGetPropertySize 的第一个参数传 kEdsPropID_PropertySize 是 EDSDK 的标准技巧表示查询的是第二个参数那个属性的尺寸。如果属性当前不可用函数会返回 EDS_ERR_PROPERTIES_UNAVAILABLE这个错误不应该被当作致命错误很多属性在录像模式下是只读的。SetProperty 的对称实现要先看属性是否可写可以先用 kEdsPropID_PropertySize 查一遍能查到大小再写能少踩一半的通信超时。4.2 模式切换与派生语义直接暴露 EdsPropertyID 给业务层的后果是每个调用方都要记住一堆 0x000000xx 的宏所以封装层基于基础属性接口派生了四个语义明确的接口。SetDevMode 切换拍照与录像模式SetMovieAEMode 控制录像时的自动曝光模式SetAFMode 配置对焦模式剩下的属性走通用的 SetProperty。EDSDK_API EdsError SetDevMode(EdsUInt16 index, eCameraMode mode) { EdsCamera* camera GetCamera(index); if (!camera) return EDS_ERR_DEVICE_NOT_FOUND; // 拍照/录像切换在多数机型上是一条命令而非属性 EdsUInt32 cmd (mode kCameraMode_Movie) ? kEdsCameraCommand_MovieSelectSwON // 切换到录像模式 : kEdsCameraCommand_MovieSelectSwOFF; // 切回拍照模式 EdsError err EdsSendCommand(camera, cmd, 0); if (err ! EDS_ERR_OK) { // 部分无反相机没有这条命令回退到 SaveTo 属性切换 return EdsSetPropertyData(camera, kEdsPropID_SaveTo, 0, sizeof(EdsUInt32), (EdsUInt32){ mode kCameraMode_Movie ? 1 : 0 }); } return err; }eCameraMode 是封装层自己定义的枚举值和按键指令对齐调用方不用去理解 MovieSelectSwON 和 OFF 的区别。切换模式后要等 kEdsCameraEvent_PropertyChanged 事件确认切换完成立刻拉取属性列表会拿到切换前的值这是模式切换最隐蔽的时序问题。SetMovieAEMode 和 SetAFMode 的底层实现都走通用的 SetPropertyData但枚举值域是独立的SetMovieAEMode 在非录像模式下调用会返回属性不可用调用方需要先确认当前设备模式。派生接口底层实现值域与说明SetDevModeMovieSelectSwON / MovieSelectSwOFF先切换模式再发录像命令GetDevMode内部模式缓存由 PropertyChanged 事件维护SetMovieAEModekEdsPropID_MovieAEProgram / Tv / Av / ManualSetAFModekEdsPropID_AFModeOneShot / AI Servo / ManualSetPropertyEdsSetPropertyData光圈、ISO、白平衡等4.3 属性缓存与事件回推属性回调触发的时机比属性写入晚几十毫秒如果上层同步读属性很可能拿到旧值。封装层在这个增强接口封装里做了一层属性缓存SetProperty 时先写缓存再发指令PropertyChanged 事件到达后用事件里的属性 ID 更新缓存并调用回调函数通知业务层。GetProperty 优先返回缓存缓存缺失时才走底层读取。缓存要区分相机索引每个 index 独立维护一份属性表。机身参数、镜头参数混在一个表里时会互相覆盖特别是焦距和光圈这类随镜头变化的属性建议按 kEdsPropID_LensID 分组存属性 ID 冲突时以最后一次事件为准每个属性再带一个时间戳读取时超过 5 秒未更新的缓存强制走真实通信。5. 多相机索引、内存释放与稳定性验证技巧5.1 索引到相机的两层映射Init(EdsUInt16 index) 里的 index 不是 USB 端口号而是 EDSDK 枚举出的相机序号。封装层只维护一个静态数组 g_camera[MAX_CAMERA]Init 时用 EdsGetCameraList 拿到相机列表再按 index 取出对应对象。枚举顺序不保证和 USB 口顺序一致同一台相机的枚举位置会随开机顺序变化所以工程里必须把相机的 kEdsPropID_ProductName 和序列号也拉出来缓存上层按序列号分配业务槽位。static EdsCamera* g_camera[MAX_CAMERA]; EDSDK_API EdsError Init(EdsUInt16 index) { if (index MAX_CAMERA) return EDS_ERR_DEVICE_NOT_FOUND; EdsCameraList list NULL; EdsError err EdsGetCameraList(list); // 枚举当前连接的相机列表 if (err ! EDS_ERR_OK) return err; err EdsGetChildAtIndex(list, index, g_camera[index]); // 按索引取相机对象 if (err EDS_ERR_OK) { EdsInitializeSDK(); // 初始化 SDK重复调用是安全的 err CreateCameraSession(index); // 打开会话并注册回调 } return err; }UnInit 的对称逻辑要先把事件回调置空再终止会话最后才调用 EdsTerminateSDK。顺序反了会在 SDK 释放后收到回调产生野指针。断线重连的场景里旧索引不能直接复用要先调 EdsGetCameraList 重新枚举再用序列号匹配新索引匹配上以后把索引映射表更新掉。5.2 文件路径与内存释放的约定TakePicture 和 StopVideo 的 char** path 是封装层 malloc 出来的调用方用完后必须 free。文件名规则由封装层统一生成格式是 IMG_YYYYMMDD_HHMMSS_%02d.CR2%02d 是相机索引。不要直接把 EDSDK 返回的设备文件名透传出去不同相机的命名规则差异太大统一格式可以省掉后续解析的麻烦。录像文件同理封装层只负责把相机存储卡上的文件下载完落盘后回填路径。5.3 无真机时的桩验证没有相机在手边时把 EdsSendCommand 和 EdsGetPropertyData 打桩成可替换的函数指针上层代码跑在 mock 层上。桩函数预置一套属性表拍照命令直接触发一个假的 ObjectCreated 事件让 WaitAndDownloadFile 的完整流程跑通。真机上容易出问题的都是文件下载逻辑写一个最小测试程序只做拍照和取图连续跑 200 次确认无内存泄漏比在业务里排查快得多。文件路径生成逻辑最好单独抽成纯函数输入时间戳索引输出路径用普通单测覆盖再把真机回收文件的下载调用单独验证路径拼接的坑基本就堵死了。本文还有配套的精品资源点击获取