1 /******************************************************************************
2 *
3 * Copyright (C) 2015 The Android Open Source Project
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at:
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 *****************************************************************************
18 * Originally developed and contributed by Ittiam Systems Pvt. Ltd, Bangalore
19 */
20
21 /**
22 *******************************************************************************
23 * @file
24 * ih264e_bitstream.h
25 *
26 * @brief
27 * This file contains encoder bitstream engine related structures and
28 * interface prototypes
29 *
30 * @author
31 * ittiam
32 *
33 * @remarks
34 * none
35 *
36 *******************************************************************************
37 */
38
39 #ifndef IH264E_BITSTREAM_H_
40 #define IH264E_BITSTREAM_H_
41
42 /*****************************************************************************/
43 /* Constant Macros */
44 /*****************************************************************************/
45
46 /**
47 ******************************************************************************
48 * @brief defines the maximum number of bits in a bitstream word
49 ******************************************************************************
50 */
51 #define WORD_SIZE 32
52
53 /**
54 ******************************************************************************
55 * @brief The number of consecutive zero bytes for emulation prevention check
56 ******************************************************************************
57 */
58 #define EPB_ZERO_BYTES 2
59
60 /**
61 ******************************************************************************
62 * @brief Emulation prevention insertion byte
63 ******************************************************************************
64 */
65 #define EPB_BYTE 0x03
66
67
68 /**
69 ******************************************************************************
70 * @brief Stream buffer allocated per frame should be atleast MIN_STREAM_SIZE
71 ******************************************************************************
72 */
73 #define MIN_STREAM_SIZE 0x800
74
75
76 /*****************************************************************************/
77 /* Function Macros */
78 /*****************************************************************************/
79
80 /**
81 ******************************************************************************
82 * @brief Macro to check if emulation prevention byte insertion is required
83 ******************************************************************************
84 */
85 #define INSERT_EPB(zero_run, next_byte) \
86 ((zero_run) == EPB_ZERO_BYTES) && (0 == ((next_byte) & 0xFC))
87
88 /**
89 ******************************************************************************
90 * @brief returns the bit position of a leading 1 (msb) in a code value
91 ******************************************************************************
92 */
93 #if !MSVC
94 #define GETRANGE(r,value) \
95 { \
96 r = 0; \
97 if(0 == value) \
98 r = 1; \
99 else \
100 { \
101 r = 32-CLZ(value); \
102 }\
103 }
104 #else
105 #define GETRANGE(r,value) \
106 { \
107 unsigned long msb_one_bit = 0; \
108 r = _BitScanReverse(&msb_one_bit, value) ? (UWORD32)(msb_one_bit + 1) : 1 ; \
109 }
110 #endif
111
112 /**
113 ******************************************************************************
114 * @brief returns bits required to code a value
115 ******************************************************************************
116 */
117 #define UE_LENGTH(bits,x) \
118 { \
119 UWORD32 r_bit; \
120 GETRANGE(r_bit,x+1) \
121 bits =(((r_bit - 1) << 1)+1);\
122 } \
123
124 /**
125 ******************************************************************************
126 * @brief Inserts 1 byte and Emulation Prevention Byte(if any) into bitstream
127 * Increments the stream offset and zero run correspondingly
128 ******************************************************************************
129 */
130 #define PUTBYTE_EPB(ptr,off,byte,zero_run) \
131 { \
132 if( INSERT_EPB(zero_run, byte) ) \
133 { \
134 ptr[off] = EPB_BYTE; \
135 off++; \
136 zero_run = 0; \
137 } \
138 \
139 ptr[off] = byte; \
140 off++; \
141 zero_run = byte ? 0 : zero_run+1; \
142 } \
143
144 /**
145 ******************************************************************************
146 * @brief Ensures Byte alignment of the slice header
147 ******************************************************************************
148 */
149 #define BYTE_ALIGNMENT(ps_bitstrm) ih264e_put_rbsp_trailing_bits(ps_bitstrm)
150
151 /**
152 ******************************************************************************
153 * @brief Gets number of bits coded
154 ******************************************************************************
155 */
156
157 #define GET_NUM_BITS(ps_bitstream) ((ps_bitstream->u4_strm_buf_offset << 3) \
158 + 32 - ps_bitstream->i4_bits_left_in_cw);
159
160
161
162 /**
163 ******************************************************************************
164 * @macro Align bitstream to byte - Remainig bits are filled with '1'
165 ******************************************************************************
166 */
167 #define BITSTREAM_BYTE_ALIGN(ps_bitstrm) \
168 if (ps_bitstrm->i4_bits_left_in_cw & 0x07) \
169 { \
170 const WORD32 len = (WORD32)((ps_bitstrm->i4_bits_left_in_cw) & 0x07);\
171 ih264e_put_bits(ps_bitstrm, (UWORD32)((1 << len) - 1), len); \
172 } \
173
174
175 /*****************************************************************************/
176 /* Structures */
177 /*****************************************************************************/
178
179 /**
180 ******************************************************************************
181 * @brief Bitstream context for encoder
182 ******************************************************************************
183 */
184 typedef struct bitstrm
185 {
186 /** points to start of stream buffer. */
187 UWORD8 *pu1_strm_buffer;
188
189 /**
190 * max bitstream size (in bytes).
191 * Encoded stream shall not exceed this size.
192 */
193 UWORD32 u4_max_strm_size;
194
195 /**
196 * byte offset (w.r.t pu1_strm_buffer) where next byte would be written
197 * Bitstream engine makes sure it would not corrupt data beyond
198 * u4_max_strm_size bytes
199 */
200 UWORD32 u4_strm_buf_offset;
201
202 /**
203 * current bitstream word; It is a scratch word containing max of
204 * WORD_SIZE bits. Will be copied to stream buffer when the word is
205 * full
206 */
207 UWORD32 u4_cur_word;
208
209 /**
210 * signifies number of bits available in u4_cur_word
211 * bits from msb to i4_bits_left_in_cw of u4_cur_word have already been
212 * inserted next bits would be inserted from pos [i4_bits_left_in_cw-1]
213 * Range of this variable [1 : WORD_SIZE]
214 */
215 WORD32 i4_bits_left_in_cw;
216
217 /**
218 * signifies the number of consecutive zero bytes propogated from previous
219 * word. It is used for emulation prevention byte insertion in the stream
220 */
221 WORD32 i4_zero_bytes_run;
222
223 } bitstrm_t;
224
225
226 /**
227 ******************************************************************************
228 * @brief Inserts 1 byte and Emulation Prevention Byte(if any) into bitstream
229 * Increments the stream offset and zero run correspondingly
230 ******************************************************************************
231 */
ih264e_put_byte_epb(bitstrm_t * ps_bitstrm,UWORD8 byte)232 static inline IH264E_ERROR_T ih264e_put_byte_epb(bitstrm_t *ps_bitstrm, UWORD8 byte)
233 {
234 if (INSERT_EPB(ps_bitstrm->i4_zero_bytes_run, byte))
235 {
236 if ((ps_bitstrm->u4_strm_buf_offset + 1) >= ps_bitstrm->u4_max_strm_size)
237 {
238 return IH264E_BITSTREAM_BUFFER_OVERFLOW;
239 }
240 ps_bitstrm->pu1_strm_buffer[ps_bitstrm->u4_strm_buf_offset++] = EPB_BYTE;
241 ps_bitstrm->i4_zero_bytes_run = 0;
242 }
243
244 if ((ps_bitstrm->u4_strm_buf_offset + 1) >= ps_bitstrm->u4_max_strm_size)
245 {
246 return IH264E_BITSTREAM_BUFFER_OVERFLOW;
247 }
248 ps_bitstrm->pu1_strm_buffer[ps_bitstrm->u4_strm_buf_offset++] = byte;
249 ps_bitstrm->i4_zero_bytes_run = byte ? 0 : ps_bitstrm->i4_zero_bytes_run + 1;
250
251 return IH264E_SUCCESS;
252 }
253
254 /**
255 ******************************************************************************
256 * flush the bits in cur word byte by byte and copy to stream *
257 * (current word is assumed to be byte aligned) *
258 ******************************************************************************
259 */
260 #define BITSTREAM_FLUSH(ps_bitstrm, err) \
261 { \
262 WORD32 i; \
263 for (i = WORD_SIZE; i > ps_bitstrm->i4_bits_left_in_cw; i -= 8) \
264 { \
265 UWORD8 u1_next_byte = (ps_bitstrm->u4_cur_word >> (i - 8)) & 0xFF; \
266 err |= ih264e_put_byte_epb(ps_bitstrm, u1_next_byte); \
267 } \
268 ps_bitstrm->u4_cur_word = 0; \
269 ps_bitstrm->i4_bits_left_in_cw = WORD_SIZE; \
270 } \
271
272
273
274 /*****************************************************************************/
275 /* Extern Function Declarations */
276 /*****************************************************************************/
277
278 /**
279 ******************************************************************************
280 *
281 * @brief Initializes the encoder bitstream engine
282 *
283 * @par Description
284 * This routine needs to be called at start of slice/frame encode
285 *
286 * @param[in] ps_bitstrm
287 * pointer to bitstream context (handle)
288 *
289 * @param[in] p1_bitstrm_buf
290 * bitstream buffer pointer where the encoded stream is generated in byte order
291 *
292 * @param[in] u4_max_bitstrm_size
293 * indicates maximum bitstream buffer size. (in bytes)
294 * If actual stream size exceeds the maximum size, encoder should
295 * 1. Not corrupt data beyond u4_max_bitstrm_size bytes
296 * 2. Report an error back to application indicating overflow
297 *
298 * @return success or failure error code
299 *
300 ******************************************************************************
301 */
302 IH264E_ERROR_T ih264e_bitstrm_init
303 (
304 bitstrm_t *ps_bitstrm,
305 UWORD8 *pu1_bitstrm_buf,
306 UWORD32 u4_max_bitstrm_size
307 );
308
309 /**
310 ******************************************************************************
311 *
312 * @brief puts a code with specified number of bits into the bitstream
313 *
314 * @par Description
315 * inserts code_len number of bits from lsb of code_val into the
316 * bitstream. If the total bytes (u4_strm_buf_offset) exceeds max
317 * available size (u4_max_strm_size), returns error without corrupting data
318 * beyond it
319 *
320 * @param[in] ps_bitstrm
321 * pointer to bitstream context (handle)
322 *
323 * @param[in] u4_code_val
324 * code value that needs to be inserted in the stream.
325 *
326 * @param[in] code_len
327 * indicates code length (in bits) of code_val that would be inserted in
328 * bitstream buffer size.
329 *
330 * @remarks Assumptions: all bits from bit position code_len to msb of
331 * code_val shall be zero
332 *
333 * @return success or failure error code
334 *
335 ******************************************************************************
336 */
337 IH264E_ERROR_T ih264e_put_bits
338 (
339 bitstrm_t *ps_bitstrm,
340 UWORD32 u4_code_val,
341 WORD32 code_len
342 );
343
344 /**
345 ******************************************************************************
346 *
347 * @brief inserts a 1-bit code into the bitstream
348 *
349 * @par Description
350 * inserts 1bit lsb of code_val into the bitstream
351 * updates context members like u4_cur_word, u4_strm_buf_offset and
352 * i4_bits_left_in_cw. If the total words (u4_strm_buf_offset) exceeds max
353 * available size (u4_max_strm_size), returns error without corrupting data
354 * beyond it
355 *
356 * @param[in] ps_bitstrm
357 * pointer to bitstream context (handle)
358 *
359 * @param[in] u4_code_val
360 * code value that needs to be inserted in the stream.
361 *
362 * @remarks Assumptions: all bits from bit position 1 to msb of code_val
363 * shall be zero
364 *
365 * @return success or failure error code
366 *
367 ******************************************************************************
368 */
369 IH264E_ERROR_T ih264e_put_bit
370 (
371 bitstrm_t *ps_bitstrm,
372 UWORD32 u4_code_val
373 );
374
375 /**
376 ******************************************************************************
377 *
378 * @brief inserts rbsp trailing bits at the end of stream buffer (NAL)
379 *
380 * @par Description
381 * inserts rbsp trailing bits, updates context members like u4_cur_word and
382 * i4_bits_left_in_cw and flushes the same in the bitstream buffer. If the
383 * total words (u4_strm_buf_offset) exceeds max available size
384 * (u4_max_strm_size), returns error without corrupting data beyond it
385 *
386 * @param[in] ps_bitstrm
387 * pointer to bitstream context (handle)
388 *
389 * @return success or failure error code
390 *
391 ******************************************************************************
392 */
393 IH264E_ERROR_T ih264e_put_rbsp_trailing_bits
394 (
395 bitstrm_t *ps_bitstrm
396 );
397
398 /**
399 ******************************************************************************
400 *
401 * @brief puts exponential golomb code of a unsigned integer into bitstream
402 *
403 * @par Description
404 * computes uev code for given syntax element and inserts the same into
405 * bitstream by calling ih264e_put_bits() interface.
406 *
407 * @param[in] ps_bitstrm
408 * pointer to bitstream context (handle)
409 *
410 * @param[in] u4_code_num
411 * unsigned integer input whose golomb code is written in stream
412 *
413 * @remarks Assumptions: code value can be represented in less than 16bits
414 *
415 * @return success or failure error code
416 *
417 ******************************************************************************
418 */
419 IH264E_ERROR_T ih264e_put_uev
420 (
421 bitstrm_t *ps_bitstrm,
422 UWORD32 u4_code_num
423 );
424
425 /**
426 ******************************************************************************
427 *
428 * @brief puts exponential golomb code of a signed integer into bitstream
429 *
430 * @par Description
431 * computes sev code for given syntax element and inserts the same into
432 * bitstream by calling ih264e_put_bits() interface.
433 *
434 * @param[in] ps_bitstrm
435 * pointer to bitstream context (handle)
436 *
437 * @param[in] syntax_elem
438 * signed integer input whose golomb code is written in stream
439 *
440 * @remarks Assumptions: code value can be represented in less than 16bits
441 *
442 * @return success or failure error code
443 *
444 ******************************************************************************
445 */
446 IH264E_ERROR_T ih264e_put_sev
447 (
448 bitstrm_t *ps_bitstrm,
449 WORD32 syntax_elem
450 );
451
452 /**
453 ******************************************************************************
454 *
455 * @brief insert NAL start code prefix (0x000001) into bitstream with an option
456 * of inserting leading_zero_8bits (which makes startcode prefix as 0x00000001)
457 *
458 * @par Description
459 * Although start code prefix could have been put by calling ih264e_put_bits(),
460 * ih264e_put_nal_start_code_prefix() is specially added to make sure emulation
461 * prevention insertion is not done for the NAL start code prefix which will
462 * surely happen otherwise by calling ih264e_put_bits() interface.
463 *
464 * @param[in] ps_bitstrm
465 * pointer to bitstream context (handle)
466 *
467 * @param[in] insert_leading_zero_8bits
468 * flag indicating if one more zero bytes needs to prefixed before start code
469 *
470 * @return success or failure error code
471 *
472 ******************************************************************************
473 */
474 IH264E_ERROR_T ih264e_put_nal_start_code_prefix
475 (
476 bitstrm_t *ps_bitstrm,
477 WORD32 insert_leading_zero_8bits
478 );
479
480 #endif /* IH264E_BITSTREAM_H_ */
481