libxcoder  5.2.0
ni_bitstream.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * This file is part of Kvazaar HEVC encoder.
3  *
4  * Copyright (c) 2021, Tampere University, ITU/ISO/IEC, project contributors
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without modification,
8  * are permitted provided that the following conditions are met:
9  *
10  * * Redistributions of source code must retain the above copyright notice, this
11  * list of conditions and the following disclaimer.
12  *
13  * * Redistributions in binary form must reproduce the above copyright notice, this
14  * list of conditions and the following disclaimer in the documentation and/or
15  * other materials provided with the distribution.
16  *
17  * * Neither the name of the Tampere University or ITU/ISO/IEC nor the names of its
18  * contributors may be used to endorse or promote products derived from
19  * this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
22  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
25  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
28  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  ****************************************************************************/
32 
33 /*!*****************************************************************************
34  * \file ni_bitstream.h
35  *
36  * \brief Utility definitions to operate on bits in a bitstream
37  ******************************************************************************/
38 
39 #pragma once
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 #ifdef _WIN32
46  #ifdef XCODER_DLL
47  #ifdef LIB_EXPORTS
48  #define LIB_API_BITSTREAM __declspec(dllexport)
49  #else
50  #define LIB_API_BITSTREAM __declspec(dllimport)
51  #endif
52  #else
53  #define LIB_API_BITSTREAM
54  #endif
55 #elif __linux__ || __APPLE__
56  #define LIB_API_BITSTREAM
57 #endif
58 
59 // the following is for bitstream put operations
60 #define NI_DATA_CHUNK_SIZE 4096
61 
62 typedef struct ni_data_chunk_t
63 {
64  // buffer for the data
66 
67  // number of bytes filled in this chunk
68  uint32_t len;
69 
70  // next chunk in the list
73 
74 // bitstream writer and operations
75 typedef struct _ni_bitstream_writer_t
76 {
77  // total number of complete bytes
78  uint32_t len;
79 
80  // pointer to the first chunk of data, or NULL
82 
83  // pointer to the last chunk of data, or NULL
85 
86  // the incomplete byte
87  uint8_t data;
88 
89  // number of bits in the incomplete byte
90  uint8_t cur_bit;
92 
93 // bitstream writer init
95 
96 // get the number of bits written to bitstream so far
97 uint64_t ni_bs_writer_tell(const ni_bitstream_writer_t *const stream);
98 
99 // write a specified number (<= 32) of bits to bitstream
100 void ni_bs_writer_put(ni_bitstream_writer_t *stream, uint32_t data,
101  uint8_t bits);
102 
103 // write unsigned/signed Exp-Golomb bit string to bitstream, 2^32-2 at most
104 void ni_bs_writer_put_ue(ni_bitstream_writer_t *stream, uint32_t data);
105 void ni_bs_writer_put_se(ni_bitstream_writer_t *stream, int32_t data);
106 
107 // align the bitstream with zero
109 
110 // copy bitstream data to dst
111 void ni_bs_writer_copy(uint8_t *dst, const ni_bitstream_writer_t *stream);
112 
113 // clear and reset bitstream
115 
116 // the following is for bitstream get operations
117 
118 // bitstream reader and operations
120 {
121  const uint8_t *buf; // data
122  int byte_offset; // byte offset of the current read position
123  int bit_offset; // bit offset of the current read position
124  int size_in_bits; // number of total bits in data
126 
127 // bitstream reader init
128 LIB_API_BITSTREAM void ni_bitstream_reader_init(ni_bitstream_reader_t *br, const uint8_t *data,
129  int bit_size);
130 
131 // return number of bits already parsed
132 LIB_API_BITSTREAM int ni_bs_reader_bits_count(ni_bitstream_reader_t *br);
133 
134 // return number of bits left to parse
135 LIB_API_BITSTREAM int ni_bs_reader_get_bits_left(ni_bitstream_reader_t *br);
136 
137 // skip a number of bits ahead in the bitstream reader
138 LIB_API_BITSTREAM void ni_bs_reader_skip_bits(ni_bitstream_reader_t *br, int n);
139 
140 // read bits (up to 32) from the bitstream reader, after reader init
141 LIB_API_BITSTREAM uint32_t ni_bs_reader_get_bits(ni_bitstream_reader_t *br, int n);
142 
143 // read an unsigned Exp-Golomb code ue(v)
144 LIB_API_BITSTREAM uint32_t ni_bs_reader_get_ue(ni_bitstream_reader_t *br);
145 
146 // read a signed Exp-Golomb code se(v)
147 LIB_API_BITSTREAM int32_t ni_bs_reader_get_se(ni_bitstream_reader_t *br);
148 
149 #ifdef __cplusplus
150 }
151 #endif
ni_bs_reader_bits_count
LIB_API_BITSTREAM int ni_bs_reader_bits_count(ni_bitstream_reader_t *br)
return the number of bits already parsed in stream
Definition: ni_bitstream.c:338
ni_bs_writer_put_ue
void ni_bs_writer_put_ue(ni_bitstream_writer_t *stream, uint32_t data)
write unsigned Exp-Golomb bit string to bitstream, 2^32-2 at most.
Definition: ni_bitstream.c:219
_ni_bitstream_writer_t::last
ni_data_chunk_t * last
Definition: ni_bitstream.h:84
ni_bitstream_reader_init
LIB_API_BITSTREAM void ni_bitstream_reader_init(ni_bitstream_reader_t *br, const uint8_t *data, int bit_size)
init a bitstream reader Note: bitstream_reader takes reading ownership of the data
Definition: ni_bitstream.c:317
_ni_bitstream_writer_t::len
uint32_t len
Definition: ni_bitstream.h:78
_ni_bitstream_writer_t::data
uint8_t data
Definition: ni_bitstream.h:87
ni_bs_writer_clear
void ni_bs_writer_clear(ni_bitstream_writer_t *stream)
clear and reset bitstream
Definition: ni_bitstream.c:300
ni_data_chunk_t
struct ni_data_chunk_t ni_data_chunk_t
_ni_bitstream_writer_t::first
ni_data_chunk_t * first
Definition: ni_bitstream.h:81
ni_data_chunk_t::data
uint8_t data[NI_DATA_CHUNK_SIZE]
Definition: ni_bitstream.h:65
ni_bs_reader_get_bits
LIB_API_BITSTREAM uint32_t ni_bs_reader_get_bits(ni_bitstream_reader_t *br, int n)
read bits (up to 32) from the bitstream reader, after reader init
Definition: ni_bitstream.c:471
ni_bs_writer_put
void ni_bs_writer_put(ni_bitstream_writer_t *stream, uint32_t data, uint8_t bits)
write a specified number (<= 32) of bits to bitstream, buffer individual bits until a full byte is ma...
Definition: ni_bitstream.c:183
_ni_bitstream_writer_t
Definition: ni_bitstream.h:75
ni_bitstream_writer_t
struct _ni_bitstream_writer_t ni_bitstream_writer_t
ni_bs_writer_tell
uint64_t ni_bs_writer_tell(const ni_bitstream_writer_t *const stream)
return the number of bits written to bitstream so far
Definition: ni_bitstream.c:169
ni_bs_reader_get_bits_left
LIB_API_BITSTREAM int ni_bs_reader_get_bits_left(ni_bitstream_reader_t *br)
return the number of bits left to parse in stream
Definition: ni_bitstream.c:349
_ni_bitstream_reader_t::buf
const uint8_t * buf
Definition: ni_bitstream.h:121
ni_bs_reader_get_se
LIB_API_BITSTREAM int32_t ni_bs_reader_get_se(ni_bitstream_reader_t *br)
read a signed Exp-Golomb code se(v)
Definition: ni_bitstream.c:546
_ni_bitstream_reader_t::bit_offset
int bit_offset
Definition: ni_bitstream.h:123
NI_DATA_CHUNK_SIZE
#define NI_DATA_CHUNK_SIZE
Definition: ni_bitstream.h:60
ni_bitstream_writer_init
void ni_bitstream_writer_init(ni_bitstream_writer_t *stream)
init a bitstream writer
Definition: ni_bitstream.c:158
_ni_bitstream_writer_t::cur_bit
uint8_t cur_bit
Definition: ni_bitstream.h:90
ni_data_chunk_t::len
uint32_t len
Definition: ni_bitstream.h:68
ni_bs_writer_align_zero
void ni_bs_writer_align_zero(ni_bitstream_writer_t *stream)
align the bitstream with zero
Definition: ni_bitstream.c:266
ni_data_chunk_t::next
struct ni_data_chunk_t * next
Definition: ni_bitstream.h:71
_ni_bitstream_reader_t::size_in_bits
int size_in_bits
Definition: ni_bitstream.h:124
ni_bs_writer_put_se
void ni_bs_writer_put_se(ni_bitstream_writer_t *stream, int32_t data)
write signed Exp-Golomb bit string to bitstream
Definition: ni_bitstream.c:253
ni_data_chunk_t
Definition: ni_bitstream.h:62
ni_bs_reader_skip_bits
LIB_API_BITSTREAM void ni_bs_reader_skip_bits(ni_bitstream_reader_t *br, int n)
skip a number of bits ahead in the bitstream reader
Definition: ni_bitstream.c:361
ni_bs_writer_copy
void ni_bs_writer_copy(uint8_t *dst, const ni_bitstream_writer_t *stream)
copy bitstream data to dst Note: caller must ensure sufficient space in dst
Definition: ni_bitstream.c:282
ni_bs_reader_get_ue
LIB_API_BITSTREAM uint32_t ni_bs_reader_get_ue(ni_bitstream_reader_t *br)
read an unsigned Exp-Golomb code ue(v)
Definition: ni_bitstream.c:522
_ni_bitstream_reader_t
Definition: ni_bitstream.h:119
_ni_bitstream_reader_t::byte_offset
int byte_offset
Definition: ni_bitstream.h:122
ni_bitstream_reader_t
struct _ni_bitstream_reader_t ni_bitstream_reader_t