FFmpeg
bsf.h
Go to the documentation of this file.
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 
37 typedef 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  */
49 typedef 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  */
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  */
84 
85  /**
86  * The timebase used for the timestamps of the input packets. Set by the
87  * caller before av_bsf_init().
88  */
90 
91  /**
92  * The timebase used for the timestamps of the output packets. Set by the
93  * filter in av_bsf_init().
94  */
96 } AVBSFContext;
97 
98 typedef 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  */
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 
130  void (*close)(AVBSFContext *ctx);
133 
134 /**
135  * @return a bitstream filter with the specified name or NULL if no such
136  * bitstream filter exists.
137  */
138 const 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  */
149 const 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  */
164 
165 /**
166  * Prepare the filter for use, after all the parameters and options have been
167  * set.
168  */
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  */
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  */
216 
217 /**
218  * Reset the internal bitstream filter state / flush internal buffers.
219  */
221 
222 /**
223  * Free a bitstream filter context and everything associated with it; write NULL
224  * into the supplied pointer.
225  */
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  */
234 const 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  */
240 typedef 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  */
250 
251 /**
252  * Free list of bitstream filters.
253  *
254  * @param lst Pointer to pointer returned by av_bsf_list_alloc()
255  */
256 void 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  */
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  */
278 int 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  */
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  */
310 int 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  */
320 
321 /**
322  * @}
323  */
324 
325 #endif // AVCODEC_BSF_H
int av_bsf_list_append(AVBSFList *lst, AVBSFContext *bsf)
Append bitstream filter to the list of bitstream filters.
Definition: bsf.c:434
const AVBitStreamFilter * av_bsf_get_by_name(const char *name)
const AVClass * priv_class
A class for the private data, used to declare bitstream filter private AVOptions. ...
Definition: bsf.h:117
AVCodecParameters * par_out
Parameters of the output stream.
Definition: bsf.h:83
int av_bsf_get_null_filter(AVBSFContext **bsf)
Get null/pass-through bitstream filter.
Definition: bsf.c:556
static void flush(AVCodecContext *avctx)
static av_cold int init(AVCodecContext *avctx)
Definition: avrndec.c:35
const struct AVBitStreamFilter * filter
The bitstream filter this context is an instance of.
Definition: bsf.h:58
The bitstream filter state.
Definition: bsf.h:49
Structure for chain/list of bitstream filters.
Definition: bsf.c:411
static AVPacket pkt
void av_bsf_flush(AVBSFContext *ctx)
Reset the internal bitstream filter state / flush internal buffers.
Definition: bsf.c:188
void * priv_data
Opaque filter-specific private data.
Definition: bsf.h:70
This struct describes the properties of an encoded stream.
Definition: codec_par.h:52
Public dictionary API.
const char * name
Definition: bsf.h:99
int av_bsf_alloc(const AVBitStreamFilter *filter, AVBSFContext **ctx)
Allocate a context for a given bitstream filter.
Definition: bsf.c:94
AVCodecID
Identify the syntax and semantics of the bitstream.
Definition: codec_id.h:46
enum AVCodecID * codec_ids
A list of codec ids supported by the filter, terminated by AV_CODEC_ID_NONE.
Definition: bsf.h:106
AVRational time_base_in
The timebase used for the timestamps of the input packets.
Definition: bsf.h:89
int av_bsf_list_append2(AVBSFList *lst, const char *bsf_name, AVDictionary **options)
Construct new bitstream filter context given it's name and options and append it to the list of bitst...
Definition: bsf.c:480
int av_bsf_init(AVBSFContext *ctx)
Prepare the filter for use, after all the parameters and options have been set.
Definition: bsf.c:147
int av_bsf_list_parse_str(const char *str, AVBSFContext **bsf)
Parse string describing list of bitstream filters and create single AVBSFContext describing the whole...
Definition: bsf.c:522
typedef void(APIENTRY *FF_PFNGLACTIVETEXTUREPROC)(GLenum texture)
AVRational time_base_out
The timebase used for the timestamps of the output packets.
Definition: bsf.h:95
AVFormatContext * ctx
Definition: movenc.c:48
const AVClass * av_class
A class for logging and AVOptions.
Definition: bsf.h:53
int priv_data_size
Definition: bsf.h:127
const AVClass * av_bsf_get_class(void)
Get the AVClass for AVBSFContext.
Definition: bsf.c:89
int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt)
Submit a packet for filtering.
Definition: bsf.c:200
int av_bsf_receive_packet(AVBSFContext *ctx, AVPacket *pkt)
Retrieve a filtered packet.
Definition: bsf.c:226
Describe the class of an AVClass context structure.
Definition: log.h:67
AVBSFList * av_bsf_list_alloc(void)
Allocate empty list of bitstream filters.
Definition: bsf.c:416
Rational number (pair of numerator and denominator).
Definition: rational.h:58
const AVBitStreamFilter * av_bsf_iterate(void **opaque)
Iterate over all registered bitstream filters.
int av_bsf_list_finalize(AVBSFList **lst, AVBSFContext **bsf)
Finalize list of bitstream filters.
Definition: bsf.c:485
int
const OptionDef options[]
Definition: ffmpeg_opt.c:3391
Utilties for rational number calculation.
void av_bsf_free(AVBSFContext **ctx)
Free a bitstream filter context and everything associated with it; write NULL into the supplied point...
Definition: bsf.c:40
This structure stores compressed data.
Definition: packet.h:340
AVCodecParameters * par_in
Parameters of the input stream.
Definition: bsf.h:77
void av_bsf_list_free(AVBSFList **lst)
Free list of bitstream filters.
Definition: bsf.c:421
const char * name
Definition: opengl_enc.c:102