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 request callback. A call to this should result in some progress
97  * towards producing output over the given link. This should return zero
98  * on success, and another value on error.
99  *
100  * Output pads only.
101  */
103 
104  /**
105  * Link configuration callback.
106  *
107  * For output pads, this should set the link properties such as
108  * width/height. This should NOT set the format property - that is
109  * negotiated between filters by the filter system using the
110  * query_formats() callback before this function is called.
111  *
112  * For input pads, this should check the properties of the link, and update
113  * the filter's internal state as necessary.
114  *
115  * For both input and output filters, this should return zero on success,
116  * and another value on error.
117  */
119 
120  /**
121  * The filter expects a fifo to be inserted on its input link,
122  * typically because it has a delay.
123  *
124  * input pads only.
125  */
127 
128  /**
129  * The filter expects writable frames from its input link,
130  * duplicating data buffers if needed.
131  *
132  * input pads only.
133  */
135 };
136 
138  void *thread;
141 };
142 
145 };
146 
147 /**
148  * Tell if an integer is contained in the provided -1-terminated list of integers.
149  * This is useful for determining (for instance) if an AVPixelFormat is in an
150  * array of supported formats.
151  *
152  * @param fmt provided format
153  * @param fmts -1-terminated list of formats
154  * @return 1 if present, 0 if absent
155  */
156 int ff_fmt_is_in(int fmt, const int *fmts);
157 
158 /* Functions to parse audio format arguments */
159 
160 /**
161  * Parse a pixel format.
162  *
163  * @param ret pixel format pointer to where the value should be written
164  * @param arg string to parse
165  * @param log_ctx log context
166  * @return >= 0 in case of success, a negative AVERROR code on error
167  */
169 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
170 
171 /**
172  * Parse a sample rate.
173  *
174  * @param ret unsigned integer 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_sample_rate(int *ret, const char *arg, void *log_ctx);
181 
182 /**
183  * Parse a time base.
184  *
185  * @param ret unsigned AVRational 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_time_base(AVRational *ret, const char *arg, void *log_ctx);
192 
193 /**
194  * Parse a sample format name or a corresponding integer representation.
195  *
196  * @param ret integer 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_sample_format(int *ret, const char *arg, void *log_ctx);
203 
204 /**
205  * Parse a channel layout or a corresponding integer representation.
206  *
207  * @param ret 64bit integer pointer to where the value should be written.
208  * @param nret integer pointer to the number of channels;
209  * if not NULL, then unknown channel layouts are accepted
210  * @param arg string to parse
211  * @param log_ctx log context
212  * @return >= 0 in case of success, a negative AVERROR code on error
213  */
215 int ff_parse_channel_layout(int64_t *ret, int *nret, const char *arg,
216  void *log_ctx);
217 
219 
220 /**
221  * Set the status field of a link from the source filter.
222  * The pts should reflect the timestamp of the status change,
223  * in link time base and relative to the frames timeline.
224  * In particular, for AVERROR_EOF, it should reflect the
225  * end time of the last frame.
226  */
228 
229 /**
230  * Set the status field of a link from the destination filter.
231  * The pts should probably be left unset (AV_NOPTS_VALUE).
232  */
234 
236 
237 /* misc trace functions */
238 
239 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
240 
241 char *ff_get_ref_perms_string(char *buf, size_t buf_size, int perms);
242 
243 void ff_tlog_ref(void *ctx, AVFrame *ref, int end);
244 
245 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
246 
247 /**
248  * Insert a new pad.
249  *
250  * @param idx Insertion point. Pad is inserted at the end if this point
251  * is beyond the end of the list of pads.
252  * @param count Pointer to the number of pads in the list
253  * @param padidx_off Offset within an AVFilterLink structure to the element
254  * to increment when inserting a new pad causes link
255  * numbering to change
256  * @param pads Pointer to the pointer to the beginning of the list of pads
257  * @param links Pointer to the pointer to the beginning of the list of links
258  * @param newpad The new pad to add. A copy is made when adding.
259  * @return >= 0 in case of success, a negative AVERROR code on error
260  */
261 int ff_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
262  AVFilterPad **pads, AVFilterLink ***links,
263  AVFilterPad *newpad);
264 
265 /** Insert a new input pad for the filter. */
266 static inline int ff_insert_inpad(AVFilterContext *f, unsigned index,
267  AVFilterPad *p)
268 {
269  return ff_insert_pad(index, &f->nb_inputs, offsetof(AVFilterLink, dstpad),
270  &f->input_pads, &f->inputs, p);
271 }
272 
273 /** Insert a new output pad for the filter. */
274 static inline int ff_insert_outpad(AVFilterContext *f, unsigned index,
275  AVFilterPad *p)
276 {
277  return ff_insert_pad(index, &f->nb_outputs, offsetof(AVFilterLink, srcpad),
278  &f->output_pads, &f->outputs, p);
279 }
280 
281 /**
282  * Request an input frame from the filter at the other end of the link.
283  *
284  * This function must not be used by filters using the activate callback,
285  * use ff_link_set_frame_wanted() instead.
286  *
287  * The input filter may pass the request on to its inputs, fulfill the
288  * request from an internal buffer or any other means specific to its function.
289  *
290  * When the end of a stream is reached AVERROR_EOF is returned and no further
291  * frames are returned after that.
292  *
293  * When a filter is unable to output a frame for example due to its sources
294  * being unable to do so or because it depends on external means pushing data
295  * into it then AVERROR(EAGAIN) is returned.
296  * It is important that a AVERROR(EAGAIN) return is returned all the way to the
297  * caller (generally eventually a user application) as this step may (but does
298  * not have to be) necessary to provide the input with the next frame.
299  *
300  * If a request is successful then some progress has been made towards
301  * providing a frame on the link (through ff_filter_frame()). A filter that
302  * needs several frames to produce one is allowed to return success if one
303  * more frame has been processed but no output has been produced yet. A
304  * filter is also allowed to simply forward a success return value.
305  *
306  * @param link the input link
307  * @return zero on success
308  * AVERROR_EOF on end of file
309  * AVERROR(EAGAIN) if the previous filter cannot output a frame
310  * currently and can neither guarantee that EOF has been reached.
311  */
313 
314 #define AVFILTER_DEFINE_CLASS(fname) \
315  static const AVClass fname##_class = { \
316  .class_name = #fname, \
317  .item_name = av_default_item_name, \
318  .option = fname##_options, \
319  .version = LIBAVUTIL_VERSION_INT, \
320  .category = AV_CLASS_CATEGORY_FILTER, \
321  }
322 
323 /**
324  * Find the index of a link.
325  *
326  * I.e. find i such that link == ctx->(in|out)puts[i]
327  */
328 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
329 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
330 
331 /**
332  * Send a frame of data to the next filter.
333  *
334  * @param link the output link over which the data is being sent
335  * @param frame a reference to the buffer of data being sent. The
336  * receiving filter will free this reference when it no longer
337  * needs it or pass it on to the next filter.
338  *
339  * @return >= 0 on success, a negative AVERROR on error. The receiving filter
340  * is responsible for unreferencing frame in case of error.
341  */
343 
344 /**
345  * Allocate a new filter context and return it.
346  *
347  * @param filter what filter to create an instance of
348  * @param inst_name name to give to the new filter context
349  *
350  * @return newly created filter context or NULL on failure
351  */
352 AVFilterContext *ff_filter_alloc(const AVFilter *filter, const char *inst_name);
353 
355 
356 /**
357  * Remove a filter from a graph;
358  */
360 
361 /**
362  * The filter is aware of hardware frames, and any hardware frame context
363  * should not be automatically propagated through it.
364  */
365 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
366 
367 /**
368  * Run one round of processing on a filter graph.
369  */
371 
372 /**
373  * Normalize the qscale factor
374  * FIXME the H264 qscale is a log based scale, mpeg1/2 is not, the code below
375  * cannot be optimal
376  */
377 static inline int ff_norm_qscale(int qscale, int type)
378 {
379  switch (type) {
380  case FF_QSCALE_TYPE_MPEG1: return qscale;
381  case FF_QSCALE_TYPE_MPEG2: return qscale >> 1;
382  case FF_QSCALE_TYPE_H264: return qscale >> 2;
383  case FF_QSCALE_TYPE_VP56: return (63 - qscale + 2) >> 2;
384  }
385  return qscale;
386 }
387 
388 /**
389  * Get number of threads for current filter instance.
390  * This number is always same or less than graph->nb_threads.
391  */
393 
394 /**
395  * Generic processing of user supplied commands that are set
396  * in the same way as the filter options.
397  */
398 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
399  const char *arg, char *res, int res_len, int flags);
400 
401 /**
402  * Perform any additional setup required for hardware frames.
403  *
404  * link->hw_frames_ctx must be set before calling this function.
405  * Inside link->hw_frames_ctx, the fields format, sw_format, width and
406  * height must be set. If dynamically allocated pools are not supported,
407  * then initial_pool_size must also be set, to the minimum hardware frame
408  * pool size necessary for the filter to work (taking into account any
409  * frames which need to stored for use in operations as appropriate). If
410  * default_pool_size is nonzero, then it will be used as the pool size if
411  * no other modification takes place (this can be used to preserve
412  * compatibility).
413  */
415  int default_pool_size);
416 
417 #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:1075
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:89
Libavfilter version macros.
int ff_filter_activate(AVFilterContext *filter)
Definition: avfilter.c:1416
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
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:1635
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:869
void ff_update_link_current_pts(AVFilterLink *link, int64_t pts)
Definition: avfilter.c:528
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:784
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:134
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:90
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:377
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:88
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:144
void ff_tlog_ref(void *ctx, AVFrame *ref, int end)
Definition: avfilter.c:49
avfilter_execute_func * thread_execute
Definition: internal.h:139
void ff_tlog_link(void *ctx, AVFilterLink *link, int end)
Definition: avfilter.c:383
An instance of a filter.
Definition: avfilter.h:338
AVFilterContext * ff_filter_alloc(const AVFilter *filter, const char *inst_name)
Allocate a new filter context and return it.
Definition: avfilter.c:645
FFFrameQueueGlobal frame_queues
Definition: internal.h:140
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:126
#define FF_QSCALE_TYPE_MPEG1
Definition: internal.h:87
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:274
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:266
char * arg
optional argument for the command
Definition: internal.h:41