Noah Richards | bbf7c86 | 2015-04-21 23:30:13 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2015 The WebRTC Project Authors. All rights reserved. |
| 3 | * |
| 4 | * Use of this source code is governed by a BSD-style license |
| 5 | * that can be found in the LICENSE file in the root of the source |
| 6 | * tree. An additional intellectual property rights grant can be found |
| 7 | * in the file PATENTS. All contributing project authors may |
| 8 | * be found in the AUTHORS file in the root of the source tree. |
| 9 | */ |
| 10 | |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 11 | #ifndef RTC_BASE_BIT_BUFFER_H_ |
| 12 | #define RTC_BASE_BIT_BUFFER_H_ |
Noah Richards | bbf7c86 | 2015-04-21 23:30:13 | [diff] [blame] | 13 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 14 | #include <stddef.h> // For size_t. |
Yves Gerey | 665174f | 2018-06-19 13:03:05 | [diff] [blame] | 15 | #include <stdint.h> // For integer types. |
Noah Richards | 9b9f1c4 | 2015-05-12 19:20:47 | [diff] [blame] | 16 | |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 17 | #include "rtc_base/constructor_magic.h" |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 18 | |
| 19 | namespace rtc { |
| 20 | |
| 21 | // A class, similar to ByteBuffer, that can parse bit-sized data out of a set of |
| 22 | // bytes. Has a similar API to ByteBuffer, plus methods for reading bit-sized |
| 23 | // and exponential golomb encoded data. For a writable version, use |
| 24 | // BitBufferWriter. Unlike ByteBuffer, this class doesn't make a copy of the |
| 25 | // source bytes, so it can be used on read-only data. |
| 26 | // Sizes/counts specify bits/bytes, for clarity. |
| 27 | // Byte order is assumed big-endian/network. |
| 28 | class BitBuffer { |
| 29 | public: |
| 30 | BitBuffer(const uint8_t* bytes, size_t byte_count); |
| 31 | |
| 32 | // Gets the current offset, in bytes/bits, from the start of the buffer. The |
| 33 | // bit offset is the offset into the current byte, in the range [0,7]. |
| 34 | void GetCurrentOffset(size_t* out_byte_offset, size_t* out_bit_offset); |
| 35 | |
| 36 | // The remaining bits in the byte buffer. |
| 37 | uint64_t RemainingBitCount() const; |
| 38 | |
| 39 | // Reads byte-sized values from the buffer. Returns false if there isn't |
| 40 | // enough data left for the specified type. |
| 41 | bool ReadUInt8(uint8_t* val); |
| 42 | bool ReadUInt16(uint16_t* val); |
| 43 | bool ReadUInt32(uint32_t* val); |
| 44 | |
| 45 | // Reads bit-sized values from the buffer. Returns false if there isn't enough |
Elad Alon | 21c6638 | 2018-09-12 13:59:30 | [diff] [blame] | 46 | // data left for the specified bit count. |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 47 | bool ReadBits(uint32_t* val, size_t bit_count); |
| 48 | |
| 49 | // Peeks bit-sized values from the buffer. Returns false if there isn't enough |
| 50 | // data left for the specified number of bits. Doesn't move the current |
| 51 | // offset. |
| 52 | bool PeekBits(uint32_t* val, size_t bit_count); |
| 53 | |
Danil Chapovalov | a2b30d8 | 2019-07-03 12:41:50 | [diff] [blame] | 54 | // Reads value in range [0, num_values - 1]. |
| 55 | // This encoding is similar to ReadBits(val, Ceil(Log2(num_values)), |
| 56 | // but reduces wastage incurred when encoding non-power of two value ranges |
| 57 | // Non symmetric values are encoded as: |
| 58 | // 1) n = countbits(num_values) |
| 59 | // 2) k = (1 << n) - num_values |
| 60 | // Value v in range [0, k - 1] is encoded in (n-1) bits. |
| 61 | // Value v in range [k, num_values - 1] is encoded as (v+k) in n bits. |
| 62 | // https://aomediacodec.github.io/av1-spec/#nsn |
| 63 | // Returns false if there isn't enough data left. |
| 64 | bool ReadNonSymmetric(uint32_t* val, uint32_t num_values); |
| 65 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 66 | // Reads the exponential golomb encoded value at the current offset. |
| 67 | // Exponential golomb values are encoded as: |
| 68 | // 1) x = source val + 1 |
| 69 | // 2) In binary, write [countbits(x) - 1] 0s, then x |
| 70 | // To decode, we count the number of leading 0 bits, read that many + 1 bits, |
| 71 | // and increment the result by 1. |
| 72 | // Returns false if there isn't enough data left for the specified type, or if |
| 73 | // the value wouldn't fit in a uint32_t. |
| 74 | bool ReadExponentialGolomb(uint32_t* val); |
| 75 | // Reads signed exponential golomb values at the current offset. Signed |
| 76 | // exponential golomb values are just the unsigned values mapped to the |
| 77 | // sequence 0, 1, -1, 2, -2, etc. in order. |
| 78 | bool ReadSignedExponentialGolomb(int32_t* val); |
| 79 | |
| 80 | // Moves current position |byte_count| bytes forward. Returns false if |
| 81 | // there aren't enough bytes left in the buffer. |
| 82 | bool ConsumeBytes(size_t byte_count); |
| 83 | // Moves current position |bit_count| bits forward. Returns false if |
| 84 | // there aren't enough bits left in the buffer. |
| 85 | bool ConsumeBits(size_t bit_count); |
| 86 | |
| 87 | // Sets the current offset to the provied byte/bit offsets. The bit |
| 88 | // offset is from the given byte, in the range [0,7]. |
| 89 | bool Seek(size_t byte_offset, size_t bit_offset); |
| 90 | |
| 91 | protected: |
| 92 | const uint8_t* const bytes_; |
| 93 | // The total size of |bytes_|. |
| 94 | size_t byte_count_; |
| 95 | // The current offset, in bytes, from the start of |bytes_|. |
| 96 | size_t byte_offset_; |
| 97 | // The current offset, in bits, into the current byte. |
| 98 | size_t bit_offset_; |
| 99 | |
| 100 | RTC_DISALLOW_COPY_AND_ASSIGN(BitBuffer); |
| 101 | }; |
| 102 | |
| 103 | // A BitBuffer API for write operations. Supports symmetric write APIs to the |
| 104 | // reading APIs of BitBuffer. Note that the read/write offset is shared with the |
| 105 | // BitBuffer API, so both reading and writing will consume bytes/bits. |
| 106 | class BitBufferWriter : public BitBuffer { |
| 107 | public: |
| 108 | // Constructs a bit buffer for the writable buffer of |bytes|. |
| 109 | BitBufferWriter(uint8_t* bytes, size_t byte_count); |
| 110 | |
| 111 | // Writes byte-sized values from the buffer. Returns false if there isn't |
| 112 | // enough data left for the specified type. |
| 113 | bool WriteUInt8(uint8_t val); |
| 114 | bool WriteUInt16(uint16_t val); |
| 115 | bool WriteUInt32(uint32_t val); |
| 116 | |
| 117 | // Writes bit-sized values to the buffer. Returns false if there isn't enough |
| 118 | // room left for the specified number of bits. |
| 119 | bool WriteBits(uint64_t val, size_t bit_count); |
| 120 | |
Danil Chapovalov | a2b30d8 | 2019-07-03 12:41:50 | [diff] [blame] | 121 | // Writes value in range [0, num_values - 1] |
| 122 | // See ReadNonSymmetric documentation for the format, |
| 123 | // Call SizeNonSymmetricBits to get number of bits needed to store the value. |
| 124 | // Returns false if there isn't enough room left for the value. |
| 125 | bool WriteNonSymmetric(uint32_t val, uint32_t num_values); |
| 126 | // Returns number of bits required to store |val| with NonSymmetric encoding. |
| 127 | static size_t SizeNonSymmetricBits(uint32_t val, uint32_t num_values); |
| 128 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 129 | // Writes the exponential golomb encoded version of the supplied value. |
| 130 | // Returns false if there isn't enough room left for the value. |
| 131 | bool WriteExponentialGolomb(uint32_t val); |
| 132 | // Writes the signed exponential golomb version of the supplied value. |
| 133 | // Signed exponential golomb values are just the unsigned values mapped to the |
| 134 | // sequence 0, 1, -1, 2, -2, etc. in order. |
| 135 | bool WriteSignedExponentialGolomb(int32_t val); |
| 136 | |
| 137 | private: |
| 138 | // The buffer, as a writable array. |
| 139 | uint8_t* const writable_bytes_; |
| 140 | |
| 141 | RTC_DISALLOW_COPY_AND_ASSIGN(BitBufferWriter); |
| 142 | }; |
| 143 | |
| 144 | } // namespace rtc |
Noah Richards | bbf7c86 | 2015-04-21 23:30:13 | [diff] [blame] | 145 | |
Steve Anton | 10542f2 | 2019-01-11 17:11:00 | [diff] [blame] | 146 | #endif // RTC_BASE_BIT_BUFFER_H_ |