rawlib/
ffi.rs

1//! Foreign Function Interface (FFI) bindings to LibRaw C API
2//!
3//! This module provides safe Rust bindings to the LibRaw C library functions.
4//! LibRaw is a library for reading RAW files from digital cameras.
5//!
6//! The bindings include:
7//! - Core initialization and cleanup functions
8//! - File opening and processing operations
9//! - Thumbnail extraction functionality
10//! - Memory management helpers
11//! - Error code constants and utilities
12
13use libc::{c_char, c_int, c_ushort, c_uchar};
14
15// Windows 平台需要使用宽字符 API
16#[cfg(windows)]
17use std::os::raw::c_ushort as wchar_t;
18
19// libraw_data_t 是一个不透明指针类型，用于表示 LibRaw 数据结构
20// 我们使用空枚举来创建类型安全的指针，而不暴露内部结构
21pub enum libraw_data_t {}
22
23// LibRaw 处理后的图像数据结构
24// 这个结构体表示 LibRaw 解码后的图像数据，包括缩略图和完整图像
25#[repr(C)]  // 确保 C 内存布局兼容性
26pub struct libraw_processed_image_t {
27    /// 图像格式类型 (JPEG = 1, Bitmap = 2)
28    pub image_type: c_int,
29    /// 图像高度（像素）
30    pub height: c_ushort,
31    /// 图像宽度（像素）
32    pub width: c_ushort,
33    /// 颜色通道数
34    pub colors: c_ushort,
35    /// 每像素位数
36    pub bits: c_ushort,
37    /// 图像数据大小（字节）
38    pub data_size: u32,
39    /// 图像数据（柔性数组成员，实际大小由 data_size 决定）
40    /// 注意：在 Rust 中我们使用长度为 1 的数组来表示柔性数组成员
41    pub data: [c_uchar; 1],
42}
43
44// 链接配置：根据目标平台选择不同的库名称
45// Windows MSVC 使用 libraw_static 静态库
46#[cfg_attr(all(target_os = "windows", target_env = "msvc"), link(name = "libraw_static", kind = "static"))]
47// 其他平台使用 raw 静态库（如果可用）或动态库
48#[cfg_attr(not(all(target_os = "windows", target_env = "msvc")), link(name = "raw", kind = "static"))]
49extern "C" {
50    // === 库版本信息 ===
51    /// 获取 LibRaw 版本字符串
52    pub fn libraw_version() -> *const c_char;
53
54    /// 获取 LibRaw 版本号（整数格式）
55    pub fn libraw_versionNumber() -> c_int;
56
57    // === 构造函数和析构函数 ===
58    /// 初始化 LibRaw 实例
59    /// flags: 初始化标志，通常使用 LIBRAW_OPTIONS_NONE
60    /// 返回: 指向 libraw_data_t 的指针，失败时返回 NULL
61    pub fn libraw_init(flags: c_int) -> *mut libraw_data_t;
62
63    /// 关闭 LibRaw 实例并释放所有资源
64    pub fn libraw_close(data: *mut libraw_data_t);
65
66    // === 文件操作 ===
67    /// 打开 RAW 文件
68    /// data: LibRaw 实例指针
69    /// filename: 文件名（UTF-8 字符串）
70    /// 返回: LIBRAW_SUCCESS 表示成功，其他值表示错误
71    pub fn libraw_open_file(data: *mut libraw_data_t, filename: *const c_char) -> c_int;
72
73    /// Windows 平台：打开宽字符文件名
74    #[cfg(windows)]
75    pub fn libraw_open_wfile(data: *mut libraw_data_t, filename: *const wchar_t) -> c_int;
76
77    /// 解包 RAW 文件数据（解析文件头和基本信息）
78    pub fn libraw_unpack(data: *mut libraw_data_t) -> c_int;
79
80    /// 处理 RAW 数据（去马赛克、色彩转换等）
81    pub fn libraw_dcraw_process(data: *mut libraw_data_t) -> c_int;
82
83    // === 缩略图操作 ===
84    /// 解包缩略图数据
85    pub fn libraw_unpack_thumb(data: *mut libraw_data_t) -> c_int;
86
87    /// 从缩略图数据创建内存中的图像
88    /// errc: 输出参数，接收错误代码
89    /// 返回: 指向处理后图像的指针，失败时返回 NULL
90    pub fn libraw_dcraw_make_mem_thumb(data: *mut libraw_data_t, errc: *mut c_int) -> *mut libraw_processed_image_t;
91
92    /// 释放由 libraw_dcraw_make_mem_* 分配的内存
93    pub fn libraw_dcraw_clear_mem(img: *mut libraw_processed_image_t);
94
95    // === 错误处理 ===
96    /// 获取错误代码的描述字符串
97    pub fn libraw_strerror(error_code: c_int) -> *const c_char;
98
99    // === 内存管理 ===
100    /// 回收 LibRaw 实例的数据流，准备处理新文件
101    /// 这比 libraw_close 更轻量级，不会释放所有内存
102    pub fn libraw_recycle(data: *mut libraw_data_t);
103}
104
105// === LibRaw 初始化标志常量 ===
106/// 无特殊选项
107pub const LIBRAW_OPTIONS_NONE: c_int = 0;
108
109/// 禁用内存错误回调
110pub const LIBRAW_OPIONS_NO_MEMERR_CALLBACK: c_int = 1;
111
112/// 禁用数据错误回调
113pub const LIBRAW_OPIONS_NO_DATAERR_CALLBACK: c_int = 1 << 1;
114
115// === LibRaw 返回代码常量 ===
116/// 操作成功
117pub const LIBRAW_SUCCESS: c_int = 0;
118
119/// 未指定错误
120pub const LIBRAW_UNSPECIFIED_ERROR: c_int = -1;
121
122/// 不支持的文件格式
123pub const LIBRAW_FILE_UNSUPPORTED: c_int = -2;
124
125/// 请求不存在的图像
126pub const LIBRAW_REQUEST_FOR_NONEXISTENT_IMAGE: c_int = -3;
127
128/// 函数调用顺序错误
129pub const LIBRAW_OUT_OF_ORDER_CALL: c_int = -4;
130
131/// 没有缩略图
132pub const LIBRAW_NO_THUMBNAIL: c_int = -5;
133
134/// 不支持的缩略图格式
135pub const LIBRAW_UNSUPPORTED_THUMBNAIL: c_int = -6;
136
137/// 输入已关闭
138pub const LIBRAW_INPUT_CLOSED: c_int = -7;
139
140/// 内存不足
141pub const LIBRAW_INSUFFICIENT_MEMORY: c_int = -100;
142
143/// 数据错误（损坏的文件）
144pub const LIBRAW_DATA_ERROR: c_int = -101;
145
146/// I/O 错误（读写失败）
147pub const LIBRAW_IO_ERROR: c_int = -102;
148
149/// 操作被回调取消
150pub const LIBRAW_CANCELLED_BY_CALLBACK: c_int = -103;
151
152/// 错误的裁剪参数
153pub const LIBRAW_BAD_CROP: c_int = -104;
154
155/// 图像太大
156pub const LIBRAW_TOO_BIG: c_int = -105;
157
158/// 内存池溢出
159pub const LIBRAW_MEMPOOL_OVERFLOW: c_int = -106;
160
161// === 图像格式常量 ===
162/// JPEG 格式图像
163pub const LIBRAW_IMAGE_JPEG: c_int = 1;
164
165/// 位图格式图像（未压缩的 RGB 数据）
166pub const LIBRAW_IMAGE_BITMAP: c_int = 2;
rawlib/ffi.rs

rawlib/
ffi.rs
