FFmpeg
internal.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVFILTER_INTERNAL_H
20 #define AVFILTER_INTERNAL_H
21 
22 /**
23  * @file
24  * internal API functions
25  */
26 
27 #include "libavutil/internal.h"
28 #include "avfilter.h"
29 #include "formats.h"
30 #include "framepool.h"
31 #include "framequeue.h"
32 #include "thread.h"
33 #include "version.h"
34 #include "video.h"
35 #include "libavcodec/avcodec.h"
36 #include "libavcodec/internal.h"
37 
38 typedef struct AVFilterCommand {
39  double time; ///< time expressed in seconds
40  char *command; ///< command
41  char *arg; ///< optional argument for the command
42  int flags;
45 
46 /**
47  * Update the position of a link in the age heap.
48  */
50 
51 /**
52  * A filter pad used for either input or output.
53  */
54 struct AVFilterPad {
55  /**
56  * Pad name. The name is unique among inputs and among outputs, but an
57  * input may have the same name as an output. This may be NULL if this
58  * pad has no need to ever be referenced by name.
59  */
60  const char *name;
61 
62  /**
63  * AVFilterPad type.
64  */
66 
67  /**
68  * Callback function to get a video buffer. If NULL, the filter system will
69  * use ff_default_get_video_buffer().
70  *
71  * Input video pads only.
72  */
73  AVFrame *(*get_video_buffer)(AVFilterLink *link, int w, int h);
74 
75  /**
76  * Callback function to get an audio buffer. If NULL, the filter system will
77  * use ff_default_get_audio_buffer().
78  *
79  * Input audio pads only.
80  */
81  AVFrame *(*get_audio_buffer)(AVFilterLink *link, int nb_samples);
82 
83  /**
84  * Filtering callback. This is where a filter receives a frame with
85  * audio/video data and should do its processing.
86  *
87  * Input pads only.
88  *
89  * @return >= 0 on success, a negative AVERROR on error. This function
90  * must ensure that frame is properly unreferenced on error if it
91  * hasn't been passed on to another filter.
92  */
94 
95  /**
96  * Frame poll callback. This returns the number of immediately available
97  * samples. It should return a positive value if the next request_frame()
98  * is guaranteed to return one frame (with no delay).
99  *
100  * Defaults to just calling the source poll_frame() method.
101  *
102  * Output pads only.
103  */
105 
106  /**
107  * Frame request callback. A call to this should result in some progress
108  * towards producing output over the given link. This should return zero
109  * on success, and another value on error.
110  *
111  * Output pads only.
112  */
114 
115  /**
116  * Link configuration callback.
117  *
118  * For output pads, this should set the link properties such as
119  * width/height. This should NOT set the format property - that is
120  * negotiated between filters by the filter system using the
121  * query_formats() callback before this function is called.
122  *
123  * For input pads, this should check the properties of the link, and update
124  * the filter's internal state as necessary.
125  *
126  * For both input and output filters, this should return zero on success,
127  * and another value on error.
128  */
130 
131  /**
132  * The filter expects a fifo to be inserted on its input link,
133  * typically because it has a delay.
134  *
135  * input pads only.
136  */
138 
139  /**
140  * The filter expects writable frames from its input link,
141  * duplicating data buffers if needed.
142  *
143  * input pads only.
144  */
146 };
147 
149  void *thread;
152 };
153 
156 };
157 
158 /**
159  * Tell if an integer is contained in the provided -1-terminated list of integers.
160  * This is useful for determining (for instance) if an AVPixelFormat is in an
161  * array of supported formats.
162  *
163  * @param fmt provided format
164  * @param fmts -1-terminated list of formats
165  * @return 1 if present, 0 if absent
166  */
167 int ff_fmt_is_in(int fmt, const int *fmts);
168 
169 /* Functions to parse audio format arguments */
170 
171 /**
172  * Parse a pixel format.
173  *
174  * @param ret pixel format pointer to where the value should be written
175  * @param arg string to parse
176  * @param log_ctx log context
177  * @return >= 0 in case of success, a negative AVERROR code on error
178  */
180 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
181 
182 /**
183  * Parse a sample rate.
184  *
185  * @param ret unsigned integer pointer to where the value should be written
186  * @param arg string to parse
187  * @param log_ctx log context
188  * @return >= 0 in case of success, a negative AVERROR code on error
189  */
191 int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx);
192 
193 /**
194  * Parse a time base.
195  *
196  * @param ret unsigned AVRational pointer to where the value should be written
197  * @param arg string to parse
198  * @param log_ctx log context
199  * @return >= 0 in case of success, a negative AVERROR code on error
200  */
202 int ff_parse_time_base(AVRational *ret, const char *arg, void *log_ctx);
203 
204 /**
205  * Parse a sample format name or a corresponding integer representation.
206  *
207  * @param ret integer pointer to where the value should be written
208  * @param arg string to parse
209  * @param log_ctx log context
210  * @return >= 0 in case of success, a negative AVERROR code on error
211  */
213 int ff_parse_sample_format(int *ret, const char *arg, void *log_ctx);
214 
215 /**
216  * Parse a channel layout or a corresponding integer representation.
217  *
218  * @param ret 64bit integer pointer to where the value should be written.
219  * @param nret integer pointer to the number of channels;
220  * if not NULL, then unknown channel layouts are accepted
221  * @param arg string to parse
222  * @param log_ctx log context
223  * @return >= 0 in case of success, a negative AVERROR code on error
224  */
226 int ff_parse_channel_layout(int64_t *ret, int *nret, const char *arg,
227  void *log_ctx);
228 
230 
231 /**
232  * Set the status field of a link from the source filter.
233  * The pts should reflect the timestamp of the status change,
234  * in link time base and relative to the frames timeline.
235  * In particular, for AVERROR_EOF, it should reflect the
236  * end time of the last frame.
237  */
239 
240 /**
241  * Set the status field of a link from the destination filter.
242  * The pts should probably be left unset (AV_NOPTS_VALUE).
243  */
245 
247 
248 /* misc trace functions */
249 
250 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
251 
252 char *ff_get_ref_perms_string(char *buf, size_t buf_size, int perms);
253 
254 void ff_tlog_ref(void *ctx, AVFrame *ref, int end);
255 
256 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
257 
258 /**
259  * Insert a new pad.
260  *
261  * @param idx Insertion point. Pad is inserted at the end if this point
262  * is beyond the end of the list of pads.
263  * @param count Pointer to the number of pads in the list
264  * @param padidx_off Offset within an AVFilterLink structure to the element
265  * to increment when inserting a new pad causes link
266  * numbering to change
267  * @param pads Pointer to the pointer to the beginning of the list of pads
268  * @param links Pointer to the pointer to the beginning of the list of links
269  * @param newpad The new pad to add. A copy is made when adding.
270  * @return >= 0 in case of success, a negative AVERROR code on error
271  */
272 int ff_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
273  AVFilterPad **pads, AVFilterLink ***links,
274  AVFilterPad *newpad);
275 
276 /** Insert a new input pad for the filter. */
277 static inline int ff_insert_inpad(AVFilterContext *f, unsigned index,
278  AVFilterPad *p)
279 {
280  return ff_insert_pad(index, &f->nb_inputs, offsetof(AVFilterLink, dstpad),
281  &f->input_pads, &f->inputs, p);
282 }
283 
284 /** Insert a new output pad for the filter. */
285 static inline int ff_insert_outpad(AVFilterContext *f, unsigned index,
286  AVFilterPad *p)
287 {
288  return ff_insert_pad(index, &f->nb_outputs, offsetof(AVFilterLink, srcpad),
289  &f->output_pads, &f->outputs, p);
290 }
291 
292 /**
293  * Poll a frame from the filter chain.
294  *
295  * @param link the input link
296  * @return the number of immediately available frames, a negative
297  * number in case of error
298  */
300 
301 /**
302  * Request an input frame from the filter at the other end of the link.
303  *
304  * This function must not be used by filters using the activate callback,
305  * use ff_link_set_frame_wanted() instead.
306  *
307  * The input filter may pass the request on to its inputs, fulfill the
308  * request from an internal buffer or any other means specific to its function.
309  *
310  * When the end of a stream is reached AVERROR_EOF is returned and no further
311  * frames are returned after that.
312  *
313  * When a filter is unable to output a frame for example due to its sources
314  * being unable to do so or because it depends on external means pushing data
315  * into it then AVERROR(EAGAIN) is returned.
316  * It is important that a AVERROR(EAGAIN) return is returned all the way to the
317  * caller (generally eventually a user application) as this step may (but does
318  * not have to be) necessary to provide the input with the next frame.
319  *
320  * If a request is successful then some progress has been made towards
321  * providing a frame on the link (through ff_filter_frame()). A filter that
322  * needs several frames to produce one is allowed to return success if one
323  * more frame has been processed but no output has been produced yet. A
324  * filter is also allowed to simply forward a success return value.
325  *
326  * @param link the input link
327  * @return zero on success
328  * AVERROR_EOF on end of file
329  * AVERROR(EAGAIN) if the previous filter cannot output a frame
330  * currently and can neither guarantee that EOF has been reached.
331  */
332 int ff_request_frame(AVFilterLink *link);
333 
334 #define AVFILTER_DEFINE_CLASS(fname) \
335  static const AVClass fname##_class = { \
336  .class_name = #fname, \
337  .item_name = av_default_item_name, \
338  .option = fname##_options, \
339  .version = LIBAVUTIL_VERSION_INT, \
340  .category = AV_CLASS_CATEGORY_FILTER, \
341  }
342 
343 /**
344  * Find the index of a link.
345  *
346  * I.e. find i such that link == ctx->(in|out)puts[i]
347  */
348 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
349 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
350 
351 /**
352  * Send a frame of data to the next filter.
353  *
354  * @param link the output link over which the data is being sent
355  * @param frame a reference to the buffer of data being sent. The
356  * receiving filter will free this reference when it no longer
357  * needs it or pass it on to the next filter.
358  *
359  * @return >= 0 on success, a negative AVERROR on error. The receiving filter
360  * is responsible for unreferencing frame in case of error.
361  */
363 
364 /**
365  * Allocate a new filter context and return it.
366  *
367  * @param filter what filter to create an instance of
368  * @param inst_name name to give to the new filter context
369  *
370  * @return newly created filter context or NULL on failure
371  */
372 AVFilterContext *ff_filter_alloc(const AVFilter *filter, const char *inst_name);
373 
375 
376 /**
377  * Remove a filter from a graph;
378  */
380 
381 /**
382  * The filter is aware of hardware frames, and any hardware frame context
383  * should not be automatically propagated through it.
384  */
385 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
386 
387 /**
388  * Run one round of processing on a filter graph.
389  */
391 
392 /**
393  * Normalize the qscale factor
394  * FIXME the H264 qscale is a log based scale, mpeg1/2 is not, the code below
395  * cannot be optimal
396  */
397 static inline int ff_norm_qscale(int qscale, int type)
398 {
399  switch (type) {
400  case FF_QSCALE_TYPE_MPEG1: return qscale;
401  case FF_QSCALE_TYPE_MPEG2: return qscale >> 1;
402  case FF_QSCALE_TYPE_H264: return qscale >> 2;
403  case FF_QSCALE_TYPE_VP56: return (63 - qscale + 2) >> 2;
404  }
405  return qscale;
406 }
407 
408 /**
409  * Get number of threads for current filter instance.
410  * This number is always same or less than graph->nb_threads.
411  */
413 
414 /**
415  * Generic processing of user supplied commands that are set
416  * in the same way as the filter options.
417  */
418 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
419  const char *arg, char *res, int res_len, int flags);
420 
421 /**
422  * Perform any additional setup required for hardware frames.
423  *
424  * link->hw_frames_ctx must be set before calling this function.
425  * Inside link->hw_frames_ctx, the fields format, sw_format, width and
426  * height must be set. If dynamically allocated pools are not supported,
427  * then initial_pool_size must also be set, to the minimum hardware frame
428  * pool size necessary for the filter to work (taking into account any
429  * frames which need to stored for use in operations as appropriate). If
430  * default_pool_size is nonzero, then it will be used as the pool size if
431  * no other modification takes place (this can be used to preserve
432  * compatibility).
433  */
435  int default_pool_size);
436 
437 #endif /* AVFILTER_INTERNAL_H */
This structure describes decoded (raw) audio or video data.
Definition: frame.h:295
int ff_filter_frame(AVFilterLink *link, AVFrame *frame)
Send a frame of data to the next filter.
Definition: avfilter.c:1093
const char * fmt
Definition: avisynth_c.h:861
int ff_insert_pad(unsigned idx, unsigned *count, size_t padidx_off, AVFilterPad **pads, AVFilterLink ***links, AVFilterPad *newpad)
Insert a new pad.
Definition: avfilter.c:103
Main libavfilter public API header.
#define FF_QSCALE_TYPE_H264
Definition: internal.h:83
Libavfilter version macros.
int ff_filter_activate(AVFilterContext *filter)
Definition: avfilter.c:1434
GLint GLenum type
Definition: opengl_enc.c:104
void ff_avfilter_graph_update_heap(AVFilterGraph *graph, AVFilterLink *link)
Update the position of a link in the age heap.
const char * name
Pad name.
Definition: internal.h:60
AVFilterLink ** inputs
array of pointers to input links
Definition: avfilter.h:346
void ff_avfilter_link_set_in_status(AVFilterLink *link, int status, int64_t pts)
Set the status field of a link from the source filter.
Definition: avfilter.c:211
AVFilterPad * output_pads
array of output pads
Definition: avfilter.h:349
#define f(width, name)
Definition: cbs_vp9.c:255
static av_cold int end(AVCodecContext *avctx)
Definition: avrndec.c:90
int ff_fmt_is_in(int fmt, const int *fmts)
Tell if an integer is contained in the provided -1-terminated list of integers.
Definition: formats.c:254
int( avfilter_execute_func)(AVFilterContext *ctx, avfilter_action_func *func, void *arg, int *ret, int nb_jobs)
A function executing multiple jobs, possibly in parallel.
Definition: avfilter.h:837
static int poll_frame(AVFilterLink *link)
Definition: buffersrc.c:482
int ff_filter_graph_run_once(AVFilterGraph *graph)
Run one round of processing on a filter graph.
int ff_filter_init_hw_frames(AVFilterContext *avctx, AVFilterLink *link, int default_pool_size)
Perform any additional setup required for hardware frames.
Definition: avfilter.c:1653
int ff_filter_process_command(AVFilterContext *ctx, const char *cmd, const char *arg, char *res, int res_len, int flags)
Generic processing of user supplied commands that are set in the same way as the filter options...
Definition: avfilter.c:887
void ff_update_link_current_pts(AVFilterLink *link, int64_t pts)
Definition: avfilter.c:546
A filter pad used for either input or output.
Definition: internal.h:54
AVFilterPad * input_pads
array of input pads
Definition: avfilter.h:345
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce then the filter should push the output frames on the output link immediately As an exception to the previous rule if the input frame is enough to produce several output frames then the filter needs output only at least one per link The additional frames can be left buffered in the filter
int ff_filter_get_nb_threads(AVFilterContext *ctx)
Get number of threads for current filter instance.
Definition: avfilter.c:802
unsigned nb_outputs
number of output pads
Definition: avfilter.h:351
GLsizei count
Definition: opengl_enc.c:108
common internal API header
static int request_frame(AVFilterLink *outlink)
Definition: aeval.c:274
av_warn_unused_result int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx)
Parse a pixel format.
Definition: formats.c:610
unsigned nb_inputs
number of input pads
Definition: avfilter.h:347
struct AVFilterCommand * next
Definition: internal.h:43
uint8_t w
Definition: llviddspenc.c:38
void ff_command_queue_pop(AVFilterContext *filter)
Definition: avfilter.c:94
AVFormatContext * ctx
Definition: movenc.c:48
int needs_writable
The filter expects writable frames from its input link, duplicating data buffers if needed...
Definition: internal.h:145
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output links
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
char * ff_get_ref_perms_string(char *buf, size_t buf_size, int perms)
Libavcodec external API header.
av_warn_unused_result int ff_parse_channel_layout(int64_t *ret, int *nret, const char *arg, void *log_ctx)
Parse a channel layout or a corresponding integer representation.
Definition: formats.c:663
void ff_filter_graph_remove_filter(AVFilterGraph *graph, AVFilterContext *filter)
Remove a filter from a graph;.
static int config_props(AVFilterLink *outlink)
Definition: aeval.c:223
void * buf
Definition: avisynth_c.h:766
void ff_avfilter_link_set_out_status(AVFilterLink *link, int status, int64_t pts)
Set the status field of a link from the destination filter.
Definition: avfilter.c:224
Filter definition.
Definition: avfilter.h:144
int index
Definition: gxfenc.c:89
Rational number (pair of numerator and denominator).
Definition: rational.h:58
they must not be accessed directly The fifo field contains the frames that are queued in the input for processing by the filter The status_in and status_out fields contains the queued status(EOF or error) of the link
AVMediaType
Definition: avutil.h:199
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a link
#define FF_QSCALE_TYPE_VP56
Definition: internal.h:84
AVFilterLink ** outputs
array of pointers to output links
Definition: avfilter.h:350
static int ff_norm_qscale(int qscale, int type)
Normalize the qscale factor FIXME the H264 qscale is a log based scale, mpeg1/2 is not...
Definition: internal.h:397
static int64_t pts
static int filter_frame(DBEContext *s, AVFrame *frame)
Definition: dolby_e.c:565
#define av_warn_unused_result
Definition: attributes.h:56
#define FF_QSCALE_TYPE_MPEG2
Definition: internal.h:82
av_warn_unused_result int ff_parse_time_base(AVRational *ret, const char *arg, void *log_ctx)
Parse a time base.
Definition: formats.c:640
int
common internal api header.
av_warn_unused_result int ff_parse_sample_format(int *ret, const char *arg, void *log_ctx)
Parse a sample format name or a corresponding integer representation.
Definition: formats.c:625
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:107
av_warn_unused_result int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx)
Parse a sample rate.
Definition: formats.c:651
avfilter_execute_func * execute
Definition: internal.h:155
void ff_tlog_ref(void *ctx, AVFrame *ref, int end)
Definition: avfilter.c:49
avfilter_execute_func * thread_execute
Definition: internal.h:150
void ff_tlog_link(void *ctx, AVFilterLink *link, int end)
Definition: avfilter.c:383
An instance of a filter.
Definition: avfilter.h:338
int ff_poll_frame(AVFilterLink *link)
Poll a frame from the filter chain.
Definition: avfilter.c:470
AVFilterContext * ff_filter_alloc(const AVFilter *filter, const char *inst_name)
Allocate a new filter context and return it.
Definition: avfilter.c:663
FFFrameQueueGlobal frame_queues
Definition: internal.h:151
double time
time expressed in seconds
Definition: internal.h:39
int needs_fifo
The filter expects a fifo to be inserted on its input link, typically because it has a delay...
Definition: internal.h:137
#define FF_QSCALE_TYPE_MPEG1
Definition: internal.h:81
int ff_request_frame(AVFilterLink *link)
Request an input frame from the filter at the other end of the link.
Definition: avfilter.c:407
static int ff_insert_outpad(AVFilterContext *f, unsigned index, AVFilterPad *p)
Insert a new output pad for the filter.
Definition: internal.h:285
Structure to hold global options and statistics for frame queues.
Definition: framequeue.h:46
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
char * command
command
Definition: internal.h:40
static int ff_insert_inpad(AVFilterContext *f, unsigned index, AVFilterPad *p)
Insert a new input pad for the filter.
Definition: internal.h:277
char * arg
optional argument for the command
Definition: internal.h:41