Документация по API контейнеров WebP

Манипулирование контейнером RIFF для изображений WebP.

API мультиплексирования

Позволяет манипулировать изображениями контейнеров WebP, содержащими такие функции, как цветовой профиль, метаданные, анимацию и фрагментированные изображения.

Примеры кода

Создайте MUX с данными изображения, цветовым профилем и метаданными XMP.

int copy_data = 0;
WebPMux* mux = WebPMuxNew();
// ... (Prepare image data).
WebPMuxSetImage(mux, &image, copy_data);
// ... (Prepare ICCP color profile data).
WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
// ... (Prepare XMP metadata).
WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
// Get data from mux in WebP RIFF format.
WebPMuxAssemble(mux, &output_data);
WebPMuxDelete(mux);
// ... (Consume output_data; e.g. write output_data.bytes to file).
WebPDataClear(&output_data);

Получить данные изображения и цветового профиля из файла WebP

int copy_data = 0;
// ... (Read data from file).
WebPMux* mux = WebPMuxCreate(&data, copy_data);
WebPMuxGetFrame(mux, 1, &image);
// ... (Consume image; e.g. call WebPDecode() to decode the data).
WebPMuxGetChunk(mux, "ICCP", &icc_profile);
// ... (Consume icc_data).
WebPMuxDelete(mux);
free(data);

Жизнь объекта мультиплексирования

Перечисления

// Error codes
typedef enum WebPMuxError {
  WEBP_MUX_OK                 =  1,
  WEBP_MUX_NOT_FOUND          =  0,
  WEBP_MUX_INVALID_ARGUMENT   = -1,
  WEBP_MUX_BAD_DATA           = -2,
  WEBP_MUX_MEMORY_ERROR       = -3,
  WEBP_MUX_NOT_ENOUGH_DATA    = -4
} WebPMuxError;

// IDs for different types of chunks.
typedef enum WebPChunkId {
  WEBP_CHUNK_VP8X,     // VP8X
  WEBP_CHUNK_ICCP,     // ICCP
  WEBP_CHUNK_ANIM,     // ANIM
  WEBP_CHUNK_ANMF,     // ANMF
  WEBP_CHUNK_ALPHA,    // ALPH
  WEBP_CHUNK_IMAGE,    // VP8/VP8L
  WEBP_CHUNK_EXIF,     // EXIF
  WEBP_CHUNK_XMP,      // XMP
  WEBP_CHUNK_UNKNOWN,  // Other chunks.
  WEBP_CHUNK_NIL
} WebPChunkId;

WebPGetMuxVersion()

Возвращает номер версии библиотеки мультиплексирования, упакованный в шестнадцатеричном формате с использованием 8 бит для каждой основной/вспомогательной версии/версии. Например, v2.5.7 — это 0x020507 .

int WebPGetMuxVersion(void);

WebPMuxNew()

Создает пустой объект мультиплексирования.

WebPMux* WebPMuxNew(void);

Возврат

Указатель на вновь созданный пустой объект мультиплексора.

WebPMuxDelete()

Удаляет объект мультиплексирования.

void WebPMuxDelete(WebPMux* mux);

Параметры

mux -- (входной/выходной) объект, который нужно удалить

Создание мультиплексора

WebPMuxCreate()

Создает объект мультиплексирования из необработанных данных, заданных в формате WebP RIFF.

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);

Параметры

bitstream -- (в) данные битового потока в формате WebP RIFF.

copy_data -- (входное) значение 1 указывает, что данные данные БУДУТ скопированы в мультиплексор, а значение 0 указывает, что данные НЕ будут копироваться в объект мультиплексора .

Возврат

Указатель на объект мультиплексирования, созданный на основе заданных данных — в случае успеха.

NULL — в случае неверных данных или ошибки памяти.

Фрагменты, не являющиеся изображениями

WebPMuxSetChunk()

Добавляет чанк с идентификатором fourcc и данными chunk_data в объект мультиплексирования. Любой существующий фрагмент(ы) с таким же идентификатором будет удален.

WebPMuxError WebPMuxSetChunk(WebPMux* mux,
                             const char fourcc[4],
                             const WebPData* chunk_data,
                             int copy_data);

Примечание. Через API фрагментов следует управлять только фрагментами, не связанными с изображениями. (Часки, связанные с изображением: «ANMF», «FRGM», «VP8», «VP8L» и «ALPH»). Чтобы добавлять, получать и удалять изображения, используйте WebPMuxSetImage() , WebPMuxPushFrame() , WebPMuxGetFrame() и WebPMuxDeleteFrame() .

Параметры

mux -- (входной/выходной) объект, к которому должен быть добавлен фрагмент

fourcc -- (в) массив символов, содержащий fourcc данного фрагмента; например, «ICCP», «XMP», «EXIF» и т. д.

chunk_data — (в) данные чанка, которые нужно добавить

copy_data -- (входное) значение 1 указывает, что данные данные БУДУТ скопированы в мультиплексор, а значение 0 указывает, что данные НЕ будут копироваться в объект мультиплексора .

Возврат

WEBP_MUX_INVALID_ARGUMENT — если mux, fourcc или chunk_data имеют значение NULL или fourcc соответствует фрагменту изображения.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WEBP_MUX_OK — в случае успеха.

WebPMuxGetChunk()

Получает ссылку на данные фрагмента с идентификатором fourcc в объекте мультиплексирования. Вызывающий НЕ должен освобождать возвращенные данные.

WebPMuxError WebPMuxGetChunk(const WebPMux* mux,
                             const char fourcc[4],
                             WebPData* chunk_data);

Параметры

mux -- (внутренний) объект, из которого должны быть извлечены данные фрагмента

fourcc -- (в) массив символов, содержащий fourcc фрагмента; например, «ICCP», «XMP», «EXIF» и т. д.

chunk_data — (выход) возвращенные данные чанка

Возврат

WEBP_MUX_INVALID_ARGUMENT — если mux, fourcc или chunk_data имеют значение NULL или fourcc соответствует фрагменту изображения.

WEBP_MUX_NOT_FOUND — если мультиплексор не содержит чанка с заданным идентификатором.

WEBP_MUX_OK — в случае успеха.

WebPMuxDeleteChunk()

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

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);

Параметры

mux -- (входной/выходной) объект, из которого нужно удалить фрагмент

fourcc -- (в) массив символов, содержащий fourcc фрагмента; например, «ICCP», «XMP», «EXIF» и т. д.

Возврат

WEBP_MUX_INVALID_ARGUMENT — если mux или fourcc имеет значение NULL или fourcc соответствует фрагменту изображения.

WEBP_MUX_NOT_FOUND -- Если мультиплексор не содержит чанка с заданным fourcc.

WEBP_MUX_OK — в случае успеха.

Изображений

Инкапсулирует данные об одном кадре/фрагменте.

struct WebPMuxFrameInfo {
  WebPData    bitstream;  // image data: can be a raw VP8/VP8L bitstream
                          // or a single-image WebP file.
  int         x_offset;   // x-offset of the frame.
  int         y_offset;   // y-offset of the frame.
  int         duration;   // duration of the frame (in milliseconds).

  WebPChunkId id;         // frame type: should be one of WEBP_CHUNK_ANMF,
                          // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE
  WebPMuxAnimDispose dispose_method;  // Disposal method for the frame.
  WebPMuxAnimBlend   blend_method;    // Blend operation for the frame.
};

WebPMuxSetImage()

Устанавливает (неанимированное и нефрагментированное) изображение в объекте мультиплексирования. Примечание. Любые существующие изображения (включая кадры/фрагменты) будут удалены.

WebPMuxError WebPMuxSetImage(WebPMux* mux,
                             const WebPData* bitstream,
                             int copy_data);

Параметры

mux -- (входной/выходной) объект, в котором должно быть установлено изображение

битовый поток -- (in) может быть необработанным битовым потоком VP8/VP8L или файлом WebP с одним изображением (неанимированным и нефрагментированным).

copy_data -- (входное) значение 1 указывает, что данные данные БУДУТ скопированы в мультиплексор, а значение 0 указывает, что данные НЕ будут копироваться в объект мультиплексора .

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор имеет значение NULL или битовый поток имеет значение NULL.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WEBP_MUX_OK — в случае успеха.

WebPMuxPushFrame()

Добавляет кадр в конец объекта мультиплексирования.

WebPMuxError WebPMuxPushFrame(WebPMux* mux,
                              const WebPMuxFrameInfo* frame,
                              int copy_data);

Примечания:

1. Frame.id должен быть одним из WEBP_CHUNK_ANMF или WEBP_CHUNK_FRGM
2. Для установки неанимированного нефрагментированного изображения используйте вместо этого WebPMuxSetImage() .
3. Тип передаваемого кадра должен быть таким же, как и кадры в мультиплексоре.
4. Поскольку WebP поддерживает только четные смещения, любое нечетное смещение будет привязано к четному местоположению с помощью: offset &= ~1.

Параметры

mux -- (входной/выходной) объект, к которому должен быть добавлен кадр

кадр -- (в) данные кадра.

copy_data -- (входное) значение 1 указывает, что данные данные БУДУТ скопированы в мультиплексор, а значение 0 указывает, что данные НЕ будут копироваться в объект мультиплексора .

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор или кадр имеет значение NULL или если содержимое кадра недопустимо.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WEBP_MUX_OK — в случае успеха.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WebPMuxGetFrame()

Получает n-й кадр из объекта мультиплексирования. Содержимое кадра->битового потока выделяется с помощью malloc() и НЕ принадлежит объекту мультиплексирования . Он ДОЛЖЕН быть освобожден вызывающей стороной путем вызова WebPDataClear() . nth=0 имеет особое значение — последняя позиция.

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);

Параметры

mux -- (внутренний) объект, из которого должна быть получена информация

nth -- (in) индекс кадра в объекте мультиплексирования

кадр -- (выходящие) данные возвращенного кадра

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор или кадр имеет значение NULL.

WEBP_MUX_NOT_FOUND — если в объекте мультиплексирования меньше n-ных кадров.

WEBP_MUX_BAD_DATA — если n-ный фрагмент кадра в мультиплексоре недействителен.

WEBP_MUX_OK — в случае успеха.

WebPMuxDeleteFrame()

Удаляет кадр из объекта мультиплексирования. nth=0 имеет особое значение — последняя позиция.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

Параметры

mux -- (входной/выходной) объект, из которого должен быть удален кадр

nth -- (in) Позиция, из которой должен быть удален кадр.

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор имеет значение NULL.

WEBP_MUX_NOT_FOUND — если перед удалением в объекте мультиплексирования меньше n-ных кадров.

WEBP_MUX_OK — в случае успеха.

Анимация

Параметры анимации

struct WebPMuxAnimParams {
  uint32_t bgcolor;  // Background color of the canvas stored (in MSB order) as:
                     // Bits 00 to 07: Alpha.
                     // Bits 08 to 15: Red.
                     // Bits 16 to 23: Green.
                     // Bits 24 to 31: Blue.
  int loop_count;    // Number of times to repeat the animation [0 = infinite].
};

WebPMuxSetAnimationParams()

Устанавливает параметры анимации в объекте мультиплексирования. Все существующие фрагменты ANIM будут удалены.

WebPMuxError WebPMuxSetAnimationParams(WebPMux* mux,
                                       const WebPMuxAnimParams* params);

Параметры

mux -- объект (вход/выход), в котором должен быть установлен/добавлен фрагмент ANIM

params -- (в) параметры анимации.

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор или параметры равны NULL.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WEBP_MUX_OK — в случае успеха.

WebPMuxGetAnimationParams()

Получает параметры анимации из объекта мультиплексирования.

WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
                                       WebPMuxAnimParams* params);

Параметры

mux -- (внутренний) объект, из которого извлекаются параметры анимации

params -- (выходные) параметры анимации, извлеченные из фрагмента ANIM.

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор или параметры равны NULL.

WEBP_MUX_NOT_FOUND — если чанк ANIM отсутствует в объекте мультиплексирования.

WEBP_MUX_OK — в случае успеха.

Разное. Утилиты

WebPMuxGetCanvasSize()

Получает размер холста из объекта мультиплексирования.

WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
                                  int* width,
                                  int* height);

Примечание. Этот метод предполагает, что чанк VP8X, если он присутствует, обновлен. То есть объект мультиплексора не изменялся с момента последнего вызова WebPMuxAssemble() или WebPMuxCreate() .

Параметры

mux -- (внутренний) объект, из которого нужно получить размер холста

ширина -- (внешняя) ширина холста

height -- (внешняя) высота холста

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор, ширина или высота равны NULL.

WEBP_MUX_BAD_DATA — если размер чанка или холста VP8X/VP8/VP8L недействителен.

WEBP_MUX_OK — в случае успеха.

WebPMuxGetFeatures()

Получает флаги функций из объекта мультиплексирования.

WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, uint32_t* flags);

Примечание. Этот метод предполагает, что чанк VP8X, если он присутствует, обновлен. То есть объект мультиплексора не был изменен с момента последнего вызова WebPMuxAssemble() или WebPMuxCreate() .

Параметры

mux -- (внутренний) объект, из которого должны быть извлечены функции

flags -- (out) флаги, определяющие, какие функции присутствуют в объекте мультиплексирования. Это будет ИЛИ различных значений флагов. Enum WebPFeatureFlags можно использовать для проверки отдельных значений флагов.

Возврат

WEBP_MUX_INVALID_ARGUMENT — если мультиплексор или флаги равны NULL.

WEBP_MUX_BAD_DATA — если размер чанка или холста VP8X/VP8/VP8L недействителен.

WEBP_MUX_OK — в случае успеха.

WebPMuxNumChunks()

Получает количество фрагментов, имеющих заданное значение тега в объекте мультиплексирования .

WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
                              WebPChunkId id,
                              int* num_elements);

Параметры

mux -- (внутренний) объект, из которого должна быть получена информация

id -- (in) идентификатор чанка, указывающий тип чанка

num_elements -- (выходное) количество фрагментов с заданным идентификатором фрагмента

Возврат

WEBP_MUX_INVALID_ARGUMENT — если mux или num_elements имеет значение NULL.

WEBP_MUX_OK — в случае успеха.

WebPMuxAssemble()

Собирает все фрагменты в формате WebP RIFF и возвращает сборку_данных . Эта функция также проверяет объект мультиплексора.

WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data);

Примечание. Содержимое сборки_данных будет проигнорировано и перезаписано. Кроме того, содержимое сборки_данных выделяется с помощью malloc() и НЕ принадлежит объекту мультиплексирования . Он ДОЛЖЕН быть освобожден вызывающей стороной путем вызова WebPDataClear() .

Параметры

mux -- (входной/выходной) объект, фрагменты которого должны быть собраны

сборка_данных -- (выход) собранные данные WebP

Возврат

WEBP_MUX_BAD_DATA — если объект мультиплексирования недействителен.

WEBP_MUX_INVALID_ARGUMENT — если mux илиsemble_data имеют значение NULL.

WEBP_MUX_MEMORY_ERROR — при ошибке выделения памяти.

WEBP_MUX_OK — в случае успеха.

API вебПАнимэнкодера

Этот API позволяет кодировать (возможно) анимированные изображения WebP.

Пример кода

WebPAnimEncoderOptions enc_options;
WebPAnimEncoderOptionsInit(&enc_options);
// Tune 'enc_options' as needed.
WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
while(<there are more frames>) {
  WebPConfig config;
  WebPConfigInit(&config);
  // Tune 'config' as needed.
  WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
}
WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
WebPAnimEncoderAssemble(enc, webp_data);
WebPAnimEncoderDelete(enc);
// Write the 'webp_data' to a file, or re-mux it further.

typedef struct WebPAnimEncoder WebPAnimEncoder;  // Main opaque object.

Глобальные параметры

struct WebPAnimEncoderOptions {
  WebPMuxAnimParams anim_params;  // Animation parameters.
  int minimize_size;    // If true, minimize the output size (slow). Implicitly
                        // disables key-frame insertion.
  int kmin;
  int kmax;             // Minimum and maximum distance between consecutive key
                        // frames in the output. The library may insert some key
                        // frames as needed to satisfy this criteria.
                        // Note that these conditions should hold: kmax > kmin
                        // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
                        // key-frame insertion is disabled; and if kmax == 1,
                        // then all frames will be key-frames (kmin value does
                        // not matter for these special cases).
  int allow_mixed;      // If true, use mixed compression mode; may choose
                        // either lossy and lossless for each frame.
  int verbose;          // If true, print info and warning messages to stderr.
};

WebPAnimEncoderOptionsInit()

Всегда следует вызывать для инициализации новой структуры WebPAnimEncoderOptions перед изменением. Возвращает false в случае несоответствия версий. Прежде чем использовать объект enc_options , WebPAnimEncoderOptionsInit() должен завершиться успешно.

Параметры

enc_options — параметры (вход/выход), используемые для кодирования анимации.

Возврат

Правда об успехе.

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Создает и инициализирует объект WebPAnimEncoder.

Параметры

ширина/высота — (дюймы) ширина и высота холста анимации.

enc_options -- (в) параметры кодирования; можно передать NULL, чтобы выбрать разумные значения по умолчанию.

Возврат

Указатель на вновь созданный объект WebPAnimEncoder или NULL в случае ошибки памяти.

WebPAnimEncoder* WebPAnimEncoderNew(
    int width, int height, const WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderAdd()

Оптимизируйте данный кадр для WebP, закодируйте его и добавьте в объект WebPAnimEncoder .

Последний вызов WebPAnimEncoderAdd должен иметь frame = NULL , что указывает на то, что больше фреймы добавляться не должны. Этот вызов также используется для определения продолжительности последнего кадра.

Параметры

enc -- (входной/выходной) объект, к которому должен быть добавлен кадр.

кадр — (входящие/исходящие) данные кадра в формате ARGB или YUV(A). Если он в формате YUV(A), он будет преобразован в ARGB, что приведет к небольшой потере.

timestamp_ms -- (in) временная метка этого кадра в миллисекундах. Длительность кадра будет рассчитываться как «временная метка следующего кадра - временная метка этого кадра». Следовательно, временные метки должны быть в неубывающем порядке.

config -- (в) параметры кодирования; можно передать NULL, чтобы выбрать разумные значения по умолчанию.

Возврат

В случае ошибки возвращается false, и frame->error_code устанавливается соответствующим образом. В противном случае возвращает true.

int WebPAnimEncoderAdd(
    WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
    const struct WebPConfig* config);

WebPAnimEncoderAssemble()

Соберите все добавленные кадры в битовый поток WebP. Этому вызову должен предшествовать вызов WebPAnimEncoderAdd с frame = NULL ; в противном случае продолжительность последнего кадра будет оценена внутренне.

Параметры

enc -- (входной/выходной) объект, из которого должны быть собраны кадры.

webp_data — (выход) сгенерированный битовый поток WebP.

Возврат

Правда об успехе.

int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data);

WebPAnimEncoderGetError()

Получите строку ошибки, соответствующую самому последнему вызову, используя enc . Возвращенная строка принадлежит enc и действительна только до следующего вызова WebPAnimEncoderAdd() , WebPAnimEncoderAssemble() или WebPAnimEncoderDelete() .

Параметры

enc — объект (входной/выходной), из которого должна быть получена строка ошибки.

Возврат

NULL, если enc имеет значение NULL. В противном случае возвращается строка ошибки, если при последнем вызове enc возникла ошибка, или пустая строка, если последний вызов был успешным.

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Удаляет объект WebPAnimEncoder .

Параметры

enc -- (входной/выходной) объект, который нужно удалить

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Демукс API

Позволяет извлекать изображения и данные расширенного формата из файлов WebP.

Примеры кода

Демуксирование данных WebP для извлечения всех кадров, профиля ICC и метаданных EXIF/XMP

WebPDemuxer* demux = WebPDemux(&webp_data);

uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
// ... (Get information about the features present in the WebP file).
uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);

// ... (Iterate over all frames).
WebPIterator iter;
if (WebPDemuxGetFrame(demux, 1, &iter)) {
  do {
    // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
    // ... and get other frame properties like width, height, offsets etc.
    // ... see 'struct WebPIterator' below for more info).
  } while (WebPDemuxNextFrame(&iter));
  WebPDemuxReleaseIterator(&iter);
}

// ... (Extract metadata).
WebPChunkIterator chunk_iter;
if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
// ... (Consume the ICC profile in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
// ... (Consume the EXIF metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
// ... (Consume the XMP metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
WebPDemuxDelete(demux);

Жизнь демультиплексного объекта

Перечисления

typedef enum WebPDemuxState {
  WEBP_DEMUX_PARSE_ERROR    = -1,  // An error occurred while parsing.
  WEBP_DEMUX_PARSING_HEADER =  0,  // Not enough data to parse full header.
  WEBP_DEMUX_PARSED_HEADER  =  1,  // Header parsing complete,
                                   // data may be available.
  WEBP_DEMUX_DONE           =  2   // Entire file has been parsed.
} WebPDemuxState;

WebPGetDemuxVersion()

Возвращает номер версии демультиплексной библиотеки, упакованный в шестнадцатеричном формате с использованием 8 бит для каждой основной/вспомогательной/версии. Например, v2.5.7 — это 0x020507 .

int WebPGetDemuxVersion(void);

WebPDemux()

Анализирует полный файл WebP, заданный data .

WebPDemuxer WebPDemux(const WebPData* data);

Возвращает объект WebPDemuxer при успешном анализе, в противном случае — NULL.

WebPDemuxPartial()

Анализирует возможно неполный файл WebP, заданный data . Если состояние не равно NULL, оно будет установлено для указания состояния демультиплексора.

WebPDemuxer WebPDemuxPartial(const WebPData* data, WebPDemuxState* state);

Возвращает NULL в случае ошибки или если данных недостаточно для начала анализа; и объект WebPDemuxer при успешном анализе.

Обратите внимание, что WebPDemuxer сохраняет внутренние указатели на сегмент памяти данных . Если эти данные нестабильны, объект демультиплексора следует удалить (путем вызова WebPDemuxDelete() ) и снова вызвать WebPDemuxPartial() для новых данных. Обычно это недорогая операция.

WebPDemuxDelete()

Освобождает память, связанную с dmux .

void WebPDemuxDelete(WebPDemuxer* dmux);

Извлечение данных/информации

typedef enum WebPFormatFeature {
  WEBP_FF_FORMAT_FLAGS,      // bit-wise combination of WebPFeatureFlags
                             // corresponding to the 'VP8X' chunk (if present).
  WEBP_FF_CANVAS_WIDTH,
  WEBP_FF_CANVAS_HEIGHT,
  WEBP_FF_LOOP_COUNT,        // only relevant for animated file
  WEBP_FF_BACKGROUND_COLOR,  // idem.
  WEBP_FF_FRAME_COUNT        // Number of frames present in the demux object.
                             // In case of a partial demux, this is the number
                             // of frames seen so far, with the last frame
                             // possibly being partial.
} WebPFormatFeature;

WebPDemuxGetI()

Получите значение функции из dmux .

uint32_t WebPDemuxGetI(const WebPDemuxer* dmux, WebPFormatFeature feature);

Примечание. Значения действительны только в том случае, если использовался WebPDemux() или WebPDemuxPartial() вернул состояние > WEBP_DEMUX_PARSING_HEADER .

Итерация кадра

struct WebPIterator {
  int frame_num;
  int num_frames;          // equivalent to WEBP_FF_FRAME_COUNT.
  int fragment_num;
  int num_fragments;
  int x_offset, y_offset;  // offset relative to the canvas.
  int width, height;       // dimensions of this frame or fragment.
  int duration;            // display duration in milliseconds.
  WebPMuxAnimDispose dispose_method;  // dispose method for the frame.
  int complete;   // true if 'fragment' contains a full frame. partial images
                  // may still be decoded with the WebP incremental decoder.
  WebPData fragment;  // The frame or fragment given by 'frame_num' and
                      // 'fragment_num'.
  int has_alpha;      // True if the frame or fragment contains transparency.
  WebPMuxAnimBlend blend_method;  // Blend operation for the frame.
};

WebPDemuxGetFrame()

Получает кадр номер_фрейма из dmux .

int WebPDemuxGetFrame(const WebPDemuxer* dmux,
                      int frame_number,
                      WebPIterator* iter);

iter->fragment указывает на первый фрагмент возврата из этой функции. Отдельные фрагменты можно извлечь с помощью WebPDemuxSelectFragment() . Установка параметраframe_number , равного 0, вернет последний кадр изображения.

Возвращает false, если dmux имеет значение NULL или номер кадра_номер отсутствует. Вызовите WebPDemuxReleaseIterator() после завершения использования итератора.

Примечание. dmux должен сохраняться на протяжении всего времени существования iter .

WebPDemuxNextFrame() , WebPDemuxPrevFrame()

Устанавливает iter->fragment так, чтобы он указывал на следующий ( iter->frame_num + 1) или предыдущий ( iter->frame_num - 1) кадр. Эти функции не зацикливаются.

int WebPDemuxNextFrame(WebPIterator* iter);
int WebPDemuxPrevFrame(WebPIterator* iter);

Возвращает true в случае успеха и false в противном случае.

WebPDemuxSelectFragment()

Устанавливает iter->fragment для отражения номера фрагмента фрагмент_num .

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Возвращает true, если присутствует фрагмент фрагмент_number , в противном случае — false.

WebPDemuxReleaseIterator()

Освобождает всю память, связанную с iter .

void WebPDemuxReleaseIterator(WebPIterator* iter);

Должен вызываться перед любыми последующими вызовами WebPDemuxGetChunk() на том же итере. Кроме того, его необходимо вызывать перед уничтожением связанного WebPDemuxer с помощью WebPDemuxDelete() .

Итерация фрагмента

struct WebPChunkIterator {
  // The current and total number of chunks with the fourcc given to
  // WebPDemuxGetChunk().
  int chunk_num;
  int num_chunks;
  WebPData chunk;    // The payload of the chunk.
};

WebPDemuxGetChunk()

Извлекает экземпляр chunk_number чанка с идентификатором fourcc из dmux .

int WebPDemuxGetChunk(const WebPDemuxer* dmux,
                      const char fourcc[4], int chunk_number,
                      WebPChunkIterator* iter);

fourcc — это массив символов, содержащий fourcc возвращаемого фрагмента, например «ICCP», «XMP», «EXIF» и т. д.

Установка chunk_number , равного 0, вернет последний фрагмент в наборе.

Возвращает true, если чанк найден, и false в противном случае. Доступ к полезной нагрузке фрагмента изображения осуществляется через WebPDemuxGetFrame() и связанные функции. Вызовите WebPDemuxReleaseChunkIterator() , когда использование итератора будет завершено.

Примечание. dmux должен сохраняться на протяжении всего времени существования итератора.

WebPDemuxNextChunk() , WebPDemuxPrevChunk()

Устанавливает iter->chunk так, чтобы он указывал на следующий ( iter->chunk_num + 1) или предыдущий ( iter->chunk_num - 1) чанк. Эти функции не зацикливаются.

int WebPDemuxNextChunk(WebPChunkIterator* iter);
int WebPDemuxPrevChunk(WebPChunkIterator* iter);

Возвращает true в случае успеха и false в противном случае.

WebPDemuxReleaseChunkIterator()

Освобождает всю память, связанную с iter .

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Должен быть вызван перед уничтожением связанного WebPDemuxer с помощью WebPDemuxDelete() .

API вебПАнимдекодера

Этот API позволяет декодировать (возможно) анимированные изображения WebP.

Пример кода

WebPAnimDecoderOptions dec_options;
WebPAnimDecoderOptionsInit(&dec_options);
// Tune 'dec_options' as needed.
WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
WebPAnimInfo anim_info;
WebPAnimDecoderGetInfo(dec, &anim_info);
for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
  while (WebPAnimDecoderHasMoreFrames(dec)) {
    uint8_t* buf;
    int timestamp;
    WebPAnimDecoderGetNext(dec, &buf, &timestamp);
    // ... (Render 'buf' based on 'timestamp').
    // ... (Do NOT free 'buf', as it is owned by 'dec').
  }
  WebPAnimDecoderReset(dec);
}
const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
// ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
WebPAnimDecoderDelete(dec);

typedef struct WebPAnimDecoder WebPAnimDecoder;  // Main opaque object.

Глобальные параметры

struct WebPAnimDecoderOptions {
  // Output colorspace. Only the following modes are supported:
  // MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA.
  WEBP_CSP_MODE color_mode;
  int use_threads;           // If true, use multi-threaded decoding.
};

WebPAnimDecoderOptionsInit()

Всегда следует вызывать для инициализации новой структуры WebPAnimDecoderOptions перед изменением. Возвращает false в случае несоответствия версий. Прежде чем использовать объект dec_options , WebPAnimDecoderOptionsInit() должен завершиться успешно.

Параметры

dec_options — параметры (вход/выход), используемые для декодирования анимации.

Возврат

Правда об успехе

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Создает и инициализирует объект WebPAnimDecoder .

Параметры

webp_data -- (в) битовый поток WebP. Это должно оставаться неизменным в течение всего срока существования выходного объекта WebPAnimDecoder .

dec_options -- (в) параметры декодирования. Может быть передан NULL для выбора разумных значений по умолчанию (в частности, будет выбран цветовой режим MODE_RGBA).

Возврат

Указатель на вновь созданный объект WebPAnimDecoder или NULL в случае ошибки синтаксического анализа, недопустимой опции или ошибки памяти.

WebPAnimDecoder* WebPAnimDecoderNew(
    const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options);

Глобальная информация об анимации.

struct WebPAnimInfo {
  uint32_t canvas_width;
  uint32_t canvas_height;
  uint32_t loop_count;
  uint32_t bgcolor;
  uint32_t frame_count;
};

WebPAnimDecoderGetInfo()

Получите глобальную информацию об анимации.

Параметры

dec -- (in) экземпляр декодера, из которого нужно получить информацию.

info — (out) глобальная информация, полученная из анимации.

Возврат

Правда об успехе.

int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec,
                           WebPAnimInfo* info);

WebPAnimDecoderGetNext()

Получите следующий кадр из декабря на основе параметров, предоставленных WebPAnimDecoderNew() . Это будет полностью реконструированный холст размером canvas_width * 4 * canvas_height , а не только подпрямоугольник кадра. Возвращенный буферный буфер действителен только до следующего вызова WebPAnimDecoderGetNext() , WebPAnimDecoderReset() или WebPAnimDecoderDelete() .

Параметры

dec -- экземпляр декодера (вход/выход), из которого должен быть получен следующий кадр.

buf -- (выход) декодированный кадр.

timestamp -- (выходная) временная метка кадра в миллисекундах.

Возврат

False, если какой-либо из аргументов имеет значение NULL, или если произошла ошибка синтаксического анализа или декодирования, или если кадров больше нет. В противном случае возвращает true.

int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
                           uint8_t** buf, int* timestamp);

WebPAnimDecoderHasMoreFrames()

Проверьте, осталось ли еще кадров для декодирования.

Параметры

dec -- (in) экземпляр декодера, который необходимо проверить.

Возврат

Истинно, если значение dec не равно NULL и некоторые кадры еще не декодированы. В противном случае возвращает ложь.

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Сбрасывает объект WebPAnimDecoder, чтобы следующий вызов WebPAnimDecoderGetNext() перезапустил декодирование с 1-го кадра. Это будет полезно, когда все кадры необходимо декодировать несколько раз (например, раз info.loop_count) без разрушения и повторного создания объекта dec .

Параметры

dec -- экземпляр декодера (вход/выход), который нужно сбросить

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Возьмите внутренний объект демультиплексора.

Получение объекта демультиплексора может быть полезно, если вы хотите использовать операции, доступные только через демультиплексор; например, чтобы получить метаданные XMP/EXIF/ICC. Возвращенный объект демультиплексора принадлежит dec и действителен только до следующего вызова WebPAnimDecoderDelete() .

Параметры

dec -- (in) экземпляр декодера, из которого должен быть получен объект демультиплексора.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Удаляет объект WebPAnimDecoder .

Параметры

dec -- (входной/выходной) экземпляр декодера, который нужно удалить.

Возврат

Правда об успехе.

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Общие типы данных

Перечисления

typedef enum WebPFeatureFlags {
  FRAGMENTS_FLAG  = 0x00000001,
  ANIMATION_FLAG  = 0x00000002,
  XMP_FLAG        = 0x00000004,
  EXIF_FLAG       = 0x00000008,
  ALPHA_FLAG      = 0x00000010,
  ICCP_FLAG       = 0x00000020
} WebPFeatureFlags;

// Dispose method (animation only). Indicates how the area used by the current
// frame is to be treated before rendering the next frame on the canvas.
typedef enum WebPMuxAnimDispose {
  WEBP_MUX_DISPOSE_NONE,       // Do not dispose.
  WEBP_MUX_DISPOSE_BACKGROUND  // Dispose to background color.
} WebPMuxAnimDispose;

// Blend operation (animation only). Indicates how transparent pixels of the
// current frame are blended with those of the previous canvas.
typedef enum WebPMuxAnimBlend {
  WEBP_MUX_BLEND,              // Blend.
  WEBP_MUX_NO_BLEND            // Do not blend.
} WebPMuxAnimBlend;

WebPDataInit()

Инициализирует содержимое объекта webp_data значениями по умолчанию.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Очищает содержимое объекта webp_data , вызывая free() . Не освобождает сам объект.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Выделяет необходимое пространство для dst и копирует содержимое src . Возвращает true в случае успеха.

int WebPDataCopy(const WebPData* src, WebPData* dst);