WebP API Documentation

Page Summary

The WebP library provides APIs for decoding and encoding WebP images, offering both simple and advanced options for controlling the process.
Decoding APIs allow for retrieving image information, decoding into various color formats, and advanced features like cropping and rescaling during decoding.
Encoding APIs support both lossy and lossless compression, with options to customize parameters like quality, speed, and filtering for fine-grained control.
The advanced encoding API uses WebPConfig and WebPPicture structures to manage compression settings and image data, offering flexibility in handling the input and output.
Developers can leverage these APIs to optimize WebP image compression based on specific quality, size, and speed requirements for their applications.

This section describes the API for the encoder and decoder that are included in the WebP library. This API description pertains to version 1.6.0.

Headers and Libraries

When you install libwebp, a directory named webp/ will be installed at the typical location for your platform. For example, on Unix platforms, the following header files would be copied to /usr/local/include/webp/.

decode.h
encode.h
types.h

The libraries are located in the usual library directories. The static and dynamic libraries are in /usr/local/lib/ on Unix platforms.

Simple Decoding API

To get started using the decoding API, you must ensure that you have the library and header files installed as described above.

Include the decoding API header in your C/C++ code as follows:

#include "webp/decode.h"
int WebPGetInfo(const uint8_t* data, size_t data_size, int* width, int* height);

This function will validate the WebP image header and retrieve the image width and height. Pointers *width and *height can be passed NULL if deemed irrelevant.

Input Attributes

data: Pointer to WebP image data
data_size: This is the size of the memory block pointed to by data containing the image data.

Returns

false: Error code returned in the case of (a) formatting error(s).
true: On success. *width and *height are only valid on successful return.
width: Integer value. The range is limited from 1 to 16383.
height: Integer value. The range is limited from 1 to 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);

This function will retrieve features from the bitstream. The *features structure is filled with information gathered from the bitstream:

Input Attributes

data: Pointer to WebP image data
data_size: This is the size of the memory block pointed to by data containing the image data.

Returns

VP8_STATUS_OK: When the features are successfully retrieved.
VP8_STATUS_NOT_ENOUGH_DATA: When more data is needed to retrieve the features from headers.

Additional VP8StatusCode error values in other cases.

features: Pointer to WebPBitstreamFeatures structure.

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

These functions decode a WebP image pointed to by data.

WebPDecodeRGBA returns RGBA image samples in [r0, g0, b0, a0, r1, g1, b1, a1, ...] order.
WebPDecodeARGB returns ARGB image samples in [a0, r0, g0, b0, a1, r1, g1, b1, ...] order.
WebPDecodeBGRA returns BGRA image samples in [b0, g0, r0, a0, b1, g1, r1, a1, ...] order.
WebPDecodeRGB returns RGB image samples in [r0, g0, b0, r1, g1, b1, ...] order.
WebPDecodeBGR returns BGR image samples in [b0, g0, r0, b1, g1, r1, ...] order.

The code that calls any of these functions must delete the data buffer (uint8_t*) returned by these functions with WebPFree().

Input Attributes

data: Pointer to WebP image data
data_size: This is the size of the memory block pointed to by data containing the image data
width: Integer value. The range is limited currently from 1 to 16383.
height: Integer value. The range is limited currently from 1 to 16383.

Returns

uint8_t*: Pointer to decoded WebP image samples in linear RGBA/ARGB/BGRA/RGB/BGR order respectively.

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

These functions are variants of the above ones and decode the image directly into a pre-allocated buffer output_buffer. The maximum storage available in this buffer is indicated by output_buffer_size. If this storage is not sufficient (or an error occurred), NULL is returned. Otherwise, output_buffer is returned, for convenience.

The parameter output_stride specifies the distance (in bytes) between scanlines. Hence, output_buffer_size is expected to be at least output_stride * picture - height.

Input Attributes

data: Pointer to WebP image data
data_size: This is the size of the memory block pointed to by data containing the image data
output_buffer_size: Integer value. Size of allocated buffer
output_stride: Integer value. Specifies the distance between scanlines.

Returns

output_buffer: Pointer to decoded WebP image.
uint8_t*: output_buffer if function succeeds; NULL otherwise.

Advanced Decoding API

WebP decoding supports an advanced API to provide ability to have on-the-fly cropping and rescaling, something of great usefulness on memory-constrained environments like mobile phones. Basically, the memory usage will scale with the output's size, not the input's when one only needs a quick preview or a zoomed in portion of an otherwise too-large picture. Some CPU can be saved too, incidentally.

WebP decoding comes in two variants viz full image decoding and incremental decoding over small input buffers. Users can optionally provide an external memory buffer for decoding the image. The following code sample will go through the steps of using the advanced decoding API.

First we need to initialize a configuration object:

#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.

The decode options are gathered within the WebPDecoderConfig structure:

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]
};

Optionally the bitstream features can be read into config.input, in case we need to know them in advance. For instance it can handy to know whether the picture has some transparency at all. Note that this will also parse the bitstream's header, and is therefore a good way of knowing if the bitstream looks like a valid WebP one.

CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);

Then we need to setup the decoding memory buffer in case we want to supply it directly instead of relying on the decoder for its allocation. We only need to supply the pointer to the memory as well as the total size of the buffer and the line stride (distance in bytes between scanlines).

// 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.

WebP API Documentation Stay organized with collections Save and categorize content based on your preferences.

Page Summary

Headers and Libraries

Simple Decoding API

Input Attributes

Returns

Input Attributes

Returns

Input Attributes

Returns

Input Attributes

Returns

Advanced Decoding API

WebP API Documentation