类型

crate darra-ai 对外导出的值类型。错误枚举见 错误处理；会话见 Session。

use darra_ai::{Error, ImageDesc, ImageFormat, Session, SessionOptions};

类别	属性	类型	访问	说明
图像	ImageFormat	enum	类型	Auto / Encoded / Rgb888 / Bgr888。裸缓冲禁止 Auto
	ImageDesc	struct	类型	图像描述。调用 infer_image 时绑定自动填 FFI size
	ImageDesc::format	ImageFormat	字段	图像输入格式。Auto/Encoded 时 width/height/stride 忽略（填 0）
	ImageDesc::width	u32	字段	裸缓冲宽。Rgb888/Bgr888 时必填（>0）
	ImageDesc::height	u32	字段	裸缓冲高。Rgb888/Bgr888 时必填（>0）
	ImageDesc::stride	u32	字段	每行字节数。0 = 紧凑排列（Rgb888/Bgr888 = width×3）
会话选项	SessionOptions	struct	类型	open_ex 的可扩展选项。构造本对象不加载 native
	SessionOptions::key_path	Option<String>	字段	.darmkey 路径；None = 走密码/试用通道
	SessionOptions::password	Option<String>	字段	永久密码；None = 走授权文件/试用通道
	SessionOptions::prefer_provider	Option<String>	字段	指名 Provider；None = 自动选。指名但不可用 = fail-closed

图像

ImageFormat

图像输入格式。本绑定目前露出四个值。头文件另有 GRAY8 / RGBA8888，Rust 枚举尚未露出。

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(i32)]
pub enum ImageFormat {
    Auto = 0,     // 按字节魔数自嗅探编码格式（JPG/PNG/BMP）。裸缓冲禁止用 Auto
    Encoded = 1,  // 显式声明为已编码字节流（JPG/PNG/BMP）；行为同 Auto
    Rgb888 = 2,   // 裸缓冲，RGB 三通道 8bit，须给宽高
    Bgr888 = 3,   // 裸缓冲，BGR 三通道 8bit，须给宽高
}

每次 infer_image 处理一张图（一帧）。连续采集循环调用。

ImageDesc

对应 C ABI darra_image_desc。调用 infer_image 时绑定自动填 size = sizeof(darra_image_desc)，用户侧不必碰 FFI。

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ImageDesc {
    pub format: ImageFormat,
    pub width: u32,
    pub height: u32,
    pub stride: u32, // 每行字节数；0 = 紧凑排列（width * 3）
}

相关结构: 构造函数

impl ImageDesc {
    pub fn auto() -> Self;
    pub fn rgb888(width: u32, height: u32, stride: u32) -> Self;
    pub fn bgr888(width: u32, height: u32, stride: u32) -> Self;
}

• auto() — 编码字节流（JPG/PNG/BMP），自嗅探。width/height/stride = 0
• rgb888(w, h, stride) — 裸 RGB888。stride = 0 表示紧凑（= w × 3）
• bgr888(w, h, stride) — 裸 BGR888（工业相机常见）

没有 encoded() 关联函数；需要显式 Encoded 时用结构体字面量：

use darra_ai::{ImageDesc, ImageFormat};

let encoded = ImageDesc {
    format: ImageFormat::Encoded,
    width: 0,
    height: 0,
    stride: 0,
};

Rgb888 / Bgr888 时 width / height 必填（>0）；缺宽高 = Error::Internal（调用方 bug，不崩溃）。裸缓冲禁止 Auto（嗅探不出通道序）。

用法见 推理。

会话选项

SessionOptions

开会话的可扩展选项（对齐 C# SessionOptions）。字段对应 darra_session_open 的可选通道。当前没有 Core darra_session_options 的 intra_op_threads / inter_op_threads / cpu_affinity_mask。

#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct SessionOptions {
    pub key_path: Option<String>,
    pub password: Option<String>,
    pub prefer_provider: Option<String>,
}

相关结构: 构造与链式 setter

impl SessionOptions {
    pub fn new() -> Self; // 全部可选通道为空
    pub fn key_path(self, v: impl Into<String>) -> Self;
    pub fn password(self, v: impl Into<String>) -> Self;
    pub fn prefer_provider(self, v: impl Into<String>) -> Self;
}

示例:

use darra_ai::SessionOptions;

let opt = SessionOptions::new()
    .key_path("model.darmkey")
    .prefer_provider("onnx-cpu");

prefer_provider 合法 ID 见 ensure · 合法 ID。Windows 上不要指名 edge-rknn（Error::UnsupportedPlatform）。两个授权通道至少给一个；都给则 key 文件优先验票。

用法见 Session::open_ex。

Session 是不透明 RAII 句柄，不可 Clone，Send + Sync，详见 Session。Error 是 #[non_exhaustive] 枚举，详见 错误处理。