typedef struct FSImageProcParamsC {
    const char* command;          // 必填："filter.sr"
    const char* paramsJson;       // 可空：命令参数 JSON（UTF-8）
    const char* teachingFile;     // 可空：teach.* 用
    const char* resultPath;       // 可空：服务端落盘路径（filter.* 也支持，命中后跳过 SHM 回传）
                                  //       paramsJson["option.resultPath"] 优先级更高
    int         timeoutMs;        // 0=默认 300000ms
} FSImageProcParamsC;

typedef struct FSImageProcResultC {
    int32_t  procStatus;          // 0=OK；详见错误码表
    int32_t  taskStatus;
    uint32_t outRows, outCols, outChannels;  // 服务端落盘模式下全为 0（SHM 跳过）
    int      outImageType;        // FS_IMAGE_C_RGB24 / FS_IMAGE_C_GRAY8 ...
    uint64_t outStride;
    void*    outImage;            // DLL 分配，必须 fsChannelFreeImageProcResult 释放
                                  // 服务端落盘 / option.returnImage=false 时为 NULL
    char*    resultJson;          // 落盘模式下含 savedPath/savedRows/savedCols/savedChans
    char*    errorMsg;            // 失败时填充
    uint64_t queuedUs;            // 入队等待时间
    uint64_t computeUs;           // 服务端实际计算时间
    uint64_t totalUs;             // 服务端总时间
    int64_t  elapsedMs;
} FSImageProcResultC;

#include "fixSharedMemory_api.h"

// 1. 建通道（FIX 必须已运行）
FSChannelHandle ch = fsChannelCreate(nullptr);   // 默认共享内存名 "FIXSharedMemory"
if (!ch) { /* 处理失败 */ }

// 2. 启用接收缓冲（容纳输出图像 + JSON + 余量）
fsChannelEnableImageProcReceiver(ch, 512ULL * 1024 * 1024);

// 3. 配参数
FSImageProcParamsC params{};
params.command    = "filter.sr";
params.paramsJson = R"({"filter.sr.scaleMode":"scale1"})";
params.timeoutMs  = 600000;

// 4. 调用（阻塞）
FSImageProcResultC result{};
int rc = fsChannelSendImageProcAndWait(ch, &params,
    inputBgrBytes, rows, cols, 3,
    FS_IMAGE_C_RGB24,
    static_cast<uint64_t>(cols) * 3,
    &result);

// 5. 用 result.outImage（DLL 分配）

// 6. 释放 + 关闭
fsChannelFreeImageProcResult(&result);
fsChannelDestroy(ch);

// 注册回调（注册即生效；不注册=不接收对应消息）
fsChannelSetImageProcProgressCallback(ch,
    [](uint32_t reqId, uint32_t done, uint32_t total,
       const char* msg, void*) {
        std::printf("req#%u %u/%u: %s\n", reqId, done, total, msg);
    }, nullptr);

fsChannelSetImageProcCompleteCallback(ch,
    [](uint32_t reqId, const FSImageProcResultC* r, void*) {
        if (r->procStatus == FS_PROC_C_OK) { /* 用 r->outImage */ }
    }, nullptr);

// 发送（立即返回 requestId，0=失败）
uint32_t reqId = fsChannelSendImageProcAsync(ch, &params,
    inputBgrBytes, rows, cols, 3, FS_IMAGE_C_RGB24,
    static_cast<uint64_t>(cols) * 3);

// 方式 A：结构体字段（C 客户端最方便）
FSImageProcParamsC p{};
p.command    = "filter.sr";
p.paramsJson = "{\"filter.sr.scaleMode\":\"scale4\"}";
p.resultPath = "z:/sr_x4.jpg";

// 方式 B：JSON 字段（推荐，便于一次塞所有参数）
p.command    = "filter.sr";
p.paramsJson = "{"
                  "\"filter.sr.scaleMode\":\"scale4\","
                  "\"option.resultPath\":\"z:/sr_x4.jpg\""
               "}";
p.resultPath = nullptr;

// 方式 C：只要 resultJson，不要图、不落盘
p.command    = "filter.sr";
p.paramsJson = "{\"option.returnImage\":false}";

done = 已完成的 tile 数
total = 总 tile 数（≈ ⌈rows/(tileSize-2*overlap)⌉ × ⌈cols/(tileSize-2*overlap)⌉）
message = "SR tile {done}/{total} batch={N}"

FSImageProcParamsC params{};
params.command = "filter.sr";
params.paramsJson =
    "{\"filter.sr.scaleMode\":\"scale4\","
    " \"filter.sr.blendRatio\":1.0,"
    " \"filter.sr.tileSize\":1024,"
    " \"filter.sr.tileOverlap\":32,"
    " \"filter.sr.batchHint\":1}";
params.timeoutMs = 600000;     // 10 分钟，大图必备

FSImageProcResultC result{};
int rc = fsChannelSendImageProcAndWait(ch, &params,
    bgrBytes, /*rows*/ 10997, /*cols*/ 15360, /*channels*/ 3,
    FS_IMAGE_C_RGB24, /*stride*/ 15360 * 3, &result);

if (rc == FS_API_OK && result.procStatus == FS_PROC_C_OK) {
    printf("SR done: %ux%u in %.2fs (compute=%.2fs)\n",
           result.outCols, result.outRows,
           result.totalUs / 1e6, result.computeUs / 1e6);
    // 处理 result.outImage
} else {
    printf("SR failed: rc=%d procStatus=%d msg=%s\n",
           rc, result.procStatus,
           result.errorMsg ? result.errorMsg : "(null)");
}
fsChannelFreeImageProcResult(&result);

客户端 fsChannelSendImageProcAndWait("filter.<name>", ...)
    │
    │ 共享内存写包 (FS_DATA_IMAGE_PROC_REQ + JSON params + image bytes)
    ▼
fixSharedMemoryManager::processPacket   (fiCore)
    │
    ▼
fiTaskScheduler::onSharedImageProcReceived
    │ 拷贝图像 + JSON → SharedMemoryTask → 入 m_detectQueue
    ▼
fiImageProcWorker (独立 QThread，FIFO 串行消费)
    │ 解析 JSON / 路由 cmd 前缀
    ▼
fiImageProcFilter::runFilter("filter.sr", ...)
    └── filter.sr → fiSRTiler::process → fiModelManager::inferenceFIXSR_*_batch
    │
    ▼
output → 共享内存写回 / 服务端 cv::imwrite 落盘 → 客户端