1// Copyright 2010 Google Inc. All Rights Reserved. 2// 3// This code is licensed under the same terms as WebM: 4// Software License Agreement: http://www.webmproject.org/license/software/ 5// Additional IP Rights Grant: http://www.webmproject.org/license/additional/ 6// ----------------------------------------------------------------------------- 7// 8// Main decoding functions for WebP images. 9// 10// Author: Skal (pascal.massimino@gmail.com) 11 12#ifndef WEBP_WEBP_DECODE_H_ 13#define WEBP_WEBP_DECODE_H_ 14 15#include "./types.h" 16 17#if defined(__cplusplus) || defined(c_plusplus) 18extern "C" { 19#endif 20 21#define WEBP_DECODER_ABI_VERSION 0x0200 // MAJOR(8b) + MINOR(8b) 22 23// Return the decoder's version number, packed in hexadecimal using 8bits for 24// each of major/minor/revision. E.g: v2.5.7 is 0x020507. 25WEBP_EXTERN(int) WebPGetDecoderVersion(void); 26 27// Retrieve basic header information: width, height. 28// This function will also validate the header and return 0 in 29// case of formatting error. 30// Pointers 'width' and 'height' can be passed NULL if deemed irrelevant. 31WEBP_EXTERN(int) WebPGetInfo(const uint8_t* data, size_t data_size, 32 int* width, int* height); 33 34// Decodes WebP images pointed to by 'data' and returns RGBA samples, along 35// with the dimensions in *width and *height. The ordering of samples in 36// memory is R, G, B, A, R, G, B, A... in scan order (endian-independent). 37// The returned pointer should be deleted calling free(). 38// Returns NULL in case of error. 39WEBP_EXTERN(uint8_t*) WebPDecodeRGBA(const uint8_t* data, size_t data_size, 40 int* width, int* height); 41 42// Same as WebPDecodeRGBA, but returning A, R, G, B, A, R, G, B... ordered data. 43WEBP_EXTERN(uint8_t*) WebPDecodeARGB(const uint8_t* data, size_t data_size, 44 int* width, int* height); 45 46// Same as WebPDecodeRGBA, but returning B, G, R, A, B, G, R, A... ordered data. 47WEBP_EXTERN(uint8_t*) WebPDecodeBGRA(const uint8_t* data, size_t data_size, 48 int* width, int* height); 49 50// Same as WebPDecodeRGBA, but returning R, G, B, R, G, B... ordered data. 51// If the bitstream contains transparency, it is ignored. 52WEBP_EXTERN(uint8_t*) WebPDecodeRGB(const uint8_t* data, size_t data_size, 53 int* width, int* height); 54 55// Same as WebPDecodeRGB, but returning B, G, R, B, G, R... ordered data. 56WEBP_EXTERN(uint8_t*) WebPDecodeBGR(const uint8_t* data, size_t data_size, 57 int* width, int* height); 58 59 60// Decode WebP images pointed to by 'data' to Y'UV format(*). The pointer 61// returned is the Y samples buffer. Upon return, *u and *v will point to 62// the U and V chroma data. These U and V buffers need NOT be free()'d, 63// unlike the returned Y luma one. The dimension of the U and V planes 64// are both (*width + 1) / 2 and (*height + 1)/ 2. 65// Upon return, the Y buffer has a stride returned as '*stride', while U and V 66// have a common stride returned as '*uv_stride'. 67// Return NULL in case of error. 68// (*) Also named Y'CbCr. See: http://en.wikipedia.org/wiki/YCbCr 69WEBP_EXTERN(uint8_t*) WebPDecodeYUV(const uint8_t* data, size_t data_size, 70 int* width, int* height, 71 uint8_t** u, uint8_t** v, 72 int* stride, int* uv_stride); 73 74// These five functions are variants of the above ones, that decode the image 75// directly into a pre-allocated buffer 'output_buffer'. The maximum storage 76// available in this buffer is indicated by 'output_buffer_size'. If this 77// storage is not sufficient (or an error occurred), NULL is returned. 78// Otherwise, output_buffer is returned, for convenience. 79// The parameter 'output_stride' specifies the distance (in bytes) 80// between scanlines. Hence, output_buffer_size is expected to be at least 81// output_stride x picture-height. 82WEBP_EXTERN(uint8_t*) WebPDecodeRGBAInto( 83 const uint8_t* data, size_t data_size, 84 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 85WEBP_EXTERN(uint8_t*) WebPDecodeARGBInto( 86 const uint8_t* data, size_t data_size, 87 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 88WEBP_EXTERN(uint8_t*) WebPDecodeBGRAInto( 89 const uint8_t* data, size_t data_size, 90 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 91 92// RGB and BGR variants. Here too the transparency information, if present, 93// will be dropped and ignored. 94WEBP_EXTERN(uint8_t*) WebPDecodeRGBInto( 95 const uint8_t* data, size_t data_size, 96 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 97WEBP_EXTERN(uint8_t*) WebPDecodeBGRInto( 98 const uint8_t* data, size_t data_size, 99 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 100 101// WebPDecodeYUVInto() is a variant of WebPDecodeYUV() that operates directly 102// into pre-allocated luma/chroma plane buffers. This function requires the 103// strides to be passed: one for the luma plane and one for each of the 104// chroma ones. The size of each plane buffer is passed as 'luma_size', 105// 'u_size' and 'v_size' respectively. 106// Pointer to the luma plane ('*luma') is returned or NULL if an error occurred 107// during decoding (or because some buffers were found to be too small). 108WEBP_EXTERN(uint8_t*) WebPDecodeYUVInto( 109 const uint8_t* data, size_t data_size, 110 uint8_t* luma, size_t luma_size, int luma_stride, 111 uint8_t* u, size_t u_size, int u_stride, 112 uint8_t* v, size_t v_size, int v_stride); 113 114//------------------------------------------------------------------------------ 115// Output colorspaces and buffer 116 117// Colorspaces 118// Note: the naming describes the byte-ordering of packed samples in memory. 119// For instance, MODE_BGRA relates to samples ordered as B,G,R,A,B,G,R,A,... 120// Non-capital names (e.g.:MODE_Argb) relates to pre-multiplied RGB channels. 121// RGB-565 and RGBA-4444 are also endian-agnostic and byte-oriented. 122typedef enum { MODE_RGB = 0, MODE_RGBA = 1, 123 MODE_BGR = 2, MODE_BGRA = 3, 124 MODE_ARGB = 4, MODE_RGBA_4444 = 5, 125 MODE_RGB_565 = 6, 126 // RGB-premultiplied transparent modes (alpha value is preserved) 127 MODE_rgbA = 7, 128 MODE_bgrA = 8, 129 MODE_Argb = 9, 130 MODE_rgbA_4444 = 10, 131 // YUV modes must come after RGB ones. 132 MODE_YUV = 11, MODE_YUVA = 12, // yuv 4:2:0 133 MODE_LAST = 13 134 } WEBP_CSP_MODE; 135 136// Some useful macros: 137static WEBP_INLINE int WebPIsPremultipliedMode(WEBP_CSP_MODE mode) { 138 return (mode == MODE_rgbA || mode == MODE_bgrA || mode == MODE_Argb || 139 mode == MODE_rgbA_4444); 140} 141 142static WEBP_INLINE int WebPIsAlphaMode(WEBP_CSP_MODE mode) { 143 return (mode == MODE_RGBA || mode == MODE_BGRA || mode == MODE_ARGB || 144 mode == MODE_RGBA_4444 || mode == MODE_YUVA || 145 WebPIsPremultipliedMode(mode)); 146} 147 148static WEBP_INLINE int WebPIsRGBMode(WEBP_CSP_MODE mode) { 149 return (mode < MODE_YUV); 150} 151 152//------------------------------------------------------------------------------ 153// WebPDecBuffer: Generic structure for describing the output sample buffer. 154 155typedef struct { // view as RGBA 156 uint8_t* rgba; // pointer to RGBA samples 157 int stride; // stride in bytes from one scanline to the next. 158 size_t size; // total size of the *rgba buffer. 159} WebPRGBABuffer; 160 161typedef struct { // view as YUVA 162 uint8_t* y, *u, *v, *a; // pointer to luma, chroma U/V, alpha samples 163 int y_stride; // luma stride 164 int u_stride, v_stride; // chroma strides 165 int a_stride; // alpha stride 166 size_t y_size; // luma plane size 167 size_t u_size, v_size; // chroma planes size 168 size_t a_size; // alpha-plane size 169} WebPYUVABuffer; 170 171// Output buffer 172typedef struct { 173 WEBP_CSP_MODE colorspace; // Colorspace. 174 int width, height; // Dimensions. 175 int is_external_memory; // If true, 'internal_memory' pointer is not used. 176 union { 177 WebPRGBABuffer RGBA; 178 WebPYUVABuffer YUVA; 179 } u; // Nameless union of buffer parameters. 180 uint32_t pad[4]; // padding for later use 181 182 uint8_t* private_memory; // Internally allocated memory (only when 183 // is_external_memory is false). Should not be used 184 // externally, but accessed via the buffer union. 185} WebPDecBuffer; 186 187// Internal, version-checked, entry point 188WEBP_EXTERN(int) WebPInitDecBufferInternal(WebPDecBuffer*, int); 189 190// Initialize the structure as empty. Must be called before any other use. 191// Returns false in case of version mismatch 192static WEBP_INLINE int WebPInitDecBuffer(WebPDecBuffer* buffer) { 193 return WebPInitDecBufferInternal(buffer, WEBP_DECODER_ABI_VERSION); 194} 195 196// Free any memory associated with the buffer. Must always be called last. 197// Note: doesn't free the 'buffer' structure itself. 198WEBP_EXTERN(void) WebPFreeDecBuffer(WebPDecBuffer* buffer); 199 200//------------------------------------------------------------------------------ 201// Enumeration of the status codes 202 203typedef enum { 204 VP8_STATUS_OK = 0, 205 VP8_STATUS_OUT_OF_MEMORY, 206 VP8_STATUS_INVALID_PARAM, 207 VP8_STATUS_BITSTREAM_ERROR, 208 VP8_STATUS_UNSUPPORTED_FEATURE, 209 VP8_STATUS_SUSPENDED, 210 VP8_STATUS_USER_ABORT, 211 VP8_STATUS_NOT_ENOUGH_DATA 212} VP8StatusCode; 213 214//------------------------------------------------------------------------------ 215// Incremental decoding 216// 217// This API allows streamlined decoding of partial data. 218// Picture can be incrementally decoded as data become available thanks to the 219// WebPIDecoder object. This object can be left in a SUSPENDED state if the 220// picture is only partially decoded, pending additional input. 221// Code example: 222// 223// WebPInitDecBuffer(&buffer); 224// buffer.colorspace = mode; 225// ... 226// WebPIDecoder* idec = WebPINewDecoder(&buffer); 227// while (has_more_data) { 228// // ... (get additional data) 229// status = WebPIAppend(idec, new_data, new_data_size); 230// if (status != VP8_STATUS_SUSPENDED || 231// break; 232// } 233// 234// // The above call decodes the current available buffer. 235// // Part of the image can now be refreshed by calling to 236// // WebPIDecGetRGB()/WebPIDecGetYUVA() etc. 237// } 238// WebPIDelete(idec); 239 240typedef struct WebPIDecoder WebPIDecoder; 241 242// Creates a new incremental decoder with the supplied buffer parameter. 243// This output_buffer can be passed NULL, in which case a default output buffer 244// is used (with MODE_RGB). Otherwise, an internal reference to 'output_buffer' 245// is kept, which means that the lifespan of 'output_buffer' must be larger than 246// that of the returned WebPIDecoder object. 247// Returns NULL if the allocation failed. 248WEBP_EXTERN(WebPIDecoder*) WebPINewDecoder(WebPDecBuffer* output_buffer); 249 250// This function allocates and initializes an incremental-decoder object, which 251// will output the RGB/A samples specified by 'csp' into a preallocated 252// buffer 'output_buffer'. The size of this buffer is at least 253// 'output_buffer_size' and the stride (distance in bytes between two scanlines) 254// is specified by 'output_stride'. Returns NULL if the allocation failed. 255WEBP_EXTERN(WebPIDecoder*) WebPINewRGB( 256 WEBP_CSP_MODE csp, 257 uint8_t* output_buffer, size_t output_buffer_size, int output_stride); 258 259// This function allocates and initializes an incremental-decoder object, which 260// will output the raw luma/chroma samples into a preallocated planes. The luma 261// plane is specified by its pointer 'luma', its size 'luma_size' and its stride 262// 'luma_stride'. Similarly, the chroma-u plane is specified by the 'u', 263// 'u_size' and 'u_stride' parameters, and the chroma-v plane by 'v' 264// and 'v_size'. And same for the alpha-plane. The 'a' pointer can be pass 265// NULL in case one is not interested in the transparency plane. 266// Returns NULL if the allocation failed. 267WEBP_EXTERN(WebPIDecoder*) WebPINewYUVA( 268 uint8_t* luma, size_t luma_size, int luma_stride, 269 uint8_t* u, size_t u_size, int u_stride, 270 uint8_t* v, size_t v_size, int v_stride, 271 uint8_t* a, size_t a_size, int a_stride); 272 273// Deprecated version of the above, without the alpha plane. 274// Kept for backward compatibility. 275WEBP_EXTERN(WebPIDecoder*) WebPINewYUV( 276 uint8_t* luma, size_t luma_size, int luma_stride, 277 uint8_t* u, size_t u_size, int u_stride, 278 uint8_t* v, size_t v_size, int v_stride); 279 280// Deletes the WebPIDecoder object and associated memory. Must always be called 281// if WebPINewDecoder, WebPINewRGB or WebPINewYUV succeeded. 282WEBP_EXTERN(void) WebPIDelete(WebPIDecoder* idec); 283 284// Copies and decodes the next available data. Returns VP8_STATUS_OK when 285// the image is successfully decoded. Returns VP8_STATUS_SUSPENDED when more 286// data is expected. Returns error in other cases. 287WEBP_EXTERN(VP8StatusCode) WebPIAppend( 288 WebPIDecoder* idec, const uint8_t* data, size_t data_size); 289 290// A variant of the above function to be used when data buffer contains 291// partial data from the beginning. In this case data buffer is not copied 292// to the internal memory. 293// Note that the value of the 'data' pointer can change between calls to 294// WebPIUpdate, for instance when the data buffer is resized to fit larger data. 295WEBP_EXTERN(VP8StatusCode) WebPIUpdate( 296 WebPIDecoder* idec, const uint8_t* data, size_t data_size); 297 298// Returns the RGB/A image decoded so far. Returns NULL if output params 299// are not initialized yet. The RGB/A output type corresponds to the colorspace 300// specified during call to WebPINewDecoder() or WebPINewRGB(). 301// *last_y is the index of last decoded row in raster scan order. Some pointers 302// (*last_y, *width etc.) can be NULL if corresponding information is not 303// needed. 304WEBP_EXTERN(uint8_t*) WebPIDecGetRGB( 305 const WebPIDecoder* idec, int* last_y, 306 int* width, int* height, int* stride); 307 308// Same as above function to get a YUVA image. Returns pointer to the luma 309// plane or NULL in case of error. If there is no alpha information 310// the alpha pointer '*a' will be returned NULL. 311WEBP_EXTERN(uint8_t*) WebPIDecGetYUVA( 312 const WebPIDecoder* idec, int* last_y, 313 uint8_t** u, uint8_t** v, uint8_t** a, 314 int* width, int* height, int* stride, int* uv_stride, int* a_stride); 315 316// Deprecated alpha-less version of WebPIDecGetYUVA(): it will ignore the 317// alpha information (if present). Kept for backward compatibility. 318static WEBP_INLINE uint8_t* WebPIDecGetYUV( 319 const WebPIDecoder* idec, int* last_y, uint8_t** u, uint8_t** v, 320 int* width, int* height, int* stride, int* uv_stride) { 321 return WebPIDecGetYUVA(idec, last_y, u, v, NULL, width, height, 322 stride, uv_stride, NULL); 323} 324 325// Generic call to retrieve information about the displayable area. 326// If non NULL, the left/right/width/height pointers are filled with the visible 327// rectangular area so far. 328// Returns NULL in case the incremental decoder object is in an invalid state. 329// Otherwise returns the pointer to the internal representation. This structure 330// is read-only, tied to WebPIDecoder's lifespan and should not be modified. 331WEBP_EXTERN(const WebPDecBuffer*) WebPIDecodedArea( 332 const WebPIDecoder* idec, int* left, int* top, int* width, int* height); 333 334//------------------------------------------------------------------------------ 335// Advanced decoding parametrization 336// 337// Code sample for using the advanced decoding API 338/* 339 // A) Init a configuration object 340 WebPDecoderConfig config; 341 CHECK(WebPInitDecoderConfig(&config)); 342 343 // B) optional: retrieve the bitstream's features. 344 CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK); 345 346 // C) Adjust 'config', if needed 347 config.no_fancy = 1; 348 config.output.colorspace = MODE_BGRA; 349 // etc. 350 351 // Note that you can also make config.output point to an externally 352 // supplied memory buffer, provided it's big enough to store the decoded 353 // picture. Otherwise, config.output will just be used to allocate memory 354 // and store the decoded picture. 355 356 // D) Decode! 357 CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK); 358 359 // E) Decoded image is now in config.output (and config.output.u.RGBA) 360 361 // F) Reclaim memory allocated in config's object. It's safe to call 362 // this function even if the memory is external and wasn't allocated 363 // by WebPDecode(). 364 WebPFreeDecBuffer(&config.output); 365*/ 366 367// Features gathered from the bitstream 368typedef struct { 369 int width; // Width in pixels, as read from the bitstream. 370 int height; // Height in pixels, as read from the bitstream. 371 int has_alpha; // True if the bitstream contains an alpha channel. 372 373 // Unused for now: 374 int bitstream_version; // should be 0 for now. TODO(later) 375 int no_incremental_decoding; // if true, using incremental decoding is not 376 // recommended. 377 int rotate; // TODO(later) 378 int uv_sampling; // should be 0 for now. TODO(later) 379 uint32_t pad[3]; // padding for later use 380} WebPBitstreamFeatures; 381 382// Internal, version-checked, entry point 383WEBP_EXTERN(VP8StatusCode) WebPGetFeaturesInternal( 384 const uint8_t*, size_t, WebPBitstreamFeatures*, int); 385 386// Retrieve features from the bitstream. The *features structure is filled 387// with information gathered from the bitstream. 388// Returns false in case of error or version mismatch. 389// In case of error, features->bitstream_status will reflect the error code. 390static WEBP_INLINE VP8StatusCode WebPGetFeatures( 391 const uint8_t* data, size_t data_size, 392 WebPBitstreamFeatures* features) { 393 return WebPGetFeaturesInternal(data, data_size, features, 394 WEBP_DECODER_ABI_VERSION); 395} 396 397// Decoding options 398typedef struct { 399 int bypass_filtering; // if true, skip the in-loop filtering 400 int no_fancy_upsampling; // if true, use faster pointwise upsampler 401 int use_cropping; // if true, cropping is applied _first_ 402 int crop_left, crop_top; // top-left position for cropping. 403 // Will be snapped to even values. 404 int crop_width, crop_height; // dimension of the cropping area 405 int use_scaling; // if true, scaling is applied _afterward_ 406 int scaled_width, scaled_height; // final resolution 407 int use_threads; // if true, use multi-threaded decoding 408 409 // Unused for now: 410 int force_rotation; // forced rotation (to be applied _last_) 411 int no_enhancement; // if true, discard enhancement layer 412 uint32_t pad[6]; // padding for later use 413} WebPDecoderOptions; 414 415// Main object storing the configuration for advanced decoding. 416typedef struct { 417 WebPBitstreamFeatures input; // Immutable bitstream features (optional) 418 WebPDecBuffer output; // Output buffer (can point to external mem) 419 WebPDecoderOptions options; // Decoding options 420} WebPDecoderConfig; 421 422// Internal, version-checked, entry point 423WEBP_EXTERN(int) WebPInitDecoderConfigInternal(WebPDecoderConfig*, int); 424 425// Initialize the configuration as empty. This function must always be 426// called first, unless WebPGetFeatures() is to be called. 427// Returns false in case of mismatched version. 428static WEBP_INLINE int WebPInitDecoderConfig(WebPDecoderConfig* config) { 429 return WebPInitDecoderConfigInternal(config, WEBP_DECODER_ABI_VERSION); 430} 431 432// Instantiate a new incremental decoder object with the requested 433// configuration. The bitstream can be passed using 'data' and 'data_size' 434// parameter, in which case the features will be parsed and stored into 435// config->input. Otherwise, 'data' can be NULL and no parsing will occur. 436// Note that 'config' can be NULL too, in which case a default configuration 437// is used. 438// The return WebPIDecoder object must always be deleted calling WebPIDelete(). 439// Returns NULL in case of error (and config->status will then reflect 440// the error condition). 441WEBP_EXTERN(WebPIDecoder*) WebPIDecode(const uint8_t* data, size_t data_size, 442 WebPDecoderConfig* config); 443 444// Non-incremental version. This version decodes the full data at once, taking 445// 'config' into account. Returns decoding status (which should be VP8_STATUS_OK 446// if the decoding was successful). 447WEBP_EXTERN(VP8StatusCode) WebPDecode(const uint8_t* data, size_t data_size, 448 WebPDecoderConfig* config); 449 450#if defined(__cplusplus) || defined(c_plusplus) 451} // extern "C" 452#endif 453 454#endif /* WEBP_WEBP_DECODE_H_ */ 455