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 */ 206typedef 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*/ 276IH264E_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*/ 311IH264E_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*/ 343IH264E_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*/ 367IH264E_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*/ 393IH264E_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*/ 420IH264E_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*/ 448IH264E_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