Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/webp/decode.h @ 69:33d812a61356

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