Пояснения к API (соглашения о кодах ошибок, использование памяти)

Submitted by lexa on

Содержание

  1. Варианты LibRaw
  2. Соглашения о кодах ошибок и действиях при ошибках
  3. Нештатные ситуации, не являющиеся ошибкой
  4. Абстракция ввода данных
  5. Thread safety
  6. Использование C++
  7. Параметры структуры LibRaw::imgdata.params, влияющие на поведение open_file/unpack/unpack_thumb
  8. Использование памяти
    1. Использование стека
    2. Управление динамической памятью
    3. Использование динамической памяти
      1. Память для хранения RAW-данных
      2. Память для раскодированного изображения
      3. Память для раскодированного thumbnail
      4. Память для раскодированного ICC-profile
      5. Память для распаковки RAW
      6. Память для постобработки
      7. Память для записи файла
      8. Память для распаковки в буфер в памяти
  9. Несовместимости с dcraw
    1. Обработка Thumbnails от камер Kodak

Варианты LibRaw

Начиная с версии 0.9, библиотека LibRaw существует в единственном варианте. Более старые версии существовали в трех редакциях (основная, облегченная и коммерческая).

Соглашения о кодах ошибок и действиях при ошибках

Приняты следующие соглашения о возвращаемых ошибках

  1. Все функции, которые могут вернуть код ошибки имеют целый тип возвращаемых данных.
  2. При отсутствии ошибки возвращается 0 (LIBRAW_SUCCESS).
  3. Если случилась ошибка в системном вызове, то возвращается значение errno (это положительное число), которое может быть проанализировано с помощью strerror() или подобных средств.
  4. Все собственные коды ошибок LibRaw - отрицательные, при этом ошибки делятся на два типа:
    Нефатальные ошибки
    Нефатальные ошибки не запрещают исполнение других функций в последовательности обработки (например, unpack_thumb() вполне может вернуть код, означающий "preview отсутствует" и это не мешает затем вызвать unpack()).
    Фатальные ошибки
    В случае возникновения фатальной ошибки (нехватка памяти, ошибка во входных данных, невозможность распаковки данных) текущая стадия обработки завершается, все аллоцированные ресурсы освобождаются.
    В случае попытки продолжения обработки - все последущие вызовы API вернут ошибку LIBRAW_OUT_OF_ORDER_CALL.
    Вместе с тем, экземпляр LibRaw, в котором возникла фатальная ошибка, может обрабатывать следущие RAW-файлы обычным образом (вызов open_file() (либо open_datastream(), open_buffer()) затем unpack() и так далее).
  5. Проверка фатальности ошибки осуществляется макросом LIBAW_FATAL_ERROR(код ошибки)
  6. Коды ошибок перечислены и расшифрованы здесь.

Нештатные ситуации, не являющиеся ошибкой

В случае возникновения нештатной ситуации, не мешающей получить из файла какие-то данные, о ней будет просигнализировано путем взведения соответствующего бита в 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

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 версия.

Использование C++

При обработке исключительных ситуаций внутри LibRaw используется механизм C++ exceptions. Все исключения перехватываются внутри функций библиотеки и проникать наружу не должны.

Для аллокации/освобождения памяти используются функции malloc(calloc)/free, а не new/delete.

Какие-либо специфические библиотеки (STL, Boost, smart pointers) - не используются.

При использовании С API ссылки на C++-вызовы new/delete остаются, поэтому линковаться надо с libstdc++(Unix)/....(Windows).

Параметры структуры LibRaw::imgdata.params, влияющие на поведение open_file/unpack/unpack_thumb

Большинство полей данных структуры LibRaw::imgdata.params влияют только на постобработку данных, но есть ряд исключений, унаследованных текущей версией LibRaw от особенностей исходных текстов dcraw (постепенно эти зависимости будут удаляться).

imgdata.params.use_camera_matrix и imgdata.params.use_camera_wb
Влияют на загрузку RAW-данных для камер у которых есть colormatrix.
Внимание! Если параметр imgdata.params.use_camera_matrix не установлен пользователем, то он копируется из imgdata.params.use_camera_wb на этапе открытия файла.
imgdata.params.user_flip
Если этот параметр больше или равен нулю, то на этапе открытия файла (open_file() и остальные подобные вызовы) производится присваивание imgdata.sizes.flip = imgdata.params.user_flip.
imgdata.params.shot_select
Позволяет выбрать номер извлекаемого изображения для тех форматов данных, где возможно хранение нескольких RAW-изображений в одном файле данных.
imgdata.params.half_size
Влияет на загрузку RAW-данных для задников Phase One и Sinar. Кроме того, если установлен этот параметр, то считывание данных будет производиться в битмэп половинного размера в котором будут заполняться 4 компонента.
imgdata.params.threshold, imgdata.params.aber
Использование этих параметров (т.е. указание, что будет использоваться, соответственно, wavelet denoising и исправление аберраций) то чтение данных будет производиться в битмэп половинного размера, у каждого пиксела будут заполнены вcе 4 компонента (для байеровских матриц).
imgdata.params.use_camera_wb
Влияет на загрузку матрицы баланса белого для задников Leaf.

Использование памяти

Использование стека

Экземпляр класса 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-данных;
  • для постобработки изображения;
  • для раскодированного thumbnail;
  • для извлеченного из RAW-файла ICC-профиля (если он там есть);
  • для временных данных на этапе распаковки RAW-файла;
  • для временных данных на этапе постобработки и записи результата;
  • для чтения исходного RAW-файла (только на Win32)

Память для хранения RAW-данных

Извлеченные из файла RAW-данные хранятся в формате:

  • 16-битное целое на пиксель для "байеровских" (1 цвет на пиксель) камер. Если у RAW-изображения есть черная рамка, она хранится вместе с изображением.
  • 4 16-битных целых для полноцветных изображений (Foveon, Linear DNG, Canon sRAW и т.п.). Полноцветные изображения бывают как 3, так и 4-цветные, все они хранятся в виде 4 компонента на пиксел, для трехцветных изображений четвертый компонент будет нулевым.

Буфер для раскодированного изображения аллоцируется при вызове unpack() и освобождается при recycle().

Память для постобработки изображения

Для каждого пикселя при постобработке отводится 4 16-битных компонента Таким образом, размер памяти под буфер изображения в 6-10 раз превышает размер исходного RAW-файла (с учетом сжатия RAW-данных).

Буфер для раскодированного изображения аллоцируется при вызове dcraw_process() или raw2image() и освобождается при recycle() или free_image()

Память для раскодированного thumbnail

Память для thumbnail аллоцируется при вызове unpack_thumb() и освобождается при recycle(). Аллоцируется буфер размером ровно под thumbnail т.е. до нескольких мегабайт.

Память для раскодированного ICC-profile

Память для ICC-профиля аллоцируется при вызове unpack_profile() и освобождается при recycle(). Аллоцируется буфер размером ровно под размер ICC-профиля т.е. до нескольких сотен килобайт.

Память для распаковки RAW

Память для временных буферов, нужных при распаковке RAW-данных может быт аллоцирована во время работы unpack() и освобождается до завершения этой функции. Размеры аллоцированных буферов невелики, в пределах нескольких десятков килобайт.

Память для постобработки

При постобработке изображений (унаследованной от dcraw) выделяется память под гистограмму (128 килобайт). Эта память выделяется при вызове dcraw_process(), а освобождается при вызове recycle().

Помимо этого, при работе dcraw_process() и использовании ряда имеющихся возможностей:

  • ротации изображений с камер FUJI;
  • коррекции хроматических аберраций;
  • изменении размеров изображения (включая случаи коррекции неквадратного пиксела);
  • highlight recovery;

будет аллоцирован временный буфер, размер которого равен размеру результирующего изображения (из расчета 6-8 байт на пиксел для разных стадий обработки). При завершении промежуточной подстадии обработки, буфер с предыдущей копией изображения будет освобожден.
Если постобработка не используется, то временные буферы не аллоцируются.

Память для записи файла

Вызов dcraw_ppm_tiff_writer() аллоцирует память под одну строку выходного изображения. Аллоцированная память освобождается перед выходом из вызова.

Память для распаковки в буфер в памяти

Вызовы dcraw_make_mem_image() и dcraw_make_mem_thumb() (и их аналоги в C-API) аллоцируют дополнительную память в объеме, необходимом для хранения выводимых данных (изображения и thumbnail, соответственно).Освобождение этой памяти - задача вызывающей функции.

Несовместимости с dcraw

Обработка Thumbnails от камер Kodak

В ряде камер Kodak preview (thumbnail) хранится в виде нескорректированного изображения. При извлечении его с помощью dcraw -e используются те же настройки баланса белого, коррекции цветов и так далее, что и для извлечения основных RAW-данных (включая удаление дефектов и вычитание dark frame, что ошибочно т.к. размер изображения другой).
В вызове LibRaw::unpack_thumb() всегда используется баланс белого, взятый из камеры (as shot), какие-либо настроки из imgdata.params не используются.

Для Всех остальных камер thumbnails извлекаются as-is, без каких-либо цветовых преобразований, как в dcraw, так и в LibRaw.