1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27#ifndef VC_PACKETIZERS_H
28#define VC_PACKETIZERS_H
29
30/** \file packetizers.h
31 * Public API for packetizing data (i.e. framing and timestamping)
32 */
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38#include "containers/containers.h"
39
40/** \defgroup VcPacketizerApi Packetizer API
41 * API for packetizers */
42/* @{ */
43
44/** \name Packetizer flags
45 * \anchor packetizerflags
46 * The following flags describe properties of a packetizer */
47/* @{ */
48#define VC_PACKETIZER_FLAG_ES_CHANGED 0x1 /**< ES definition has changed */
49/* @} */
50
51/** Definition of the packetizer type */
52typedef struct VC_PACKETIZER_T
53{
54 struct VC_PACKETIZER_PRIVATE_T *priv; /**< Private member used by the implementation */
55 uint32_t flags; /**< Flags describing the properties of a packetizer.
56 * See \ref packetizerflags "Packetizer flags". */
57
58 VC_CONTAINER_ES_FORMAT_T *in; /**< Format of the input elementary stream */
59 VC_CONTAINER_ES_FORMAT_T *out; /**< Format of the output elementary stream */
60
61 uint32_t max_frame_size; /**< Maximum size of a packetized frame */
62
63} VC_PACKETIZER_T;
64
65/** Open a packetizer to convert the input format into the requested output format.
66 * This will create an an instance of a packetizer and its associated context.
67 *
68 * If no packetizer is found for the requested format, this will return a null pointer as well as
69 * an error code indicating why this failed.
70 *
71 * \param in Input elementary stream format
72 * \param out_variant Requested output variant for the output elementary stream format
73 * \param status Returns the status of the operation
74 * \return A pointer to the context of the new instance of the packetizer.
75 * Returns NULL on failure.
76 */
77VC_PACKETIZER_T *vc_packetizer_open(VC_CONTAINER_ES_FORMAT_T *in, VC_CONTAINER_FOURCC_T out_variant,
78 VC_CONTAINER_STATUS_T *status);
79
80/** Closes an instance of a packetizer.
81 * This will free all the resources associated with the context.
82 *
83 * \param context Pointer to the context of the instance to close
84 * \return the status of the operation
85 */
86VC_CONTAINER_STATUS_T vc_packetizer_close( VC_PACKETIZER_T *context );
87
88/** \name Packetizer flags
89 * The following flags can be passed during a packetize call */
90/* @{ */
91/** Type definition for the packetizer flags */
92typedef uint32_t VC_PACKETIZER_FLAGS_T;
93/** Ask the packetizer to only return information on the next packet without reading it */
94#define VC_PACKETIZER_FLAG_INFO 0x1
95/** Ask the packetizer to skip the next packet */
96#define VC_PACKETIZER_FLAG_SKIP 0x2
97/** Ask the packetizer to flush any data being processed */
98#define VC_PACKETIZER_FLAG_FLUSH 0x4
99/** Force the packetizer to release an input packet */
100#define VC_PACKETIZER_FLAG_FORCE_RELEASE_INPUT 0x8
101/* @} */
102
103/** Push a new packet of data to the packetizer.
104 * This is the mechanism used to feed data into the packetizer. Once a packet has been
105 * pushed into the packetizer it is owned by the packetizer until released by a call to
106 * \ref vc_packetizer_pop
107 *
108 * \param context Pointer to the context of the packetizer to use
109 * \param packet Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
110 * to push into the packetizer.
111 * \return the status of the operation
112 */
113VC_CONTAINER_STATUS_T vc_packetizer_push( VC_PACKETIZER_T *context,
114 VC_CONTAINER_PACKET_T *packet);
115
116/** Pop a packet of data from the packetizer.
117 * This allows the client to retrieve consumed data from the packetizer. Packets returned by
118 * the packetizer in this manner can then be released / recycled by the client.
119 * It is possible for the client to retrieve non-consumed data by passing the
120 * VC_PACKETIZER_FLAG_FORCE_RELEASE_INPUT flag. This will however trigger some internal buffering
121 * inside the packetizer and thus is less efficient.
122 *
123 * \param context Pointer to the context of the packetizer to use
124 * \param packet Pointer used to return a consumed packet
125 * \param flags Miscellaneous flags controlling the operation
126 *
127 * \return VC_CONTAINER_SUCCESS if a consumed packet was retrieved,
128 * VC_CONTAINER_ERROR_INCOMPLETE_DATA if none is available.
129 */
130VC_CONTAINER_STATUS_T vc_packetizer_pop( VC_PACKETIZER_T *context,
131 VC_CONTAINER_PACKET_T **packet, VC_PACKETIZER_FLAGS_T flags);
132
133/** Read packetized data out of the packetizer.
134 *
135 * \param context Pointer to the context of the packetizer to use
136 * \param packet Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
137 * This might need to be partially filled before the call (buffer, buffer_size)
138 * depending on the flags used.
139 * \param flags Miscellaneous flags controlling the operation
140 * \return the status of the operation
141 */
142VC_CONTAINER_STATUS_T vc_packetizer_read( VC_PACKETIZER_T *context,
143 VC_CONTAINER_PACKET_T *out, VC_PACKETIZER_FLAGS_T flags);
144
145/** Reset packetizer state.
146 * This will reset the state of the packetizer as well as mark all data pushed to it as consumed.
147 *
148 * \param context Pointer to the context of the packetizer to reset
149 * \return the status of the operation
150 */
151VC_CONTAINER_STATUS_T vc_packetizer_reset( VC_PACKETIZER_T *context );
152
153/* @} */
154
155#ifdef __cplusplus
156}
157#endif
158
159#endif /* VC_PACKETIZERS_H */
160