WebP API Documentation

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

Headers and Libraries

When you installlibwebp, 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.

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.

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.

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

The image is ready to be decoded. There are two possible variants for decoding
the image. We can decode the image in one go using:

CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);

Alternately, we can use the incremental method to progressively decode
the image as fresh bytes become available:

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.

The decoded image is now in config.output (or, rather, in config.output.u.RGBA
in this case, since the requested output colorspace was MODE_BGRA). Image can
be saved, displayed or otherwise processed.
Afterward, we only need to reclaim the memory allocated in config's object.
It's safe to call this function even if the memory is external and wasn't
allocated by WebPDecode():

WebPFreeDecBuffer(&config.output);

Using this API the image can also be decoded to YUV and YUVA formats, using
MODE_YUV and MODE_YUVA respectively. This format is also called
Y'CbCr.

Simple Encoding API

Some very simple functions are supplied for encoding arrays of RGBA samples
in most common layouts. They are declared in the webp/encode.h
header as:

The quality factor quality_factor ranges from 0 to 100 and
controls the loss and quality during compression. The value 0 corresponds to low
quality and small output sizes, whereas 100 is the highest quality and largest
output size.
Upon success, the compressed bytes are placed in the *output
pointer, and the size in bytes is returned (otherwise 0 is returned, in case
of failure). The caller must call WebPFree() on the *output
pointer to reclaim memory.

The input array should be a packed array of bytes (one for each channel, as
expected by the name of the function). stride corresponds to the
number of bytes needed to jump from one row to the next. For instance,
BGRA layout is:

There are equivalent functions for lossless encoding, with signatures:

Advanced Encoding API

Under the hood, the encoder comes with numerous advanced encoding parameters.
They can be useful to better balance the trade-off between compression
efficiency and processing time.
These parameters are gathered within the WebPConfig structure.
The most used fields of this structure are:

This structure also has a function to emit the compressed bytes as they
are made available. See below for an example with an in-memory writer.
Other writers can directly store data to a file (see
examples/cwebp.c for such an example).

The general flow for encoding using the advanced API looks like the
following:

First, we need to set up an encoding configuration containing the
compression parameters. Note that the same configuration can be used
for compressing several different images afterward.

Then, the input samples need to be referenced into a WebPPicture either
by reference or copy. Here is an example allocating the buffer for holding
the samples. But one can easily set up a "view" to an already-allocated
sample array. See the WebPPictureView() function.

// 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 (!WebPPictureAllocate(&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.

To emit the compressed bytes, a hook is called every time new bytes are
available. Here's a simple example with the memory-writer declared in
webp/encode.h. This initialization is likely to be needed for
each picture to compress:

For more advanced use of the API and structure, it is recommended to look
at the documentation available in the webp/encode.h header.
Reading the example code examples/cwebp.c can prove useful
for discovering less used parameters.