1 /*
2 * Bitstream filters public API
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21 #ifndef AVCODEC_BSF_H
22 #define AVCODEC_BSF_H
23
27
31
32 /**
33 * @addtogroup lavc_core
34 * @{
35 */
36
37 /**
38 * The bitstream filter state.
39 *
40 * This struct must be allocated with av_bsf_alloc() and freed with
41 * av_bsf_free().
42 *
43 * The fields in the struct will only be changed (by the caller or by the
44 * filter) as described in their documentation, and are to be considered
45 * immutable otherwise.
46 */
48 /**
49 * A class for logging and AVOptions
50 */
52
53 /**
54 * The bitstream filter this context is an instance of.
55 */
57
58 /**
59 * Opaque filter-specific private data. If filter->priv_class is non-NULL,
60 * this is an AVOptions-enabled struct.
61 */
63
64 /**
65 * Parameters of the input stream. This field is allocated in
66 * av_bsf_alloc(), it needs to be filled by the caller before
67 * av_bsf_init().
68 */
70
71 /**
72 * Parameters of the output stream. This field is allocated in
73 * av_bsf_alloc(), it is set by the filter in av_bsf_init().
74 */
76
77 /**
78 * The timebase used for the timestamps of the input packets. Set by the
79 * caller before av_bsf_init().
80 */
82
83 /**
84 * The timebase used for the timestamps of the output packets. Set by the
85 * filter in av_bsf_init().
86 */
89
92
93 /**
94 * A list of codec ids supported by the filter, terminated by
95 * AV_CODEC_ID_NONE.
96 * May be NULL, in that case the bitstream filter works with any codec id.
97 */
99
100 /**
101 * A class for the private data, used to declare bitstream filter private
102 * AVOptions. This field is NULL for bitstream filters that do not declare
103 * any options.
104 *
105 * If this field is non-NULL, the first member of the filter private data
106 * must be a pointer to AVClass, which will be set by libavcodec generic
107 * code to this class.
108 */
110
111 /*****************************************************************
112 * No fields below this line are part of the public API. They
113 * may not be used outside of libavcodec and can be changed and
114 * removed at will.
115 * New public fields should be added right above.
116 *****************************************************************
117 */
118
125
126 /**
127 * @return a bitstream filter with the specified name or NULL if no such
128 * bitstream filter exists.
129 */
131
132 /**
133 * Iterate over all registered bitstream filters.
134 *
135 * @param opaque a pointer where libavcodec will store the iteration state. Must
136 * point to NULL to start the iteration.
137 *
138 * @return the next registered bitstream filter or NULL when the iteration is
139 * finished
140 */
142
143 /**
144 * Allocate a context for a given bitstream filter. The caller must fill in the
145 * context parameters as described in the documentation and then call
146 * av_bsf_init() before sending any data to the filter.
147 *
148 * @param filter the filter for which to allocate an instance.
149 * @param ctx a pointer into which the pointer to the newly-allocated context
150 * will be written. It must be freed with av_bsf_free() after the
151 * filtering is done.
152 *
153 * @return 0 on success, a negative AVERROR code on failure
154 */
156
157 /**
158 * Prepare the filter for use, after all the parameters and options have been
159 * set.
160 */
162
163 /**
164 * Submit a packet for filtering.
165 *
166 * After sending each packet, the filter must be completely drained by calling
167 * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
168 * AVERROR_EOF.
169 *
170 * @param pkt the packet to filter. The bitstream filter will take ownership of
171 * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
172 * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
173 * it signals the end of the stream (i.e. no more non-empty packets will be sent;
174 * sending more empty packets does nothing) and will cause the filter to output
175 * any packets it may have buffered internally.
176 *
177 * @return 0 on success. AVERROR(EAGAIN) if packets need to be retrieved from the
178 * filter (using av_bsf_receive_packet()) before new input can be consumed. Another
179 * negative AVERROR value if an error occurs.
180 */
182
183 /**
184 * Retrieve a filtered packet.
185 *
186 * @param[out] pkt this struct will be filled with the contents of the filtered
187 * packet. It is owned by the caller and must be freed using
188 * av_packet_unref() when it is no longer needed.
189 * This parameter should be "clean" (i.e. freshly allocated
190 * with av_packet_alloc() or unreffed with av_packet_unref())
191 * when this function is called. If this function returns
192 * successfully, the contents of pkt will be completely
193 * overwritten by the returned data. On failure, pkt is not
194 * touched.
195 *
196 * @return 0 on success. AVERROR(EAGAIN) if more packets need to be sent to the
197 * filter (using av_bsf_send_packet()) to get more output. AVERROR_EOF if there
198 * will be no further output from the filter. Another negative AVERROR value if
199 * an error occurs.
200 *
201 * @note one input packet may result in several output packets, so after sending
202 * a packet with av_bsf_send_packet(), this function needs to be called
203 * repeatedly until it stops returning 0. It is also possible for a filter to
204 * output fewer packets than were sent to it, so this function may return
205 * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
206 */
208
209 /**
210 * Reset the internal bitstream filter state. Should be called e.g. when seeking.
211 */
213
214 /**
215 * Free a bitstream filter context and everything associated with it; write NULL
216 * into the supplied pointer.
217 */
219
220 /**
221 * Get the AVClass for AVBSFContext. It can be used in combination with
222 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
223 *
224 * @see av_opt_find().
225 */
227
228 /**
229 * Structure for chain/list of bitstream filters.
230 * Empty list can be allocated by av_bsf_list_alloc().
231 */
233
234 /**
235 * Allocate empty list of bitstream filters.
236 * The list must be later freed by av_bsf_list_free()
237 * or finalized by av_bsf_list_finalize().
238 *
239 * @return Pointer to @ref AVBSFList on success, NULL in case of failure
240 */
242
243 /**
244 * Free list of bitstream filters.
245 *
246 * @param lst Pointer to pointer returned by av_bsf_list_alloc()
247 */
249
250 /**
251 * Append bitstream filter to the list of bitstream filters.
252 *
253 * @param lst List to append to
254 * @param bsf Filter context to be appended
255 *
256 * @return >=0 on success, negative AVERROR in case of failure
257 */
259
260 /**
261 * Construct new bitstream filter context given it's name and options
262 * and append it to the list of bitstream filters.
263 *
264 * @param lst List to append to
265 * @param bsf_name Name of the bitstream filter
266 * @param options Options for the bitstream filter, can be set to NULL
267 *
268 * @return >=0 on success, negative AVERROR in case of failure
269 */
271 /**
272 * Finalize list of bitstream filters.
273 *
274 * This function will transform @ref AVBSFList to single @ref AVBSFContext,
275 * so the whole chain of bitstream filters can be treated as single filter
276 * freshly allocated by av_bsf_alloc().
277 * If the call is successful, @ref AVBSFList structure is freed and lst
278 * will be set to NULL. In case of failure, caller is responsible for
279 * freeing the structure by av_bsf_list_free()
280 *
281 * @param lst Filter list structure to be transformed
282 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
283 * representing the chain of bitstream filters
284 *
285 * @return >=0 on success, negative AVERROR in case of failure
286 */
288
289 /**
290 * Parse string describing list of bitstream filters and create single
291 * @ref AVBSFContext describing the whole chain of bitstream filters.
292 * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
293 * allocated by av_bsf_alloc().
294 *
295 * @param str String describing chain of bitstream filters in format
296 * `bsf1[=opt1=val1:opt2=val2][,bsf2]`
297 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
298 * representing the chain of bitstream filters
299 *
300 * @return >=0 on success, negative AVERROR in case of failure
301 */
303
304 /**
305 * Get null/pass-through bitstream filter.
306 *
307 * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
308 *
309 * @return
310 */
312
313 /**
314 * @}
315 */
316
317 #endif // AVCODEC_BSF_H