get_bits: whitespace (mostly) cosmetics
[libav.git] / libavcodec / get_bits.h
1 /*
2 * copyright (c) 2004 Michael Niedermayer <michaelni@gmx.at>
3 *
4 * This file is part of Libav.
5 *
6 * Libav is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * Libav is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with Libav; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21 /**
22 * @file
23 * bitstream reader API header.
24 */
25
26 #ifndef AVCODEC_GET_BITS_H
27 #define AVCODEC_GET_BITS_H
28
29 #include <stdint.h>
30 #include "libavutil/common.h"
31 #include "libavutil/intreadwrite.h"
32 #include "libavutil/log.h"
33 #include "mathops.h"
34
35 /*
36 * Safe bitstream reading:
37 * optionally, the get_bits API can check to ensure that we
38 * don't read past input buffer boundaries. This is protected
39 * with CONFIG_SAFE_BITSTREAM_READER at the global level, and
40 * then below that with UNCHECKED_BITSTREAM_READER at the per-
41 * decoder level. This means that decoders that check internally
42 * can "#define UNCHECKED_BITSTREAM_READER 1" to disable
43 * overread checks.
44 * Boundary checking causes a minor performance penalty so for
45 * applications that won't want/need this, it can be disabled
46 * globally using "#define CONFIG_SAFE_BITSTREAM_READER 0".
47 */
48 #ifndef UNCHECKED_BITSTREAM_READER
49 #define UNCHECKED_BITSTREAM_READER !CONFIG_SAFE_BITSTREAM_READER
50 #endif
51
52 /* bit input */
53 /* buffer, buffer_end and size_in_bits must be present and used by every reader */
54 typedef struct GetBitContext {
55 const uint8_t *buffer, *buffer_end;
56 int index;
57 int size_in_bits;
58 #if !UNCHECKED_BITSTREAM_READER
59 int size_in_bits_plus8;
60 #endif
61 } GetBitContext;
62
63 #define VLC_TYPE int16_t
64
65 typedef struct VLC {
66 int bits;
67 VLC_TYPE (*table)[2]; ///< code, bits
68 int table_size, table_allocated;
69 } VLC;
70
71 typedef struct RL_VLC_ELEM {
72 int16_t level;
73 int8_t len;
74 uint8_t run;
75 } RL_VLC_ELEM;
76
77 /* Bitstream reader API docs:
78 name
79 arbitrary name which is used as prefix for the internal variables
80
81 gb
82 getbitcontext
83
84 OPEN_READER(name, gb)
85 load gb into local variables
86
87 CLOSE_READER(name, gb)
88 store local vars in gb
89
90 UPDATE_CACHE(name, gb)
91 refill the internal cache from the bitstream
92 after this call at least MIN_CACHE_BITS will be available,
93
94 GET_CACHE(name, gb)
95 will output the contents of the internal cache, next bit is MSB of 32 or 64 bit (FIXME 64bit)
96
97 SHOW_UBITS(name, gb, num)
98 will return the next num bits
99
100 SHOW_SBITS(name, gb, num)
101 will return the next num bits and do sign extension
102
103 SKIP_BITS(name, gb, num)
104 will skip over the next num bits
105 note, this is equivalent to SKIP_CACHE; SKIP_COUNTER
106
107 SKIP_CACHE(name, gb, num)
108 will remove the next num bits from the cache (note SKIP_COUNTER MUST be called before UPDATE_CACHE / CLOSE_READER)
109
110 SKIP_COUNTER(name, gb, num)
111 will increment the internal bit counter (see SKIP_CACHE & SKIP_BITS)
112
113 LAST_SKIP_CACHE(name, gb, num)
114 will remove the next num bits from the cache if it is needed for UPDATE_CACHE otherwise it will do nothing
115
116 LAST_SKIP_BITS(name, gb, num)
117 is equivalent to LAST_SKIP_CACHE; SKIP_COUNTER
118
119 for examples see get_bits, show_bits, skip_bits, get_vlc
120 */
121
122 #ifdef LONG_BITSTREAM_READER
123 # define MIN_CACHE_BITS 32
124 #else
125 # define MIN_CACHE_BITS 25
126 #endif
127
128 #define OPEN_READER(name, gb) \
129 unsigned int name##_index = (gb)->index; \
130 unsigned int av_unused name##_cache = 0
131
132 #define CLOSE_READER(name, gb) (gb)->index = name##_index
133
134 #ifdef ALT_BITSTREAM_READER_LE
135
136 # ifdef LONG_BITSTREAM_READER
137 # define UPDATE_CACHE(name, gb) name##_cache = \
138 AV_RL64((gb)->buffer + (name##_index >> 3)) >> (name##_index & 7)
139 # else
140 # define UPDATE_CACHE(name, gb) name##_cache = \
141 AV_RL32((gb)->buffer + (name##_index >> 3)) >> (name##_index & 7)
142 # endif
143
144 # define SKIP_CACHE(name, gb, num) name##_cache >>= (num)
145
146 #else
147
148 # ifdef LONG_BITSTREAM_READER
149 # define UPDATE_CACHE(name, gb) name##_cache = \
150 AV_RB64((gb)->buffer + (name##_index >> 3)) >> (32 - (name##_index & 7))
151 # else
152 # define UPDATE_CACHE(name, gb) name##_cache = \
153 AV_RB32((gb)->buffer + (name##_index >> 3)) << (name##_index & 7)
154 # endif
155
156 # define SKIP_CACHE(name, gb, num) name##_cache <<= (num)
157
158 #endif
159
160 // FIXME name?
161 #if UNCHECKED_BITSTREAM_READER
162 # define SKIP_COUNTER(name, gb, num) name##_index += (num)
163 #else
164 # define SKIP_COUNTER(name, gb, num) \
165 name##_index = FFMIN((gb)->size_in_bits_plus8, name##_index + (num))
166 #endif
167
168 #define SKIP_BITS(name, gb, num) do { \
169 SKIP_CACHE(name, gb, num); \
170 SKIP_COUNTER(name, gb, num); \
171 } while (0)
172
173 #define LAST_SKIP_BITS(name, gb, num) SKIP_COUNTER(name, gb, num)
174 #define LAST_SKIP_CACHE(name, gb, num)
175
176 #ifdef ALT_BITSTREAM_READER_LE
177 # define SHOW_UBITS(name, gb, num) zero_extend(name##_cache, num)
178 # define SHOW_SBITS(name, gb, num) sign_extend(name##_cache, num)
179 #else
180 # define SHOW_UBITS(name, gb, num) NEG_USR32(name##_cache, num)
181 # define SHOW_SBITS(name, gb, num) NEG_SSR32(name##_cache, num)
182 #endif
183
184 #define GET_CACHE(name, gb) ((uint32_t)name##_cache)
185
186 static inline int get_bits_count(const GetBitContext *s)
187 {
188 return s->index;
189 }
190
191 static inline void skip_bits_long(GetBitContext *s, int n){
192 #if UNCHECKED_BITSTREAM_READER
193 s->index += n;
194 #else
195 s->index += av_clip(n, -s->index, s->size_in_bits_plus8 - s->index);
196 #endif
197 }
198
199 /**
200 * read mpeg1 dc style vlc (sign bit + mantisse with no MSB).
201 * if MSB not set it is negative
202 * @param n length in bits
203 * @author BERO
204 */
205 static inline int get_xbits(GetBitContext *s, int n)
206 {
207 register int sign;
208 register int32_t cache;
209 OPEN_READER(re, s);
210 UPDATE_CACHE(re, s);
211 cache = GET_CACHE(re, s);
212 sign = ~cache >> 31;
213 LAST_SKIP_BITS(re, s, n);
214 CLOSE_READER(re, s);
215 return (NEG_USR32(sign ^ cache, n) ^ sign) - sign;
216 }
217
218 static inline int get_sbits(GetBitContext *s, int n)
219 {
220 register int tmp;
221 OPEN_READER(re, s);
222 UPDATE_CACHE(re, s);
223 tmp = SHOW_SBITS(re, s, n);
224 LAST_SKIP_BITS(re, s, n);
225 CLOSE_READER(re, s);
226 return tmp;
227 }
228
229 /**
230 * Read 1-25 bits.
231 */
232 static inline unsigned int get_bits(GetBitContext *s, int n)
233 {
234 register int tmp;
235 OPEN_READER(re, s);
236 UPDATE_CACHE(re, s);
237 tmp = SHOW_UBITS(re, s, n);
238 LAST_SKIP_BITS(re, s, n);
239 CLOSE_READER(re, s);
240 return tmp;
241 }
242
243 /**
244 * Show 1-25 bits.
245 */
246 static inline unsigned int show_bits(GetBitContext *s, int n)
247 {
248 register int tmp;
249 OPEN_READER(re, s);
250 UPDATE_CACHE(re, s);
251 tmp = SHOW_UBITS(re, s, n);
252 return tmp;
253 }
254
255 static inline void skip_bits(GetBitContext *s, int n)
256 {
257 //Note gcc seems to optimize this to s->index+=n for the ALT_READER :))
258 OPEN_READER(re, s);
259 UPDATE_CACHE(re, s);
260 LAST_SKIP_BITS(re, s, n);
261 CLOSE_READER(re, s);
262 }
263
264 static inline unsigned int get_bits1(GetBitContext *s)
265 {
266 unsigned int index = s->index;
267 uint8_t result = s->buffer[index>>3];
268 #ifdef ALT_BITSTREAM_READER_LE
269 result >>= index & 7;
270 result &= 1;
271 #else
272 result <<= index & 7;
273 result >>= 8 - 1;
274 #endif
275 #if !UNCHECKED_BITSTREAM_READER
276 if (s->index < s->size_in_bits_plus8)
277 #endif
278 index++;
279 s->index = index;
280
281 return result;
282 }
283
284 static inline unsigned int show_bits1(GetBitContext *s)
285 {
286 return show_bits(s, 1);
287 }
288
289 static inline void skip_bits1(GetBitContext *s)
290 {
291 skip_bits(s, 1);
292 }
293
294 /**
295 * Read 0-32 bits.
296 */
297 static inline unsigned int get_bits_long(GetBitContext *s, int n)
298 {
299 if (n <= MIN_CACHE_BITS)
300 return get_bits(s, n);
301 else {
302 #ifdef ALT_BITSTREAM_READER_LE
303 int ret = get_bits(s, 16);
304 return ret | (get_bits(s, n-16) << 16);
305 #else
306 int ret = get_bits(s, 16) << (n-16);
307 return ret | get_bits(s, n-16);
308 #endif
309 }
310 }
311
312 /**
313 * Read 0-32 bits as a signed integer.
314 */
315 static inline int get_sbits_long(GetBitContext *s, int n)
316 {
317 return sign_extend(get_bits_long(s, n), n);
318 }
319
320 /**
321 * Show 0-32 bits.
322 */
323 static inline unsigned int show_bits_long(GetBitContext *s, int n)
324 {
325 if (n <= MIN_CACHE_BITS)
326 return show_bits(s, n);
327 else {
328 GetBitContext gb = *s;
329 return get_bits_long(&gb, n);
330 }
331 }
332
333 static inline int check_marker(GetBitContext *s, const char *msg)
334 {
335 int bit = get_bits1(s);
336 if (!bit)
337 av_log(NULL, AV_LOG_INFO, "Marker bit missing %s\n", msg);
338
339 return bit;
340 }
341
342 /**
343 * Inititalize GetBitContext.
344 * @param buffer bitstream buffer, must be FF_INPUT_BUFFER_PADDING_SIZE bytes larger than the actual read bits
345 * because some optimized bitstream readers read 32 or 64 bit at once and could read over the end
346 * @param bit_size the size of the buffer in bits
347 *
348 * While GetBitContext stores the buffer size, for performance reasons you are
349 * responsible for checking for the buffer end yourself (take advantage of the padding)!
350 */
351 static inline void init_get_bits(GetBitContext *s, const uint8_t *buffer,
352 int bit_size)
353 {
354 int buffer_size = (bit_size+7)>>3;
355 if (buffer_size < 0 || bit_size < 0) {
356 buffer_size = bit_size = 0;
357 buffer = NULL;
358 }
359
360 s->buffer = buffer;
361 s->size_in_bits = bit_size;
362 #if !UNCHECKED_BITSTREAM_READER
363 s->size_in_bits_plus8 = bit_size + 8;
364 #endif
365 s->buffer_end = buffer + buffer_size;
366 s->index = 0;
367 }
368
369 static inline void align_get_bits(GetBitContext *s)
370 {
371 int n = -get_bits_count(s) & 7;
372 if (n) skip_bits(s, n);
373 }
374
375 #define init_vlc(vlc, nb_bits, nb_codes, \
376 bits, bits_wrap, bits_size, \
377 codes, codes_wrap, codes_size, \
378 flags) \
379 init_vlc_sparse(vlc, nb_bits, nb_codes, \
380 bits, bits_wrap, bits_size, \
381 codes, codes_wrap, codes_size, \
382 NULL, 0, 0, flags)
383
384 int init_vlc_sparse(VLC *vlc, int nb_bits, int nb_codes,
385 const void *bits, int bits_wrap, int bits_size,
386 const void *codes, int codes_wrap, int codes_size,
387 const void *symbols, int symbols_wrap, int symbols_size,
388 int flags);
389 #define INIT_VLC_LE 2
390 #define INIT_VLC_USE_NEW_STATIC 4
391 void free_vlc(VLC *vlc);
392
393 #define INIT_VLC_STATIC(vlc, bits, a,b,c,d,e,f,g, static_size) do { \
394 static VLC_TYPE table[static_size][2]; \
395 (vlc)->table = table; \
396 (vlc)->table_allocated = static_size; \
397 init_vlc(vlc, bits, a,b,c,d,e,f,g, INIT_VLC_USE_NEW_STATIC); \
398 } while (0)
399
400
401 /**
402 * If the vlc code is invalid and max_depth=1, then no bits will be removed.
403 * If the vlc code is invalid and max_depth>1, then the number of bits removed
404 * is undefined.
405 */
406 #define GET_VLC(code, name, gb, table, bits, max_depth) \
407 do { \
408 int n, nb_bits; \
409 unsigned int index; \
410 \
411 index = SHOW_UBITS(name, gb, bits); \
412 code = table[index][0]; \
413 n = table[index][1]; \
414 \
415 if (max_depth > 1 && n < 0) { \
416 LAST_SKIP_BITS(name, gb, bits); \
417 UPDATE_CACHE(name, gb); \
418 \
419 nb_bits = -n; \
420 \
421 index = SHOW_UBITS(name, gb, nb_bits) + code; \
422 code = table[index][0]; \
423 n = table[index][1]; \
424 if (max_depth > 2 && n < 0) { \
425 LAST_SKIP_BITS(name, gb, nb_bits); \
426 UPDATE_CACHE(name, gb); \
427 \
428 nb_bits = -n; \
429 \
430 index = SHOW_UBITS(name, gb, nb_bits) + code; \
431 code = table[index][0]; \
432 n = table[index][1]; \
433 } \
434 } \
435 SKIP_BITS(name, gb, n); \
436 } while (0)
437
438 #define GET_RL_VLC(level, run, name, gb, table, bits, max_depth, need_update) \
439 do { \
440 int n, nb_bits; \
441 unsigned int index; \
442 \
443 index = SHOW_UBITS(name, gb, bits); \
444 level = table[index].level; \
445 n = table[index].len; \
446 \
447 if (max_depth > 1 && n < 0) { \
448 SKIP_BITS(name, gb, bits); \
449 if (need_update) { \
450 UPDATE_CACHE(name, gb); \
451 } \
452 \
453 nb_bits = -n; \
454 \
455 index = SHOW_UBITS(name, gb, nb_bits) + level; \
456 level = table[index].level; \
457 n = table[index].len; \
458 } \
459 run = table[index].run; \
460 SKIP_BITS(name, gb, n); \
461 } while (0)
462
463
464 /**
465 * Parse a vlc code, faster than get_vlc().
466 * @param bits is the number of bits which will be read at once, must be
467 * identical to nb_bits in init_vlc()
468 * @param max_depth is the number of times bits bits must be read to completely
469 * read the longest vlc code
470 * = (max_vlc_length + bits - 1) / bits
471 */
472 static av_always_inline int get_vlc2(GetBitContext *s, VLC_TYPE (*table)[2],
473 int bits, int max_depth)
474 {
475 int code;
476
477 OPEN_READER(re, s);
478 UPDATE_CACHE(re, s);
479
480 GET_VLC(code, re, s, table, bits, max_depth);
481
482 CLOSE_READER(re, s);
483 return code;
484 }
485
486 static inline int decode012(GetBitContext *gb)
487 {
488 int n;
489 n = get_bits1(gb);
490 if (n == 0)
491 return 0;
492 else
493 return get_bits1(gb) + 1;
494 }
495
496 static inline int decode210(GetBitContext *gb)
497 {
498 if (get_bits1(gb))
499 return 0;
500 else
501 return 2 - get_bits1(gb);
502 }
503
504 static inline int get_bits_left(GetBitContext *gb)
505 {
506 return gb->size_in_bits - get_bits_count(gb);
507 }
508
509 //#define TRACE
510
511 #ifdef TRACE
512 static inline void print_bin(int bits, int n)
513 {
514 int i;
515
516 for (i = n-1; i >= 0; i--) {
517 av_log(NULL, AV_LOG_DEBUG, "%d", (bits>>i)&1);
518 }
519 for (i = n; i < 24; i++)
520 av_log(NULL, AV_LOG_DEBUG, " ");
521 }
522
523 static inline int get_bits_trace(GetBitContext *s, int n, char *file,
524 const char *func, int line)
525 {
526 int r = get_bits(s, n);
527
528 print_bin(r, n);
529 av_log(NULL, AV_LOG_DEBUG, "%5d %2d %3d bit @%5d in %s %s:%d\n",
530 r, n, r, get_bits_count(s)-n, file, func, line);
531 return r;
532 }
533 static inline int get_vlc_trace(GetBitContext *s, VLC_TYPE (*table)[2],
534 int bits, int max_depth, char *file,
535 const char *func, int line)
536 {
537 int show = show_bits(s, 24);
538 int pos = get_bits_count(s);
539 int r = get_vlc2(s, table, bits, max_depth);
540 int len = get_bits_count(s) - pos;
541 int bits2 = show >> (24-len);
542
543 print_bin(bits2, len);
544
545 av_log(NULL, AV_LOG_DEBUG, "%5d %2d %3d vlc @%5d in %s %s:%d\n",
546 bits2, len, r, pos, file, func, line);
547 return r;
548 }
549 static inline int get_xbits_trace(GetBitContext *s, int n, char *file,
550 const char *func, int line)
551 {
552 int show = show_bits(s, n);
553 int r = get_xbits(s, n);
554
555 print_bin(show, n);
556 av_log(NULL, AV_LOG_DEBUG, "%5d %2d %3d xbt @%5d in %s %s:%d\n",
557 show, n, r, get_bits_count(s)-n, file, func, line);
558 return r;
559 }
560
561 #define get_bits(s, n) get_bits_trace(s, n, __FILE__, __PRETTY_FUNCTION__, __LINE__)
562 #define get_bits1(s) get_bits_trace(s, 1, __FILE__, __PRETTY_FUNCTION__, __LINE__)
563 #define get_xbits(s, n) get_xbits_trace(s, n, __FILE__, __PRETTY_FUNCTION__, __LINE__)
564 #define get_vlc(s, vlc) get_vlc_trace(s, (vlc)->table, (vlc)->bits, 3, __FILE__, __PRETTY_FUNCTION__, __LINE__)
565 #define get_vlc2(s, tab, bits, max) get_vlc_trace(s, tab, bits, max, __FILE__, __PRETTY_FUNCTION__, __LINE__)
566
567 #define tprintf(p, ...) av_log(p, AV_LOG_DEBUG, __VA_ARGS__)
568
569 #else //TRACE
570 #define tprintf(p, ...) {}
571 #endif
572
573 #endif /* AVCODEC_GET_BITS_H */