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
24#include "libavutil/dict.h"
25#include "libavutil/log.h"
26#include "libavutil/rational.h"
27
28#include "codec_id.h"
29#include "codec_par.h"
30#include "packet.h"
31
32/**
33 * @addtogroup lavc_core
34 * @{
35 */
36
37typedef struct AVBSFInternal AVBSFInternal;
38
39/**
40 * The bitstream filter state.
41 *
42 * This struct must be allocated with av_bsf_alloc() and freed with
43 * av_bsf_free().
44 *
45 * The fields in the struct will only be changed (by the caller or by the
46 * filter) as described in their documentation, and are to be considered
47 * immutable otherwise.
48 */
49typedef struct AVBSFContext {
50 /**
51 * A class for logging and AVOptions
52 */
53 const AVClass *av_class;
54
55 /**
56 * The bitstream filter this context is an instance of.
57 */
58 const struct AVBitStreamFilter *filter;
59
60 /**
61 * Opaque libavcodec internal data. Must not be touched by the caller in any
62 * way.
63 */
64 AVBSFInternal *internal;
65
66 /**
67 * Opaque filter-specific private data. If filter->priv_class is non-NULL,
68 * this is an AVOptions-enabled struct.
69 */
70 void *priv_data;
71
72 /**
73 * Parameters of the input stream. This field is allocated in
74 * av_bsf_alloc(), it needs to be filled by the caller before
75 * av_bsf_init().
76 */
77 AVCodecParameters *par_in;
78
79 /**
80 * Parameters of the output stream. This field is allocated in
81 * av_bsf_alloc(), it is set by the filter in av_bsf_init().
82 */
83 AVCodecParameters *par_out;
84
85 /**
86 * The timebase used for the timestamps of the input packets. Set by the
87 * caller before av_bsf_init().
88 */
89 AVRational time_base_in;
90
91 /**
92 * The timebase used for the timestamps of the output packets. Set by the
93 * filter in av_bsf_init().
94 */
95 AVRational time_base_out;
96} AVBSFContext;
97
98typedef struct AVBitStreamFilter {
99 const char *name;
100
101 /**
102 * A list of codec ids supported by the filter, terminated by
103 * AV_CODEC_ID_NONE.
104 * May be NULL, in that case the bitstream filter works with any codec id.
105 */
106 const enum AVCodecID *codec_ids;
107
108 /**
109 * A class for the private data, used to declare bitstream filter private
110 * AVOptions. This field is NULL for bitstream filters that do not declare
111 * any options.
112 *
113 * If this field is non-NULL, the first member of the filter private data
114 * must be a pointer to AVClass, which will be set by libavcodec generic
115 * code to this class.
116 */
117 const AVClass *priv_class;
118
119 /*****************************************************************
120 * No fields below this line are part of the public API. They
121 * may not be used outside of libavcodec and can be changed and
122 * removed at will.
123 * New public fields should be added right above.
124 *****************************************************************
125 */
126
127 int priv_data_size;
128 int (*init)(AVBSFContext *ctx);
129 int (*filter)(AVBSFContext *ctx, AVPacket *pkt);
130 void (*close)(AVBSFContext *ctx);
131 void (*flush)(AVBSFContext *ctx);
132} AVBitStreamFilter;
133
134/**
135 * @return a bitstream filter with the specified name or NULL if no such
136 * bitstream filter exists.
137 */
138const AVBitStreamFilter *av_bsf_get_by_name(const char *name);
139
140/**
141 * Iterate over all registered bitstream filters.
142 *
143 * @param opaque a pointer where libavcodec will store the iteration state. Must
144 * point to NULL to start the iteration.
145 *
146 * @return the next registered bitstream filter or NULL when the iteration is
147 * finished
148 */
149const AVBitStreamFilter *av_bsf_iterate(void **opaque);
150
151/**
152 * Allocate a context for a given bitstream filter. The caller must fill in the
153 * context parameters as described in the documentation and then call
154 * av_bsf_init() before sending any data to the filter.
155 *
156 * @param filter the filter for which to allocate an instance.
157 * @param ctx a pointer into which the pointer to the newly-allocated context
158 * will be written. It must be freed with av_bsf_free() after the
159 * filtering is done.
160 *
161 * @return 0 on success, a negative AVERROR code on failure
162 */
163int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx);
164
165/**
166 * Prepare the filter for use, after all the parameters and options have been
167 * set.
168 */
169int av_bsf_init(AVBSFContext *ctx);
170
171/**
172 * Submit a packet for filtering.
173 *
174 * After sending each packet, the filter must be completely drained by calling
175 * av_bsf_receive_packet() repeatedly until it returns AVERROR(EAGAIN) or
176 * AVERROR_EOF.
177 *
178 * @param pkt the packet to filter. The bitstream filter will take ownership of
179 * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
180 * If pkt is empty (i.e. NULL, or pkt->data is NULL and pkt->side_data_elems zero),
181 * it signals the end of the stream (i.e. no more non-empty packets will be sent;
182 * sending more empty packets does nothing) and will cause the filter to output
183 * any packets it may have buffered internally.
184 *
185 * @return 0 on success. AVERROR(EAGAIN) if packets need to be retrieved from the
186 * filter (using av_bsf_receive_packet()) before new input can be consumed. Another
187 * negative AVERROR value if an error occurs.
188 */
189int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt);
190
191/**
192 * Retrieve a filtered packet.
193 *
194 * @param[out] pkt this struct will be filled with the contents of the filtered
195 * packet. It is owned by the caller and must be freed using
196 * av_packet_unref() when it is no longer needed.
197 * This parameter should be "clean" (i.e. freshly allocated
198 * with av_packet_alloc() or unreffed with av_packet_unref())
199 * when this function is called. If this function returns
200 * successfully, the contents of pkt will be completely
201 * overwritten by the returned data. On failure, pkt is not
202 * touched.
203 *
204 * @return 0 on success. AVERROR(EAGAIN) if more packets need to be sent to the
205 * filter (using av_bsf_send_packet()) to get more output. AVERROR_EOF if there
206 * will be no further output from the filter. Another negative AVERROR value if
207 * an error occurs.
208 *
209 * @note one input packet may result in several output packets, so after sending
210 * a packet with av_bsf_send_packet(), this function needs to be called
211 * repeatedly until it stops returning 0. It is also possible for a filter to
212 * output fewer packets than were sent to it, so this function may return
213 * AVERROR(EAGAIN) immediately after a successful av_bsf_send_packet() call.
214 */
215int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt);
216
217/**
218 * Reset the internal bitstream filter state. Should be called e.g. when seeking.
219 */
220void av_bsf_flush(AVBSFContext *ctx);
221
222/**
223 * Free a bitstream filter context and everything associated with it; write NULL
224 * into the supplied pointer.
225 */
226void av_bsf_free(AVBSFContext **ctx);
227
228/**
229 * Get the AVClass for AVBSFContext. It can be used in combination with
230 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
231 *
232 * @see av_opt_find().
233 */
234const AVClass *av_bsf_get_class(void);
235
236/**
237 * Structure for chain/list of bitstream filters.
238 * Empty list can be allocated by av_bsf_list_alloc().
239 */
240typedef struct AVBSFList AVBSFList;
241
242/**
243 * Allocate empty list of bitstream filters.
244 * The list must be later freed by av_bsf_list_free()
245 * or finalized by av_bsf_list_finalize().
246 *
247 * @return Pointer to @ref AVBSFList on success, NULL in case of failure
248 */
249AVBSFList *av_bsf_list_alloc(void);
250
251/**
252 * Free list of bitstream filters.
253 *
254 * @param lst Pointer to pointer returned by av_bsf_list_alloc()
255 */
256void av_bsf_list_free(AVBSFList **lst);
257
258/**
259 * Append bitstream filter to the list of bitstream filters.
260 *
261 * @param lst List to append to
262 * @param bsf Filter context to be appended
263 *
264 * @return >=0 on success, negative AVERROR in case of failure
265 */
266int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf);
267
268/**
269 * Construct new bitstream filter context given it's name and options
270 * and append it to the list of bitstream filters.
271 *
272 * @param lst List to append to
273 * @param bsf_name Name of the bitstream filter
274 * @param options Options for the bitstream filter, can be set to NULL
275 *
276 * @return >=0 on success, negative AVERROR in case of failure
277 */
278int av_bsf_list_append2(AVBSFList *lst, const char * bsf_name, AVDictionary **options);
279/**
280 * Finalize list of bitstream filters.
281 *
282 * This function will transform @ref AVBSFList to single @ref AVBSFContext,
283 * so the whole chain of bitstream filters can be treated as single filter
284 * freshly allocated by av_bsf_alloc().
285 * If the call is successful, @ref AVBSFList structure is freed and lst
286 * will be set to NULL. In case of failure, caller is responsible for
287 * freeing the structure by av_bsf_list_free()
288 *
289 * @param lst Filter list structure to be transformed
290 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
291 * representing the chain of bitstream filters
292 *
293 * @return >=0 on success, negative AVERROR in case of failure
294 */
295int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf);
296
297/**
298 * Parse string describing list of bitstream filters and create single
299 * @ref AVBSFContext describing the whole chain of bitstream filters.
300 * Resulting @ref AVBSFContext can be treated as any other @ref AVBSFContext freshly
301 * allocated by av_bsf_alloc().
302 *
303 * @param str String describing chain of bitstream filters in format
304 * `bsf1[=opt1=val1:opt2=val2][,bsf2]`
305 * @param[out] bsf Pointer to be set to newly created @ref AVBSFContext structure
306 * representing the chain of bitstream filters
307 *
308 * @return >=0 on success, negative AVERROR in case of failure
309 */
310int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf);
311
312/**
313 * Get null/pass-through bitstream filter.
314 *
315 * @param[out] bsf Pointer to be set to new instance of pass-through bitstream filter
316 *
317 * @return
318 */
319int av_bsf_get_null_filter(AVBSFContext **bsf);
320
321/**
322 * @}
323 */
324
325#endif // AVCODEC_BSF_H
326

source code of include/x86_64-linux-gnu/libavcodec/bsf.h