针对 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);
注意:
- frame.id 应为
WEBP_CHUNK_ANMF
或WEBP_CHUNK_FRGM
之一 - 如需设置非动画不碎片化的图片,请改用
WebPMuxSetImage()
。 - 推送的帧类型必须与多路复用器中的帧类型相同。
- 由于 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, ×tamp);
// ... (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);