1 // Copyright 2010 Google Inc. All Rights Reserved.
2 //
3 // Use of this source code is governed by a BSD-style license
4 // that can be found in the COPYING file in the root of the source
5 // tree. An additional intellectual property rights grant can be found
6 // in the file PATENTS. All contributing project authors may
7 // be found in the AUTHORS file in the root of the source tree.
8 // -----------------------------------------------------------------------------
9 //
10 // VP8 decoder: internal header.
11 //
12 // Author: Skal (pascal.massimino@gmail.com)
13 
14 #ifndef WEBP_DEC_VP8I_DEC_H_
15 #define WEBP_DEC_VP8I_DEC_H_
16 
17 #include <string.h>     // for memcpy()
18 #include "src/dec/common_dec.h"
19 #include "src/dec/vp8li_dec.h"
20 #include "src/utils/bit_reader_utils.h"
21 #include "src/utils/random_utils.h"
22 #include "src/utils/thread_utils.h"
23 #include "src/dsp/dsp.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 //------------------------------------------------------------------------------
30 // Various defines and enums
31 
32 // version numbers
33 #define DEC_MAJ_VERSION 1
34 #define DEC_MIN_VERSION 0
35 #define DEC_REV_VERSION 2
36 
37 // YUV-cache parameters. Cache is 32-bytes wide (= one cacheline).
38 // Constraints are: We need to store one 16x16 block of luma samples (y),
39 // and two 8x8 chroma blocks (u/v). These are better be 16-bytes aligned,
40 // in order to be SIMD-friendly. We also need to store the top, left and
41 // top-left samples (from previously decoded blocks), along with four
42 // extra top-right samples for luma (intra4x4 prediction only).
43 // One possible layout is, using 32 * (17 + 9) bytes:
44 //
45 //   .+------   <- only 1 pixel high
46 //   .|yyyyt.
47 //   .|yyyyt.
48 //   .|yyyyt.
49 //   .|yyyy..
50 //   .+--.+--   <- only 1 pixel high
51 //   .|uu.|vv
52 //   .|uu.|vv
53 //
54 // Every character is a 4x4 block, with legend:
55 //  '.' = unused
56 //  'y' = y-samples   'u' = u-samples     'v' = u-samples
57 //  '|' = left sample,   '-' = top sample,    '+' = top-left sample
58 //  't' = extra top-right sample for 4x4 modes
59 #define YUV_SIZE (BPS * 17 + BPS * 9)
60 #define Y_OFF    (BPS * 1 + 8)
61 #define U_OFF    (Y_OFF + BPS * 16 + BPS)
62 #define V_OFF    (U_OFF + 16)
63 
64 // minimal width under which lossy multi-threading is always disabled
65 #define MIN_WIDTH_FOR_THREADS 512
66 
67 //------------------------------------------------------------------------------
68 // Headers
69 
70 typedef struct {
71   uint8_t key_frame_;
72   uint8_t profile_;
73   uint8_t show_;
74   uint32_t partition_length_;
75 } VP8FrameHeader;
76 
77 typedef struct {
78   uint16_t width_;
79   uint16_t height_;
80   uint8_t xscale_;
81   uint8_t yscale_;
82   uint8_t colorspace_;   // 0 = YCbCr
83   uint8_t clamp_type_;
84 } VP8PictureHeader;
85 
86 // segment features
87 typedef struct {
88   int use_segment_;
89   int update_map_;        // whether to update the segment map or not
90   int absolute_delta_;    // absolute or delta values for quantizer and filter
91   int8_t quantizer_[NUM_MB_SEGMENTS];        // quantization changes
92   int8_t filter_strength_[NUM_MB_SEGMENTS];  // filter strength for segments
93 } VP8SegmentHeader;
94 
95 // probas associated to one of the contexts
96 typedef uint8_t VP8ProbaArray[NUM_PROBAS];
97 
98 typedef struct {   // all the probas associated to one band
99   VP8ProbaArray probas_[NUM_CTX];
100 } VP8BandProbas;
101 
102 // Struct collecting all frame-persistent probabilities.
103 typedef struct {
104   uint8_t segments_[MB_FEATURE_TREE_PROBS];
105   // Type: 0:Intra16-AC  1:Intra16-DC   2:Chroma   3:Intra4
106   VP8BandProbas bands_[NUM_TYPES][NUM_BANDS];
107   const VP8BandProbas* bands_ptr_[NUM_TYPES][16 + 1];
108 } VP8Proba;
109 
110 // Filter parameters
111 typedef struct {
112   int simple_;                  // 0=complex, 1=simple
113   int level_;                   // [0..63]
114   int sharpness_;               // [0..7]
115   int use_lf_delta_;
116   int ref_lf_delta_[NUM_REF_LF_DELTAS];
117   int mode_lf_delta_[NUM_MODE_LF_DELTAS];
118 } VP8FilterHeader;
119 
120 //------------------------------------------------------------------------------
121 // Informations about the macroblocks.
122 
123 typedef struct {  // filter specs
124   uint8_t f_limit_;      // filter limit in [3..189], or 0 if no filtering
125   uint8_t f_ilevel_;     // inner limit in [1..63]
126   uint8_t f_inner_;      // do inner filtering?
127   uint8_t hev_thresh_;   // high edge variance threshold in [0..2]
128 } VP8FInfo;
129 
130 typedef struct {  // Top/Left Contexts used for syntax-parsing
131   uint8_t nz_;        // non-zero AC/DC coeffs (4bit for luma + 4bit for chroma)
132   uint8_t nz_dc_;     // non-zero DC coeff (1bit)
133 } VP8MB;
134 
135 // Dequantization matrices
136 typedef int quant_t[2];      // [DC / AC].  Can be 'uint16_t[2]' too (~slower).
137 typedef struct {
138   quant_t y1_mat_, y2_mat_, uv_mat_;
139 
140   int uv_quant_;   // U/V quantizer value
141   int dither_;     // dithering amplitude (0 = off, max=255)
142 } VP8QuantMatrix;
143 
144 // Data needed to reconstruct a macroblock
145 typedef struct {
146   int16_t coeffs_[384];   // 384 coeffs = (16+4+4) * 4*4
147   uint8_t is_i4x4_;       // true if intra4x4
148   uint8_t imodes_[16];    // one 16x16 mode (#0) or sixteen 4x4 modes
149   uint8_t uvmode_;        // chroma prediction mode
150   // bit-wise info about the content of each sub-4x4 blocks (in decoding order).
151   // Each of the 4x4 blocks for y/u/v is associated with a 2b code according to:
152   //   code=0 -> no coefficient
153   //   code=1 -> only DC
154   //   code=2 -> first three coefficients are non-zero
155   //   code=3 -> more than three coefficients are non-zero
156   // This allows to call specialized transform functions.
157   uint32_t non_zero_y_;
158   uint32_t non_zero_uv_;
159   uint8_t dither_;      // local dithering strength (deduced from non_zero_*)
160   uint8_t skip_;
161   uint8_t segment_;
162 } VP8MBData;
163 
164 // Persistent information needed by the parallel processing
165 typedef struct {
166   int id_;              // cache row to process (in [0..2])
167   int mb_y_;            // macroblock position of the row
168   int filter_row_;      // true if row-filtering is needed
169   VP8FInfo* f_info_;    // filter strengths (swapped with dec->f_info_)
170   VP8MBData* mb_data_;  // reconstruction data (swapped with dec->mb_data_)
171   VP8Io io_;            // copy of the VP8Io to pass to put()
172 } VP8ThreadContext;
173 
174 // Saved top samples, per macroblock. Fits into a cache-line.
175 typedef struct {
176   uint8_t y[16], u[8], v[8];
177 } VP8TopSamples;
178 
179 //------------------------------------------------------------------------------
180 // VP8Decoder: the main opaque structure handed over to user
181 
182 struct VP8Decoder {
183   VP8StatusCode status_;
184   int ready_;     // true if ready to decode a picture with VP8Decode()
185   const char* error_msg_;  // set when status_ is not OK.
186 
187   // Main data source
188   VP8BitReader br_;
189 
190   // headers
191   VP8FrameHeader   frm_hdr_;
192   VP8PictureHeader pic_hdr_;
193   VP8FilterHeader  filter_hdr_;
194   VP8SegmentHeader segment_hdr_;
195 
196   // Worker
197   WebPWorker worker_;
198   int mt_method_;      // multi-thread method: 0=off, 1=[parse+recon][filter]
199                        // 2=[parse][recon+filter]
200   int cache_id_;       // current cache row
201   int num_caches_;     // number of cached rows of 16 pixels (1, 2 or 3)
202   VP8ThreadContext thread_ctx_;  // Thread context
203 
204   // dimension, in macroblock units.
205   int mb_w_, mb_h_;
206 
207   // Macroblock to process/filter, depending on cropping and filter_type.
208   int tl_mb_x_, tl_mb_y_;  // top-left MB that must be in-loop filtered
209   int br_mb_x_, br_mb_y_;  // last bottom-right MB that must be decoded
210 
211   // number of partitions minus one.
212   uint32_t num_parts_minus_one_;
213   // per-partition boolean decoders.
214   VP8BitReader parts_[MAX_NUM_PARTITIONS];
215 
216   // Dithering strength, deduced from decoding options
217   int dither_;                // whether to use dithering or not
218   VP8Random dithering_rg_;    // random generator for dithering
219 
220   // dequantization (one set of DC/AC dequant factor per segment)
221   VP8QuantMatrix dqm_[NUM_MB_SEGMENTS];
222 
223   // probabilities
224   VP8Proba proba_;
225   int use_skip_proba_;
226   uint8_t skip_p_;
227 
228   // Boundary data cache and persistent buffers.
229   uint8_t* intra_t_;      // top intra modes values: 4 * mb_w_
230   uint8_t  intra_l_[4];   // left intra modes values
231 
232   VP8TopSamples* yuv_t_;  // top y/u/v samples
233 
234   VP8MB* mb_info_;        // contextual macroblock info (mb_w_ + 1)
235   VP8FInfo* f_info_;      // filter strength info
236   uint8_t* yuv_b_;        // main block for Y/U/V (size = YUV_SIZE)
237 
238   uint8_t* cache_y_;      // macroblock row for storing unfiltered samples
239   uint8_t* cache_u_;
240   uint8_t* cache_v_;
241   int cache_y_stride_;
242   int cache_uv_stride_;
243 
244   // main memory chunk for the above data. Persistent.
245   void* mem_;
246   size_t mem_size_;
247 
248   // Per macroblock non-persistent infos.
249   int mb_x_, mb_y_;       // current position, in macroblock units
250   VP8MBData* mb_data_;    // parsed reconstruction data
251 
252   // Filtering side-info
253   int filter_type_;                          // 0=off, 1=simple, 2=complex
254   VP8FInfo fstrengths_[NUM_MB_SEGMENTS][2];  // precalculated per-segment/type
255 
256   // Alpha
257   struct ALPHDecoder* alph_dec_;  // alpha-plane decoder object
258   const uint8_t* alpha_data_;     // compressed alpha data (if present)
259   size_t alpha_data_size_;
260   int is_alpha_decoded_;      // true if alpha_data_ is decoded in alpha_plane_
261   uint8_t* alpha_plane_mem_;  // memory allocated for alpha_plane_
262   uint8_t* alpha_plane_;      // output. Persistent, contains the whole data.
263   const uint8_t* alpha_prev_line_;  // last decoded alpha row (or NULL)
264   int alpha_dithering_;       // derived from decoding options (0=off, 100=full)
265 };
266 
267 //------------------------------------------------------------------------------
268 // internal functions. Not public.
269 
270 // in vp8.c
271 int VP8SetError(VP8Decoder* const dec,
272                 VP8StatusCode error, const char* const msg);
273 
274 // in tree.c
275 void VP8ResetProba(VP8Proba* const proba);
276 void VP8ParseProba(VP8BitReader* const br, VP8Decoder* const dec);
277 // parses one row of intra mode data in partition 0, returns !eof
278 int VP8ParseIntraModeRow(VP8BitReader* const br, VP8Decoder* const dec);
279 
280 // in quant.c
281 void VP8ParseQuant(VP8Decoder* const dec);
282 
283 // in frame.c
284 int VP8InitFrame(VP8Decoder* const dec, VP8Io* const io);
285 // Call io->setup() and finish setting up scan parameters.
286 // After this call returns, one must always call VP8ExitCritical() with the
287 // same parameters. Both functions should be used in pair. Returns VP8_STATUS_OK
288 // if ok, otherwise sets and returns the error status on *dec.
289 VP8StatusCode VP8EnterCritical(VP8Decoder* const dec, VP8Io* const io);
290 // Must always be called in pair with VP8EnterCritical().
291 // Returns false in case of error.
292 int VP8ExitCritical(VP8Decoder* const dec, VP8Io* const io);
293 // Return the multi-threading method to use (0=off), depending
294 // on options and bitstream size. Only for lossy decoding.
295 int VP8GetThreadMethod(const WebPDecoderOptions* const options,
296                        const WebPHeaderStructure* const headers,
297                        int width, int height);
298 // Initialize dithering post-process if needed.
299 void VP8InitDithering(const WebPDecoderOptions* const options,
300                       VP8Decoder* const dec);
301 // Process the last decoded row (filtering + output).
302 int VP8ProcessRow(VP8Decoder* const dec, VP8Io* const io);
303 // To be called at the start of a new scanline, to initialize predictors.
304 void VP8InitScanline(VP8Decoder* const dec);
305 // Decode one macroblock. Returns false if there is not enough data.
306 int VP8DecodeMB(VP8Decoder* const dec, VP8BitReader* const token_br);
307 
308 // in alpha.c
309 const uint8_t* VP8DecompressAlphaRows(VP8Decoder* const dec,
310                                       const VP8Io* const io,
311                                       int row, int num_rows);
312 
313 //------------------------------------------------------------------------------
314 
315 #ifdef __cplusplus
316 }    // extern "C"
317 #endif
318 
319 #endif  // WEBP_DEC_VP8I_DEC_H_
320