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_cabac_structs.h
25  *
26  * @brief
27  *  This file contains cabac related macros, enums, tables and function declarations.
28  *
29  * @author
30  *  Doney Alex
31  *
32  * @remarks
33  *  none
34  *
35  *******************************************************************************
36  */
37 
38 #ifndef IH264E_CABAC_H_
39 #define IH264E_CABAC_H_
40 
41 
42 
43 /*******************************************************************************
44 @brief Bit precision of cabac engine;
45 *******************************************************************************
46 */
47 #define CABAC_BITS  9
48 
49 
50 /**
51 ******************************************************************************
52  *  @macro Reverse bits in an unsigned integer
53 ******************************************************************************
54 */
55 #define REV(u4_input, u4_output)                 \
56 {                                                \
57     UWORD32 u4_temp = (u4_input);                \
58     WORD8 i;                                     \
59     u4_output = 0;                               \
60     for (i = 0; i < 32; i++)                     \
61     {                                            \
62         u4_output = (u4_output << 1) +           \
63                         ((u4_temp >> i) & 0x01); \
64     }                                            \
65 }
66 
67 /**
68 ******************************************************************************
69 *! Bit manipulation macros
70 ******************************************************************************
71 */
72 #define SETBIT(a, i)   ((a) |= (1 << (i)))
73 #define CLEARBIT(a, i) ((a) &= ~(1 << (i)))
74 
75 
76 /**
77 ******************************************************************************
78 *! Cabac module expect atlesat MIN_STREAM_SIZE_MB bytes left in stream buffer
79 *! for encoding an MB
80 ******************************************************************************
81 */
82 #define MIN_STREAM_SIZE_MB   1024
83 
84 
85 
86 /*****************************************************************************/
87 /* Function Declarations                                                 */
88 /*****************************************************************************/
89 
90 
91 /**
92  *******************************************************************************
93  *
94  * @brief
95  * Initialize default context values and pointers.
96  *
97  * @param[in] ps_ent_ctxt
98  *  Pointer to entropy context structure
99  *
100  * @returns
101  *
102  * @remarks
103  *  None
104  *
105  *******************************************************************************
106  */
107 void ih264e_init_cabac_table(entropy_ctxt_t *ps_ent_ctxt);
108 
109 
110 /**
111  *******************************************************************************
112  *
113  * @brief
114  * Initialize cabac context: Intitalize all contest with init values given in the spec.
115  * Called at the beginning of entropy coding of each slice for CABAC encoding.
116  *
117  * @param[in] ps_ent_ctxt
118  *  Pointer to entropy context structure
119  *
120  * @returns
121  *
122  * @remarks
123  *  None
124  *
125  *******************************************************************************
126  */
127 void ih264e_init_cabac_ctxt(entropy_ctxt_t *ps_ent_ctxt);
128 
129 
130 
131 /**
132  *******************************************************************************
133  *
134  * @brief
135  *  k-th order Exp-Golomb (UEGk) binarization process: Implements concatenated
136  *   unary/ k-th order Exp-Golomb  (UEGk) binarization process,
137  *   where k = 0 as defined in 9.3.2.3 of  ITU_T_H264-201402
138  *
139  * @param[in] i2_sufs
140  *  Suffix bit string
141  *
142  * @param[in] pi1_bins_len
143  *  Pointer to length of the string
144  *
145  * @returns Binarized value
146  *
147  * @remarks
148  *  None
149  *
150  *******************************************************************************
151  */
152 UWORD32 ih264e_cabac_UEGk0_binarization(WORD16 i2_sufs, WORD8 *pi1_bins_len);
153 
154 
155 /**
156  *******************************************************************************
157  *
158  * @brief
159  *  Get cabac context for the MB :calculates the pointers to Top and   left
160  *          cabac neighbor context depending upon neighbor  availability.
161  *
162  * @param[in] ps_ent_ctxt
163  *  Pointer to entropy context structure
164  *
165  * @param[in] u4_mb_type
166  *  Type of MB
167  *
168  * @returns
169  *
170  * @remarks
171  *  None
172  *
173  *******************************************************************************
174  */
175 void ih264e_get_cabac_context(entropy_ctxt_t *ps_ent_ctxt, WORD32 u4_mb_type);
176 
177 
178 /**
179  *******************************************************************************
180  * @brief
181  *  flushing at termination: Explained in flowchart 9-12(ITU_T_H264-201402).
182  *
183  *  @param[in]   ps_cabac_ctxt
184  *  pointer to cabac context (handle)
185  *
186  * @returns  none
187  *
188  * @remarks
189  *  None
190  *
191  *******************************************************************************
192  */
193 IH264E_ERROR_T ih264e_cabac_flush(cabac_ctxt_t *ps_cabac_ctxt);
194 
195 
196 /**
197  ******************************************************************************
198  *
199  *  @brief Puts new byte (and outstanding bytes) into bitstream after cabac
200  *         renormalization
201  *
202  *  @par   Description
203  *  1. Extract the leading byte of low(L)
204  *  2. If leading byte=0xff increment outstanding bytes and return
205  *     (as the actual bits depend on carry propogation later)
206  *  3. If leading byte is not 0xff check for any carry propogation
207  *  4. Insert the carry (propogated in previous byte) along with outstanding
208  *     bytes (if any) and leading byte
209  *
210  *
211  *  @param[inout]   ps_cabac_ctxt
212  *  pointer to cabac context (handle)
213  *
214  *  @return
215  *
216  ******************************************************************************
217  */
218 IH264E_ERROR_T ih264e_cabac_put_byte(cabac_ctxt_t *ps_cabac_ctxt);
219 
220 
221 /**
222  ******************************************************************************
223  *
224  *  @brief Codes a bin based on probablilty and mps packed context model
225  *
226  *  @par   Description
227  *  1. Apart from encoding bin, context model is updated as per state transition
228  *  2. Range and Low renormalization is done based on bin and original state
229  *  3. After renorm bistream is updated (if required)
230  *
231  *  @param[inout]   ps_cabac
232  *  pointer to cabac context (handle)
233  *
234  *  @param[in]   bin
235  *  bin(boolean) to be encoded
236  *
237  *  @param[in]  pu1_bin_ctxts
238  *  index of cabac context model containing pState[bits 5-0] | MPS[bit6]
239  *
240  *  @return
241  *
242  ******************************************************************************
243  */
244 void ih264e_cabac_encode_bin(cabac_ctxt_t *ps_cabac, WORD32 bin,
245                              bin_ctxt_model *pu1_bin_ctxts);
246 
247 
248 
249 /**
250  *******************************************************************************
251  *
252  * @brief
253  *  Encoding process for a binary decision :implements encoding process of a decision
254  *  as defined in 9.3.4.2 . This function encodes multiple bins, of a symbol. Implements
255  *  flowchart Figure 9-7( ITU_T_H264-201402)
256  *
257  * @param[in] u4_bins
258  * array of bin values
259  *
260  * @param[in] i1_bins_len
261  *  Length of bins, maximum 32
262  *
263  * @param[in] u4_ctx_inc
264  *  CtxInc, byte0- bin0, byte1-bin1 ..
265  *
266  * @param[in] i1_valid_len
267  *  valid length of bins, after that CtxInc is constant
268  *
269  * @param[in] pu1_bin_ctxt_type
270  *  Pointer to binary contexts
271 
272  * @param[in] ps_cabac
273  *  Pointer to cabac_context_structure
274  *
275  * @returns
276  *
277  * @remarks
278  *  None
279  *
280  *******************************************************************************
281  */
282 void ih264e_encode_decision_bins(UWORD32 u4_bins, WORD8 i1_bins_len,
283                                  UWORD32 u4_ctx_inc, WORD8 i1_valid_len,
284                                  bin_ctxt_model *pu1_bin_ctxt_type,
285                                  cabac_ctxt_t *ps_cabac);
286 
287 /**
288  *******************************************************************************
289  * @brief
290  *  Encoding process for a binary decision before termination:Encoding process
291  *  of a termination(9.3.4.5 :ITU_T_H264-201402) . Explained in flowchart 9-11.
292  *
293  * @param[in] ps_cabac
294  *  Pointer to cabac structure
295  *
296  * @param[in] term_bin
297  *  Symbol value, end of slice or not, term_bin is binary
298  *
299  * @returns
300  *
301  * @remarks
302  *  None
303  *
304  *******************************************************************************
305  */
306 void ih264e_cabac_encode_terminate(cabac_ctxt_t *ps_cabac, WORD32 term_bin);
307 
308 
309 /**
310  *******************************************************************************
311  * @brief
312  * Bypass encoding process for binary decisions:  Explained (9.3.4.4 :ITU_T_H264-201402)
313  * , flowchart 9-10.
314  *
315  *  @param[in]  ps_cabac : pointer to cabac context (handle)
316  *
317  *  @param[in]   bin :  bypass bin(0/1) to be encoded
318  *
319  *  @returns
320  *
321  *  @remarks
322  *  None
323  *
324  *******************************************************************************
325  */
326 
327 void ih264e_cabac_encode_bypass_bin(cabac_ctxt_t *ps_cabac, WORD32 bin);
328 
329 
330 
331 /**
332  ******************************************************************************
333  *
334  *  @brief Encodes a series of bypass bins (FLC bypass bins)
335  *
336  *  @par   Description
337  *  This function is more optimal than calling ih264e_cabac_encode_bypass_bin()
338  *  in a loop as cabac low, renorm and generating the stream (8bins at a time)
339  *  can be done in one operation
340  *
341  *  @param[inout]ps_cabac
342  *   pointer to cabac context (handle)
343  *
344  *  @param[in]   u4_bins
345  *   syntax element to be coded (as FLC bins)
346  *
347  *  @param[in]   num_bins
348  *   This is the FLC length for u4_sym
349  *
350  *  @return
351  *
352  ******************************************************************************
353  */
354 
355 void ih264e_cabac_encode_bypass_bins(cabac_ctxt_t *ps_cabac, UWORD32 u4_bins,
356                                      WORD32 num_bins);
357 
358 
359 
360 
361 
362 /**
363  *******************************************************************************
364  *
365  * @brief
366  *  This function generates CABAC coded bit stream for an Intra Slice.
367  *
368  * @description
369  *  The mb syntax layer for intra slices constitutes luma mb mode, luma sub modes
370  *  (if present), mb qp delta, coded block pattern, chroma mb mode and
371  *  luma/chroma residue. These syntax elements are written as directed by table
372  *  7.3.5 of h264 specification.
373  *
374  * @param[in] ps_ent_ctxt
375  *  pointer to entropy context
376  *
377  * @returns error code
378  *
379  * @remarks none
380  *
381  *******************************************************************************
382  */
383 IH264E_ERROR_T ih264e_write_islice_mb_cabac(entropy_ctxt_t *ps_ent_ctxt);
384 
385 
386 /**
387  *******************************************************************************
388  *
389  * @brief
390  *  This function generates CABAC coded bit stream for Inter slices
391  *
392  * @description
393  *  The mb syntax layer for inter slices constitutes luma mb mode, luma sub modes
394  *  (if present), mb qp delta, coded block pattern, chroma mb mode and
395  *  luma/chroma residue. These syntax elements are written as directed by table
396  *  7.3.5 of h264 specification
397  *
398  * @param[in] ps_ent_ctxt
399  *  pointer to entropy context
400  *
401  * @returns error code
402  *
403  * @remarks none
404  *
405  *******************************************************************************
406  */
407 IH264E_ERROR_T ih264e_write_pslice_mb_cabac(entropy_ctxt_t *ps_ent_ctxt);
408 
409 
410 /**
411  *******************************************************************************
412  *
413  * @brief
414  *  This function generates CABAC coded bit stream for B slices
415  *
416  * @description
417  *  The mb syntax layer for inter slices constitutes luma mb mode,
418  *  mb qp delta, coded block pattern, chroma mb mode and
419  *  luma/chroma residue. These syntax elements are written as directed by table
420  *  7.3.5 of h264 specification
421  *
422  * @param[in] ps_ent_ctxt
423  *  pointer to entropy context
424  *
425  * @returns error code
426  *
427  * @remarks none
428  *
429  *******************************************************************************
430  */
431 IH264E_ERROR_T ih264e_write_bslice_mb_cabac(entropy_ctxt_t *ps_ent_ctxt);
432 
433 
434 #endif /* IH264E_CABAC_H_ */
435