img_encode_callouts_t

Таблица колбэков кодировщика

Прототип:

#include <img.h>
                                       
typedef struct {
    img_encode_choose_format_f      *choose_format_f;
    img_encode_setup_f              *setup_f;
    img_encode_abort_f              *abort_f;
    img_encode_scanline_f           *scanline_f;
    img_encode_set_palette_f        *get_palette_f;
    img_encode_set_transparency_f   *get_transparency_f;
    img_encode_frame_f              *frame_f;
    uintptrt_t                      data;
} img_encode_callouts_t;

Описание:

Структура содержит таблицу указателей на колбэки кодировщика. Таблица предоставляет кодировщику список колбэков, которые он может вызывать на различных этапах кодирования.

Рассмотрим каждый колбэк отдельно.

img_encode_choose_format_f *choose_format_f

Указатель на функцию, которая выбирает альтернативный формат изображения из списка, предоставленного кодировщиком. Данный колбэк вызывается первым во впремя процесса кодирования, но это происходит только в том случае, если формат преданного изображения не может быть представлен кодировщиком. В таком случае приложение может подготовиться к предоставлению данных в одном из запрошенных форматов или полностью прервать кодирование. Функция имеет следующий прототип:

typdef unsigned (img_encode_choose_format_f)( uintptrt_t data,
                                              const img_t *img,
                                              const img_format_t *formats,
                                              unsigned nformats );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

formats

Массив возможных форматов img_format_t.

nformats

Количество элементов массива formats.

Если колбэк choose_format() не будет предоставлен, то библиотека выберет формат, который лучше всего соответствует предоставленному изображению, и автоматически преобразует данные в этот формат.

Функция возвращает индекс массива formats или выходящее за его пределы значение (например, nformats), если требуется указать, что формат не найден; в таком случае кодировщик вернет код ошибки IMG_ERR_NOSUPPORT.

img_encode_setup_f *setup_f

Указатель на функцию, выполняющую настройки для начала кодирования кадра. Функция имеет следующий прототип:

typedef int (img_encode_setup_f)( uintptrt_t data,
                                  img_t *img,
                                  unsigned flags );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

flags

Флаги, указывающие на способ кодирования данных, которые могут повлиять на допущения и действия, производимые функцией. Допустимы следующие значения:

IMG_SETUP_TOP_DOWN

строки сканирования кодируются по порядку, двигаясь сверху вниз

IMG_SETUP_BOTTOM_UP

строки сканирования кодируются по порядку, двигаясь снизу вверх

IMG_SETUP_MULTIPASS

строки сканирования фрагментируются и обрабатываются в несколько проходов (например, в случае планарного формата или для некоторых схем чересстрочного сканирования).

Функция вернет значение IMG_ERR_OK, если все в порядке или код ошибки в протвном. Любое значение, кроме IMG_ERR_OK, вызывает остановку кодирования и передачу кода ошибки обратно в приложение.

img_encode_abort_f *abort_f

Указатель на функцию, которая вызывается в случае сбоя кодирования (испольуется если img_encode_setup_f уже была вызвана). Функция имеет следующий прототип:

typedef void (img_encode_abort_f)( uintptrt_t data,
                                   img_t *img );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

img_encode_scanline_f* scanline_f

Указатель на функцию, которая вызывается для уведомления приложения о начале кодирования строки сканирования. Функция имеет следующий прототип:

typedef int (img_encode_scanline_f)( uintptrt_t data,
                                     img_t *img,
                                     unsigned row,
                                     unsigned npass_line,
                                     unsigned npass_total );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

row

Индекс кодируемой строки сканирования. Строки сканирования нумеруются, начиная с 0 (самая верхняя строка сканирования) до (h - 1), где h - высота изображения.

npass_line

Количество дополнительных проходов (после текущего), необходимых для завершения обработки растровой строки. Планарные и некоторые чересстрочные форматы разделяют растровые строки при обработке, получая только састь данных в единицу времени (это случай, когда в колбэке img_encode_setup_f установлен бит IMG_SETUP_MULTIPASS). Растрая строка завершена, когда это значение равно 0.

npass_total

Количество дополнительных проходов (после текущего), оставшихся для обработки всего кадра. Обработка кадра завершена, когда это значение равно 0. Общее количество включает частичные проходы, если в колбэке img_encode_setup_f был установлен флаг IMG_SETUP_MULTIPASS. Если флаг не установлен, тогда обработка растровой строки сичтается полностью завершенной, а значение npass_total отражает количество строк, оставшихся до окончания кодирования. В любом случае данное значение показывает, каков объем оставшейся работы по сравнению с выполненным.

Для продолжения кодирования функция должна вернуть IMG_ERR_OK или другое значение при необходимости его прервать. Возвращенный код предается обратно в приложение. Обычно применяют IMG_ERR_INTR, если нет других предпочтений.

img_encode_set_palette_f *get_palette_f

Указатель на функцию, уведомляющую приложение о наличии палитры у изображения. Функцию необходимо вызывать только в том случае, если палитра не является точно представленной в img_t. Функция имеет следующий прототип:

typedef int (img_encode_get_palette_f)( uintptrt_t data,
                                        img_t *img,
                                        uint8_t *palette,
                                        img_format_t format );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

palette

Указатель на буфер для заполнения данными палитры.

format

Формат, в котором кодировщик ожидает данные палитры.

Следует вернуть значение IMG_ERR_OK, если все в порядке, в противном случае соответствующий код ошибки. Любое значение, кроме IMG_ERR_OK, вызывает остановку кодирования и передачу кода ошибки обратно в приложение.

img_encode_set_transparency_f *get_transparency_f

Указатель на функцию, удовлетворяющую запросу цвета прозрачности изображения. Данная функция передается только в том случае, если по какой-либо причине цвет прозрачности не точно отображается в поле прозрачности img_t. Функция имеет следующий прототип:

typedef int (img_encode_get_transparency_f)( uintptrt_t data,
                                             img_t *img,
                                             img_color_t *color );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

color

Указатель на img_color_t для заливки прозрачным цветом. Формат этих данных должен соответствовать формату самих данных кадра.

---

В случае, если данный колбэк не вызывается, библиотека будет автоматически использовать и преобразовывать поле прозрачности изображения.

---

Функция должна возвращать IMG_ERR_OK для того, чтобы указать, что запрашиваемое поле является действительным. В случае, если возвращено другое значение, кодировщик проигнорирует преобразование и не будет представлен в результирующих закодированных данных. Кодирование будет продолжаться независимо.

img_encode_frame_f *frame_f

Указатель на функцию, которая вызывается после успешного кодирования кадра. Функция имеет следующий прототип:

typedef void (img_encode_frame_f)( uintptrt_t data,
                                   img_t *img );

data

Данные приложения - значение элемента data структуры img_encode_callouts_t.

img

Указатель на структуру img_t, описывающую кодируемый кадр.

data

Пользовательские данные, передаваемые в колбэк в качестве дополнительного аргумента.

Классификация:

Графическая подсистема ЗОСРВ «Нейтрино», Библиотека Image

Тематические ссылки:

img_t, img_format_t, img_encode_frame(), IMG_FMT_BPL(), img_write_file()

Предыдущий раздел: Image API