本部分介绍了所包含的编码器和解码器 API 此 API 说明与版本 1.4.0.
头文件和库
安装 libwebp 时，将创建一个名为 webp/ 的目录。
将安装在您的平台的典型位置。例如，在
Unix 平台，以下头文件将被复制到
/usr/local/include/webp/。
decode.h
encode.h
types.h
这些库位于常规的库目录中。静态和
动态库位于 Unix 平台上的 /usr/local/lib/ 中。
Simple Decoding API
要开始使用解码 API，您必须确保自己具有 库和头文件 上方。
在 C/C++ 代码中添加解码 API 标头，如下所示：
#include "webp/decode.h"
int WebPGetInfo(const uint8_t* data, size_t data_size, int* width, int* height);
此函数将验证 WebP 图片标头并检索图片宽度
和高度如果系统认为，可以传递指针 *width 和 *height，NULL
不相关。
输入属性
- 数据
- 指向 WebP 图片数据的指针
- data_size
- 这是
data指向的内存块大小，其中包含 图片数据。
返回
- false
- 出现 (a) 格式错误时返回的错误代码。
- true
- 成功时。
*width和*height仅在成功返回后有效。 - width
- 整数值。范围限制为 1 到 16383。
- 高度
- 整数值。范围限制为 1 到 16383。
struct WebPBitstreamFeatures {
int width; // Width in pixels.
int height; // Height in pixels.
int has_alpha; // True if the bitstream contains an alpha channel.
int has_animation; // True if the bitstream is an animation.
int format; // 0 = undefined (/mixed), 1 = lossy, 2 = lossless
}
VP8StatusCode WebPGetFeatures(const uint8_t* data,
size_t data_size,
WebPBitstreamFeatures* features);
此函数将从比特流中检索特征。*features
结构中填充了从比特流收集的信息：
输入属性
- 数据
- 指向 WebP 图片数据的指针
- data_size
- 这是
data指向的内存块大小，其中包含 图片数据。
返回
VP8_STATUS_OK- 成功检索特征时。
VP8_STATUS_NOT_ENOUGH_DATA- 当需要更多数据才能从标题中检索地图项时。
其他情况下的 VP8StatusCode 错误值。
- 功能
- 指向 WebPBitstreamFeatures 结构的指针。
uint8_t* WebPDecodeRGBA(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeARGB(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeBGRA(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeBGR(const uint8_t* data, size_t data_size, int* width, int* height);
这些函数会对 data 所指向的 WebP 图片进行解码。
WebPDecodeRGBA会返回按[r0, g0, b0, a0, r1, g1, b1, a1, ...]顺序的 RGBA 图片样本。WebPDecodeARGB会返回按[a0, r0, g0, b0, a1, r1, g1, b1, ...]顺序的 ARGB 图片样本。WebPDecodeBGRA以[b0, g0, r0, a0, b1, g1, r1, a1, ...]顺序返回 BGRA 图片样本。WebPDecodeRGB会返回按[r0, g0, b0, r1, g1, b1, ...]顺序的 RGB 图片样本。WebPDecodeBGR以[b0, g0, r0, b1, g1, r1, ...]顺序返回 BGR 图片样本。
调用任何这些函数的代码都必须删除数据缓冲区
这些函数通过 WebPFree() 返回的 (uint8_t*)。
输入属性
- 数据
- 指向 WebP 图片数据的指针
- data_size
- 这是
data指向的内存块大小，其中包含 图片数据 - width
- 整数值。目前的范围是 1 到 16383。
- 高度
- 整数值。目前限制的范围是 1 到 16383。
返回
- uint8_t*
- 一个指针，指向已解码为线性 RGBA/ARGB/BGRA/RGB/BGR 的 WebP 图片样本 订单。
uint8_t* WebPDecodeRGBAInto(const uint8_t* data, size_t data_size,
uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeARGBInto(const uint8_t* data, size_t data_size,
uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeBGRAInto(const uint8_t* data, size_t data_size,
uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeRGBInto(const uint8_t* data, size_t data_size,
uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeBGRInto(const uint8_t* data, size_t data_size,
uint8_t* output_buffer, int output_buffer_size, int output_stride);
这些函数是上述函数的变体，可直接解码图片
到预分配的缓冲区 output_buffer 中。可用存储空间上限
该缓冲区由 output_buffer_size 指示。如果此存储空间
足够（或发生了错误）时，系统会返回 NULL。否则
为方便起见，会返回 output_buffer。
参数output_stride指定网页之间的距离（以字节为单位）
扫描线。因此，output_buffer_size 应至少为
output_stride * picture - height。
输入属性
- 数据
- 指向 WebP 图片数据的指针
- data_size
- 这是
data指向的内存块大小，其中包含 图片数据 - output_buffer_size
- 整数值。分配的缓冲区大小
- output_stride
- 整数值。指定扫描线之间的距离。
返回
- output_buffer
- 指向已解码 WebP 图片的指针。
- uint8_t*
output_buffer（如果函数运行成功）；否则为NULL。
高级解码 API
WebP 解码支持高级 API 剪裁和重新缩放，在内存受限的情况下非常有用 例如手机等环境从根本上说，内存用量 输出的大小，而不是只需快速预览或 放大的部分图片。可以节省一些 CPU 不经意间发现
WebP 解码有两种变体，即完整图像解码和增量解码 在小型输入缓冲区中进行解码。用户可以选择提供外部 内存缓冲区，以便对图像进行解码。以下代码示例将详细介绍 使用高级解码 API 的步骤。
首先，我们需要初始化一个配置对象：
#include "webp/decode.h"
WebPDecoderConfig config;
CHECK(WebPInitDecoderConfig(&config));
// One can adjust some additional decoding options:
config.options.no_fancy_upsampling = 1;
config.options.use_scaling = 1;
config.options.scaled_width = scaledWidth();
config.options.scaled_height = scaledHeight();
// etc.
解码选项收集在 WebPDecoderConfig 中，
结构：
struct WebPDecoderOptions {
int bypass_filtering; // if true, skip the in-loop filtering
int no_fancy_upsampling; // if true, use faster pointwise upsampler
int use_cropping; // if true, cropping is applied first
int crop_left, crop_top; // top-left position for cropping.
// Will be snapped to even values.
int crop_width, crop_height; // dimension of the cropping area
int use_scaling; // if true, scaling is applied afterward
int scaled_width, scaled_height; // final resolution
int use_threads; // if true, use multi-threaded decoding
int dithering_strength; // dithering strength (0=Off, 100=full)
int flip; // if true, flip output vertically
int alpha_dithering_strength; // alpha dithering strength in [0..100]
};
（可选）可将比特流特征读入 config.input，
以防我们需要提前知晓。例如，知道
即图片是否完全透明。请注意，
也要解析比特流的标头
如果比特流看起来像是有效的 WebP 流，则会发生此错误。
CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
然后，我们需要设置解码内存缓冲区，以防我们想要提供 而不是依赖解码器进行分配。我们只需要 提供指向内存的指针以及缓冲区的总大小和 线步长（扫描线之间的距离，以字节为单位）。
// Specify the desired output colorspace:
config.output.colorspace = MODE_BGRA;
// Have config.output point to an external buffer:
config.output.u.RGBA.rgba = (uint8_t*)memory_buffer;
config.output.u.RGBA.stride = scanline_stride;
config.output.u.RGBA.size = total_size_of_the_memory_buffer;
config.output.is_external_memory = 1;
图片已准备好进行解码。有两种可能的解码变体 图片。我们可以使用以下代码一次性解码图像：
CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
或者，我们可以使用增量方法 在有新字节可用时上传映像：
WebPIDecoder* idec = WebPINewDecoder(&config.output);
CHECK(idec != NULL);
while (additional_data_is_available) {
// ... (get additional data in some new_data[] buffer)
VP8StatusCode status = WebPIAppend(idec, new_data, new_data_size);
if (status != VP8_STATUS_OK && status != VP8_STATUS_SUSPENDED) {
break;
}
// The above call decodes the current available buffer.
// Part of the image can now be refreshed by calling
// WebPIDecGetRGB()/WebPIDecGetYUVA() etc.
}
WebPIDelete(idec); // the object doesn't own the image memory, so it can
// now be deleted. config.output memory is preserved.
解码后的图片现在位于 config.output 中（或者，位于 config.output.u.RGBA 中） 因为请求的输出颜色空间是 MODE_BGRA）。图片可 保存、显示或以其他方式处理这些广告素材。 之后，我们只需回收在配置的对象中分配的内存。 即使内存是外部内存（而不是外部内存）， 由 WebPDecode() 分配：
WebPFreeDecBuffer(&config.output);
您还可以使用此 API 将图片解码为 YUV 和 YUVA 格式，方法是使用
MODE_YUV 和 MODE_YUVA。这种格式也称为
Y'CbCr。
简单的编码 API
提供一些非常简单的函数，用于对 RGBA 样本数组进行编码
最常见的布局中它们在 webp/encode.h 中声明，
标头为：
size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, float quality_factor, uint8_t** output);
质量因数 quality_factor 介于 0 到 100 之间，
控制压缩过程中的损耗和质量。值 0 对应低
但输出大小较小，而 100 表示最高质量和
输出大小。
成功后，系统会将压缩的字节放在 *output 中
指针，并返回以字节为单位的大小（否则返回 0，如果
）。调用方必须对 *output 调用 WebPFree()
用于回收内存的指针
输入数组应该是打包的字节数组（每个通道一个，如
函数名称所需的值）。stride 对应于
从一行跳到下一行所需的字节数。例如，
BGRA 布局如下：
无损编码的等效函数具有签名：
size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height, int stride, uint8_t** output);
请注意，这些函数与有损版本一样，使用库的默认
设置。对于无损，这意味着“精确”已停用。RGB 值
将修改透明区域以提高压缩率。为避免出现这种情况，请使用
WebPEncode() 并将 WebPConfig::exact 设置为 1。
高级编码 API
从本质上讲，编码器自带许多高级编码参数。
它们有助于更好地平衡压缩
效率和处理时间。
这些参数是在 WebPConfig 结构中收集的。
此结构中最常用的字段包括：
struct WebPConfig {
int lossless; // Lossless encoding (0=lossy(default), 1=lossless).
float quality; // between 0 and 100. For lossy, 0 gives the smallest
// size and 100 the largest. For lossless, this
// parameter is the amount of effort put into the
// compression: 0 is the fastest but gives larger
// files compared to the slowest, but best, 100.
int method; // quality/speed trade-off (0=fast, 6=slower-better)
WebPImageHint image_hint; // Hint for image type (lossless only for now).
// Parameters related to lossy compression only:
int target_size; // if non-zero, set the desired target size in bytes.
// Takes precedence over the 'compression' parameter.
float target_PSNR; // if non-zero, specifies the minimal distortion to
// try to achieve. Takes precedence over target_size.
int segments; // maximum number of segments to use, in [1..4]
int sns_strength; // Spatial Noise Shaping. 0=off, 100=maximum.
int filter_strength; // range: [0 = off .. 100 = strongest]
int filter_sharpness; // range: [0 = off .. 7 = least sharp]
int filter_type; // filtering type: 0 = simple, 1 = strong (only used
// if filter_strength > 0 or autofilter > 0)
int autofilter; // Auto adjust filter's strength [0 = off, 1 = on]
int alpha_compression; // Algorithm for encoding the alpha plane (0 = none,
// 1 = compressed with WebP lossless). Default is 1.
int alpha_filtering; // Predictive filtering method for alpha plane.
// 0: none, 1: fast, 2: best. Default if 1.
int alpha_quality; // Between 0 (smallest size) and 100 (lossless).
// Default is 100.
int pass; // number of entropy-analysis passes (in [1..10]).
int show_compressed; // if true, export the compressed picture back.
// In-loop filtering is not applied.
int preprocessing; // preprocessing filter (0=none, 1=segment-smooth)
int partitions; // log2(number of token partitions) in [0..3]
// Default is set to 0 for easier progressive decoding.
int partition_limit; // quality degradation allowed to fit the 512k limit on
// prediction modes coding (0: no degradation,
// 100: maximum possible degradation).
int use_sharp_yuv; // if needed, use sharp (and slow) RGB->YUV conversion
};
请注意，这些参数大多可用于实验
使用 cwebp 命令行工具来执行此操作。
输入示例应封装到 WebPPicture 结构中。
此结构能够以 RGBA 或 YUVA 格式存储输入样本，
针对 use_argb 标志的值进行改进。
其结构如下：
struct WebPPicture {
int use_argb; // To select between ARGB and YUVA input.
// YUV input, recommended for lossy compression.
// Used if use_argb = 0.
WebPEncCSP colorspace; // colorspace: should be YUVA420 or YUV420 for now (=Y'CbCr).
int width, height; // dimensions (less or equal to WEBP_MAX_DIMENSION)
uint8_t *y, *u, *v; // pointers to luma/chroma planes.
int y_stride, uv_stride; // luma/chroma strides.
uint8_t* a; // pointer to the alpha plane
int a_stride; // stride of the alpha plane
// Alternate ARGB input, recommended for lossless compression.
// Used if use_argb = 1.
uint32_t* argb; // Pointer to argb (32 bit) plane.
int argb_stride; // This is stride in pixels units, not bytes.
// Byte-emission hook, to store compressed bytes as they are ready.
WebPWriterFunction writer; // can be NULL
void* custom_ptr; // can be used by the writer.
// Error code for the latest error encountered during encoding
WebPEncodingError error_code;
};
此结构还有一个函数，用于在压缩字节
可用有关内存中写入程序的示例，请参阅下文。
其他写入者可以直接将数据存储到文件中（请参阅
examples/cwebp.c）。
使用高级 API 进行编码的一般流程如下所示： 以下：
首先，我们需要设置包含 压缩参数。请注意，您可以使用相同的配置 之后又压缩了几张不同的图像。
#include "webp/encode.h"
WebPConfig config;
if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) return 0; // version error
// Add additional tuning:
config.sns_strength = 90;
config.filter_sharpness = 6;
config.alpha_quality = 90;
config_error = WebPValidateConfig(&config); // will verify parameter ranges (always a good habit)
然后，需要将输入样本引用到 WebPPicture 中，
参考或复制。以下是分配缓冲区以
示例。不过，您可以轻松设置已经分配的
示例数组。请参阅 WebPPictureView() 函数。
// Setup the input data, allocating a picture of width x height dimension
WebPPicture pic;
if (!WebPPictureInit(&pic)) return 0; // version error
pic.width = width;
pic.height = height;
if (!WebPPictureAlloc(&pic)) return 0; // memory error
// At this point, 'pic' has been initialized as a container, and can receive the YUVA or RGBA samples.
// Alternatively, one could use ready-made import functions like WebPPictureImportRGBA(), which will take
// care of memory allocation. In any case, past this point, one will have to call WebPPictureFree(&pic)
// to reclaim allocated memory.
为了发出压缩字节，每次添加新字节时，都会调用钩子
可用。下面是一个简单的示例，其中声明了
webp/encode.h。可能需要进行此初始化
要压缩的图片大小：
// Set up a byte-writing method (write-to-memory, in this case):
WebPMemoryWriter writer;
WebPMemoryWriterInit(&writer);
pic.writer = WebPMemoryWrite;
pic.custom_ptr = &writer;
现在，我们可以压缩输入样本（之后释放其内存）：
int ok = WebPEncode(&config, &pic);
WebPPictureFree(&pic); // Always free the memory associated with the input.
if (!ok) {
printf("Encoding error: %d\n", pic.error_code);
} else {
printf("Output size: %d\n", writer.size);
}
有关 API 和结构的更高级用法，建议您查看
参阅 webp/encode.h 标头中提供的文档。
事实证明，阅读示例代码 examples/cwebp.c 会很有帮助
来发现不太常用的参数。