WebP Container API 文档

针对 WebP 图片的 RIFF 容器操作。

多路复用 API

允许处理 WebP 容器映像,其中包含颜色配置文件、元数据、动画和碎片图像等功能。

代码示例

使用图片数据、颜色配置文件和 XMP 元数据创建 MUX

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);

Mux 对象的生命周期

枚举

// 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 - 要删除的 (in/out) 对象

多路复用器创建

WebPMuxCreate()

根据以 WebP RIFF 格式给定的原始数据创建多路复用对象。

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

bitstream -(中)WebP RIFF 格式的比特流数据

copy_data -(输入)值 1 表示给定数据将被复制到多路复用器,值 0 表示数据不会复制到 mux 对象。

返回

一个指针,指向根据给定数据创建的多路复用对象(如果成功)。

NULL - 出现无效数据或内存错误时抛出的异常。

非图片块

WebPMuxSetChunk()

在多路复用对象中添加 ID 为 fourcc 和数据 chunk_data 的区块。任何具有相同 ID 的现有分块都将被移除。

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 - 区块添加到的 (in/out) 对象

fourcc -(输入)一个字符数组,包含给定块的 4cc;例如,“ICCP”“XMP”“EXIF”等

chunk_data -(在)要添加的块数据

copy_data -(输入)值 1 表示给定数据将被复制到多路复用器,值 0 表示数据不会复制到 mux 对象。

返回

WEBP_MUX_INVALID_ARGUMENT - 如果 mux、fourcc 或 chunk_data 为 NULL,或者 fourcc 对应于一个图像块,则;

WEBP_MUX_MEMORY_ERROR - 内存分配错误时。

WEBP_MUX_OK - 如果成功,

WebPMuxGetChunk()

获取对多路复用对象中 ID 为 fourcc 的分块数据的引用。 调用方不应释放返回的数据。

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

mux:要从中提取块数据的 (in) 对象

fourcc -(输入)一个字符数组,包含区块的 4cc;例如,“ICCP”“XMP”“EXIF”等

chunk_data - (out) 返回的块数据

返回

WEBP_MUX_INVALID_ARGUMENT - 如果 mux、fourcc 或 chunk_data 为 NULL,或者 fourcc 对应于一个图像块,则;

WEBP_MUX_NOT_FOUND - 如果多路复用器不包含具有指定 ID 的分块。

WEBP_MUX_OK - 如果成功,

WebPMuxDeleteChunk()

从多路复用对象中删除具有指定 fourcc 的分块。

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

mux - 要从中删除区块的 (in/out) 对象

fourcc -(输入)一个字符数组,包含区块的 4cc;例如,“ICCP”“XMP”“EXIF”等

返回

WEBP_MUX_INVALID_ARGUMENT - 如果 mux 或 fcc 为 NULL,或当 Threecc 对应于一个图像块。

WEBP_MUX_NOT_FOUND - 如果多路复用器不包含具有给定 fourcc 的分块。

WEBP_MUX_OK - 如果成功,

图像

封装有关单个帧/fragment 的数据。

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()

在 mux 对象中设置(非动画和非片段)图片。 注意:所有现有图片(包括帧/片段)都将被移除。

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

mux - 要在其中设置图像的 (in/out) 对象

bitstream - (in) 可以是原始 VP8/VP8L 比特流或单图 WebP 文件(非动画和非片段)

copy_data -(输入)值 1 表示给定数据将被复制到多路复用器,值 0 表示数据不会复制到 mux 对象。

返回

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_ANMFWEBP_CHUNK_FRGM 之一
  2. 如需设置非动画不碎片化的图片,请改用 WebPMuxSetImage()
  3. 推送的帧类型必须与多路复用器中的帧类型相同。
  4. 由于 WebP 仅支持偶数偏移,因此任何奇数偏移量都将使用“offset &= ~1”项对齐到偶数位置
参数

mux - 将帧添加到的 (in/out) 对象

frame -(输入)帧数据。

copy_data -(输入)值 1 表示给定数据将被复制到多路复用器,值 0 表示数据不会复制到 mux 对象。

返回

WEBP_MUX_INVALID_ARGUMENT - 如果多路复用器或帧为 NULL 或的内容无效。

WEBP_MUX_MEMORY_ERROR - 内存分配错误时。

WEBP_MUX_OK - 如果成功,

WEBP_MUX_MEMORY_ERROR - 内存分配错误时。

WebPMuxGetFrame()

从多路复用对象中获取第 n 帧。frame->bitstream 的内容使用 malloc() 分配,并且不归 mux 对象所有。该内存必须由调用方通过调用 WebPDataClear() 取消分配。nth=0 有一个特殊含义 - 最后一个位置。

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

mux:要从中提取信息的对象(在对象中)

nth - 多路复用对象中帧的 (in) 索引

frame - 所返回帧的(输出)数据

返回

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 - 要从中删除帧的 (in/out) 对象

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()

在 mux 对象中设置动画参数。任何现有的 ANIM 块都将被移除。

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

mux - 要设置/添加 ANIM 块的 (in/out) 对象

params -(输入)动画参数。

返回

WEBP_MUX_INVALID_ARGUMENT - 如果多路复用器或参数为 NULL。

WEBP_MUX_MEMORY_ERROR - 内存分配错误时。

WEBP_MUX_OK - 如果成功,

WebPMuxGetAnimationParams()

从多路复用对象中获取动画参数。

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

mux - 要获取动画参数的 (in) 对象

params - 从 ANIM 块中提取的 (out) 动画参数

返回

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:要从中提取画布大小的 (in) 对象

width - (out) 画布宽度

height - (out) 画布高度

返回

WEBP_MUX_INVALID_ARGUMENT - 如果 mux,width 或 height 为 NULL。

WEBP_MUX_BAD_DATA - 如果 VP8X/VP8/VP8L 分块或画布大小无效。

WEBP_MUX_OK - 如果成功,

WebPMuxGetFeatures()

从多路复用对象中获取功能标记。

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

注意:此方法假定 VP8X 分块(如果存在)是最新的。 也就是说,自上次调用 WebPMuxAssemble()WebPMuxCreate() 以来,多路复用对象未被修改。

参数

mux - 要从中提取地图项的 (in) 对象

flags - (out) 指定多路复用对象中存在的特征的标记。这将是各种标志值的“或”(OR)。枚举 WebPFeatureFlags 可用于测试各个标志值。

返回

WEBP_MUX_INVALID_ARGUMENT - 如果多路复用器或标志为 NULL。

WEBP_MUX_BAD_DATA - 如果 VP8X/VP8/VP8L 分块或画布大小无效。

WEBP_MUX_OK - 如果成功,

WebPMuxNumChunks()

获取 mux 对象中具有指定标记值的区块数量。

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

mux:要从中提取信息的对象(在对象中)

id -(输入)区块 ID,用于指定区块的类型

num_elements -(输出)具有指定区块 ID 的区块数

返回

WEBP_MUX_INVALID_ARGUMENT - 如果 mux 或 num_elements 为 NULL。

WEBP_MUX_OK - 如果成功,

WebPMuxAssemble()

以 WebP RIFF 格式组建所有区块,并在 assembled_data 中返回。 此函数还可验证多路复用对象。

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

注意aggregated_data 的内容将被忽略并覆盖。此外,assembled_data 的内容是使用 malloc() 分配的,而不是 mux 对象拥有的内容。必须由调用方通过调用 WebPDataClear() 取消分配该内存。

参数

mux - 要组合其区块的 (in/out) 对象

assembled_data - (out) 组合的 WebP 数据

返回

WEBP_MUX_BAD_DATA - 如果多路复用对象无效。

WEBP_MUX_INVALID_ARGUMENT - 如果 mux 或 compiled_data 为 NULL。

WEBP_MUX_MEMORY_ERROR - 内存分配错误时。

WEBP_MUX_OK - 如果成功,

WebPAnimEncoder 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 - 用于对动画进行编码的 (in/out) 选项
返回
如果成功,则为 true。
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

创建并初始化 WebPAnimEncoder 对象。

参数

width/height - 动画的画布宽度和高度。

enc_options -(输入)编码选项;可以传递 NULL 以选择合理的默认值。

返回

指向新创建的 WebPAnimEncoder 对象的指针;如果发生内存错误,则返回 NULL。

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

WebPAnimEncoderAdd()

针对 WebP 优化给定帧,对其进行编码并将其添加到 WebPAnimEncoder 对象。

WebPAnimEncoderAdd 的最后一次调用应使用 frame = NULL,这表示不再添加帧。此调用还可用于确定最后一帧的时长。

参数

enc - 将帧添加到的 (in/out) 对象。

frame - ARGB 或 YUV(A) 格式的(输入/输出)帧数据。如果它采用 YUV(A) 格式,则会被转换为 ARGB,这会引起较小的损失。

timestamp_ms - 此帧的时间戳(以毫秒为单位)。帧的时长将计算为“下一帧的时间戳 - 此帧的时间戳”。因此,时间戳应采用非递减顺序。

config -(在)编码选项中;可以传递 NULL 以选择合理的默认值。

返回

发生错误时,返回 false 且 frame->error_code 已正确设置。 否则,返回 true。

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

WebPAnimEncoderAssemble()

将到目前为止添加的所有帧组合到 WebP 比特流中。在该调用之前,应先使用 frame = NULL 调用 WebPAnimEncoderAdd;否则,将在内部估算最后一帧的时长。

参数

enc - 用于组建框架的 (in/out) 对象。

webp_data -(输出)生成的 WebP 比特流。

返回

如果成功,则为 true。

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

WebPAnimEncoderGetError()

使用 enc 获取与最近一次调用相对应的错误字符串。返回的字符串由 enc 所有,仅在下一次调用 WebPAnimEncoderAdd()WebPAnimEncoderAssemble()WebPAnimEncoderDelete() 之前有效。

参数
enc - 要从中提取错误字符串的 (in/out) 对象。
返回
NULL if enc is NULL. 否则,如果上次调用 enc 出错,则返回错误字符串;如果上次调用成功,则返回空字符串。
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

删除 WebPAnimEncoder 对象。

参数
enc -- 要删除的 (in/out) 对象
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()

解析由 data 提供的完整 WebP 文件。

WebPDemuxer WebPDemux(const WebPData* data);

成功解析后返回 WebPDemuxer 对象,否则返回 NULL。

WebPDemuxPartial()

解析 data 提供的可能不完整的 WebP 文件。如果 state 为非 NULL,则会设置它来指示多路分配器的状态。

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

如果出现错误或没有足够的数据开始解析,则返回 NULL;成功解析时返回 WebPDemuxer 对象。

请注意,WebPDemuxer 会保留指向 data 内存段的内部指针。如果此数据是易失性的,则应删除多路分配器对象(通过调用 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 获取 feature 值。

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 中检索帧 frame_number

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

从此函数返回时,iter->fragment 会指向第一个 fragment。您可以使用 WebPDemuxSelectFragment() 提取各个 fragment。将 frame_number 设置为 0 将返回图像的最后一帧。

如果 dmux 为 NULL 或帧 frame_number 不存在,则返回 false。 使用完迭代器后调用 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 以反映 fragment 编号 fragment_num

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

如果存在 fragment fragment_num,则返回 true,否则返回 false。

WebPDemuxReleaseIterator()

释放与 iter 关联的所有内存。

void WebPDemuxReleaseIterator(WebPIterator* iter);

必须在对同一迭代器进行任何后续调用 WebPDemuxGetChunk() 之前调用。此外,在使用 WebPDemuxDelete() 销毁关联的 WebPDemuxer 之前,必须调用此方法。

分块迭代

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()

dmux 中检索 ID 为 fourcc 的分块的 chunk_number 实例。

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);

必须在使用 WebPDemuxDelete() 销毁关联的 WebPDemuxer 之前调用。

WebPAnimDecoder 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 - 用于解码动画的 (in/out) 选项

返回
成功时返回 True
int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

创建并初始化 WebPAnimDecoder 对象。

参数

webp_data -(位于 WebP 比特流中)。在输出 WebPAnimDecoder 对象的生命周期内,此 ID 应保持不变。

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 -(从中获取信息的)解码器实例。

info - 从动画中提取的全局信息(输出)。

返回

如果成功,则为 true。

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

WebPAnimDecoderGetNext()

根据提供给 WebPAnimDecoderNew() 的选项,从 dec 提取下一帧。这将是一个大小为 canvas_width * 4 * canvas_height 的完全重建的画布,而不仅仅是框架子矩形。返回的缓冲区 buf 仅在下次调用 WebPAnimDecoderGetNext()WebPAnimDecoderReset()WebPAnimDecoderDelete() 之前有效。

参数

dec - 要从中提取下一帧的(输入/输出)解码器实例。

buf -(输出)解码的帧。

timestamp - 帧的(输出)时间戳,以毫秒为单位。

返回

如果任何参数为 NULL,存在解析或解码错误,或者没有更多帧,则为 false。否则,返回 true。

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

WebPAnimDecoderHasMoreFrames()

检查是否还有更多需要解码的帧。

参数
dec - 要检查的(输入)解码器实例。
返回
如果 dec 不为 NULL 且某些帧尚未解码,则为 true。否则,返回 false。
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 - 要从中提取多路分配器对象的(输入)解码器实例。
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

删除 WebPAnimDecoder 对象。

参数
dec - 要删除的(输入/输出)解码器实例。
返回
如果成功,则为 true。
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()

通过调用 free() 清除 webp_data 对象的内容。不会取消分配对象本身。

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

dst 分配必要的存储空间并复制 src 的内容。 成功时返回 true。

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