GrabBag/Device/IKapDevice/Inc/IIKapDevice.h

#ifndef IIKAPDEVICE_H
#define IIKAPDEVICE_H

#include <iostream>
#include <functional>

// 前向声明，避免直接暴露 IKapC 的类型给外部
struct ImageData
{
    unsigned char* pData;       // 图像数据指针
    unsigned int width;         // 图像宽度
    unsigned int height;        // 图像高度
    unsigned int pixelFormat;   // 像素格式
    unsigned int imageSize;     // 图像数据大小
    uint64_t timestamp;         // 时间戳
    uint64_t frameID;           // 帧ID
};

// 设备信息结构
struct IKapDeviceInfo
{
    char vendorName[256];       // 厂商名称
    char modelName[256];        // 型号名称
    char serialNumber[256];     // 序列号
    char userDefinedName[256];  // 用户定义名称
    char ipAddress[256];        // IP地址（网络相机）
    char macAddress[256];       // MAC地址（网络相机）
};

// 图像回调函数类型
using ImageCallback = std::function<void(const ImageData& imageData, void* pUser)>;

/**
 * @brief IKapDevice 接口类
 * 封装 IKapLibrary C 接口，提供相机操作的 C++ 接口
 */
class IIKapDevice
{
public:
    virtual ~IIKapDevice() = default;

    /**
     * @brief 创建设备对象
     * @param ppDevice 设备对象指针
     * @return 0-成功，其他-失败
     */
    static int CreateObject(IIKapDevice** ppDevice);

    /**
     * @brief 初始化 IKapC 库
     * @return 0-成功，其他-失败
     */
    virtual int InitLibrary() = 0;

    /**
     * @brief 释放 IKapC 库资源
     * @return 0-成功，其他-失败
     */
    virtual int TerminateLibrary() = 0;

    /**
     * @brief 枚举所有可用相机
     * @param nCount 返回相机数量
     * @return 0-成功，其他-失败
     */
    virtual int EnumerateDevices(unsigned int& nCount) = 0;

    /**
     * @brief 获取指定索引的相机设备信息
     * @param nIndex 相机索引（0 到 nCount-1）
     * @param deviceInfo 设备信息结构
     * @return 0-成功，其他-失败
     */
    virtual int GetDeviceInfo(unsigned int nIndex, IKapDeviceInfo& deviceInfo) = 0;

    /**
     * @brief 打开相机设备
     * @param nIndex 相机索引
     * @param accessMode 访问模式（独占、控制、流等）
     * @return 0-成功，其他-失败
     */
    virtual int OpenDevice(unsigned int nIndex, int accessMode = 4) = 0;  // 默认独占模式

    /**
     * @brief 关闭相机设备
     * @return 0-成功，其他-失败
     */
    virtual int CloseDevice() = 0;

    /**
     * @brief 检查相机是否已连接
     * @param bConnected 连接状态
     * @return 0-成功，其他-失败
     */
    virtual int IsConnected(bool& bConnected) = 0;

    /**
     * @brief 抓取单张图像（同步模式）
     * @param imageData 图像数据结构
     * @param nTimeout 超时时间（毫秒），默认5000ms
     * @return 0-成功，其他-失败
     */
    virtual int GrabSingleFrame(ImageData& imageData, unsigned int nTimeout = 5000) = 0;

    /**
     * @brief 开始连续采集（异步模式）
     * @param callback 图像回调函数
     * @param pUser 用户自定义参数
     * @return 0-成功，其他-失败
     */
    virtual int StartGrabbing(ImageCallback callback, void* pUser = nullptr) = 0;

    /**
     * @brief 停止连续采集
     * @return 0-成功，其他-失败
     */
    virtual int StopGrabbing() = 0;

    /**
     * @brief 检查是否正在采集
     * @return true-正在采集，false-未采集
     */
    virtual bool IsGrabbing() = 0;

    /**
     * @brief 设置曝光时间（微秒）
     * @param exposureTime 曝光时间（us）
     * @return 0-成功，其他-失败
     */
    virtual int SetExposureTime(double exposureTime) = 0;

    /**
     * @brief 获取曝光时间（微秒）
     * @param exposureTime 曝光时间（us）
     * @return 0-成功，其他-失败
     */
    virtual int GetExposureTime(double& exposureTime) = 0;

    /**
     * @brief 设置增益
     * @param gain 增益值
     * @return 0-成功，其他-失败
     */
    virtual int SetGain(double gain) = 0;

    /**
     * @brief 获取增益
     * @param gain 增益值
     * @return 0-成功，其他-失败
     */
    virtual int GetGain(double& gain) = 0;

    /**
     * @brief 设置触发模式
     * @param bEnable true-开启触发，false-关闭触发
     * @return 0-成功，其他-失败
     */
    virtual int SetTriggerMode(bool bEnable) = 0;

    /**
     * @brief 发送软触发信号
     * @return 0-成功，其他-失败
     */
    virtual int ExecuteSoftwareTrigger() = 0;

    /**
     * @brief 获取图像宽度
     * @param width 图像宽度
     * @return 0-成功，其他-失败
     */
    virtual int GetWidth(unsigned int& width) = 0;

    /**
     * @brief 获取图像高度
     * @param height 图像高度
     * @return 0-成功，其他-失败
     */
    virtual int GetHeight(unsigned int& height) = 0;

    /**
     * @brief 设置图像 ROI
     * @param offsetX X偏移
     * @param offsetY Y偏移
     * @param width 宽度
     * @param height 高度
     * @return 0-成功，其他-失败
     */
    virtual int SetROI(unsigned int offsetX, unsigned int offsetY,
                       unsigned int width, unsigned int height) = 0;

    /**
     * @brief 获取库版本号
     * @param version 版本号
     * @return 0-成功，其他-失败
     */
    virtual int GetLibraryVersion(unsigned int& version) = 0;
};

#endif // IIKAPDEVICE_H