 | Функция вызывается только для форматов изображений, поддерживающих прозрачность цветовой маски (в отличие от прозрачности, достигаемой за счет альфа-смешивания), что в настоящее время справедливо только для формата GIF. |
Таблица колбэков декодера
#include <img.h>typedef struct {img_decode_choose_format_f *choose_format_f;img_decode_setup_f *setup_f;img_decode_abort_f *abort_f;img_decode_scanline_f *scanline_f;img_decode_set_palette_f *set_palette_f;img_decode_set_transparency_f *set_transparency_f;img_decode_frame_f *frame_f;img_decode_set_value_f *set_value_f;uintptrt_t data;} img_decode_callouts_t;
Структура содержит таблицу указателей на колбэки декодера. Таблица предоставляет декодру список колбэков для различных этапов кодирования.
Рассмотрим каждый колбэк отдельно.
Указатель на функцию, выбирающую формат изображения из списка, предоставленного декодером. Данный колбэк будет вызван первым (если формат был выбран предварительно, тогда вызов не будет производиться вообще). Функция имеет следующий прототип:
typdef unsigned (img_decode_choose_format_f)( uintptrt_t data,img_t *img,const img_format_t *formats,unsigned nformats );
img_decode_callouts_t. Если колбэк не предоставлен, библиотека вернет первый формат из списка как значение по умолчанию. Функция должна возвращать значение индекса в пределах массива formats. В случае, если формат не важен, и значение индекса будет за пределами массива (например, nformats), то декодер выдаст ошибку IMG_ERR_NOSUPPORT. Если нужно указать, что ни один из форматов не является приемлимым, нужно изменить бит IMG_FORMAT для img->flags, тогда результат будет таким же, как если бы формат был выбран до загрузки.
Указатель на функцию, производящую настройки, необходимые для начала декодирования кадра. Функция имеет следующий прототип:
typedef int (img_decode_setup_f)( uintptrt_t data,img_t *img,unsigned flags );
img_decode_callouts_t. С помощью этой функции есть возможноть настроить поля доступа для img_t. Данное поле сообщает декодеру, как записывать декодируемые данные изображения. Можно произвести настройку, устанавливая img->access.direct или img->access.indirect и устанавливая соответствующие флаги IMG_DIRECT или IMG_INDIRECT. Альтернативно, код, вызывающий функцию img_decode_frame() (или img_load_file() и др.), может настроить данный колбэк перед вызовом img_decode_frame() или полагаться на стандартное поведение библиотеки — выделение памяти из системной памяти для изображения и/или палитры (это произойдет только в том случае, если флаги IMG_DIRECT, IMG_INDIRECT и IMG_PALETTE не были установлены). Если применяется поведение по умолчанию, то позже необходимо осфободить память, занятую img_t::access.direct.data или img_t::palette (но не оба сразу). Это нужно сделать только по завершению работы с изображением и только в том случае, если декодирование изображения завершится успешно. В случае сбоя при декодировании, освобождение памяти производится автоматически.
Если все прошло успешно, будет возвращено значение IMG_ERR_OK, в противном случае будет возвращен другой код ошибки. Что-либо, отличное от IMG_ERR_OK означает, что декодирование прервано и код ошибки передается обратно в приложение.
Указатель на функцию, которая вызывается в случае сбоя декодирования (после вызова img_decode_setup_f). Библиотека автоматически освободит всю память, выделенную в процессе настройки (если был выбран режим работы по умолчанию, описанный выше img_decode_setup_f). Функция имеет следующий прототип:
typedef void (img_decode_abort_f)( uintptrt_t data,img_t *img );
img_decode_callouts_t.
Указатель на функцию, которая вызывается для уведомления приложения о декодировании новой растровой строки. Функция имеет следующий прототип:
typedef int (img_decode_scanline_f)( uintptrt_t data,img_t *img,unsigned row,unsigned npass_line,unsigned npass_total );
img_decode_callouts_t. 0 (самая верхняя строка) до (h - 1), где h - высота изображения. IMG_SETUP_MULTIPASS). Растрая строка закончена, когда это значение равно 0. 0. Общее количество включает частичные проходы, если в колбэке img_decode_setup_f был установлен флаг IMG_SETUP_MULTIPASS. Если флаг не установлен, тогда обработка растровой строки сичтается полностью завершенной, а значение npass_total отражает количество строк, оставшихся до окончания декодирования. В любом случае данное значение показывает, каков объем оставшейся работы по сравнению с выполненным. Для продолжения декодирования функция должна вернуть IMG_ERR_OK или другое значение при необходимости его прервать. Данное значение будет передано обратно в приложение. При прерывании декодирования обычно используется IMG_ERR_INTR.
Указатель на функцию, уведомляющую приложение о наличии палитры у изображения. Функция вызывается после настройки, но до выполнения декодирования. Если вызова колбэка не производится или данный вызов возвращает ненулевое значение, то библиотека копирует данные палитры в бувер на который указывает img->palette (если установлен флаг IMG_PALETTE) и преобразовывает их в IMG_FMT_PKHE_ARGB8888 по мере надобности (правильное представление img_color_t). Если при вызове колбэка возвращается 0, то копирования не производится. Функция имеет следующий прототип:
typedef int (img_decode_set_palette_f)( uintptrt_t data,img_t *img,const uint8_t *palette,img_format_t format );
img_decode_callouts_t. 0 если данные палитры нужно скопировать в img->palette, или отличное от нуля значение, если не нужно производить копирование/преобразование. Следует вернуть значение IMG_ERR_OK, если все в порядке, в противном случае соответствующий код ошибки. Отличное от IMG_ERR_OK значение вызовет остановку декодирования и передачу кода ошибки обратно в приложение.
Указатель на функцию, которая уведомляет приложение о том, что изображение имеет прозрачный цвет. Это означает, что дизайнер стремился обеспечить полупрозрачность определенному коду цвета. Пиксели этого цвета в исходном изображении не должны отображаться в месте назначения.
| Функция вызывается только для форматов изображений, поддерживающих прозрачность цветовой маски (в отличие от прозрачности, достигаемой за счет альфа-смешивания), что в настоящее время справедливо только для формата GIF. |
Функция имеет следующий прототип:
typedef void (img_decode_set_transparency_f)( uintptrt_t data,img_t *img,img_color_t color );
img_decode_callouts_t. IMG_FMT_G8 16-битным значением для формата 16bpp (кодировка такая же, как для формата изображения) 32-битным значением для форматов 24bpp или 32bpp (кодировка IMG_FMT_PKHE_ARGB8888)
| Поле transparency в img_t будет уже настроено к моменту вызова колбэка. Единственная причина вызова колбэка - это дополнительная обработка в результате наличия прозрачности. |
Указатель на функцию, которая вызывается после успешного декодирования кадра. Функция имеет следующий прототип:
typedef void (img_decode_frame_f)( uintptrt_t data,img_t *img );
Указатель на функцию, которая вызывается, чтобы сообщить приложению о дополнительных свойствах изображения. Функция имеет следующий прототип:
typedef int (img_decode_set_value_f)( uintptrt_t data,img_t *img,unsigned type,uintptrt_t value );
В некоторых форматах файлов изображений указывается дополнительная информация, не отображенная в img_t , например DPI, положение по осям x/y, комментарии и т.д. Цель данного колбэка - предоставить приложению возможность получать эту информацию.
 | В настоящий момент ни один из декодеров не использует данный колбэк и не зафиксировано ни одного type. Это скорее шаблон колбэка на будущее . |
Пользовательские данные, передаваемые в колбэк в качестве дополнительного аргумента.
Графическая подсистема ЗОСРВ «Нейтрино», Библиотека Image
img_t, img_format_t, img_decode_frame(), IMG_FMT_BPL(), img_load_file()
Предыдущий раздел: Image API