Содержание
Основной объект (класс) LibRaw, создается либо без параметров, либо передаются флаги, определяющие поведение объекта.
#include "libraw/libraw.h" ... LibRaw ImageProcessor(unsigned int flags=0); ...
Флаги (несколько флагов задаются через | - оператор bitwise-OR):
Для обработки изображения используются три группы методов
Результаты обработки размещаются в поле imgdata, которое имеет тип libraw_data_t, в этом же наборе данных содержатся поля, управляющие постобработкой и выводом.
Все функции LibRaw API возвращают целое число в соответствии с соглашением о кодах возврата. Пожалуйста, прочитайте описание этого соглашения и описание поведения LibRaw при фатальных ошибках.
Открывает поток с RAW-данными, считывает оттуда метаданные (EXIF), заполняет структуры:
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Перед началом обработки вызывается recycle(), следовательно при обработке нескольких изображений в batch-режиме необязательно вызываеть recycle() в конце цикла обработки.
Входной параметр: Объект класса, производного от LibRaw_abstract_datastream. Объект должен быть проиницализирован и готов к чтению. Деинициализация объекта производится в вызвавшем приложении.
Создает объект LibRaw_file_datastream или LibRaw_bigfile_datastream, вызывает open_datastream(), при успехе выставляет внутренний флаг, сигнализирующий о том, что созданный объект должен быть уничтожен при recycle(), при неуспехе открытия - уничтожает только что созданный объект.
Необязательный Параметр bigfle_size задает размер входного файла, начиная с которого происходит использование LibRaw_bigfile_datastream. По-умолчанию, этот размер равен 250 Мб.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Создает объект LibRaw_buffer_datastream, вызывает open_datastream(), при успехе выставляет внутренний флаг, сигнализирующий о том, что созданный объект должен быть уничтожен при recycle(), при неуспехе открытия - уничтожает только что созданный объект.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Производит распаковку RAW-данных изображения и вычисление уровня черного (не для всех форматов). Результаты работы помещаются в imgdata.image.
На чтение данных в ряде (редких) случаев влияют настройки, сделанные в imgdata.params (libraw_output_params_t), подробнее см. в API notes.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Производит чтение (либо распаковку) preview (thumbnail) изображения,
помещая результат в буфер imgdata.thumbnail.thumb.
JPEG-preview помещаются в данный буфер без каких-либо изменений (с
заголовком и т.п.), Другие форматы preview помещаются в буфер в виде распакованого
image bitmap (3 компонента, 8 бит на компонент).
Формат thumbnail записывается в поле imgdata.thumbnail.tformat,
возможные значения описаны в описании констант и структур данных.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Возвращает строковое представление версии библиотеки в формате MAJOR.MINOR.PATCH-Status (например, 0.6.0-Alpha2 или 0.6.1-Release).
Возвращает целочисленное представление версии библиотеки. При выходе новых версий библиотеки версия всегда не убывает.
Макрос для проверки версии в прикладных программах. Возвращает true если текущая версия библиотеки больше или равна переданной в параметрах. Макрос выполняется динамически и может использоваться для проверки версии библиотеки, загружаемой из shared library/DLL.
Возвращает количество камер, поддерживаемых текущей версией библиотеки.
Возвращает cписок камер, поддерживаемых библиотекой. Список на 1 элемент длиннее, чем количество камер, в последнем элементе списка содержится NULL.
Функция заполняет структуру libraw_decoder_info_t по переданному указателю данными о текущем декодере.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Возвращает имя функции-распаковщика файла. Интересна только разработчикам тестов для LibRaw, чтобы проверить test coverage.
Вызов производит вычитание уровня черного из RAW-данных, если вычитание не произведено самой камерой. При этом соответствующим образом исправляются поля colordata.channel_maximum, colordata.channel_maximum и даные об уровне черного (colordata.black и colordata.cblack).
Данный вызов надлежит использовать в случае, когда вы хотите делать постпроцессинг RAW-данных самостоятельно. Встроенные в LibRaw функции постпроцессинга вызовут subtract_black() самостоятельно.
Освобождает аллоцированные данные экземпляра LibRaw, делая возможным обработку следующего файла тем же процессором. Повторные вызовы recycle() вполне возможны и ничему не противоречат.
Деструктор, сводится к вызову recycle()
Выдает текстовую расшифровку (на английском языке) для кодов текущей стадии обработки LibRaw
Аналог функции strerror(3) - выдает текстовую расшифровку (на английском языке) для кодов ошибок LibRaw
При работе библиотеки можно вызывать пользовательский callback, который может быть использован для двух целей:
Кроме того, при работе библиотеки возможны два типа исключительных ситуаций, которые могут требовать уведомления вызывающего приложения:
Приложение может установить свои callbacks, которые будут вызваны в вышеперечисленных случаях, с целью уведомления пользователя (или вызывающей программы).
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);
Пользователь может определить свою функцию, которая будет многократно (10-50 раз) вызываться в процессе обработки данных RAW-файла вызовами dcraw_process()/dcraw_document_mode_processing();
Этот callback может сигнализировать о необходимости прекратить обработку путем возврата ненулевого значения. В этом случае обработка будет завершена, память освобождена вызовом recycle() и объект LibRaw будет готов к обработке следующего файла. Текущий вызов dcraw_process()/dcraw_document_mode_processing() вернет код ошибки LIBRAW_CANCELLED_BY_CALLBACK.
Параметры вызова:
При использовании OpenMP порядок следования iteration неопределен, они не обязаны строго возрастать.
Пример кода callback:
int my_progress_callback(void *data,enum LibRaw_progress p,int iteration, int expected) { char *passed_string = (char *data); printf("Callback: %s pass %d of %d, data passed: %s\n",libraw_strprogress(p),iteration,expected,passed_string); if(timeout || key_pressed ) return 1; // cancel processing immediately else return 0; // can continue }
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-функция, получающая три параметра:
Задача callback - информационная (уведомление пользователя или кода программы о невозможности выполнить обработку).
Если не установить свой обработчик, то будет использован стандартный (печать сообщения об ошибке в stderr).
Можно установить нулевой обработчик, передав NULL в set_memerror_handler, тогда функция уведомления вызываться не будет. Того же эффекта можно добиться, если создать объект LibRaw с флагом конструктора LIBRAW_OPTIONS_NO_MEMERR_CALLBACK.
В случае нехватки памяти, обработка текущего файла прекращается, вызывается уведомитель, все аллоцированные
ресурсы освобождаются, делается 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-функция, получающая три параметра:
Задача callback - информационная (уведомление пользователя или кода программы о невозможности выполнить обработку).
Если не установить свой обработчик, то будет использован стандартный (печать сообщения об ошибке в stderr).
Можно установить нулевой обработчик, передав NULL в set_dataerror_handler, тогда функция уведомления вызываться не будет. Того же эффекта можно добиться, если создать объект LibRaw с флагом конструктора LIBRAW_OPTIONS_NO_DATAERR_CALLBACK.
В случае ошибки во входных данных, обработка текущего файла прекращается, вызывается уведомитель, все
аллоцированные ресурсы освобождаются, делается recycle(). Текущий вызов вернет ошибку
LIBRAW_IO_ERROR.
При попытке продолжить обработку данных, все вызовы последущие будут возвращать
LIBRAW_OUT_OF_ORDER_CALL. Обработку нового файла можно начать обычным образом: вызвав LibRaw::open_file().
Вместо написания своей пост-обработки Bayer Pattern, можно воспользоваться вызовами dcraw (которые вызываются после вызова open_file() + unpack() /+ unpack_thumb()/).
Практически все параметры, которые можно задать через командную строку dcraw, задаются путем присваивания значений полям структуры LibRaw::imgdata.params, структура имеет тип libraw_output_params_t, все поля перечислены и достаточно подробно описаны в описании структур данных.
Функция аллоцирует буфер для постобработки imgdata.image, предварительно освобождая его, если он уже был аллоцирован, и заполняет его данными в формате, совместимыми с версиями LibRaw 0.13 и старше.
Эту функцию следует вызывать самостоятельно только если вы собираетесь самостоятельно обрабатывать RAW-данные и ваш код рассчитан на LibRaw 0.13 и более старые версии. Функции постпроцессинга (см. ниже) вызывают raw2image() самостоятельно.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Этот вызов освобождает буфер imgdata.image, аллоцированный вызовом raw2image();
Эту функцию следует вызывать, если текущий результат постпроцессинга уже не нужен (например, скопирован куда-то), но возможны повторные вызовы постпроцессинга тех же данных (например, с другими параметрами), поэтому вызывать recycle() еще рано.
Функция рассчитывает правильные размеры выходного изображения (imgdata.sizes.iwidth и imgdata.sizes.iheight) для следующих случаев:
В перечисленных выше случаях, функция меняет значения полей выходного размера изображения, причем это изменение не может быть выполнено повторно.
Функция должна использоваться в информационных целях, она несовместима с вызовами dcraw_document_mode_processing() и dcraw_process().
Функция эмулирует dcraw -D - отключение интерполяции, баланса белого и преобразования цветов.
Вызывается после вызова LibRaw::unpack();
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Функция эмулирует возможности постобработки, имеющиеся в dcraw
Вызывается после вызова LibRaw::unpack();
Поддерживается вся функциональность dcraw (задаваемая через значение полей в imgdata.params) за исключением:
Функция предназначена исключительно для демонстрационных и тестовых целей, предполагается что в большинстве реальных приложений ее исходный текст будет использован как справочник по порядку обработки RAW-данных.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Несмотря на обилие библиотек, предназначенных для записи файлов любых форматов, в LibRaw включены вызовы, эмулирующие запись в файлы, производимую dcraw. В первую очередь это сделано для облегчения верификации работы библиотеки - производимые ей файлы должны бинарно совпадать.
Записывает результаты постобработки в файл в формате PPM/PGM или TIFF (формат задается через imgdata.params.output_tiff). Производит результаты, бинарно идентичные с dcraw.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Записывает thumbnail в файл в формате PPM для bitmap-thumbnails и JPEG для JPEG-thumbnails, в формате полностью идентичном результатам работы dcraw.
Функция возвращает целое число в соответствии с соглашением о кодах возврата: положительное число, если какой-то из системных вызовов вернул ошибку, отрицательное число (из списка ошибок LibRaw) при ошибочной ситуации внутри LibRaw.
Помимо записи в файл, библиотека предоставляет возможности записи извлеченных и обработанных функциями dcraw_* данных в буфер в памяти. Для этого имеются такие вызовы:
Значения (размеры изображения) возвращаются в переменных, заданных указателями:
Параметры функции:
The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.
Аллоцирует буфер необходимого размера и записывает в него распакованное и обработанное изображение. Возвращает аллоцированную структуру libraw_processed_image_t с заполненными полями. Всегда возвращает распакованый bitmap (т.е. поле type возвращаемой структуры равно LIBRAW_IMAGE_BITMAP).
Перед вызовом этой функции должна быть вызвана dcraw_process() или dcraw_document_mode_processing().
В случае ошибки возвращается NULL. Если в качестве аргумента errorcode передан ненулевой указатель, то по адресу указателя записывается код ошибки в соответствии с соглашением о кодах возврата.
Внимание! Память, аллоцированная функцией, не освобождается при вызове деструктора или LibRaw::recycle и должна быть освобождена вызвавшим приложением путем вызова LibRaw::dcraw_clear_mem().
Аллоцирует буфер необходимого размера и записывает в него thumbnail. Возвращает аллоцированную структуру libraw_processed_image_t с заполненными полями. Для большинства типов RAW-файлов в структуре будет содержаться JPEG, (т.е. поле type возвращаемой структуры равно LIBRAW_IMAGE_JPEG), для некоторых типов камер - RGB-bitmap.
Перед вызовом этой функции должна быть вызвана unpack_thumb();
В случае ошибки возвращается NULL. Если в качестве аргумента errorcode передан ненулевой указатель, то по адресу указателя записывается код ошибки в соответствии с соглашением о кодах возврата.
Внимание! Память, аллоцированная функцией, не освобождается при вызове деструктора или LibRaw::recycle и должна быть освобождена вызвавшим приложением путем вызова LibRaw::dcraw_clear_mem().
Освобождает память, аллоцированную dcraw_make_mem_image и dcraw_make_mem_thumb.
Это статический член класса, вызывать его нужно как LibRaw::dcraw_clear_mem(...).
Данный вызов эквивалентен вызову системной функции free(), но рекомендуется использовать именно его, так как не исключено, что LibRaw и вызывающее приложение используют разные и несовместимые системы управления памятью.
Чтение RAW-данных в LibRaw производится при помощи объекта класса, производного от LibRaw_abstract_datastream. Сам этот класс не реализует никакого чтения, но задает список виртуальных методов, используемых в LibRaw. Реализации методов в базовом классе возвращают ошибку.
Данная группа методов воспроизводит семантику объекта файл (FILE*) с произвольным позиционированием.
Данная группа методов включает в себя разнообразные вспомогательные методы, обеспечивающие временное переключение потока ввода на другой объект.
Этот метод реализован в рамках базового класса, переопределение в производных классах не требуется. Однако наличие и возможная активность временного потока данных требует аккуратного программирования при реализации собственных методов ввода-вывода. Подробнее это описано в разделе реализация собственных интерфейсов чтения ниже.
В состав LibRaw входят два стандартных класса, реализующих ввод данных:
Кроме того, пользователи C++-интерфейса могут реализовывать собственные методы чтения и использовать их через метод LibRaw::open_datastream, требования и особенности реализации описаны ниже.
Данные классы реализуют ввод данных из файла.
Методы класса:
Все прочие методы класса полностью соответствуют описанным выше.
Данный класс реализует все методы, включая fname() и subfile_open().
Данный класс реализует ввод данных из буфера в памяти.
Методы класса:
Все прочие методы класса полностью соответствуют описанным выше.
Данный класс не поддерживает методы fname() subfile_open(), следовательно разбор внешних JPEG-файлов
с метаданными невозможен.
Для создания собственных интерфейсов чтения необходимо сделать класс, производный от LibRaw_abstract_datastream и реализовать в нем все методы чтения, описанные выше. В качестве образца можно использовать реализацию стандартных классов, поставляемых с LibRaw, посмотреть которую можно в файле libraw/libraw_datastream.h в поставке (оба стандартных интерфейса ввода реализованы только на inline-функциях).
Отдельного описания требует поле substream, которое объявлено в базовом классе и используется при временном
переключении ввода на другой поток данных. C++ не дает средств для красивой реализации нужной функциональности,
поэтому любой читающий метод ввода должен содержать в начале приблизительно такую строку:
int method(...args...){ if(substream) return substream->method(...args...). Например:
virtual int eof() { if(substream) return substream->eof(); .... virtual int scanf_one(const char *fmt, void* val) { if(substream) return substream->scanf_one(fmt,val);[вернуться к оглавлению]