1 /*
2 * Copyright (c) 2004 Michael Niedermayer <michaelni@gmx.at>
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg 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 * FFmpeg 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 FFmpeg; 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
34
38
39 /*
40 * Safe bitstream reading:
41 * optionally, the get_bits API can check to ensure that we
42 * don't read past input buffer boundaries. This is protected
43 * with CONFIG_SAFE_BITSTREAM_READER at the global level, and
44 * then below that with UNCHECKED_BITSTREAM_READER at the per-
45 * decoder level. This means that decoders that check internally
46 * can "#define UNCHECKED_BITSTREAM_READER 1" to disable
47 * overread checks.
48 * Boundary checking causes a minor performance penalty so for
49 * applications that won't want/need this, it can be disabled
50 * globally using "#define CONFIG_SAFE_BITSTREAM_READER 0".
51 */
52 #ifndef UNCHECKED_BITSTREAM_READER
53 #define UNCHECKED_BITSTREAM_READER !CONFIG_SAFE_BITSTREAM_READER
54 #endif
55
56 #ifndef CACHED_BITSTREAM_READER
57 #define CACHED_BITSTREAM_READER 0
58 #endif
59
60 #if CACHED_BITSTREAM_READER
61
62 // we always want the LE implementation, to provide get_bits_le()
63 #define BITSTREAM_LE
64
65 #ifndef BITSTREAM_READER_LE
66 # define BITSTREAM_BE
67 # define BITSTREAM_DEFAULT_BE
68 #endif
69
71
72 #undef BITSTREAM_LE
73 #undef BITSTREAM_BE
74 #undef BITSTREAM_DEFAULT_BE
75
77
78 #define get_bits_count bits_tell
79 #define get_bits_bytesize bits_bytesize
80 #define get_bits_left bits_left
81 #define skip_bits_long bits_skip
82 #define skip_bits bits_skip
83 #define get_bits bits_read_nz
84 #define get_bitsz bits_read
85 #define get_bits_long bits_read
86 #define get_bits1 bits_read_bit
87 #define get_bits64 bits_read_64
88 #define get_xbits bits_read_xbits
89 #define get_sbits bits_read_signed_nz
90 #define get_sbits_long bits_read_signed
91 #define show_bits bits_peek
92 #define show_bits_long bits_peek
93 #define init_get_bits bits_init
94 #define init_get_bits8 bits_init8
95 #define align_get_bits bits_align
96 #define get_vlc2 bits_read_vlc
97 #define get_vlc_multi bits_read_vlc_multi
98
99 #define init_get_bits8_le(s, buffer, byte_size) bits_init8_le((BitstreamContextLE*)s, buffer, byte_size)
100 #define get_bits_le(s, n) bits_read_le((BitstreamContextLE*)s, n)
101
102 #define show_bits1(s) bits_peek(s, 1)
103 #define skip_bits1(s) bits_skip(s, 1)
104
105 #define skip_1stop_8data_bits bits_skip_1stop_8data
106
107 #else // CACHED_BITSTREAM_READER
108
115
119
120 /* Bitstream reader API docs:
121 * name
122 * arbitrary name which is used as prefix for the internal variables
123 *
124 * gb
125 * getbitcontext
126 *
127 * OPEN_READER(name, gb)
128 * load gb into local variables
129 *
130 * CLOSE_READER(name, gb)
131 * store local vars in gb
132 *
133 * UPDATE_CACHE(name, gb)
134 * Refill the internal cache from the bitstream.
135 * After this call at least MIN_CACHE_BITS will be available.
136 *
137 * GET_CACHE(name, gb)
138 * Will output the contents of the internal cache,
139 * next bit is MSB of 32 or 64 bits (FIXME 64 bits).
140 *
141 * SHOW_UBITS(name, gb, num)
142 * Will return the next num bits.
143 *
144 * SHOW_SBITS(name, gb, num)
145 * Will return the next num bits and do sign extension.
146 *
147 * SKIP_BITS(name, gb, num)
148 * Will skip over the next num bits.
149 * Note, this is equivalent to SKIP_CACHE; SKIP_COUNTER.
150 *
151 * SKIP_CACHE(name, gb, num)
152 * Will remove the next num bits from the cache (note SKIP_COUNTER
153 * MUST be called before UPDATE_CACHE / CLOSE_READER).
154 *
155 * SKIP_COUNTER(name, gb, num)
156 * Will increment the internal bit counter (see SKIP_CACHE & SKIP_BITS).
157 *
158 * LAST_SKIP_BITS(name, gb, num)
159 * Like SKIP_BITS, to be used if next call is UPDATE_CACHE or CLOSE_READER.
160 *
161 * BITS_LEFT(name, gb)
162 * Return the number of bits left
163 *
164 * For examples see get_bits, show_bits, skip_bits, get_vlc.
165 */
166
167 #define MIN_CACHE_BITS 25
168
169 #define OPEN_READER_NOSIZE(name, gb) \
170 unsigned int name ## _index = (gb)->index; \
171 av_unused unsigned int name ## _cache
172
173 #if UNCHECKED_BITSTREAM_READER
174 #define OPEN_READER(name, gb) OPEN_READER_NOSIZE(name, gb)
175
176 #define BITS_AVAILABLE(name, gb) 1
177 #else
178 #define OPEN_READER(name, gb) \
179 OPEN_READER_NOSIZE(name, gb); \
180 unsigned int name ## _size_plus8 = (gb)->size_in_bits_plus8
181
182 #define BITS_AVAILABLE(name, gb) name ## _index < name ## _size_plus8
183 #endif
184
185 #define CLOSE_READER(name, gb) (gb)->index = name ## _index
186
187 #define UPDATE_CACHE_BE_EXT(name, gb, bits, dst_bits) name ## _cache = \
188 AV_RB ## bits((gb)->buffer + (name ## _index >> 3)) << (name ## _index & 7) >> (bits - dst_bits)
189
190 #define UPDATE_CACHE_LE_EXT(name, gb, bits, dst_bits) name ## _cache = \
191 (uint ## dst_bits ## _t)(AV_RL ## bits((gb)->buffer + (name ## _index >> 3)) >> (name ## _index & 7))
192
193 /* Using these two macros ensures that 32 bits are available. */
194 # define UPDATE_CACHE_LE_32(name, gb) UPDATE_CACHE_LE_EXT(name, (gb), 64, 32)
195 # define UPDATE_CACHE_BE_32(name, gb) UPDATE_CACHE_BE_EXT(name, (gb), 64, 32)
196
197 # define UPDATE_CACHE_LE(name, gb) UPDATE_CACHE_LE_EXT(name, (gb), 32, 32)
198 # define UPDATE_CACHE_BE(name, gb) UPDATE_CACHE_BE_EXT(name, (gb), 32, 32)
199
200 #ifdef BITSTREAM_READER_LE
201
202 # define UPDATE_CACHE(name, gb) UPDATE_CACHE_LE(name, gb)
203 # define UPDATE_CACHE_32(name, gb) UPDATE_CACHE_LE_32(name, (gb))
204
205 # define SKIP_CACHE(name, gb, num) name ## _cache >>= (num)
206
207 #else
208
209 # define UPDATE_CACHE(name, gb) UPDATE_CACHE_BE(name, gb)
210 # define UPDATE_CACHE_32(name, gb) UPDATE_CACHE_BE_32(name, (gb))
211
212 # define SKIP_CACHE(name, gb, num) name ## _cache <<= (num)
213
214 #endif
215
216 #if UNCHECKED_BITSTREAM_READER
217 # define SKIP_COUNTER(name, gb, num) name ## _index += (num)
218 #else
219 # define SKIP_COUNTER(name, gb, num) \
220 name ## _index = FFMIN(name ## _size_plus8, name ## _index + (num))
221 #endif
222
223 #define BITS_LEFT(name, gb) ((int)((gb)->size_in_bits - name ## _index))
224
225 #define SKIP_BITS(name, gb, num) \
226 do { \
227 SKIP_CACHE(name, gb, num); \
228 SKIP_COUNTER(name, gb, num); \
229 } while (0)
230
231 #define LAST_SKIP_BITS(name, gb, num) SKIP_COUNTER(name, gb, num)
232
233 #define SHOW_UBITS_LE(name, gb, num) zero_extend(name ## _cache, num)
234 #define SHOW_SBITS_LE(name, gb, num) sign_extend(name ## _cache, num)
235
236 #define SHOW_UBITS_BE(name, gb, num) NEG_USR32(name ## _cache, num)
237 #define SHOW_SBITS_BE(name, gb, num) NEG_SSR32(name ## _cache, num)
238
239 #ifdef BITSTREAM_READER_LE
240 # define SHOW_UBITS(name, gb, num) SHOW_UBITS_LE(name, gb, num)
241 # define SHOW_SBITS(name, gb, num) SHOW_SBITS_LE(name, gb, num)
242 #else
243 # define SHOW_UBITS(name, gb, num) SHOW_UBITS_BE(name, gb, num)
244 # define SHOW_SBITS(name, gb, num) SHOW_SBITS_BE(name, gb, num)
245 #endif
246
247 #define GET_CACHE(name, gb) ((uint32_t) name ## _cache)
248
249
251 {
253 }
254
255 /**
256 * Get the size of the GetBitContext's buffer in bytes.
257 *
258 * @param s the GetBitContext
259 * @param round_up If set, the number of bits will be rounded up to full bytes;
260 * this does not matter if the number of bits is known to be
261 * a multiple of eight, e.g. if the GetBitContext has been
262 * initialized with init_get_bits8.
263 */
265 {
266 return (
s->size_in_bits + (round_up ? 7 : 0)) >> 3;
267 }
268
269 /**
270 * Skips the specified number of bits.
271 * @param n the number of bits to skip,
272 * For the UNCHECKED_BITSTREAM_READER this must not cause the distance
273 * from the start to overflow int32_t. Staying within the bitstream + padding
274 * is sufficient, too.
275 */
277 {
278 #if UNCHECKED_BITSTREAM_READER
280 #else
281 s->index +=
av_clip(n, -
s->index,
s->size_in_bits_plus8 -
s->index);
282 #endif
283 }
284
285 /**
286 * Read MPEG-1 dc-style VLC (sign bit + mantissa with no MSB).
287 * if MSB not set it is negative
288 * @param n length in bits
289 */
291 {
292 register int sign;
298 sign = ~cache >> 31;
301 return (
NEG_USR32(sign ^ cache, n) ^ sign) - sign;
302 }
303
305 {
306 register int sign;
315 return (
zero_extend(sign ^ cache, n) ^ sign) - sign;
316 }
317
319 {
328 }
329
330 /**
331 * Read 1-25 bits.
332 */
334 {
335 register unsigned int tmp;
344 }
345
346 /**
347 * Read 0-25 bits.
348 */
350 {
352 }
353
355 {
364 }
365
366 /**
367 * Show 1-25 bits.
368 */
370 {
371 register unsigned int tmp;
377 }
378
380 {
384 }
385
387 {
388 unsigned int index =
s->index;
390 #ifdef BITSTREAM_READER_LE
393 #else
396 #endif
397 #if !UNCHECKED_BITSTREAM_READER
398 if (
s->index <
s->size_in_bits_plus8)
399 #endif
402
404 }
405
407 {
409 }
410
412 {
414 }
415
416 /**
417 * Read 0-32 bits.
418 */
420 {
422 if (!n) {
423 return 0;
427 } else {
428 #if HAVE_FAST_64BIT
436 #else
437 #ifdef BITSTREAM_READER_LE
440 #else
443 #endif
444 #endif
445 }
446 }
447
448 /**
449 * Read 0-64 bits.
450 */
452 {
453 if (n <= 32) {
455 } else {
456 #ifdef BITSTREAM_READER_LE
459 #else
462 #endif
463 }
464 }
465
466 /**
467 * Read 0-32 bits as a signed integer.
468 */
470 {
471 // sign_extend(x, 0) is undefined
472 if (!n)
473 return 0;
474
476 }
477
478 /**
479 * Read 0-64 bits as a signed integer.
480 */
482 {
483 // sign_extend(x, 0) is undefined
484 if (!n)
485 return 0;
486
488 }
489
490 /**
491 * Show 0-32 bits.
492 */
494 {
497 } else {
500 }
501 }
502
503
504 /**
505 * Initialize GetBitContext.
506 * @param buffer bitstream buffer, must be AV_INPUT_BUFFER_PADDING_SIZE bytes
507 * larger than the actual read bits because some optimized bitstream
508 * readers read 32 or 64 bit at once and could read over the end
509 * @param bit_size the size of the buffer in bits
510 * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow.
511 */
513 int bit_size)
514 {
516
518 bit_size = 0;
521 }
522
524 s->size_in_bits = bit_size;
525 s->size_in_bits_plus8 = bit_size + 8;
527
529 }
530
531 /**
532 * Initialize GetBitContext.
533 * @param buffer bitstream buffer, must be AV_INPUT_BUFFER_PADDING_SIZE bytes
534 * larger than the actual read bits because some optimized bitstream
535 * readers read 32 or 64 bit at once and could read over the end
536 * @param byte_size the size of the buffer in bytes
537 * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow.
538 */
540 int byte_size)
541 {
542 if (byte_size > INT_MAX / 8 || byte_size < 0)
543 byte_size = -1;
545 }
546
548 int byte_size)
549 {
550 if (byte_size > INT_MAX / 8 || byte_size < 0)
551 byte_size = -1;
553 }
554
556 {
558 if (n)
560 return s->buffer + (
s->index >> 3);
561 }
562
563 /**
564 * If the vlc code is invalid and max_depth=1, then no bits will be removed.
565 * If the vlc code is invalid and max_depth>1, then the number of bits removed
566 * is undefined.
567 */
568 #define GET_VLC(code, name, gb, table, bits, max_depth) \
569 do { \
570 int n, nb_bits; \
571 unsigned int index; \
572 \
573 index = SHOW_UBITS(name, gb, bits); \
574 code = table[index].sym; \
575 n = table[index].len; \
576 \
577 if (max_depth > 1 && n < 0) { \
578 LAST_SKIP_BITS(name, gb, bits); \
579 UPDATE_CACHE(name, gb); \
580 \
581 nb_bits = -n; \
582 \
583 index = SHOW_UBITS(name, gb, nb_bits) + code; \
584 code = table[index].sym; \
585 n = table[index].len; \
586 if (max_depth > 2 && n < 0) { \
587 LAST_SKIP_BITS(name, gb, nb_bits); \
588 UPDATE_CACHE(name, gb); \
589 \
590 nb_bits = -n; \
591 \
592 index = SHOW_UBITS(name, gb, nb_bits) + code; \
593 code = table[index].sym; \
594 n = table[index].len; \
595 } \
596 } \
597 SKIP_BITS(name, gb, n); \
598 } while (0)
599
600 #define GET_RL_VLC(level, run, name, gb, table, bits, \
601 max_depth, need_update) \
602 do { \
603 int n, nb_bits; \
604 unsigned int index; \
605 \
606 index = SHOW_UBITS(name, gb, bits); \
607 level = table[index].level; \
608 n = table[index].len8; \
609 \
610 if (max_depth > 1 && n < 0) { \
611 SKIP_BITS(name, gb, bits); \
612 if (need_update) { \
613 UPDATE_CACHE(name, gb); \
614 } \
615 \
616 nb_bits = -n; \
617 \
618 index = SHOW_UBITS(name, gb, nb_bits) + level; \
619 level = table[index].level; \
620 n = table[index].len8; \
621 if (max_depth > 2 && n < 0) { \
622 LAST_SKIP_BITS(name, gb, nb_bits); \
623 if (need_update) { \
624 UPDATE_CACHE(name, gb); \
625 } \
626 nb_bits = -n; \
627 \
628 index = SHOW_UBITS(name, gb, nb_bits) + level; \
629 level = table[index].level; \
630 n = table[index].len8; \
631 } \
632 } \
633 run = table[index].run; \
634 SKIP_BITS(name, gb, n); \
635 } while (0)
636
637 /**
638 * Parse a vlc code.
639 * @param bits is the number of bits which will be read at once, must be
640 * identical to nb_bits in vlc_init()
641 * @param max_depth is the number of times bits bits must be read to completely
642 * read the longest vlc code
643 * = (max_vlc_length + bits - 1) / bits
644 * @returns the code parsed or -1 if no vlc matches
645 */
647 int bits,
int max_depth)
648 {
650
653
655
657
659 }
660
664 const int bits,
const int max_depth,
665 const int symbols_size)
666 {
668 return 1;
669 }
670
672 {
673 int n;
675 if (n == 0)
676 return 0;
677 else
679 }
680
682 {
684 return 0;
685 else
687 }
688
690 {
692 }
693
695 {
698
703 }
704
705 return 0;
706 }
707
708 #endif // CACHED_BITSTREAM_READER
709
710 #endif /* AVCODEC_GET_BITS_H */