rkvc API 引用¶
Rockchip 媒体图运行库（C++20 会话式媒体运行库，稳定 C ABI 0.5.0）API 引用
Types¶
| Name | Description |
|---|---|
| rkvc_status | 操作状态码。负值为错误；RKVC_OK 表示成功，RKVC_AGAIN/RKVC_EOF 是会话流控的正常终态；语义与 C++ 侧 rkvc::Status 一一对应。 |
| rkvc_operation | 会话操作类型。 |
| rkvc_codec | 编解码器。 |
| rkvc_policy | 执行策略（时延/质量权衡）。 |
| rkvc_frame_fmt | 帧像素格式。 |
| rkvc_mem_domain | 帧内存域。 |
| rkvc_endpoint_kind | 端点类型。 |
| rkvc_context_options | 上下文创建选项。结构体自带 struct_size/version 用于前后向兼容演进。 |
| rkvc_endpoint | 流端点描述（会话输入或输出）。 |
| rkvc_quality | 编码质量参数。 |
| rkvc_session_request | 会话创建请求。 |
| rkvc_frame_spec | 帧规格（宽/高/stride 为 0 表示通配或待探测）。 |
| rkvc_frame_desc | 帧描述（包装与查询用）。 |
| rkvc_caps | 设备能力探测结果。 |
Macros¶
| Name | Description |
|---|---|
| RKVC_FRAME_TS_UNKNOWN | 未知时间戳标记 |
Functions¶
| Name | Description |
|---|---|
| rkvc_status_str | 状态码转可读字符串（静态存储，无需释放）。 |
| rkvc_context_options_init | 初始化上下文选项（填写 struct_size/version）。 opts : 选项结构。 size : 传入的缓冲区大小，用于向后兼容校验。 |
| rkvc_context_create | 创建运行上下文。 opts : 选项；可传 NULL 使用默认值。 out : 接收上下文句柄。 Return : 成功返回 RKVC_OK。 |
| rkvc_context_destroy | 销毁上下文，并释放其持有的一切资源。 |
| rkvc_probe_device | 探测设备能力。 ctx : 上下文句柄。 caps : 输出的能力结构。 Return : 成功返回 RKVC_OK。 |
| rkvc_context_add_model_dir | 按导出器约定扫描模型目录并注册整组原生文件（.rknn/.bin/.qppatch， id 去重；失败时可选填 diag）。一个 bundle 目录可产出 encoder/decoder 等多个模型，全部注册。 |
| rkvc_session_request_init | 初始化会话请求（填写 struct_size/version 与默认值）。 req : 请求结构。 size : 传入的缓冲区大小。 |
| rkvc_session_create | 创建会话。 req : 会话请求。 out : 接收会话句柄。 diag : 可选诊断输出。 Return : 成功返回 RKVC_OK。 |
| rkvc_session_start | 启动会话。 diag : 可选诊断输出。 Return : 成功返回 RKVC_OK。 |
| rkvc_session_push | 非阻塞入队一帧。 |
| rkvc_session_try_pull | 非阻塞拉取一帧；无可用数据时返回 RKVC_AGAIN。 |
| rkvc_session_pull | 阻塞拉取一帧。 |
| rkvc_session_push_eos | 推送流结束标记。 |
| rkvc_session_wait | 等待管道排空，返回首个错误或 RKVC_OK。 |
| rkvc_session_destroy | 销毁会话。 |
| rkvc_session_error_text | 取终端错误的阶段明细（wait 已排空后调用，立即返回；Ok 时 buf 置空）。 buf : 输出缓冲区。 size : 缓冲区大小。 |
| rkvc_frame_desc_init | 初始化帧描述（填写 struct_size/version）。 |
| rkvc_frame_wrap | 按描述包装一帧。 desc : 帧描述。 out : 接收帧句柄。 Return : 成功返回 RKVC_OK。 |
| rkvc_frame_wrap_owned | 包装一帧并持有载荷所有权：最后一个帧引用释放时回调 release(release_ctx)（典型用途：释放宿主的深拷贝副本）。 wrap 失败时所有权不转移，调用方自释放。域语义与 rkvc_frame_wrap 相同（Host 用 data，Dmabuf 用 fd）。 desc : 帧描述。 release : 载荷释放回调（不可为 NULL）。 release_ctx : 传给回调的上下文（通常即载荷指针）。 out : 接收帧句柄。 Return : 成功返回 RKVC_OK。 |
| rkvc_frame_get_desc | 查询帧的当前描述。 |
| rkvc_frame_release | 释放帧句柄。 |
| rkvc_diag_fmt_text | 将诊断信息格式化为文本。 buf : 输出缓冲区。 size : 缓冲区大小。 |
| rkvc_diag_release | 释放诊断对象。 |
- RKVC_FRAME_FLAG_KEYFRAME = 1u << 0
- 帧标志位。 关键帧
- RKVC_FRAME_FLAG_DISCONTINUITY = 1u << 1
- 流不连续
- RKVC_FRAME_FLAG_CORRUPT = 1u << 2
- 数据损坏
Macro Details¶
RKVC_FRAME_TS_UNKNOWN¶
#define RKVC_FRAME_TS_UNKNOWN
未知时间戳标记
Function Details¶
rkvc_context_add_model_dir¶
rkvc_status rkvc_context_add_model_dir(rkvc_context *ctx, const char *dir, rkvc_diagnostic **diag)
按导出器约定扫描模型目录并注册整组原生文件（.rknn/.bin/.qppatch，
id 去重；失败时可选填 diag）。一个 bundle 目录可产出 encoder/decoder
等多个模型，全部注册。
rkvc_context_create¶
rkvc_status rkvc_context_create(const rkvc_context_options *opts, rkvc_context **out)
创建运行上下文。
-
opts - 选项；可传 NULL 使用默认值。
-
out - 接收上下文句柄。
- Return
- 成功返回
RKVC_OK。
rkvc_context_destroy¶
void rkvc_context_destroy(rkvc_context *ctx)
销毁上下文，并释放其持有的一切资源。
rkvc_context_options_init¶
void rkvc_context_options_init(rkvc_context_options *opts, size_t size)
初始化上下文选项（填写 struct_size/version）。
-
opts - 选项结构。
-
size - 传入的缓冲区大小，用于向后兼容校验。
rkvc_diag_fmt_text¶
void rkvc_diag_fmt_text(const rkvc_diagnostic *diag, char *buf, size_t size)
将诊断信息格式化为文本。
-
buf - 输出缓冲区。
-
size - 缓冲区大小。
rkvc_diag_release¶
void rkvc_diag_release(rkvc_diagnostic *diag)
释放诊断对象。
rkvc_frame_desc_init¶
void rkvc_frame_desc_init(rkvc_frame_desc *desc, size_t size)
初始化帧描述（填写 `struct_size`/`version`）。
rkvc_frame_get_desc¶
rkvc_status rkvc_frame_get_desc(const rkvc_frame *f, rkvc_frame_desc *desc)
查询帧的当前描述。
rkvc_frame_release¶
void rkvc_frame_release(rkvc_frame *f)
释放帧句柄。
rkvc_frame_wrap¶
rkvc_status rkvc_frame_wrap(const rkvc_frame_desc *desc, rkvc_frame **out)
按描述包装一帧。
-
desc - 帧描述。
-
out - 接收帧句柄。
- Return
- 成功返回
RKVC_OK。
rkvc_frame_wrap_owned¶
rkvc_status rkvc_frame_wrap_owned(const rkvc_frame_desc *desc, void (*release)(void *release_ctx) RKVC_NOEXCEPT, void *release_ctx, rkvc_frame **out)
包装一帧并持有载荷所有权：最后一个帧引用释放时回调
`release(release_ctx)`（典型用途：释放宿主的深拷贝副本）。
wrap 失败时所有权不转移，调用方自释放。域语义与 `rkvc_frame_wrap`
相同（Host 用 `data`，Dmabuf 用 `fd`）。
-
desc - 帧描述。
-
release - 载荷释放回调（不可为 NULL）。
-
release_ctx - 传给回调的上下文（通常即载荷指针）。
-
out - 接收帧句柄。
- Return
- 成功返回
RKVC_OK。
rkvc_probe_device¶
rkvc_status rkvc_probe_device(rkvc_context *ctx, rkvc_caps *caps)
探测设备能力。
-
ctx - 上下文句柄。
-
caps - 输出的能力结构。
- Return
- 成功返回
RKVC_OK。
rkvc_session_create¶
rkvc_status rkvc_session_create(rkvc_context *ctx, const rkvc_session_request *req, rkvc_session **out, rkvc_diagnostic **diag)
创建会话。
-
req - 会话请求。
-
out - 接收会话句柄。
-
diag - 可选诊断输出。
- Return
- 成功返回
RKVC_OK。
rkvc_session_destroy¶
void rkvc_session_destroy(rkvc_session *s)
销毁会话。
rkvc_session_error_text¶
rkvc_status rkvc_session_error_text(rkvc_session *s, char *buf, size_t size)
取终端错误的阶段明细（wait 已排空后调用，立即返回；Ok 时 buf 置空）。
-
buf - 输出缓冲区。
-
size - 缓冲区大小。
rkvc_session_pull¶
rkvc_status rkvc_session_pull(rkvc_session *s, rkvc_frame **out)
阻塞拉取一帧。
rkvc_session_push¶
rkvc_status rkvc_session_push(rkvc_session *s, rkvc_frame *f)
非阻塞入队一帧。
rkvc_session_push_eos¶
rkvc_status rkvc_session_push_eos(rkvc_session *s)
推送流结束标记。
rkvc_session_request_init¶
void rkvc_session_request_init(rkvc_session_request *req, size_t size)
初始化会话请求（填写 `struct_size`/`version` 与默认值）。
-
req - 请求结构。
-
size - 传入的缓冲区大小。
rkvc_session_start¶
rkvc_status rkvc_session_start(rkvc_session *s, rkvc_diagnostic **diag)
启动会话。
-
diag - 可选诊断输出。
- Return
- 成功返回
RKVC_OK。
rkvc_session_try_pull¶
rkvc_status rkvc_session_try_pull(rkvc_session *s, rkvc_frame **out)
非阻塞拉取一帧；无可用数据时返回 `RKVC_AGAIN`。
rkvc_session_wait¶
rkvc_status rkvc_session_wait(rkvc_session *s)
等待管道排空，返回首个错误或 `RKVC_OK`。
rkvc_status_str¶
const char *rkvc_status_str(rkvc_status status)
状态码转可读字符串（静态存储，无需释放）。