//
// FFmpeg 风格的串口解码工具核心定义（带详细中文注释）。
// 说明：本文件使用了 C++17 引入的 std::optional（可选值容器）与 [[nodiscard]] 属性，
// 以及 C++11 的 std::initializer_list、基于 enum class 的强类型枚举，用于提高类型安全。
//

#pragma once

#include <cstdint>       // 固定宽度整数类型，便于协议字段与位宽一致
#include <cstddef>
#include <mutex>         // 互斥锁，用于注册表线程安全
#include <optional>      // C++17 可选类型，用来表示可能为空的查找结果
#include <string>
#include <string_view>   // C++17 字符串视图，避免不必要的拷贝
#include <vector>
#include <initializer_list> // C++11 可初始化列表，支持批量注册编解码器

namespace ffmsep { // 命名空间隔离所有与串口编解码相关的类型

// 错误码定义：参考 FFmpeg 的返回值约定，所有负数表示异常。
inline constexpr int CP_SUCCESS = 0;                // 成功
inline constexpr int CP_ERROR_EOF = -1;             // 流结束（End Of File）
inline constexpr int CP_ERROR_EAGAIN = -2;          // 数据暂不可用，稍后重试
inline constexpr int CP_ERROR_NOT_OPEN = -3;        // 编解码上下文尚未打开
inline constexpr int CP_ERROR_INVALID_STATE = -4;   // 当前状态不允许该操作
inline constexpr int CP_ERROR_INVALID_ARGUMENT = -5;// 传入参数不合法

// enum class 使用 C++11 强类型枚举，避免隐式转换导致的错误。
enum class CPMediaType : std::uint8_t {
    Unknown = 0, // 未知类型：默认值
    Data,        // 数据流（例如串口数据）
    Audio,       // 音频流（预留扩展）
    Video        // 视频流（预留扩展）
};

// 编解码器 ID，用于在注册表中快速定位具体实现。
enum class CPCodecID : std::uint32_t {
    Unknown = 0,            // 未知或未设置
    Tactile = 0x54514354u   // 'T','Q','C','T'：触觉传感器协议标识
};

// CPPacket 表示输入的“帧包”，与 FFmpeg 中 AVPacket 的思想类似。
struct CPPacket {
    std::vector<std::uint8_t> payload; // 有效载荷：串口原始数据
    std::int64_t pts = 0;              // 显示时间戳（presentation timestamp）
    std::int64_t dts = 0;              // 解码时间戳（decode timestamp）
    bool end_of_stream = false;        // 标记此包是否为流结尾
    bool flush = false;                // 是否请求刷新内部状态（例如重置缓冲）

    CPPacket() = default;
    CPPacket(std::vector<std::uint8_t> data, std::int64_t pts_value = 0, std::int64_t dts_value = 0) noexcept
        : payload(std::move(data)), pts(pts_value), dts(dts_value) {}

    [[nodiscard]] bool empty() const noexcept { return payload.empty(); } // [[nodiscard]] 防止忽略返回值
};

// CPFrame 表示解码后的数据帧，对应业务层可消费的实体。
struct CPFrame {
    std::vector<std::uint8_t> data; // 解码后的数据内容
    std::int64_t pts = 0;           // 与输入包对应的时间戳
    bool key_frame = false;         // 是否为关键帧（例如起始帧）
    bool valid = false;             // 是否包含有效数据

    void reset() noexcept {
        data.clear();
        pts = 0;
        key_frame = false;
        valid = false;
    }
};

struct CPCodecContext;

// CPCodec 用函数指针描述具体编解码器的行为，等价于 FFmpeg 中的 AVCodec。
struct CPCodec {
    using InitFn = int (*)(CPCodecContext*);                  // 初始化回调
    using CloseFn = void (*)(CPCodecContext*);                // 关闭回调
    using SendPacketFn = int (*)(CPCodecContext*, const CPPacket&); // 发送输入包
    using ReceiveFrameFn = int (*)(CPCodecContext*, CPFrame&);      // 拉取输出帧

    const char* name = nullptr;
    const char* long_name = nullptr;
    CPMediaType type = CPMediaType::Unknown;
    CPCodecID id = CPCodecID::Unknown;
    std::size_t priv_data_size = 0;
    InitFn init = nullptr;
    CloseFn close = nullptr;
    SendPacketFn send_packet = nullptr;
    ReceiveFrameFn receive_frame = nullptr;
};

struct CPCodecContext {
    const CPCodec* codec = nullptr;          // 指向当前使用的编解码器描述
    void* priv_data = nullptr;               // 指向编解码器私有状态（大小由 priv_data_size 控制）
    CPMediaType codec_type = CPMediaType::Unknown; // 保存媒体类型，便于外部查询
    bool is_open = false;                    // 是否已经成功调用 open

    void clear() noexcept {
        codec = nullptr;
        priv_data = nullptr;
        codec_type = CPMediaType::Unknown;
        is_open = false;
        priv_storage.clear();
    }

    void* ensure_priv_storage(std::size_t size); // 确保私有存储空间足够，不足时重新分配
    void release_priv_storage() noexcept;        // 释放私有存储

    template <typename T>
    [[nodiscard]] T* priv_as() noexcept {
        return static_cast<T*>(priv_data);
    }

    template <typename T>
    [[nodiscard]] const T* priv_as() const noexcept {
        return static_cast<const T*>(priv_data);
    }

private:
    std::vector<std::uint8_t> priv_storage; // 私有缓冲区，使用 std::vector 管理生命周期

    friend CPCodecContext* cpcodec_alloc_context3(const CPCodec*);
    friend int cpcodec_open2(CPCodecContext*, const CPCodec*);
    friend int cpcodec_close(CPCodecContext*);
};

// 注册接口：允许外部模块将编解码器加入全局列表。
void cpcodec_register(const CPCodec* codec);
void cpcodec_register_many(std::initializer_list<const CPCodec*> codecs);
const CPCodec* cpcodec_find_decoder(CPCodecID id);
const CPCodec* cpcodec_find_decoder_by_name(std::string_view name);
std::vector<const CPCodec*> cpcodec_list_codecs();

CPCodecContext* cpcodec_alloc_context3(const CPCodec* codec);             // 分配上下文，关联指定编解码器
int cpcodec_open2(CPCodecContext* ctx, const CPCodec* codec = nullptr);   // 打开上下文，可在此处指定或替换编解码器
int cpcodec_close(CPCodecContext* ctx);                                   // 关闭上下文并释放资源
void cpcodec_free_context(CPCodecContext** ctx);                          // 释放上下文指针
int cpcodec_send_packet(CPCodecContext* ctx, const CPPacket* packet);     // 推送一份待解码的数据包
int cpcodec_receive_frame(CPCodecContext* ctx, CPFrame* frame);           // 拉取解码出来的帧

} // namespace ffmsep