Начиная с версии 0.9, библиотека LibRaw существует в единственном варианте. Более старые версии существовали в трех редакциях (основная, облегченная и коммерческая).
Приняты следующие соглашения о возвращаемых ошибках
В случае возникновения нештатной ситуации, не мешающей получить из файла какие-то данные, о ней будет просигнализировано путем взведения соответствующего бита в imgdata.process_warnings. Возможные типы предупреждений перечислены и расшифрованы здесь.
LibRaw использует для чтения файла объект, производный от класса LibRaw_abstract_datastream. Cемантика этого класса схожа с семантикой объектов типа "файл с произвольным позиционированием", объект реализующий ввод должен поддерживать операции позиционирования и чтения.
Для работы с некоторыми форматами, содержащими зашифрованые куски TIFF-каталогов, требуется временное
переключение ввода на временный поток, привязанный к созданному LibRaw буферу в памяти. Эта функциональность
реализуется в базовом классе LibRaw_abstract_datastream через
имеющеется там поле substream, которое является указателем на объект класса
LibRaw_buffer_datastream.
При использовании собственных реализаций потоков данных, необходимо в методах чтения и позиционирования
проверять инициализированность этого поля и если оно не нулевое - передавать управление туда. Подробнее
см. реализацию класса
LibRaw_file_datastream в заголовочном файле
libraw/libraw_datastream.h.
Если поток данных знает имя обрабатываемого файла в файловой системе, он должен уметь сообщить его всем, кто в нем нуждается вызовом fname(). Это имя будет использовано при вызове callbacks (уведомителях об ошибках) и может быть использовано для генерации имени файла с метаданными, если это нужно для распаковываемого формата.
Для некоторых форматов данных метаданные (экспозиционные параметры, баланс белого) не хранятся в RAW-файле, но
могут быть считаны из JPEG-версии того же снимка. Если реализация надстройки над
LibRaw_abstract_datastream умеет вернуть имя обрабатываемого файла при
вызове fname(), то предполагается, что для такой реализации возможно временное переключение потока ввода
на другой файл. Чтобы это было действительно так,
реализация потока данных должна реализовать методы
subfile_open()/subfile_close(). Стандартные реализации, унаследованные от базового класса, просто
возврашают код ошибки.
Пример реализации методов открытия дополнительного потока данных можно подсмотреть в реализации класса
LibRaw_file_datastream в заголовочном файле
libraw/libraw_datastream.h.
Thread safety обеспечивается, если объект LibRaw создается и иcпользуется внутри одного thread. При этом количество threads (каждая со своим объектом LibRaw) ничем не ограничено (кроме потребностей в памяти).
В случае создания объекта LibRaw в одном потоке исполнения, а использования в другом - необходима внешняя синхронизация, не дающая произвести одновременный доступ к одному объекту.
В Unix (Linux/FreeBSD/MacOS) собираются две версии библиотеки: thread-safe версия libraw_r.a и более быстрая не thread-safe libraw.a.
Thread-safe версия использует для хранения локальных данных поля в классе LibRaw, что позволяет иметь несколько экземпляров класса LibRaw, работающих одновременно.
Не thread-safe версия хранит промежуточные данные в глобальных переменных, что несколько быстрее. Не thread-safe версия может использоваться и в multithreaded-приложениях, но только если экземпляр класса LibRaw гарантированно один.
Под Windows собирается только thread-safe версия.
При обработке исключительных ситуаций внутри LibRaw используется механизм C++ exceptions. Все исключения перехватываются внутри функций библиотеки и проникать наружу не должны.
Для аллокации/освобождения памяти используются функции malloc(calloc)/free, а не new/delete.
Какие-либо специфические библиотеки (STL, Boost, smart pointers) - не используются.
При использовании С API ссылки на C++-вызовы new/delete остаются, поэтому линковаться надо с libstdc++(Unix)/....(Windows).
Большинство полей данных структуры LibRaw::imgdata.params влияют только на постобработку данных, но есть ряд исключений, унаследованных текущей версией LibRaw от особенностей исходных текстов dcraw (постепенно эти зависимости будут удаляться).
imgdata.sizes.flip = imgdata.params.user_flip.
На этапе обработки RAW-данных LibRaw может осуществлять такие стадии обработки:
В текущей версии LibRaw возможны следующие настройки фильтрации (настройка производится через задание параметра imgdata.params.filtering_mode в одно из значений enum LibRaw_filtering:
Для части форматов RAW LibRaw извлекает данные неактивных сенсоров матрицы ("маскированные пикселы" или "черная рамка") и сохраняет их в структуре данных imgdata.masked_pixels. Эти данные затем могут быть использованы для:
Данные черной рамки доступны только RAW-данных с байеровскими данными (один компонент на пиксель) и только для тех камер, где эта рамка доступна. Извлечение данных для многоцветных RAW (Canon sRAW, Kodak YRGB, Sinar 4-shot) возможно будет добавлено в следующих версиях.
Маскированные пикселы и активные пикселы изображения можно объединить в общий 4-компонентный битмэп вызовом add_masked_borders_to_bitmap().
Экземпляр класса LibRaw имеет собственный размер около 100 килобайт, при использовании конструкций вида
LibRaw imageProcessor; эта память аллоцируется на стеке.
Методы класса LibRaw (и вызовы С API) при работе могут аллоцировать до 130-140 килобайт данных на стеке под автоматические переменные.
Таким образом, для работы одного экземпляра LibRaw может требоваться около 250 килобайт стека. В большинстве современных архитектур это не является проблемой, но при использовании LibRaw в multi-threaded-окружении необходимо не забывать аллоцировать достаточно памяти для стека thread.
При динамической аллокации (LibRaw *iProcessor = new LibRaw;) требования к памяти на стеке
снижаются (на 100 килобайт - размер экземпляра класса). При использовании C API
экземпляр LibRaw аллоцируется динамически.
LibRaw ведет учет всех блоков аллоцированной динамической памяти, при возникновении исключительной ситуации (фатальной ошибки) все они освобождаются. Код учета довольно примитивный и не расчитан на аллокацию большого числа блоков (в обычной ситуации при обработке файла аллокация происходи 2-6 раз), при расширении LibRaw собственными методами это надлежит учитывать.
LibRaw использует динамическую память:
С целью упрощения дальнейшей обработки, память под извлекаемые RAW-данные аллоцируется с 4-кратным (для
байеровских камер) запасом: для каждого пикселя отводится 4 16-битных компонента (три из которых будут
нулевыми после распаковки RAW). Это позволяет проводить дебайеризацию и прочие действия по постобработке прямо в
том же буфере, куда были извлечены данные, но повышает требования к памяти вчетверо.
Таким образом, размер памяти под буфер изображения в 6-10 раз превышает размер исходного RAW-файла.
Вполне вероятно, что в следующих версиях LibRaw аллокация этого буфера будет более экономной, при условии
неиспользования вызовов постобработки, унаследованных от dcraw..
Буфер для раскодированного изображения аллоцируется при вызове unpack() и освобождается при recycle().
Память для thumbnail аллоцируется при вызове unpack_thumb() и освобождается при recycle(). Аллоцируется буфер размером ровно под thumbnail т.е. до нескольких мегабайт.
Память для ICC-профиля аллоцируется при вызове unpack_profile() и освобождается при recycle(). Аллоцируется буфер размером ровно под размер ICC-профиля т.е. до нескольких сотен килобайт.
Память для временных буферов, нужных при распаковке RAW-данных может быт аллоцирована во время работы unpack() и освобождается до завершения этой функции. Размеры аллоцированных буферов невелики, в пределах нескольких десятков килобайт.
При постобработке изображений (унаследованной от dcraw) выделяется память под гистограмму (128 килобайт). Эта память выделяется при вызове dcraw_document_mode_processing() и dcraw_process(), а освобождается при вызове recycle().
Помимо этого, при работе dcraw_process() и использовании ряда имеющихся возможностей:
будет аллоцирован временный буфер, размер которого равен размеру результирующего изображения (из расчета 6-8
байт на пиксел для разных стадий обработки). При завершении промежуточной подстадии обработки, буфер с
предыдущей копией изображения будет освобожден.
Если постобработка не используется, то временные буферы не аллоцируются.
Вызов dcraw_ppm_tiff_writer() аллоцирует память под одну строку выходного изображения. Аллоцированная память освобождается перед выходом из вызова.
Вызовы dcraw_make_mem_image() и dcraw_make_mem_thumb() (и их аналоги в C-API) аллоцируют дополнительную память в объеме, необходимом для хранения выводимых данных (изображения и thumbnail, соответственно).Освобождение этой памяти - задача вызывающей функции.
В ряде камер Kodak preview (thumbnail) хранится в виде нескорректированного изображения. При извлечении его с
помощью dcraw -e используются те же настройки баланса белого, коррекции цветов и так далее, что и для
извлечения основных RAW-данных (включая удаление дефектов и вычитание dark frame, что ошибочно т.к. размер
изображения другой).
В вызове LibRaw::unpack_thumb() всегда используется баланс белого, взятый из камеры (as shot), какие-либо
настроки из imgdata.params не используются.
Для Всех остальных камер thumbnails извлекаются as-is, без каких-либо цветовых преобразований, как в dcraw, так и в LibRaw.
[вернуться к оглавлению]