Приняты следующие соглашения о возвращаемых ошибках
В случае возникновения нештатной ситуации, не мешающей получить из файла какие-то данные, о ней будет просигнализировано путем взведения соответствующего бита в imgdata.process_warnings. Возможные типы предупреждений перечислены и расшифрованы здесь.
Thread safety обеспечивается, если объект LibRaw создается и иcпользуется внутри одного thread. При этом количество threads (каждая со своим объектом LibRaw) ничем не ограничено (кроме потребностей в памяти).
В случае создания объекта LibRaw в одном потоке исполнения, а использования в другом - необходима внешняя синхронизация.
Для сборки в multi-threaded режиме необходимо компилировать приложение с флагом препроцессора -DLIBRAW_THREADS, ключом компилятора -pthread (Unix/gcc) и линковать с библиотекой libraw_r.a. В этом режиме (и с этим препроцессорным флагом) для сохранения локальных данных декодера используется не общая статическая память, а поля в объекте LibRaw. Это незначительно замедляет работу отдельного потока управления, но при использовании нескольких параллельных потоков распаковки получается общий выигрыш.
Если в программе используется один экземпляр LibRaw без одновременного вызова его методов из разных потоков, то линковка с multi-threaded-версией библиотеки (и описанные выше флаги сборки) - необязательны.
При обработке исключительных ситуаций внутри 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
.
Экземпляр класса 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() аллоцирует память под одну строку выходного изображения. Аллоцированная память освобождается перед выходом из вызова.
С целью ускорения чтения, обрабатываемый файл целиком располагается в памяти. На Unix-системах это делается через mmap(), что не приводит к явной аллокации буфера. На win32-системах выполняется аллокация буфера, размер которого равен размеру входного файла.
В ряде камер Kodak preview (thumbnail) хранится в виде нескорректированного изображения. При извлечении его с
помощью dcraw -e используются те же настройки баланса белого, коррекции цветов и так далее, что и для
извлечения основных RAW-данных (включая удаление дефектов и вычитание dark frame, что ошибочно т.к. размер
изображения другой).
В вызове LibRaw::unpack_thumb() всегда используется баланс белого, взятый из камеры (as shot), какие-либо
настроки из imgdata.params не используются.
Для Всех остальных камер thumbnails извлекаются as-is, без каких-либо цветовых преобразований, как в dcraw, так и в LibRaw.
[вернуться к оглавлению]