source: svn/trunk/newcon3bcm2_21bu/magnum/syslib/vbilib/bvbilib_dccreorder.h

Last change on this file was 2, checked in by jglee, 11 years ago

first commit
  • Property svn:executable set to *
File size: 10.4 KB
Line 
1/***************************************************************************
2 *     Copyright (c) 2007, Broadcom Corporation
3 *     All Rights Reserved
4 *     Confidential Property of Broadcom Corporation
5 *
6 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
7 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
8 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
9 *
10 * $brcm_Workfile: bvbilib_dccreorder.h $
11 * $brcm_Revision: Hydra_Software_Devel/5 $
12 * $brcm_Date: 5/29/07 1:12p $
13 *
14 * Module Description:
15 *
16 * Revision History:
17 *
18 * $brcm_Log: /magnum/syslib/vbilib/bvbilib_dccreorder.h $
19 *
20 * Hydra_Software_Devel/5   5/29/07 1:12p darnstein
21 * PR31097: fix an ordinary typing error.
22 *
23 * Hydra_Software_Devel/4   5/25/07 6:09p darnstein
24 * PR31097: ready for testing now.
25 *
26 * Hydra_Software_Devel/3   5/24/07 6:54p darnstein
27 * PR31097: Expand tabs for readability. I won't keep doing this forever.
28 *
29 * Hydra_Software_Devel/2   5/24/07 6:50p darnstein
30 * PR31097: Second draft of the proposed API.
31 *
32 ***************************************************************************/
33
34/*= Module Overview *********************************************************
35<verbatim>
36
37Overview:
38
39BVBIlibDCCReorder module provides solves a temporary problem for
40some headend equipment. The problem at hand is an MPEG or AVC
41bitstream containing closed caption data that has been reordered. In
42particular, the bitstream will contain repeated top field data and
43repeated bottom field data.
44
45This situation leads to missed opportunities for the VEC closed
46caption encoder to insert its waveform into video fields. This causes
47the queue of waiting closed caption data to grow without bound.
48
49The 'Reorder module simply rearranges pieces of closed caption
50data. It attempts to restore the alternating top/bottom/top/bottom
51ordering of the data.
52
53Usage:
54
55The module has a state that is stored in a handle object, and it
56must be initialized:
57
58    BVBIlib_DCCReorder_Open (&handle, histSize, threshold);
59
60Thereafter, there are two API calls BVBIlib_DCCReorder_Put()
61and BVBIlib_DCCReorder_Get() that should be called after calling
62one of the BVBIlib_DCCparseXXX functions. For best results, these
63two BVBIlib_DCCReorder calls should NOT be interleaved. This will
64give the reordering algorithm maximum opportunity to find a good
65reordering. For example:
66
67    BVBIlib_DCCparse (&info, offset, &bytesParsed, &cc_count, ccdata);
68    for (icount = 0 ; icount < cc_count ; ++icount)
69    {
70        BAVC_Polarity polarity;
71        BVBIlib_DCCparse_ccdata* pccdata = &ccdata[icount];
72        if (!pccdata->bIsAnalog) continue;
73        if (pccdata->format != BVBIlib_DCCparse_Format_ATSC53) continue;
74        if (pccdata->polarity == BAVC_Polarity_eFrame) continue;
75        BVBIlib_DCCReorder_Put (
76            handle, pccdata->cc_data_1, pccdata->cc_data_2, pccdata->polarity);
77    }
78
79    uint8_t datumL;
80    uint8_t datumH;
81    BAVC_Polarity polarity;
82    while (BVBIlib_DCCReorder_Get (handle, &datumL, &datumH, &polarity) ==
83        BERR_SUCCESS)
84    {
85        BVBI_Field_Handle hField;
86        uint8_t parityMask = (1 << polarity);
87        BVBI_Field_SetCCData_isr (hField, datumL, datumH);
88        BVBI_Field_SetPolarity_isr (hField, parityMask);
89        BVBIlib_Encode_Enqueue_isr (hVbilibEncode, hField);
90    }
91
92Note:
93
94This module misuses the defined symbol BERR_OUT_OF_SYSTEM_MEMORY in
95several places. This module is expected to have a limited life time,
96so it is better to NOT define new global symbols instead.
97
98</verbatim>
99***************************************************************************/
100
101#ifndef BVBILIBDCCREORDER_H__
102#define BVBILIBDCCREORDER_H__
103
104#include "bstd.h"
105#include "bavc.h"
106
107/* Structures */
108
109/*****************************************************************************
110  Summary:
111    The BVBIlib_DCCReorder_Handle, once opened, stores the state
112    of the BVBIlib_DCCReorder module. It is a required argument to
113    all other BVBIlib_DCCReorder functions.
114
115  See Also:
116    BVBIlib_DCCReorder_Open, BVBIlib_DCCReorder_Close
117*****************************************************************************/
118typedef struct BVBIlib_P_DCCReorder_Handle* 
119    BVBIlib_DCCReorder_Handle; /* Opaque */
120
121
122/*****************************************************************************
123 * Public API
124 *****************************************************************************/
125
126/*****************************************************************************
127  Summary:
128    Initializes and configures state for BVBIlib_DCCReorder module.
129
130  Description:
131    This function initializes the BVBIlib_DCCReorder queueing/reordering
132    module. The user indicates the amount of memory to be used, and the
133    function returns a handle, which is used for all subsequent calls into
134    the BVBIlib_DCCReorder module.
135
136  Returns:
137    BERR_SUCCESS              - The handle was successfully created.
138    BERR_OUT_OF_SYSTEM_MEMORY - Memory allocation failed.
139
140  See Also:
141    BVBILIB_DCCReorder_Close
142*****************************************************************************/
143BERR_Code BVBIlib_DCCReorder_Open (
144    BVBIlib_DCCReorder_Handle* pHandle, /* [out] Initialized module handle. */
145    unsigned int histSize,              /*  [in] Maximum number of top
146                                                 field closed caption data
147                                                                         and bottom field closed
148                                                                         caption data that the
149                                                                         module will remember. THIS
150                                                                         MUST BE A POWER OF 2!      */
151    unsigned int threshold              /*  [in] Affects how aggressive
152                                                 BVBIlib_DCCReorder_Get
153                                                                         will be about returning CC
154                                                                         data with "bad" polarity.
155                                                                         See the description of
156                                                                         that function for details. */
157);
158
159/*****************************************************************************
160  Summary:
161    Destroys module handle and frees storage space.
162
163  Description:
164    This function destroys the BVBIlib_DCCReorder queueing/reordering
165    module and frees resources (memory) used by the module. Any stored
166    closed caption data is lost.
167
168  See Also:
169    BVBILIB_DCCReorder_Open
170*****************************************************************************/
171void BVBIlib_DCCReorder_Close (
172    BVBIlib_DCCReorder_Handle handle /* [in] Initialized module handle.     */
173);
174
175/*****************************************************************************
176  Summary:
177    Stores one piece of closed caption data in module.
178
179  Description:
180    This function accepts one piece of closed caption data into the
181    BVBIlib_DCCReorder module, as long as there is room for it.
182
183  Returns:
184    BERR_SUCCESS              - Success.
185    BERR_INVALID_PARAMETER    - Invalid handle detected.
186    BERR_OUT_OF_SYSTEM_MEMORY - No room in queues for any more data.
187
188  See Also:
189    BVBILIB_DCCReorder_Get
190*****************************************************************************/
191BERR_Code BVBIlib_DCCReorder_Put (
192    BVBIlib_DCCReorder_Handle handle, /* [in] Initialized module handle.    */
193    uint8_t pDatumL,                  /* [in] Closed caption data, low
194                                              byte.                         */
195    uint8_t pDatumH,                  /* [in] Closed caption data, high
196                                              byte.                         */
197    BAVC_Polarity pPolarity           /* [in] Field polarity required for
198                                              the above closed caption
199                                              data.                         */
200);
201
202/*****************************************************************************
203  Summary:
204    Retrieves one piece of closed caption data from module.
205
206  Description:
207    This function retrieves one piece of reordered, closed
208    caption data from the BVBIlib_DCCReorder module.
209
210    This function "tries" to return alternating top and bottom field closed
211    caption data in repeated calls to it. The details of this algorithm depend
212    on the threshold argument passed in to BVBIlib_DCCReorder_Open and are as
213    follows:
214
215    If the module contains a piece "xxx" of closed caption data having
216    opposite polarity as the last piece of closed caption data returned,
217    then datum "xxx" will be returned.
218
219    Otherwise, if the module contains (histSize - threshold) pieces of
220    top field or bottom field data, then one of those pieces of data will
221    be returned. Here, histSize and threshold are the arguments that were
222    passed in to function BVBIlib_DCCReorder_Open.
223
224  Returns:
225    BERR_SUCCESS              - Success.
226    BERR_INVALID_PARAMETER    - Invalid handle detected.
227    BERR_OUT_OF_SYSTEM_MEMORY - No stored data in module to return, according
228                                to the rules above.
229
230  See Also:
231    BVBILIB_DCCReorder_Put
232*****************************************************************************/
233BERR_Code BVBIlib_DCCReorder_Get (
234    BVBIlib_DCCReorder_Handle handle,  /*  [in] Initialized module handle.  */
235    uint8_t* datumL,                   /* [out] Returned closed caption
236                                                data, low byte.             */
237    uint8_t* datumH,                   /* [out] Returned closed caption
238                                                data, high byte.            */
239    BAVC_Polarity* polarity            /* [out] Field polarity required for
240                                                the above closed caption
241                                                data.                       */
242);
243
244/*****************************************************************************
245  Summary:
246    Indicates how full the queues in the BVBIlib_DCCReorder module are.
247
248  Description:
249    This function counts the number of pieces of closed caption top
250    field data, and the number of pieces of closed caption bottom
251    field data. It returns the maximum of these two numbers.
252
253  Returns:
254    BERR_SUCCESS              - Success.
255    BERR_INVALID_PARAMETER    - Invalid handle detected.
256
257*****************************************************************************/
258BERR_Code BVBIlib_DCCReorder_Count (
259    BVBIlib_DCCReorder_Handle* handle, /*  [in] Initialized module handle.  */
260    unsigned int* count                /* [out] Maximum queue length, as
261                                                defined above.              */
262);
263
264
265#endif /* BVBILIBDCCREORDER_H__ */
Note: See TracBrowser for help on using the repository browser.