GrabBag/Device/RsLidarDevice/Inc/IRsLidarDevice.h

#ifndef IRSLIDARDEVICE_H
#define IRSLIDARDEVICE_H

#include <functional>
#include <string>

#include "RsLidarDevice_global.h"

// ============================================================
// 自定义数据类型 — 完全不依赖 rs_driver SDK
// 使用内置类型(unsigned char/short/int)替代 stdint.h
// 以避免跨编译器的头文件兼容性问题
// ============================================================

/// 单个点 (x/y/z/intensity)，与 SDK PointXYZI 内存布局一致
/// SDK 使用 #pragma pack(1)，sizeof=13，此处必须严格对齐
#pragma pack(push, 1)
struct RsPointXYZI
{
    float          x = 0.0f;
    float          y = 0.0f;
    float          z = 0.0f;
    unsigned char  intensity = 0;
};
#pragma pack(pop)

/// 一帧完整点云数据（指针指向内部缓冲区，仅在回调期间有效）
struct RsPointCloudData
{
    unsigned int      seq = 0;         ///< 帧序号（单调递增）
    double            timestamp = 0.0; ///< 帧时间戳（秒）
    unsigned int      height = 0;      ///< 激光线数
    unsigned int      width = 0;       ///< 每线点数
    bool              isDense = false; ///< 是否丢弃了 NaN 点
    std::string       frameId;         ///< 帧标识
    unsigned int      pointCount = 0;  ///< 点数
    const RsPointXYZI* points;         ///< 指向内部点数组，回调返回后失效
};

/// 原始数据包信息（is_frame_begin=1 表示新一圈扫描起始）
struct RsPacketInfo
{
    double         timestamp = 0.0;
    unsigned int   seq = 0;
    unsigned char  is_difop = 0;
    unsigned char  is_frame_begin = 0;  ///< =1 新一帧扫描开始
    std::string    frameId;
    unsigned int   dataSize = 0;        ///< 原始数据字节数
};

/// 异常/错误信息
struct RsExceptionInfo
{
    int         code = 0;
    std::string message;
};

/// LiDAR 配置参数
struct RsLidarConfig
{
    std::string    lidarType     = "RSEM4";    ///< 雷达型号
    std::string    hostAddress   = "0.0.0.0";  ///< 主机地址
    unsigned short msopPort      = 6699;        ///< MSOP 数据端口
    unsigned short difopPort     = 7788;        ///< DIFOP 数据端口
    unsigned short imuPort       = 0;           ///< IMU 端口 (0=禁用)
    float          minDistance   = 0.0f;        ///< 最小距离(米) 0=不限
    float          maxDistance   = 0.0f;        ///< 最大距离(米) 0=不限
    bool           densePoints   = false;       ///< 丢弃 NaN 点
    bool           useLidarClock = false;       ///< 使用雷达内部时钟
    bool           tsFirstPoint  = false;       ///< 时间戳取首点时刻
    bool           waitForDifop  = false;       ///< 等待 DIFOP 包
    float          startAngle    = 0.0f;        ///< 有效角度起始(度)
    float          endAngle      = 360.0f;      ///< 有效角度结束(度)
    float          splitAngle    = 0.0f;        ///< 帧分割角度(度)
    std::string    frameId       = "rslidar";   ///< 帧标识字符串
    unsigned int   socketRecvBufBytes = 33554432;  ///< socket 接收缓冲，默认 32MB；低配机推荐 ≥16MB
};

/// 帧元数据（不含点数据，用于原始点云回调）
struct RsFrameMeta
{
    unsigned int      seq = 0;
    double            timestamp = 0.0;
    unsigned int      height = 0;
    unsigned int      width = 0;
    bool              isDense = false;
    std::string       frameId;
};

/// 用户回调耗时统计（来自最近一个 5s 滚动窗口的快照）
struct RsCallbackStats
{
    unsigned long long maxUs = 0;   ///< 窗口内单次回调最大耗时(μs)
    unsigned long long avgUs = 0;   ///< 窗口内平均耗时(μs)
    unsigned long long count = 0;   ///< 窗口内回调次数
};

class RSLIDARDEVICE_EXPORT IRsLidarDevice
{
public:
    using PointCloudCallback  = std::function<void(const RsPointCloudData&)>;
    using PacketCallback      = std::function<void(const RsPacketInfo&)>;
    using ExceptionCallback   = std::function<void(const RsExceptionInfo&)>;

    /// 原始点云回调：提供未经转换的 SDK 原始点（含 NaN，单位米），
    /// 用户可在一次遍历中完成 NaN 清洗 + 单位转换 + 格式复制，
    /// 避免 RsLidarDevice 内部和用户侧各做一次点级循环
    using RawCloudCallback    = std::function<void(const RsPointXYZI* points, uint32_t pointCount, const RsFrameMeta& meta)>;

    virtual ~IRsLidarDevice() = default;

    /// 工厂方法
    static int CreateObject(IRsLidarDevice** ppDevice);

    /// 初始化 SDK 环境（WSAStartup 等）
    virtual int InitDevice() = 0;

    /// 配置并打开设备
    virtual int OpenDevice(const RsLidarConfig& config) = 0;

    /// 关闭设备
    virtual int CloseDevice() = 0;

    /// 设备是否已打开
    virtual bool IsOpened() const = 0;

    /// 开始接收数据
    virtual int Start() = 0;

    /// 停止接收数据
    virtual int Stop() = 0;

    /// 是否正在运行
    virtual bool IsRunning() const = 0;

    /// 注册点云回调（每次回调 = 完整一圈扫描）
    virtual int SetPointCloudCallback(PointCloudCallback callback) = 0;

    /// 注册数据包回调（is_frame_begin 标记帧起始）
    virtual int SetPacketCallback(PacketCallback callback) = 0;

    /// 注册原始点云回调（注册后优先使用，跳过内部 Transform 循环）
    virtual int SetRawCloudCallback(RawCloudCallback callback) = 0;

    /// 注册异常回调
    virtual int SetExceptionCallback(ExceptionCallback callback) = 0;

    /// 获取驱动版本
    virtual std::string GetVersion() = 0;

    /// 获取丢帧计数（m_stuffedQueue 满时被丢弃的帧数）
    virtual uint64_t GetDroppedFrameCount() const = 0;

    /// 获取当前就绪队列深度（待消费的帧数）
    virtual size_t GetStuffedQueueDepth() const = 0;

    /// 获取指定 SDK ErrCode 的累计触发次数（接受原始 SDK error_code，如 0x40/0x48/0x49/0x42）
    virtual uint64_t GetExceptionCount(int errCode) const = 0;

    /// 获取并清零最近一个 5s 滚动窗口内用户回调耗时统计
    /// 注意：内部统计字段每 5s 由 processCloudThread 重置，此接口仅返回当前累计快照
    virtual RsCallbackStats GetCallbackLatencyStats() const = 0;

    /// 获取就绪队列历史峰值深度（Open 以来）
    virtual size_t GetStuffedQueuePeak() const = 0;
};

#endif // IRSLIDARDEVICE_H