API 接口文档
按实摘自仓库公开头 include/vyntek.h 与 include/vyntek/**（嵌套子树 + CM1 扁平便利伞头），未编造未声明的 ABI。空实现 / 未齐处标注「桩 / STUB」。规格全文与对齐表见 cpp-headers；成像/内存正文 image-model · memory-management。
头树已落地，核心语义亦已实现（编排 Run/Link/Validate、
.avtgLoad/Save、采集停流与归还泵、成像句柄与内存协调）；真实算法仍 stub（Reed 职责），且全部未验收。命名空间vyntek::toolgroup/vyntek::imaging。MVP 无稳定 ABI（VYNTEK_ABI_UNSTABLE）。
导航
伞头 — vyntek.h
便利伞头（CONVENIENCE ONLY）：聚合四模块扁平便利头 + C API，并提供版本查询。优先链接 Vyntek::toolgroup + Vyntek::imaging。
版本宏
| 宏 | 说明 |
|---|---|
VYNTEK_VERSION_MAJOR | 主版本，当前 0 |
VYNTEK_VERSION_MINOR | 次版本，当前 1 |
VYNTEK_VERSION_PATCH | 补丁，当前 0 |
VYNTEK_VERSION | 字符串形式，如 "0.1.0" |
VYNTEK_VERSION_NUMBER | MAJOR*10000 + MINOR*100 + PATCH |
VYNTEK_VERSION_STRINGIZE_ / VYNTEK_VERSION_STRINGIZE | 字符串化辅助宏（VYNTEK_VERSION 由它们拼出） |
VYNTEK_ABI_UNSTABLE | 标记非稳定 ABI |
命名空间函数（vyntek::）
const char* version() noexcept — 库版本字符串。
const char* version_commit() noexcept — 配置时短 git commit，或 "unknown"。
模块索引（按实 · CM1）
| 模块 | 便利头 | 嵌套权威 | 状态 |
|---|---|---|---|
| ToolGroup | vyntek/toolgroup.hpp | vyntek/toolgroup/*.hpp | 便利转发 · 编排核心语义已实现，真实算法 stub |
| Imaging | vyntek/imaging.hpp | vyntek/imaging/*.hpp | 便利转发 · 部分实现 · 仍 STUB 标 |
| Memory | vyntek/memory.hpp | 权威在 imaging/buffer.hpp | 转发 + vyntek::BufferView 占位 |
| Session | vyntek/session.hpp | 权威在 toolgroup/run_session.hpp | 转发 + vyntek::Session 占位（≠ AcquisitionSession） |
| 测试/示例假工具 | — | toolgroup/fake_tools.hpp · imaging/fake_camera_adapter.hpp | fake::register_fake_tools（FakeAcq 等 8 件）；非产品内置 |
C API（vyntek/capi/vyntek_exports.h）
Rhett PInvoke 薄导出面。NON-STABLE / STUB：符号、参数序、错误码可无预告变更。不透明句柄 + Adopt/Release；勿解引用内部布局。
错误码（enum，int 返回）
| 码 | 值 |
|---|---|
VYNTEK_CAPI_OK | 0 |
VYNTEK_CAPI_ERR_NULL | -1 |
VYNTEK_CAPI_ERR_NOT_IMPL | -2 |
VYNTEK_CAPI_ERR_BUSY | -3 |
VYNTEK_CAPI_ERR_IO | -4 |
VYNTEK_CAPI_ERR_INVALID | -5 |
session_run 对 Succeeded（含仅报 NotImplemented 的 M1 骨架宽松路径）返回 VYNTEK_CAPI_OK，不等于「算法已实现」；仅当 status 非 Succeeded 且诊断含 NotImplemented 时映射 VYNTEK_CAPI_ERR_NOT_IMPL。
不透明句柄类型
vyntek_toolgroup_t · vyntek_run_session_t · vyntek_pixel_handle_t · vyntek_acquisition_session_t · vyntek_registry_t · vyntek_diagnostics_t
函数组
| 前缀 | 函数 | 说明 |
|---|---|---|
vyntek_toolgroup_* | create / load / validate / session_create / session_run / request_cancel / session_release / release | 编排主路径 |
diagnostics_count / diagnostics_code_at / diagnostics_at / diagnostics_clear / diagnostics_release | 诊断投影（码为 DiagnosticCode 数值） | |
registry_create / registry_release | 注册表 | |
run / adopt_group / adopt_session | PInvoke 便捷（run = session_create + session_run；优先显式两步） | |
vyntek_imaging_handle_* | adopt / release / share（TC-DISP-02 独立持有 Share）/ info（宽/高/格式窄投影）/ image_info（M5-08 全 ImageInfo 投影：origin / stride / invalid_depth / color_encoding） | 像素句柄 |
vyntek_imaging_* | create_copy（M5-01/M5-08：拷贝调用方像素成已发布只读图；row_step_bytes<=0 = packed；带 ROI origin 与 Depth16 sentinel 字段）· open_read / view_close（借用读视图；view_close 不释放图像） | 真实像素入口 / 借用读视图 |
try_get_gray8 / try_get_rgb24 / try_get_bgr24 / try_get_depth16（out_is_valid 可空）/ try_get_depth_meters | 像素投影读；格式不符 / OOB → ERR_INVALID；无隐式转换 | |
vyntek_imaging_acq_session_* | adopt / release / latest / peek_ingress_front | M4-11 / M5-09：Latest/Peek 为空 → OK + NULL（非错误） |
包含方式（按实）
#include <vyntek.h>
// 或扁平便利：
#include <vyntek/toolgroup.hpp>
#include <vyntek/imaging.hpp>
// 推荐嵌套（与规格/cpp-headers 一致）：
#include <vyntek/toolgroup/toolgroup.hpp>
#include <vyntek/toolgroup/run_session.hpp>
#include <vyntek/imaging/handle.hpp>
namespace tg = vyntek::toolgroup;
namespace im = vyntek::imaging;MVP 口径
- 无稳定 ABI（T14 / host-integration R7）。
- TC-MEM-* 摘录见本站 test-contracts-tc-mem；完整 TC-* 见 test-contracts。
- 对齐细表：cpp-headers 本仓对齐（按实）。