add some padding bytes areas for later use

so we can add few fields without breaking ABI

+ re-order fields
+ refresh the doc

Change-Id: Id60ec33934f6346e35c95fcdb4abbe1bc7b50acb
This commit is contained in:
Pascal Massimino 2012-07-18 00:44:27 +00:00 committed by James Zern
parent d03b250369
commit 90516ae8f5
3 changed files with 86 additions and 46 deletions

View File

@ -173,6 +173,8 @@ typedef struct {
WebPRGBABuffer RGBA; WebPRGBABuffer RGBA;
WebPYUVABuffer YUVA; WebPYUVABuffer YUVA;
} u; // Nameless union of buffer parameters. } u; // Nameless union of buffer parameters.
uint32_t pad[4]; // padding for later use
uint8_t* private_memory; // Internally allocated memory (only when uint8_t* private_memory; // Internally allocated memory (only when
// is_external_memory is false). Should not be used // is_external_memory is false). Should not be used
// externally, but accessed via the buffer union. // externally, but accessed via the buffer union.
@ -341,14 +343,17 @@ WEBP_EXTERN(const WebPDecBuffer*) WebPIDecodedArea(
// Features gathered from the bitstream // Features gathered from the bitstream
typedef struct { typedef struct {
int width; // the original width, as read from the bitstream int width; // Width in pixels, as read from the bitstream.
int height; // the original height, as read from the bitstream int height; // Height in pixels, as read from the bitstream.
int has_alpha; // true if bitstream contains an alpha channel int has_alpha; // True if the bitstream contains an alpha channel.
// Unused for now:
int bitstream_version; // should be 0 for now. TODO(later)
int no_incremental_decoding; // if true, using incremental decoding is not int no_incremental_decoding; // if true, using incremental decoding is not
// recommended. // recommended.
int rotate; // TODO(later) int rotate; // TODO(later)
int uv_sampling; // should be 0 for now. TODO(later) int uv_sampling; // should be 0 for now. TODO(later)
int bitstream_version; // should be 0 for now. TODO(later) uint32_t pad[3]; // padding for later use
} WebPBitstreamFeatures; } WebPBitstreamFeatures;
// Internal, version-checked, entry point // Internal, version-checked, entry point
@ -379,6 +384,7 @@ typedef struct {
int force_rotation; // forced rotation (to be applied _last_) int force_rotation; // forced rotation (to be applied _last_)
int no_enhancement; // if true, discard enhancement layer int no_enhancement; // if true, discard enhancement layer
int use_threads; // if true, use multi-threaded decoding int use_threads; // if true, use multi-threaded decoding
uint32_t pad[6]; // padding for later use
} WebPDecoderOptions; } WebPDecoderOptions;
// Main object storing the configuration for advanced decoding. // Main object storing the configuration for advanced decoding.

View File

@ -73,37 +73,42 @@ typedef enum {
} WebPImageHint; } WebPImageHint;
typedef struct { typedef struct {
float quality; // between 0 (smallest file) and 100 (biggest) int lossless; // Lossless encoding (0=lossy(default), 1=lossless).
int target_size; // if non-zero, set the desired target size in bytes. float quality; // between 0 (smallest file) and 100 (biggest)
// Takes precedence over the 'compression' parameter. int method; // quality/speed trade-off (0=fast, 6=slower-better)
float target_PSNR; // if non-zero, specifies the minimal distortion to
// try to achieve. Takes precedence over target_size.
int method; // quality/speed trade-off (0=fast, 6=slower-better)
int segments; // maximum number of segments to use, in [1..4]
int sns_strength; // Spatial Noise Shaping. 0=off, 100=maximum.
int filter_strength; // range: [0 = off .. 100 = strongest]
int filter_sharpness; // range: [0 = off .. 7 = least sharp]
int filter_type; // filtering type: 0 = simple, 1 = strong
// (only used if filter_strength > 0 or autofilter > 0)
int autofilter; // Auto adjust filter's strength [0 = off, 1 = on]
int pass; // number of entropy-analysis passes (in [1..10]).
int show_compressed; // if true, export the compressed picture back. WebPImageHint image_hint; // Hint for image type (lossless only for now).
// In-loop filtering is not applied.
int preprocessing; // preprocessing filter (0=none, 1=segment-smooth) // Parameters related to lossy compression only:
int partitions; // log2(number of token partitions) in [0..3] int target_size; // if non-zero, set the desired target size in bytes.
// Default is set to 0 for easier progressive decoding. // Takes precedence over the 'compression' parameter.
int partition_limit; // quality degradation allowed to fit the 512k limit on float target_PSNR; // if non-zero, specifies the minimal distortion to
// prediction modes coding (0=no degradation, 100=full) // try to achieve. Takes precedence over target_size.
int segments; // maximum number of segments to use, in [1..4]
int sns_strength; // Spatial Noise Shaping. 0=off, 100=maximum.
int filter_strength; // range: [0 = off .. 100 = strongest]
int filter_sharpness; // range: [0 = off .. 7 = least sharp]
int filter_type; // filtering type: 0 = simple, 1 = strong (only used
// if filter_strength > 0 or autofilter > 0)
int autofilter; // Auto adjust filter's strength [0 = off, 1 = on]
int alpha_compression; // Algorithm for encoding the alpha plane (0 = none, int alpha_compression; // Algorithm for encoding the alpha plane (0 = none,
// 1 = backward reference counts encoded with // 1 = compressed with WebP lossless). Default is 1.
// arithmetic encoder). Default is 1.
int alpha_filtering; // Predictive filtering method for alpha plane. int alpha_filtering; // Predictive filtering method for alpha plane.
// 0: none, 1: fast, 2: best. Default if 1. // 0: none, 1: fast, 2: best. Default if 1.
int alpha_quality; // Between 0 (smallest size) and 100 (lossless). int alpha_quality; // Between 0 (smallest size) and 100 (lossless).
// Default is 100. // Default is 100.
int lossless; // Lossless encoding (0=lossy(default), 1=lossless). int pass; // number of entropy-analysis passes (in [1..10]).
WebPImageHint image_hint; // Hint for image type.
int show_compressed; // if true, export the compressed picture back.
// In-loop filtering is not applied.
int preprocessing; // preprocessing filter (0=none, 1=segment-smooth)
int partitions; // log2(number of token partitions) in [0..3]. Default
// is set to 0 for easier progressive decoding.
int partition_limit; // quality degradation allowed to fit the 512k limit
// on prediction modes coding (0: no degradation,
// 100: maximum possible degradation).
uint32_t pad[8]; // padding for later use
} WebPConfig; } WebPConfig;
// Enumerate some predefined settings for WebPConfig, depending on the type // Enumerate some predefined settings for WebPConfig, depending on the type
@ -147,10 +152,11 @@ WEBP_EXTERN(int) WebPValidateConfig(const WebPConfig* config);
typedef struct WebPPicture WebPPicture; // main structure for I/O typedef struct WebPPicture WebPPicture; // main structure for I/O
// non-essential structure for storing auxiliary statistics // Structure for storing auxiliary statistics (mostly for lossy encoding).
typedef struct { typedef struct {
float PSNR[4]; // peak-signal-to-noise ratio for Y/U/V/All
int coded_size; // final size int coded_size; // final size
float PSNR[4]; // peak-signal-to-noise ratio for Y/U/V/All
int block_count[3]; // number of intra4/intra16/skipped macroblocks int block_count[3]; // number of intra4/intra16/skipped macroblocks
int header_bytes[2]; // approximate number of bytes spent for header int header_bytes[2]; // approximate number of bytes spent for header
// and mode-partition #0 // and mode-partition #0
@ -165,6 +171,8 @@ typedef struct {
void* user_data; // this field is free to be set to any value and void* user_data; // this field is free to be set to any value and
// used during callbacks (like progress-report e.g.). // used during callbacks (like progress-report e.g.).
uint32_t pad[6]; // padding for later use
} WebPAuxStats; } WebPAuxStats;
// Signature for output function. Should return true if writing was successful. // Signature for output function. Should return true if writing was successful.
@ -179,6 +187,7 @@ typedef struct {
uint8_t* mem; // final buffer (of size 'max_size', larger than 'size'). uint8_t* mem; // final buffer (of size 'max_size', larger than 'size').
size_t size; // final size size_t size; // final size
size_t max_size; // total capacity size_t max_size; // total capacity
uint32_t pad[1]; // padding for later use
} WebPMemoryWriter; } WebPMemoryWriter;
// The following must be called first before any use. // The following must be called first before any use.
@ -228,20 +237,38 @@ typedef enum {
// maximum width/height allowed (inclusive), in pixels // maximum width/height allowed (inclusive), in pixels
#define WEBP_MAX_DIMENSION 16383 #define WEBP_MAX_DIMENSION 16383
// Main exchange structure (input samples, output bytes, statistics)
struct WebPPicture { struct WebPPicture {
// input
// INPUT
//////////////
// Main flag for encoder selecting between ARGB or YUV input.
// It is recommended to use ARGB input (*argb, argb_stride) for lossless
// compression, and YUV input (*y, *u, *v, etc.) for lossy compression
// since these are the respective native colorspace for these formats.
int use_argb_input;
// YUV input (mostly used for input to lossy compression)
WebPEncCSP colorspace; // colorspace: should be YUV420 for now (=Y'CbCr). WebPEncCSP colorspace; // colorspace: should be YUV420 for now (=Y'CbCr).
int width, height; // dimensions (less or equal to WEBP_MAX_DIMENSION) int width, height; // dimensions (less or equal to WEBP_MAX_DIMENSION)
uint8_t *y, *u, *v; // pointers to luma/chroma planes. uint8_t *y, *u, *v; // pointers to luma/chroma planes.
int y_stride, uv_stride; // luma/chroma strides. int y_stride, uv_stride; // luma/chroma strides.
uint8_t* a; // pointer to the alpha plane uint8_t* a; // pointer to the alpha plane
int a_stride; // stride of the alpha plane int a_stride; // stride of the alpha plane
uint32_t pad1[2]; // padding for later use
// output // ARGB input (mostly used for input to lossless compression)
uint32_t* argb; // Pointer to argb (32 bit) plane.
int argb_stride; // This is stride in pixels units, not bytes.
uint32_t pad2[3]; // padding for later use
// OUTPUT
///////////////
// Byte-emission hook, to store compressed bytes as they are ready.
WebPWriterFunction writer; // can be NULL WebPWriterFunction writer; // can be NULL
void* custom_ptr; // can be used by the writer. void* custom_ptr; // can be used by the writer.
// map for extra information // map for extra information (only for lossy compression mode)
int extra_info_type; // 1: intra type, 2: segment, 3: quant int extra_info_type; // 1: intra type, 2: segment, 3: quant
// 4: intra-16 prediction mode, // 4: intra-16 prediction mode,
// 5: chroma prediction mode, // 5: chroma prediction mode,
@ -251,24 +278,30 @@ struct WebPPicture {
// will be filled with a macroblock map, depending // will be filled with a macroblock map, depending
// on extra_info_type. // on extra_info_type.
// where to store statistics, if not NULL: // STATS AND REPORTS
///////////////////////////
// Pointer to side statistics (updated only if not NULL)
WebPAuxStats* stats; WebPAuxStats* stats;
// original samples (for non-YUV420 modes) // Error code for the latest error encountered during encoding
WebPEncodingError error_code;
// If not NULL, report progress during encoding.
WebPProgressHook progress_hook;
uint32_t pad3[3]; // padding for later use
// Unused for now: original samples (for non-YUV420 modes)
uint8_t *u0, *v0; uint8_t *u0, *v0;
int uv0_stride; int uv0_stride;
WebPEncodingError error_code; // error code in case of problem. uint32_t pad4[7]; // padding for later use
WebPProgressHook progress_hook; // if not NULL, called while encoding. // PRIVATE FIELDS
////////////////////
int use_argb_input; // Flag for encoder to use argb pixels as input.
uint32_t* argb; // Pointer to argb (32 bit) plane.
int argb_stride; // This is stride in pixels units, not bytes.
// private fields:
void* memory_; // row chunk of memory for yuva planes void* memory_; // row chunk of memory for yuva planes
void* memory_argb_; // and for argb too. void* memory_argb_; // and for argb too.
void* pad5[2]; // padding for later use
}; };
// Internal, version-checked, entry point // Internal, version-checked, entry point

View File

@ -527,6 +527,7 @@ typedef struct {
// still be decoded with the WebP incremental decoder. // still be decoded with the WebP incremental decoder.
WebPData tile_; // The frame or tile given by 'frame_num_' and 'tile_num_'. WebPData tile_; // The frame or tile given by 'frame_num_' and 'tile_num_'.
uint32_t pad[4]; // padding for later use
void* private_; void* private_;
} WebPIterator; } WebPIterator;
@ -563,9 +564,9 @@ typedef struct {
// WebPDemuxGetChunk(). // WebPDemuxGetChunk().
int chunk_num_; int chunk_num_;
int num_chunks_; int num_chunks_;
// The payload of the chunk. WebPData chunk_; // The payload of the chunk.
WebPData chunk_;
uint32_t pad[6]; // padding for later use
void* private_; void* private_;
} WebPChunkIterator; } WebPChunkIterator;