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 "framequeue.h"
31 #include "version.h"
32 #include "video.h"
33 #include "libavcodec/avcodec.h"
34 #include "libavcodec/internal.h"
35 
36 typedef struct AVFilterCommand {
37  double time; ///< time expressed in seconds
38  char *command; ///< command
39  char *arg; ///< optional argument for the command
40  int flags;
43 
44 /**
45  * Update the position of a link in the age heap.
46  */
48 
49 /**
50  * A filter pad used for either input or output.
51  */
52 struct AVFilterPad {
53  /**
54  * Pad name. The name is unique among inputs and among outputs, but an
55  * input may have the same name as an output. This may be NULL if this
56  * pad has no need to ever be referenced by name.
57  */
58  const char *name;
59 
60  /**
61  * AVFilterPad type.
62  */
64 
65  /**
66  * Callback function to get a video buffer. If NULL, the filter system will
67  * use ff_default_get_video_buffer().
68  *
69  * Input video pads only.
70  */
71  AVFrame *(*get_video_buffer)(AVFilterLink *link, int w, int h);
72 
73  /**
74  * Callback function to get an audio buffer. If NULL, the filter system will
75  * use ff_default_get_audio_buffer().
76  *
77  * Input audio pads only.
78  */
79  AVFrame *(*get_audio_buffer)(AVFilterLink *link, int nb_samples);
80 
81  /**
82  * Filtering callback. This is where a filter receives a frame with
83  * audio/video data and should do its processing.
84  *
85  * Input pads only.
86  *
87  * @return >= 0 on success, a negative AVERROR on error. This function
88  * must ensure that frame is properly unreferenced on error if it
89  * hasn't been passed on to another filter.
90  */
92 
93  /**
94  * Frame request callback. A call to this should result in some progress
95  * towards producing output over the given link. This should return zero
96  * on success, and another value on error.
97  *
98  * Output pads only.
99  */
101 
102  /**
103  * Link configuration callback.
104  *
105  * For output pads, this should set the link properties such as
106  * width/height. This should NOT set the format property - that is
107  * negotiated between filters by the filter system using the
108  * query_formats() callback before this function is called.
109  *
110  * For input pads, this should check the properties of the link, and update
111  * the filter's internal state as necessary.
112  *
113  * For both input and output filters, this should return zero on success,
114  * and another value on error.
115  */
117 
118  /**
119  * The filter expects writable frames from its input link,
120  * duplicating data buffers if needed.
121  *
122  * input pads only.
123  */
125 };
126 
128  void *thread;
131 };
132 
135 };
136 
137 /**
138  * Tell if an integer is contained in the provided -1-terminated list of integers.
139  * This is useful for determining (for instance) if an AVPixelFormat is in an
140  * array of supported formats.
141  *
142  * @param fmt provided format
143  * @param fmts -1-terminated list of formats
144  * @return 1 if present, 0 if absent
145  */
146 int ff_fmt_is_in(int fmt, const int *fmts);
147 
148 /* Functions to parse audio format arguments */
149 
150 /**
151  * Parse a pixel format.
152  *
153  * @param ret pixel format pointer to where the value should be written
154  * @param arg string to parse
155  * @param log_ctx log context
156  * @return >= 0 in case of success, a negative AVERROR code on error
157  */
159 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
160 
161 /**
162  * Parse a sample rate.
163  *
164  * @param ret unsigned integer pointer to where the value should be written
165  * @param arg string to parse
166  * @param log_ctx log context
167  * @return >= 0 in case of success, a negative AVERROR code on error
168  */
170 int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx);
171 
172 /**
173  * Parse a channel layout or a corresponding integer representation.
174  *
175  * @param ret 64bit integer pointer to where the value should be written.
176  * @param nret integer pointer to the number of channels;
177  * if not NULL, then unknown channel layouts are accepted
178  * @param arg string to parse
179  * @param log_ctx log context
180  * @return >= 0 in case of success, a negative AVERROR code on error
181  */
183 int ff_parse_channel_layout(int64_t *ret, int *nret, const char *arg,
184  void *log_ctx);
185 
187 
188 /**
189  * Set the status field of a link from the source filter.
190  * The pts should reflect the timestamp of the status change,
191  * in link time base and relative to the frames timeline.
192  * In particular, for AVERROR_EOF, it should reflect the
193  * end time of the last frame.
194  */
196 
197 /**
198  * Set the status field of a link from the destination filter.
199  * The pts should probably be left unset (AV_NOPTS_VALUE).
200  */
202 
204 
205 #define D2TS(d) (isnan(d) ? AV_NOPTS_VALUE : (int64_t)(d))
206 #define TS2D(ts) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts))
207 #define TS2T(ts, tb) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts) * av_q2d(tb))
208 
209 /* misc trace functions */
210 
211 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
212 
213 char *ff_get_ref_perms_string(char *buf, size_t buf_size, int perms);
214 
215 void ff_tlog_ref(void *ctx, AVFrame *ref, int end);
216 
217 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
218 
219 /**
220  * Insert a new pad.
221  *
222  * @param idx Insertion point. Pad is inserted at the end if this point
223  * is beyond the end of the list of pads.
224  * @param count Pointer to the number of pads in the list
225  * @param padidx_off Offset within an AVFilterLink structure to the element
226  * to increment when inserting a new pad causes link
227  * numbering to change
228  * @param pads Pointer to the pointer to the beginning of the list of pads
229  * @param links Pointer to the pointer to the beginning of the list of links
230  * @param newpad The new pad to add. A copy is made when adding.
231  * @return >= 0 in case of success, a negative AVERROR code on error
232  */
233 int ff_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
234  AVFilterPad **pads, AVFilterLink ***links,
235  AVFilterPad *newpad);
236 
237 /** Insert a new input pad for the filter. */
238 static inline int ff_insert_inpad(AVFilterContext *f, unsigned index,
239  AVFilterPad *p)
240 {
241  return ff_insert_pad(index, &f->nb_inputs, offsetof(AVFilterLink, dstpad),
242  &f->input_pads, &f->inputs, p);
243 }
244 
245 /** Insert a new output pad for the filter. */
246 static inline int ff_insert_outpad(AVFilterContext *f, unsigned index,
247  AVFilterPad *p)
248 {
249  return ff_insert_pad(index, &f->nb_outputs, offsetof(AVFilterLink, srcpad),
250  &f->output_pads, &f->outputs, p);
251 }
252 
253 /**
254  * Request an input frame from the filter at the other end of the link.
255  *
256  * This function must not be used by filters using the activate callback,
257  * use ff_link_set_frame_wanted() instead.
258  *
259  * The input filter may pass the request on to its inputs, fulfill the
260  * request from an internal buffer or any other means specific to its function.
261  *
262  * When the end of a stream is reached AVERROR_EOF is returned and no further
263  * frames are returned after that.
264  *
265  * When a filter is unable to output a frame for example due to its sources
266  * being unable to do so or because it depends on external means pushing data
267  * into it then AVERROR(EAGAIN) is returned.
268  * It is important that a AVERROR(EAGAIN) return is returned all the way to the
269  * caller (generally eventually a user application) as this step may (but does
270  * not have to be) necessary to provide the input with the next frame.
271  *
272  * If a request is successful then some progress has been made towards
273  * providing a frame on the link (through ff_filter_frame()). A filter that
274  * needs several frames to produce one is allowed to return success if one
275  * more frame has been processed but no output has been produced yet. A
276  * filter is also allowed to simply forward a success return value.
277  *
278  * @param link the input link
279  * @return zero on success
280  * AVERROR_EOF on end of file
281  * AVERROR(EAGAIN) if the previous filter cannot output a frame
282  * currently and can neither guarantee that EOF has been reached.
283  */
285 
286 #define AVFILTER_DEFINE_CLASS(fname) \
287  static const AVClass fname##_class = { \
288  .class_name = #fname, \
289  .item_name = av_default_item_name, \
290  .option = fname##_options, \
291  .version = LIBAVUTIL_VERSION_INT, \
292  .category = AV_CLASS_CATEGORY_FILTER, \
293  }
294 
295 /**
296  * Find the index of a link.
297  *
298  * I.e. find i such that link == ctx->(in|out)puts[i]
299  */
300 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
301 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
302 
303 /**
304  * Send a frame of data to the next filter.
305  *
306  * @param link the output link over which the data is being sent
307  * @param frame a reference to the buffer of data being sent. The
308  * receiving filter will free this reference when it no longer
309  * needs it or pass it on to the next filter.
310  *
311  * @return >= 0 on success, a negative AVERROR on error. The receiving filter
312  * is responsible for unreferencing frame in case of error.
313  */
315 
316 /**
317  * Allocate a new filter context and return it.
318  *
319  * @param filter what filter to create an instance of
320  * @param inst_name name to give to the new filter context
321  *
322  * @return newly created filter context or NULL on failure
323  */
324 AVFilterContext *ff_filter_alloc(const AVFilter *filter, const char *inst_name);
325 
327 
328 /**
329  * Remove a filter from a graph;
330  */
332 
333 /**
334  * The filter is aware of hardware frames, and any hardware frame context
335  * should not be automatically propagated through it.
336  */
337 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
338 
339 /**
340  * Run one round of processing on a filter graph.
341  */
343 
344 /**
345  * Normalize the qscale factor
346  * FIXME the H264 qscale is a log based scale, mpeg1/2 is not, the code below
347  * cannot be optimal
348  */
349 static inline int ff_norm_qscale(int qscale, int type)
350 {
351  switch (type) {
352  case FF_QSCALE_TYPE_MPEG1: return qscale;
353  case FF_QSCALE_TYPE_MPEG2: return qscale >> 1;
354  case FF_QSCALE_TYPE_H264: return qscale >> 2;
355  case FF_QSCALE_TYPE_VP56: return (63 - qscale + 2) >> 2;
356  }
357  return qscale;
358 }
359 
360 /**
361  * Get number of threads for current filter instance.
362  * This number is always same or less than graph->nb_threads.
363  */
365 
366 /**
367  * Generic processing of user supplied commands that are set
368  * in the same way as the filter options.
369  * NOTE: 'enable' option is handled separately, and not by
370  * this function.
371  */
372 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
373  const char *arg, char *res, int res_len, int flags);
374 
375 /**
376  * Perform any additional setup required for hardware frames.
377  *
378  * link->hw_frames_ctx must be set before calling this function.
379  * Inside link->hw_frames_ctx, the fields format, sw_format, width and
380  * height must be set. If dynamically allocated pools are not supported,
381  * then initial_pool_size must also be set, to the minimum hardware frame
382  * pool size necessary for the filter to work (taking into account any
383  * frames which need to stored for use in operations as appropriate). If
384  * default_pool_size is nonzero, then it will be used as the pool size if
385  * no other modification takes place (this can be used to preserve
386  * compatibility).
387  */
389  int default_pool_size);
390 
391 #endif /* AVFILTER_INTERNAL_H */
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
status
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
ff_avfilter_graph_update_heap
void ff_avfilter_graph_update_heap(AVFilterGraph *graph, AVFilterLink *link)
Update the position of a link in the age heap.
Definition: avfiltergraph.c:1337
AVFilterGraphInternal::frame_queues
FFFrameQueueGlobal frame_queues
Definition: internal.h:130
ff_tlog_link
void ff_tlog_link(void *ctx, AVFilterLink *link, int end)
Definition: avfilter.c:372
graph
fg outputs[0] graph
Definition: ffmpeg_filter.c:174
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:303
index
fg index
Definition: ffmpeg_filter.c:168
w
uint8_t w
Definition: llviddspenc.c:38
internal.h
AVFilterGraphInternal
Definition: internal.h:127
filter
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
Definition: filter_design.txt:228
av_pure
#define av_pure
Definition: attributes.h:78
ff_request_frame
int ff_request_frame(AVFilterLink *link)
Request an input frame from the filter at the other end of the link.
Definition: avfilter.c:396
video.h
ff_avfilter_link_set_in_status
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:205
formats.h
AVFilterGraphInternal::thread
void * thread
Definition: internal.h:128
ff_insert_inpad
static int ff_insert_inpad(AVFilterContext *f, unsigned index, AVFilterPad *p)
Insert a new input pad for the filter.
Definition: internal.h:238
ff_filter_alloc
AVFilterContext * ff_filter_alloc(const AVFilter *filter, const char *inst_name)
Allocate a new filter context and return it.
Definition: avfilter.c:624
AVFilterCommand::flags
int flags
Definition: internal.h:40
ff_filter_activate
int ff_filter_activate(AVFilterContext *filter)
Definition: avfilter.c:1317
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
pts
static int64_t pts
Definition: transcode_aac.c:653
AVFilterPad
A filter pad used for either input or output.
Definition: internal.h:52
AVFilterPad::request_frame
int(* request_frame)(AVFilterLink *link)
Frame request callback.
Definition: internal.h:100
FFFrameQueueGlobal
Structure to hold global options and statistics for frame queues.
Definition: framequeue.h:46
ff_avfilter_link_set_out_status
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:218
FF_QSCALE_TYPE_MPEG2
#define FF_QSCALE_TYPE_MPEG2
Definition: internal.h:104
ff_filter_init_hw_frames
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:1527
ctx
AVFormatContext * ctx
Definition: movenc.c:48
ff_filter_process_command
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:843
ff_command_queue_pop
void ff_command_queue_pop(AVFilterContext *filter)
Definition: avfilter.c:95
ff_fmt_is_in
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:257
ff_parse_channel_layout
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:637
f
#define f(width, name)
Definition: cbs_vp9.c:255
link
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
Definition: filter_design.txt:23
arg
const char * arg
Definition: jacosubdec.c:67
ff_filter_graph_remove_filter
void ff_filter_graph_remove_filter(AVFilterGraph *graph, AVFilterContext *filter)
Remove a filter from a graph;.
Definition: avfiltergraph.c:102
ff_parse_pixel_format
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
framequeue.h
AVFilterInternal
Definition: internal.h:133
ff_update_link_current_pts
void ff_update_link_current_pts(AVFilterLink *link, int64_t pts)
Definition: avfilter.c:517
AVFilterPad::filter_frame
int(* filter_frame)(AVFilterLink *link, AVFrame *frame)
Filtering callback.
Definition: internal.h:91
AVFilterGraph
Definition: avfilter.h:798
AVFilterPad::config_props
int(* config_props)(AVFilterLink *link)
Link configuration callback.
Definition: internal.h:116
AVMediaType
AVMediaType
Definition: avutil.h:199
FF_QSCALE_TYPE_MPEG1
#define FF_QSCALE_TYPE_MPEG1
Definition: internal.h:103
avfilter_execute_func
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:795
AVFilterCommand::next
struct AVFilterCommand * next
Definition: internal.h:41
ff_norm_qscale
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:349
AVFilterGraphInternal::thread_execute
avfilter_execute_func * thread_execute
Definition: internal.h:129
AVFilterPad::needs_writable
int needs_writable
The filter expects writable frames from its input link, duplicating data buffers if needed.
Definition: internal.h:124
ff_filter_graph_run_once
int ff_filter_graph_run_once(AVFilterGraph *graph)
Run one round of processing on a filter graph.
Definition: avfiltergraph.c:1388
FF_QSCALE_TYPE_H264
#define FF_QSCALE_TYPE_H264
Definition: internal.h:105
av_warn_unused_result
#define av_warn_unused_result
Definition: attributes.h:64
ff_parse_sample_rate
av_warn_unused_result int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx)
Parse a sample rate.
Definition: formats.c:625
internal.h
AVFilterCommand
Definition: internal.h:36
AVFilterPad::name
const char * name
Pad name.
Definition: internal.h:58
avcodec.h
AVFilter
Filter definition.
Definition: avfilter.h:145
ret
ret
Definition: filter_design.txt:187
AVFilterPad::type
enum AVMediaType type
AVFilterPad type.
Definition: internal.h:63
links
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
Definition: filter_design.txt:14
frame
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
Definition: filter_design.txt:264
AVFilterInternal::execute
avfilter_execute_func * execute
Definition: internal.h:134
ff_filter_frame
int ff_filter_frame(AVFilterLink *link, AVFrame *frame)
Send a frame of data to the next filter.
Definition: avfilter.c:979
ff_insert_outpad
static int ff_insert_outpad(AVFilterContext *f, unsigned index, AVFilterPad *p)
Insert a new output pad for the filter.
Definition: internal.h:246
ff_tlog_ref
void ff_tlog_ref(void *ctx, AVFrame *ref, int end)
Definition: avfilter.c:50
avfilter.h
version.h
AVFilterCommand::command
char * command
command
Definition: internal.h:38
ref
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:107
AVFilterCommand::arg
char * arg
optional argument for the command
Definition: internal.h:39
FF_QSCALE_TYPE_VP56
#define FF_QSCALE_TYPE_VP56
Definition: internal.h:106
ff_insert_pad
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:104
AVFilterContext
An instance of a filter.
Definition: avfilter.h:333
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
h
h
Definition: vp9dsp_template.c:2038
ff_get_ref_perms_string
char * ff_get_ref_perms_string(char *buf, size_t buf_size, int perms)
int
int
Definition: ffmpeg_filter.c:156
ff_filter_get_nb_threads
int ff_filter_get_nb_threads(AVFilterContext *ctx) av_pure
Get number of threads for current filter instance.
Definition: avfilter.c:763
AVFilterCommand::time
double time
time expressed in seconds
Definition: internal.h:37