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 ****************************************************************************** 177 * flush the bits in cur word byte by byte and copy to stream * 178 * (current word is assumed to be byte aligned) * 179 ****************************************************************************** 180 */ 181 #define BITSTREAM_FLUSH(ps_bitstrm) \ 182 { \ 183 WORD32 i; \ 184 for (i = WORD_SIZE; i > ps_bitstrm->i4_bits_left_in_cw; i -= 8) \ 185 { \ 186 UWORD8 u1_next_byte = (ps_bitstrm->u4_cur_word >> (i - 8)) & 0xFF; \ 187 PUTBYTE_EPB(ps_bitstrm->pu1_strm_buffer, ps_bitstrm->u4_strm_buf_offset,\ 188 u1_next_byte, ps_bitstrm->i4_zero_bytes_run); \ 189 } \ 190 ps_bitstrm->u4_cur_word = 0; \ 191 ps_bitstrm->i4_bits_left_in_cw = WORD_SIZE; \ 192 } \ 193 194 195 196 197 /*****************************************************************************/ 198 /* Structures */ 199 /*****************************************************************************/ 200 201 /** 202 ****************************************************************************** 203 * @brief Bitstream context for encoder 204 ****************************************************************************** 205 */ 206 typedef struct bitstrm 207 { 208 /** points to start of stream buffer. */ 209 UWORD8 *pu1_strm_buffer; 210 211 /** 212 * max bitstream size (in bytes). 213 * Encoded stream shall not exceed this size. 214 */ 215 UWORD32 u4_max_strm_size; 216 217 /** 218 * byte offset (w.r.t pu1_strm_buffer) where next byte would be written 219 * Bitstream engine makes sure it would not corrupt data beyond 220 * u4_max_strm_size bytes 221 */ 222 UWORD32 u4_strm_buf_offset; 223 224 /** 225 * current bitstream word; It is a scratch word containing max of 226 * WORD_SIZE bits. Will be copied to stream buffer when the word is 227 * full 228 */ 229 UWORD32 u4_cur_word; 230 231 /** 232 * signifies number of bits available in u4_cur_word 233 * bits from msb to i4_bits_left_in_cw of u4_cur_word have already been 234 * inserted next bits would be inserted from pos [i4_bits_left_in_cw-1] 235 * Range of this variable [1 : WORD_SIZE] 236 */ 237 WORD32 i4_bits_left_in_cw; 238 239 /** 240 * signifies the number of consecutive zero bytes propogated from previous 241 * word. It is used for emulation prevention byte insertion in the stream 242 */ 243 WORD32 i4_zero_bytes_run; 244 245 } bitstrm_t; 246 247 248 /*****************************************************************************/ 249 /* Extern Function Declarations */ 250 /*****************************************************************************/ 251 252 /** 253 ****************************************************************************** 254 * 255 * @brief Initializes the encoder bitstream engine 256 * 257 * @par Description 258 * This routine needs to be called at start of slice/frame encode 259 * 260 * @param[in] ps_bitstrm 261 * pointer to bitstream context (handle) 262 * 263 * @param[in] p1_bitstrm_buf 264 * bitstream buffer pointer where the encoded stream is generated in byte order 265 * 266 * @param[in] u4_max_bitstrm_size 267 * indicates maximum bitstream buffer size. (in bytes) 268 * If actual stream size exceeds the maximum size, encoder should 269 * 1. Not corrupt data beyond u4_max_bitstrm_size bytes 270 * 2. Report an error back to application indicating overflow 271 * 272 * @return success or failure error code 273 * 274 ****************************************************************************** 275 */ 276 IH264E_ERROR_T ih264e_bitstrm_init 277 ( 278 bitstrm_t *ps_bitstrm, 279 UWORD8 *pu1_bitstrm_buf, 280 UWORD32 u4_max_bitstrm_size 281 ); 282 283 /** 284 ****************************************************************************** 285 * 286 * @brief puts a code with specified number of bits into the bitstream 287 * 288 * @par Description 289 * inserts code_len number of bits from lsb of code_val into the 290 * bitstream. If the total bytes (u4_strm_buf_offset) exceeds max 291 * available size (u4_max_strm_size), returns error without corrupting data 292 * beyond it 293 * 294 * @param[in] ps_bitstrm 295 * pointer to bitstream context (handle) 296 * 297 * @param[in] u4_code_val 298 * code value that needs to be inserted in the stream. 299 * 300 * @param[in] code_len 301 * indicates code length (in bits) of code_val that would be inserted in 302 * bitstream buffer size. 303 * 304 * @remarks Assumptions: all bits from bit position code_len to msb of 305 * code_val shall be zero 306 * 307 * @return success or failure error code 308 * 309 ****************************************************************************** 310 */ 311 IH264E_ERROR_T ih264e_put_bits 312 ( 313 bitstrm_t *ps_bitstrm, 314 UWORD32 u4_code_val, 315 WORD32 code_len 316 ); 317 318 /** 319 ****************************************************************************** 320 * 321 * @brief inserts a 1-bit code into the bitstream 322 * 323 * @par Description 324 * inserts 1bit lsb of code_val into the bitstream 325 * updates context members like u4_cur_word, u4_strm_buf_offset and 326 * i4_bits_left_in_cw. If the total words (u4_strm_buf_offset) exceeds max 327 * available size (u4_max_strm_size), returns error without corrupting data 328 * beyond it 329 * 330 * @param[in] ps_bitstrm 331 * pointer to bitstream context (handle) 332 * 333 * @param[in] u4_code_val 334 * code value that needs to be inserted in the stream. 335 * 336 * @remarks Assumptions: all bits from bit position 1 to msb of code_val 337 * shall be zero 338 * 339 * @return success or failure error code 340 * 341 ****************************************************************************** 342 */ 343 IH264E_ERROR_T ih264e_put_bit 344 ( 345 bitstrm_t *ps_bitstrm, 346 UWORD32 u4_code_val 347 ); 348 349 /** 350 ****************************************************************************** 351 * 352 * @brief inserts rbsp trailing bits at the end of stream buffer (NAL) 353 * 354 * @par Description 355 * inserts rbsp trailing bits, updates context members like u4_cur_word and 356 * i4_bits_left_in_cw and flushes the same in the bitstream buffer. If the 357 * total words (u4_strm_buf_offset) exceeds max available size 358 * (u4_max_strm_size), returns error without corrupting data beyond it 359 * 360 * @param[in] ps_bitstrm 361 * pointer to bitstream context (handle) 362 * 363 * @return success or failure error code 364 * 365 ****************************************************************************** 366 */ 367 IH264E_ERROR_T ih264e_put_rbsp_trailing_bits 368 ( 369 bitstrm_t *ps_bitstrm 370 ); 371 372 /** 373 ****************************************************************************** 374 * 375 * @brief puts exponential golomb code of a unsigned integer into bitstream 376 * 377 * @par Description 378 * computes uev code for given syntax element and inserts the same into 379 * bitstream by calling ih264e_put_bits() interface. 380 * 381 * @param[in] ps_bitstrm 382 * pointer to bitstream context (handle) 383 * 384 * @param[in] u4_code_num 385 * unsigned integer input whose golomb code is written in stream 386 * 387 * @remarks Assumptions: code value can be represented in less than 16bits 388 * 389 * @return success or failure error code 390 * 391 ****************************************************************************** 392 */ 393 IH264E_ERROR_T ih264e_put_uev 394 ( 395 bitstrm_t *ps_bitstrm, 396 UWORD32 u4_code_num 397 ); 398 399 /** 400 ****************************************************************************** 401 * 402 * @brief puts exponential golomb code of a signed integer into bitstream 403 * 404 * @par Description 405 * computes sev code for given syntax element and inserts the same into 406 * bitstream by calling ih264e_put_bits() interface. 407 * 408 * @param[in] ps_bitstrm 409 * pointer to bitstream context (handle) 410 * 411 * @param[in] syntax_elem 412 * signed integer input whose golomb code is written in stream 413 * 414 * @remarks Assumptions: code value can be represented in less than 16bits 415 * 416 * @return success or failure error code 417 * 418 ****************************************************************************** 419 */ 420 IH264E_ERROR_T ih264e_put_sev 421 ( 422 bitstrm_t *ps_bitstrm, 423 WORD32 syntax_elem 424 ); 425 426 /** 427 ****************************************************************************** 428 * 429 * @brief insert NAL start code prefix (0x000001) into bitstream with an option 430 * of inserting leading_zero_8bits (which makes startcode prefix as 0x00000001) 431 * 432 * @par Description 433 * Although start code prefix could have been put by calling ih264e_put_bits(), 434 * ih264e_put_nal_start_code_prefix() is specially added to make sure emulation 435 * prevention insertion is not done for the NAL start code prefix which will 436 * surely happen otherwise by calling ih264e_put_bits() interface. 437 * 438 * @param[in] ps_bitstrm 439 * pointer to bitstream context (handle) 440 * 441 * @param[in] insert_leading_zero_8bits 442 * flag indicating if one more zero bytes needs to prefixed before start code 443 * 444 * @return success or failure error code 445 * 446 ****************************************************************************** 447 */ 448 IH264E_ERROR_T ih264e_put_nal_start_code_prefix 449 ( 450 bitstrm_t *ps_bitstrm, 451 WORD32 insert_leading_zero_8bits 452 ); 453 454 #endif /* IH264E_BITSTREAM_H_ */ 455