Remove the transparency information (if present) by blending the color with
the background color background_rgb (specified as 24bit RGB triplet).
After this call, all alpha values are reset to 0xff.
Helper function: given a width x height plane of RGBA or YUV(A) samples
clean-up or smoothen the YUV or RGB samples under fully transparent area,
to help compressibility (no guarantee, though).
Should always be called, to initialize a fresh WebPConfig structure before
modification. Returns false in case of version mismatch. WebPConfigInit()
must have succeeded before using the config object.
Note that the default values are lossless=0 and quality=75.
Activate the lossless compression mode with the desired efficiency level
between 0 (fastest, lowest compression) and 9 (slower, best compression).
A good default level is 6, providing a fair tradeoff between compression
speed and final compressed size.
This function will overwrite several fields from config: method, quality
and lossless. Returns false in case of parameter error.
This function will initialize the configuration according to a predefined
set of parameters (referred to by preset) and a given quality factor.
This function can be called as a replacement to WebPConfigInit(). Will
return false in case of error.
Non-incremental version. This version decodes the full data at once, taking
‘config’ into account. Returns decoding status (which should be VP8_STATUS_OK
if the decoding was successful). Note that ‘config’ cannot be NULL.
Decodes WebP images pointed to by ‘data’ and returns RGBA samples, along
with the dimensions in *width and *height. The ordering of samples in
memory is R, G, B, A, R, G, B, A… in scan order (endian-independent).
The returned pointer should be deleted calling WebPFree().
Returns NULL in case of error.
Decode WebP images pointed to by ‘data’ to Y’UV format(*). The pointer
returned is the Y samples buffer. Upon return, *u and *v will point to
the U and V chroma data. These U and V buffers need NOT be passed to
WebPFree(), unlike the returned Y luma one. The dimension of the U and V
planes are both (*width + 1) / 2 and (*height + 1) / 2.
Upon return, the Y buffer has a stride returned as ‘*stride’, while U and V
have a common stride returned as ‘uv_stride’.
‘width’ and ‘height’ may be NULL, the other pointers must not be.
Returns NULL in case of error.
() Also named Y’CbCr. See: https://en.wikipedia.org/wiki/YCbCr
WebPDecodeYUVInto() is a variant of WebPDecodeYUV() that operates directly
into pre-allocated luma/chroma plane buffers. This function requires the
strides to be passed: one for the luma plane and one for each of the
chroma ones. The size of each plane buffer is passed as ‘luma_size’,
‘u_size’ and ‘v_size’ respectively.
Pointer to the luma plane (‘*luma’) is returned or NULL if an error occurred
during decoding (or because some buffers were found to be too small).
Main encoding call, after config and picture have been initialized.
picture must be less than 16384x16384 in dimension (cf WEBP_MAX_DIMENSION),
and the config object must be a valid one.
Returns false in case of error, true otherwise.
In case of error, picture->error_code is updated accordingly.
picture can hold the source samples in both YUV(A) or ARGB input, depending
on the value of picture->use_argb. It is highly recommended to use
the former for lossy encoding, and the latter for lossless encoding
(when config.lossless is true). Automatic conversion from one format to
another is provided but they both incur some loss.
Returns the size of the compressed data (pointed to by *output``), or 0 if an error occurred. The compressed data must be released by the caller using the call WebPFree(*output)`.
These functions compress using the lossy format, and the quality_factor
can go from 0 (smaller output, lower quality) to 100 (best quality,
larger output).
Returns the size of the compressed data (pointed to by *output``), or 0 if an error occurred. The compressed data must be released by the caller using the call WebPFree(*output)`.
These functions compress using the lossy format, and the quality_factor
can go from 0 (smaller output, lower quality) to 100 (best quality,
larger output).
Equivalent to WebPEncodeBGR, but compressing in a
lossless manner. Files are usually larger than lossy format, but will
not suffer any compression loss.
Note these functions, like the lossy versions, use the library’s default
settings. For lossless this means exact is disabled. RGB values in
transparent areas will be modified to improve compression. To avoid this,
use WebPEncode() and set WebPConfig::exact to 1.
Equivalent to WebPEncodeBGRA, but compressing in a
lossless manner. Files are usually larger than lossy format, but will
not suffer any compression loss.
Note these functions, like the lossy versions, use the library’s default
settings. For lossless this means exact is disabled. RGB values in
transparent areas will be modified to improve compression. To avoid this,
use WebPEncode() and set WebPConfig::exact to 1.
Equivalent to WebPEncodeRGB, but compressing in a
lossless manner. Files are usually larger than lossy format, but will
not suffer any compression loss.
Note these functions, like the lossy versions, use the library’s default
settings. For lossless this means exact is disabled. RGB values in
transparent areas will be modified to improve compression. To avoid this,
use WebPEncode() and set WebPConfig::exact to 1.
Equivalent to WebPEncodeRGBA, but compressing in a
lossless manner. Files are usually larger than lossy format, but will
not suffer any compression loss.
Note these functions, like the lossy versions, use the library’s default
settings. For lossless this means exact is disabled. RGB values in
transparent areas will be modified to improve compression. To avoid this,
use WebPEncode() and set WebPConfig::exact to 1.
Returns the size of the compressed data (pointed to by *output``), or 0 if an error occurred. The compressed data must be released by the caller using the call WebPFree(*output)`.
These functions compress using the lossy format, and the quality_factor
can go from 0 (smaller output, lower quality) to 100 (best quality,
larger output).
Returns the size of the compressed data (pointed to by *output``), or 0 if an error occurred. The compressed data must be released by the caller using the call WebPFree(*output)`.
These functions compress using the lossy format, and the quality_factor
can go from 0 (smaller output, lower quality) to 100 (best quality,
larger output).
Retrieve features from the bitstream. The *features structure is filled
with information gathered from the bitstream.
Returns VP8_STATUS_OK when the features are successfully retrieved. Returns
VP8_STATUS_NOT_ENOUGH_DATA when more data is needed to retrieve the
features from headers. Returns error in other cases.
Note: The following chunk sequences (before the raw VP8/VP8L data) are
considered valid by this function:
RIFF + VP8(L)
RIFF + VP8X + (optional chunks) + VP8(L)
ALPH + VP8 <– Not a valid WebP format: only allowed for internal purpose.
VP8(L) <– Not a valid WebP format: only allowed for internal purpose.
Retrieve basic header information: width, height.
This function will also validate the header, returning true on success,
false otherwise. ‘*width’ and ‘*height’ are only valid on successful return.
Pointers ‘width’ and ‘height’ can be passed NULL if deemed irrelevant.
Note: The following chunk sequences (before the raw VP8/VP8L data) are
considered valid by this function:
RIFF + VP8(L)
RIFF + VP8X + (optional chunks) + VP8(L)
ALPH + VP8 <– Not a valid WebP format: only allowed for internal purpose.
VP8(L) <– Not a valid WebP format: only allowed for internal purpose.
Copies and decodes the next available data. Returns VP8_STATUS_OK when
the image is successfully decoded. Returns VP8_STATUS_SUSPENDED when more
data is expected. Returns error in other cases.
Returns the RGB/A image decoded so far. Returns NULL if output params
are not initialized yet. The RGB/A output type corresponds to the colorspace
specified during call to WebPINewDecoder() or WebPINewRGB().
*last_y is the index of last decoded row in raster scan order. Some pointers
(*last_y, *width etc.) can be NULL if corresponding information is not
needed. The values in these pointers are only valid on successful (non-NULL)
return.
Same as above function to get a YUVA image. Returns pointer to the luma
plane or NULL in case of error. If there is no alpha information
the alpha pointer ‘*a’ will be returned NULL.
Instantiate a new incremental decoder object with the requested
configuration. The bitstream can be passed using ‘data’ and ‘data_size’
parameter, in which case the features will be parsed and stored into
config->input. Otherwise, ‘data’ can be NULL and no parsing will occur.
Note that ‘config’ can be NULL too, in which case a default configuration
is used. If ‘config’ is not NULL, it must outlive the WebPIDecoder object
as some references to its fields will be used. No internal copy of ‘config’
is made.
The return WebPIDecoder object must always be deleted calling WebPIDelete().
Returns NULL in case of error (and config->status will then reflect
the error condition, if available).
Generic call to retrieve information about the displayable area.
If non NULL, the left/right/width/height pointers are filled with the visible
rectangular area so far.
Returns NULL in case the incremental decoder object is in an invalid state.
Otherwise returns the pointer to the internal representation. This structure
is read-only, tied to WebPIDecoder’s lifespan and should not be modified.
Creates a new incremental decoder with the supplied buffer parameter.
This output_buffer can be passed NULL, in which case a default output buffer
is used (with MODE_RGB). Otherwise, an internal reference to ‘output_buffer’
is kept, which means that the lifespan of ‘output_buffer’ must be larger than
that of the returned WebPIDecoder object.
The supplied ‘output_buffer’ content MUST NOT be changed between calls to
WebPIAppend() or WebPIUpdate() unless ‘output_buffer.is_external_memory’ is
not set to 0. In such a case, it is allowed to modify the pointers, size and
stride of output_buffer.u.RGBA or output_buffer.u.YUVA, provided they remain
within valid bounds.
All other fields of WebPDecBuffer MUST remain constant between calls.
Returns NULL if the allocation failed.
This function allocates and initializes an incremental-decoder object, which
will output the RGB/A samples specified by ‘csp’ into a preallocated
buffer ‘output_buffer’. The size of this buffer is at least
‘output_buffer_size’ and the stride (distance in bytes between two scanlines)
is specified by ‘output_stride’.
Additionally, output_buffer can be passed NULL in which case the output
buffer will be allocated automatically when the decoding starts. The
colorspace ‘csp’ is taken into account for allocating this buffer. All other
parameters are ignored.
Returns NULL if the allocation failed, or if some parameters are invalid.
This function allocates and initializes an incremental-decoder object, which
will output the raw luma/chroma samples into a preallocated planes if
supplied. The luma plane is specified by its pointer ‘luma’, its size
‘luma_size’ and its stride ‘luma_stride’. Similarly, the chroma-u plane
is specified by the ‘u’, ‘u_size’ and ‘u_stride’ parameters, and the chroma-v
plane by ‘v’ and ‘v_size’. And same for the alpha-plane. The ‘a’ pointer
can be pass NULL in case one is not interested in the transparency plane.
Conversely, ‘luma’ can be passed NULL if no preallocated planes are supplied.
In this case, the output buffer will be automatically allocated (using
MODE_YUVA) when decoding starts. All parameters are then ignored.
Returns NULL if the allocation failed or if a parameter is invalid.
A variant of the above function to be used when data buffer contains
partial data from the beginning. In this case data buffer is not copied
to the internal memory.
Note that the value of the ‘data’ pointer can change between calls to
WebPIUpdate, for instance when the data buffer is resized to fit larger data.
Initialize the configuration as empty. This function must always be
called first, unless WebPGetFeatures() is to be called.
Returns false in case of mismatched version.
Allocates size bytes of memory. Returns NULL upon error. Memory
must be deallocated by calling WebPFree(). This function is made available
by the core libwebp library.
The custom writer to be used with WebPMemoryWriter as custom_ptr. Upon
completion, writer.mem and writer.size will hold the coded data.
writer.mem must be freed by calling WebPMemoryWriterClear.
Converts picture->argb data to the YUV420A format. The colorspace
parameter is deprecated and should be equal to WEBP_YUV420.
Upon return, picture->use_argb is set to false. The presence of real
non-opaque transparent values is detected, and colorspace will be
adjusted accordingly. Note that this method is lossy.
Returns false in case of error.
Same as WebPPictureARGBToYUVA(), but the conversion is done using
pseudo-random dithering with a strength dithering between
0.0 (no dithering) and 1.0 (maximum dithering). This is useful
for photographic picture.
Convenience allocation / deallocation based on picture->width/height:
Allocate y/u/v buffers as per colorspace/width/height specification.
Note! This function will free the previous buffer if needed.
Returns false in case of memory error.
Copy the pixels of *src into *dst, using WebPPictureAlloc. Upon return, *dst
will fully own the copied pixels (this is not a view). The dst picture need
not be initialized as its content is overwritten.
Returns false in case of memory allocation error.
self-crops a picture to the rectangle defined by top/left/width/height.
Returns false in case of memory allocation error, or if the rectangle is
outside of the source picture.
The rectangle for the view is defined by the top-left corner pixel
coordinates (left, top) as well as its width and height. This rectangle
must be fully be comprised inside the src source picture. If the source
picture uses the YUV420 colorspace, the top and left coordinates will be
snapped to even values.
Compute PSNR, SSIM or LSIM distortion metric between two pictures. Results
are in dB, stored in result[] in the B/G/R/A/All order. The distortion is
always performed using ARGB samples. Hence if the input is YUV(A), the
picture will be internally converted to ARGB (just for the measurement).
Warning: this function is rather CPU-intensive.
Release the memory allocated by WebPPictureAlloc() or WebPPictureImport*().
Note that this function does not free the memory used by the picture
object itself.
Besides memory (which is reclaimed) all other fields of picture are
preserved.
Scan the picture picture for the presence of non fully opaque alpha values.
Returns true in such case. Otherwise returns false (indicating that the
alpha plane can be ignored altogether e.g.).
Colorspace conversion function to import RGB samples.
Previous buffer will be free’d, if any.
*rgb buffer should have a size of at least height * rgb_stride.
Returns false in case of memory error.
Same as WebPPictureImportRGB, but for RGBA buffer. Imports the RGB direct from the 32-bit format
input buffer ignoring the alpha channel. Avoids needing to copy the data
to a temporary 24-bit RGB buffer to import the RGB only.
Should always be called, to initialize the structure. Returns false in case
of version mismatch. WebPPictureInit() must have succeeded before using the
picture object.
Note that, by default, use_argb is false and colorspace is WEBP_YUV420.
Rescale a picture to new dimension width x height.
If either width or height (but not both) is 0 the corresponding
dimension will be calculated preserving the aspect ratio.
No gamma correction is applied.
Returns false in case of error (invalid parameter or insufficient memory).
Performs sharp RGBA->YUVA420 downsampling and colorspace conversion
Downsampling is handled with extra care in case of color clipping. This
method is roughly 2x slower than WebPPictureARGBToYUVA() but produces better
and sharper YUV representation.
Returns false in case of error.
Extracts a view from src picture into dst. The rectangle for the view
is defined by the top-left corner pixel coordinates (left, top) as well
as its width and height. This rectangle must be fully be comprised inside
the src source picture. If the source picture uses the YUV420 colorspace,
the top and left coordinates will be snapped to even values.
Picture src must out-live dst picture. Self-extraction of view is allowed
(src equal to dst) as a mean of fast-cropping (but note that doing so,
the original dimension will be lost). Picture dst need not be initialized
with WebPPictureInit() if it is different from src, since its content will
be overwritten.
Returns false in case of invalid parameters.
Converts picture->yuv to picture->argb and sets picture->use_argb to true.
The input format must be YUV_420 or YUV_420A. The conversion from YUV420 to
ARGB incurs a small loss too.
Note that the use of this colorspace is discouraged if one has access to the
raw ARGB samples, since using YUV420 is comparatively lossy.
Returns false in case of error.
Compute the single distortion for packed planes of samples.
src will be compared to ref, and the raw distortion stored into
*distortion. The refined metric (log(MSE), log(1 - ssim),…) will be
stored in *result.
x_step is the horizontal stride (in bytes) between samples.
src/ref_stride is the byte distance between rows.
Returns false in case of error (bad parameter, memory allocation error, …).
Progress hook, called from time to time to report progress. It can return
false to request an abort of the encoding process, or true otherwise if
everything is OK.
Signature for output function. Should return true if writing was successful.
data/data_size is the segment of data to write, and picture is for
reference (and so one can make use of picture->custom_ptr).