【LibRaw】原始图像解码库介绍（八）——C++ API之辅助功能

辅助功能

库版本检查

const char * LibRaw :: version（）

以MAJOR.MINOR.PATCH-Status格式返回LibRaw版本的字符串表示形式（即0.6.0-Alpha2或0.6.1-Release）。

int LibRaw :: versionNumber（）

返回LibRaw版本的整数表示形式。在LibRaw开发期间，版本号总是增加。

bool LIBRAW_CHECK_VERSION（主要，次要，补丁）

用于调用者应用程序中的版本检查的宏。如果当前库版本大于或等于在宏参数中设置，则返回“true”。该宏在运行时（不是在编译时）执行，可用于检查动态加载的LibRaw的版本（来自DLL /共享库）。

支持的RAW格式列表（摄像机）

int LibRaw :: cameraCount（）

返回支持的摄像机数量。

const char ** LibRaw :: cameraList（）

返回支持的摄像头列表。列表的最新项目设置为NULL（便于打印）。

int LibRaw :: set_rawspeed_camerafile（char * path_to_cameras_xml）

（仅当LibRaw使用RawSpeed支持构建时）。

使用path_to_cameras_xml指定的RawSpeed相机描述数据（cameras.xml）加载XML文件。成功时返回0，出错时返回非零值。

int LibRaw :: get_decoder_info（libraw_decoder_info_t *）

该函数通过传递指针与当前原始解码器数据来填充libraw_decoder_info_t结构。

该函数根据返回代码约定返回一个整数：如果任何系统调用返回错误，则为正数;如果LibRaw中存在错误情况，则返回负数（来自LibRaw错误列表）。

const char * LibRaw :: unpack_function_name（）

返回文件解包功能的函数名称。仅供LibRaw测试套件设计人员用于测试覆盖率评估。

void LibRaw :: setCancelFlag（）

此调用设置内部快速取消标志。如果设置，当前的Raw解码器将尽快终止。如果您需要在多线程程序中取消所有LibRaw解码器（例如，用于快速程序终止或仅用于取消当前处理），则此调用很有用。

void LibRaw :: clearCancelFlag（）

此调用清除内部快速取消标志，因此（早期）终止的LibRaw解码器可能再次工作。

int LibRaw :: COLOR（int row，int col）

此调用返回行，列中的拜耳模式中的像素颜色（颜色组件编号）。对于4分量拜耳（RGBG2，CMYG等），返回值在0..3范围内，对于3色数据，返回值在0..2范围内。

int LibRaw :: error_count（）

此调用返回unpack（）阶段中发生的非致命数据错误（超出范围等）的计数。

void LibRaw :: subtract_black（）

该调用将从RAW数据中减去黑色电平值（对于合适的RAW数据）。colordata.data_maximum和colordata.maximum和黑电平数据（colordata.black和colordata.cblack）也将进行调整。

如果您使用自己的代码对RAW数据进行后处理，则应使用此调用。LibRaw 后处理函数将自己调用subtract_black（）。

该函数根据返回代码约定返回一个整数：如果任何系统调用返回错误，则为正数;如果LibRaw中存在错误情况，则返回负数（来自LibRaw错误列表）。

支持浮点数据

Libraw可以读取浮点DNG文件（没有其他RAW格式可以使用浮点），无论是否转换为整数数据。浮点值存储在imgdata.rawdata缓冲区中：

• float * float_image（如果不为NULL）指向浮点拜耳数据
• float（* float3_image）[3]（如果不是NULL）指向浮点3通道缓冲区
• float（* float4_image）[4]（如果不是NULL）指向浮点4通道缓冲区

函数调用浮点支持：

• int LibRaw :: is_floating_point（）; 如果文件包含浮点数据，则函数将返回1
• int LibRaw :: have_fpdata（）; 如果FP数据已读取（解码）到内存中而未转换为整数数据，则函数将返回1
• int LibRaw :: convertFloatToInt（float dmin = 4096.f，float dmax = 32767.f，float dtarget = 16383.f）将浮点数据转换为整数。如果数据最大值超出dmin..dmax范围，则将数据缩放为将最大值设置为dtarget

支持YCC格式（佳能sRAW / mRAW和尼康小型NEF）

       int LibRaw :: is_sraw（）; 
       int LibRaw :: is_nikon_sraw（）; 
       int LibRaw :: sraw_midpoint（）

• 如果当前图像是基​​于YCC的，则is_sraw（）调用返回非零值。
• is_nikon_sraw（）调用为Nikon Small NEF文件返回非零值
• sraw_midpoint（）调用返回颜色通道的中性（灰色）点

void LibRaw :: set_dng_host（void * p）

如果使用Adobe DNG SDK支持编译LibRaw并且您希望使用此支持：

• 你需要创建自己的dng_host对象
• 并使用此函数将其传递给LibRaw对象

void LibRaw :: recycle_datastream（void）

此调用关闭带有关联数据缓冲区的输入数据流并取消阻止打开的文件。

void LibRaw :: recycle（void）

释放LibRaw实例的已分配数据，使用同一处理器处理下一个文件。反复调用recycle（）是非常可能的，不要与任何东西发生冲突。

LibRaw ::〜LibRaw（）

析构函数，包含调用recycle（）。

const char * LibRaw :: strprogress（enum LibRaw_progress代码）

将进度阶段代码转换为描述字符串（英文）。

const char * LibRaw :: strerror（int errorcode）

模拟strerror（3）函数：输出LibRaw错误代码的文本描述（英文）。

设置错误通知功能

在RAW转换过程中，LibRaw可以调用用户设置的回调。此回调可用于：

• 动态状态更新（进度条等）。
• 取消处理（例如，用户按下取消按钮）。

此外，库的工作可能会导致需要通知调用应用程序的两种类型的异常情况：

• 内存不足
• 数据读取错误。

应用程序可以设置自己的回调，这些回调将在上述情况下被调用以通知用户（或调用程序）。

进度指示/处理终止

        typedef int（* progress_callback）（void * callback_data，enum LibRaw_progress stage，int iteration，int expected）; 
        void LibRaw :: set_progress_handler（progress_callback func，void * callback_data）;

LibRaw用户可以设置自己的回调，在dcraw_process（）的RAW后处理期间将调用10-50次。

该回调可以通过返回非零值来终止当前图像处理。在这种情况下，所有处理将立即取消，所有资源将通过recycle（）调用返回给系统。当前调用dcraw_process（）将返回错误代码LIBRAW_CANCELLED_BY_CALLBACK。

回调参数：

void * callback_data

void * -pointer，作为第二个参数传递给set_progress_handler（）。该指针应该用于将附加数据传递给回调（即线程本地数据等）。

枚举LibRaw_progress阶段

目前的处理阶段。可以通过调用 LibRaw :: strprogress 将此数字转换为字符串。并非所有处理阶段都包含在回调调用中。

int迭代

当前阶段内的迭代次数（从0到预期-1）。

int预期

当前阶段的预期迭代次数。

回调应返回值：0表示继续处理，非零表示立即取消处理。

 

如果使用OpenMP支持编译LibRaw，迭代参数可能不会总是在一个阶段内增加。乱序调用是可能的。

回调代码示例：

int my_progress_callback（void * data，enum LibRaw_progress p，int iteration，int expected）
{ 
    char * passed_string =（char * data）; 
    printf（“回调：％s传递％d％d，数据传递：％s \ n”，libraw_strprogress（p），iteration，expected，passed_string）; 
    if（timeout || key_pressed）
        返回1; //立即取消处理，
    否则
        返回0; //可以继续
}

用户指定的exif标记解析器回调

       typedef void（* exif_parser_callback）（void * context，int tag，int type，int len，unsigned int ord，void * ifp）; 
       void LibRaw :: set_exifparser_handler（exif_parser_callback cb，void * context）;

使用参数在每个已解析的EXIF / Makernotes标记上调用回调：

• context - 指向传递给set_exifparser_handler（）的上下文的指针;
• tag - EXIF / Makernotes标记值
• type - TIFF（EXIF）标记类型
• len - 标签长度
• ord - 字节顺序（II或MM）
• void * ifp - 指向LibRaw_abstract_datastream的指针，用于标记数据

 

内存不通知程序

        typedef void（* memory_callback）（void * callback_data，const char * file，const char * where）; 
        void LibRaw :: set_memerror_handler（memory_callback func，void * callback_data）;

在内存不足的情况下，用户可以设置他或她自己的功能。它是一个接收两个字符串参数的void函数：

• void * callback_data - void * -pointer，作为第二个参数传递给set_progress_handler（）。该指针应该用于将附加数据传递给回调（即线程本地数据等）。
• file是RAW文件的名称，其处理引发了内存不足错误。如果基础数据输入层不知道名称，则此名称可以为NULL。因此，如果调用应用程序集自己的回调，则此回调应该使用NULL文件名。
• 哪里是发生内存不足的函数的名称。

回调函数用于信息目的：它通知用户或程序代码无法进行处理。

如果用户未设置自己的处理程序，则将使用标准处理程序（stderr中的错误消息输出）。

可以通过将NULL传递给set_memerror_handler来设置null处理程序; 那么就不会调用通知函数。通过在构造函数中创建具有LIBRAW_OPTIONS_NO_MEMERR_CALLBACK标志的LibRaw对象，可以实现相同的效果。

在内存不足的情况下，终止当前文件的处理并调用通知程序; 释放所有已分配的资源，并执行recycle（）。当前调用将返回LIBRAW_UNSUFFICIENT_MEMORY。
在尝试继续数据处理时，所有后续调用都将返回LIBRAW_OUT_OF_ORDER_CALL。可以通过调用LibRaw :: open_file（）以通常的方式开始处理新文件。

文件读错误通知程序

        typedef void（* data_callback）（void * callback_data，const char * file，const int offset）; 
        void LibRaw :: set_dataerror_handler（data_callback func，void * callback_data）;

在输入数据中出现错误的情况下，用户可以定义他或她自己的要调用的函数。它是一个接收两个参数的void函数：

• void * callback_data - void * -pointer，作为第二个参数传递给set_progress_handler（）。该指针应该用于将附加数据传递给回调（即线程本地数据等）。
• file是RAW文件的名称，其处理引起文件读取错误。如果基础数据输入层不知道名称，则此名称可以为NULL。因此，如果调用应用程序集自己的回调，则此回调应该使用NULL文件名。
• offset在文件结尾处为-1（如果LibRaw需要更多数据）或正数等于发生解包错误的文件位置（文件开头的字节数）。

回调函数用于信息目的：它通知用户或程序代码无法进行处理。

如果用户未设置自己的处理程序，则将使用标准处理程序（stderr中的错误消息输出）。

可以通过将NULL传递给set_memerror_handler来设置null处理程序; 那么就不会调用通知函数。通过在构造函数中创建具有LIBRAW_OPTIONS_NO_DATAERR_CALLBACK标志的LibRaw对象，可以实现相同的效果。

在输入数据中出现错误的情况下，终止当前文件的处理并调用通知程序; 释放所有已分配的资源，并执行recycle（）。当前调用将返回LIBRAW_IO_ERROR。
在尝试继续数据处理时，所有后续调用都将返回LIBRAW_OUT_OF_ORDER_CALL。可以通过调用LibRaw :: open_file（）以通常的方式开始处理新文件。