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 writable frames from its input link,
122  * duplicating data buffers if needed.
123  *
124  * input pads only.
125  */
127 };
128 
130  void *thread;
133 };
134 
137 };
138 
139 /**
140  * Tell if an integer is contained in the provided -1-terminated list of integers.
141  * This is useful for determining (for instance) if an AVPixelFormat is in an
142  * array of supported formats.
143  *
144  * @param fmt provided format
145  * @param fmts -1-terminated list of formats
146  * @return 1 if present, 0 if absent
147  */
148 int ff_fmt_is_in(int fmt, const int *fmts);
149 
150 /* Functions to parse audio format arguments */
151 
152 /**
153  * Parse a pixel format.
154  *
155  * @param ret pixel format pointer to where the value should be written
156  * @param arg string to parse
157  * @param log_ctx log context
158  * @return >= 0 in case of success, a negative AVERROR code on error
159  */
161 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
162 
163 /**
164  * Parse a sample rate.
165  *
166  * @param ret unsigned integer pointer to where the value should be written
167  * @param arg string to parse
168  * @param log_ctx log context
169  * @return >= 0 in case of success, a negative AVERROR code on error
170  */
172 int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx);
173 
174 /**
175  * Parse a channel layout or a corresponding integer representation.
176  *
177  * @param ret 64bit integer pointer to where the value should be written.
178  * @param nret integer pointer to the number of channels;
179  * if not NULL, then unknown channel layouts are accepted
180  * @param arg string to parse
181  * @param log_ctx log context
182  * @return >= 0 in case of success, a negative AVERROR code on error
183  */
185 int ff_parse_channel_layout(int64_t *ret, int *nret, const char *arg,
186  void *log_ctx);
187 
189 
190 /**
191  * Set the status field of a link from the source filter.
192  * The pts should reflect the timestamp of the status change,
193  * in link time base and relative to the frames timeline.
194  * In particular, for AVERROR_EOF, it should reflect the
195  * end time of the last frame.
196  */
198 
199 /**
200  * Set the status field of a link from the destination filter.
201  * The pts should probably be left unset (AV_NOPTS_VALUE).
202  */
204 
206 
207 #define D2TS(d) (isnan(d) ? AV_NOPTS_VALUE : (int64_t)(d))
208 #define TS2D(ts) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts))
209 #define TS2T(ts, tb) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts) * av_q2d(tb))
210 
211 /* misc trace functions */
212 
213 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
214 
215 char *ff_get_ref_perms_string(char *buf, size_t buf_size, int perms);
216 
217 void ff_tlog_ref(void *ctx, AVFrame *ref, int end);
218 
219 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
220 
221 /**
222  * Insert a new pad.
223  *
224  * @param idx Insertion point. Pad is inserted at the end if this point
225  * is beyond the end of the list of pads.
226  * @param count Pointer to the number of pads in the list
227  * @param padidx_off Offset within an AVFilterLink structure to the element
228  * to increment when inserting a new pad causes link
229  * numbering to change
230  * @param pads Pointer to the pointer to the beginning of the list of pads
231  * @param links Pointer to the pointer to the beginning of the list of links
232  * @param newpad The new pad to add. A copy is made when adding.
233  * @return >= 0 in case of success, a negative AVERROR code on error
234  */
235 int ff_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
236  AVFilterPad **pads, AVFilterLink ***links,
237  AVFilterPad *newpad);
238 
239 /** Insert a new input pad for the filter. */
240 static inline int ff_insert_inpad(AVFilterContext *f, unsigned index,
241  AVFilterPad *p)
242 {
243  return ff_insert_pad(index, &f->nb_inputs, offsetof(AVFilterLink, dstpad),
244  &f->input_pads, &f->inputs, p);
245 }
246 
247 /** Insert a new output pad for the filter. */
248 static inline int ff_insert_outpad(AVFilterContext *f, unsigned index,
249  AVFilterPad *p)
250 {
251  return ff_insert_pad(index, &f->nb_outputs, offsetof(AVFilterLink, srcpad),
252  &f->output_pads, &f->outputs, p);
253 }
254 
255 /**
256  * Request an input frame from the filter at the other end of the link.
257  *
258  * This function must not be used by filters using the activate callback,
259  * use ff_link_set_frame_wanted() instead.
260  *
261  * The input filter may pass the request on to its inputs, fulfill the
262  * request from an internal buffer or any other means specific to its function.
263  *
264  * When the end of a stream is reached AVERROR_EOF is returned and no further
265  * frames are returned after that.
266  *
267  * When a filter is unable to output a frame for example due to its sources
268  * being unable to do so or because it depends on external means pushing data
269  * into it then AVERROR(EAGAIN) is returned.
270  * It is important that a AVERROR(EAGAIN) return is returned all the way to the
271  * caller (generally eventually a user application) as this step may (but does
272  * not have to be) necessary to provide the input with the next frame.
273  *
274  * If a request is successful then some progress has been made towards
275  * providing a frame on the link (through ff_filter_frame()). A filter that
276  * needs several frames to produce one is allowed to return success if one
277  * more frame has been processed but no output has been produced yet. A
278  * filter is also allowed to simply forward a success return value.
279  *
280  * @param link the input link
281  * @return zero on success
282  * AVERROR_EOF on end of file
283  * AVERROR(EAGAIN) if the previous filter cannot output a frame
284  * currently and can neither guarantee that EOF has been reached.
285  */
287 
288 #define AVFILTER_DEFINE_CLASS(fname) \
289  static const AVClass fname##_class = { \
290  .class_name = #fname, \
291  .item_name = av_default_item_name, \
292  .option = fname##_options, \
293  .version = LIBAVUTIL_VERSION_INT, \
294  .category = AV_CLASS_CATEGORY_FILTER, \
295  }
296 
297 /**
298  * Find the index of a link.
299  *
300  * I.e. find i such that link == ctx->(in|out)puts[i]
301  */
302 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
303 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
304 
305 /**
306  * Send a frame of data to the next filter.
307  *
308  * @param link the output link over which the data is being sent
309  * @param frame a reference to the buffer of data being sent. The
310  * receiving filter will free this reference when it no longer
311  * needs it or pass it on to the next filter.
312  *
313  * @return >= 0 on success, a negative AVERROR on error. The receiving filter
314  * is responsible for unreferencing frame in case of error.
315  */
317 
318 /**
319  * Allocate a new filter context and return it.
320  *
321  * @param filter what filter to create an instance of
322  * @param inst_name name to give to the new filter context
323  *
324  * @return newly created filter context or NULL on failure
325  */
326 AVFilterContext *ff_filter_alloc(const AVFilter *filter, const char *inst_name);
327 
329 
330 /**
331  * Remove a filter from a graph;
332  */
334 
335 /**
336  * The filter is aware of hardware frames, and any hardware frame context
337  * should not be automatically propagated through it.
338  */
339 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
340 
341 /**
342  * Run one round of processing on a filter graph.
343  */
345 
346 /**
347  * Normalize the qscale factor
348  * FIXME the H264 qscale is a log based scale, mpeg1/2 is not, the code below
349  * cannot be optimal
350  */
351 static inline int ff_norm_qscale(int qscale, int type)
352 {
353  switch (type) {
354  case FF_QSCALE_TYPE_MPEG1: return qscale;
355  case FF_QSCALE_TYPE_MPEG2: return qscale >> 1;
356  case FF_QSCALE_TYPE_H264: return qscale >> 2;
357  case FF_QSCALE_TYPE_VP56: return (63 - qscale + 2) >> 2;
358  }
359  return qscale;
360 }
361 
362 /**
363  * Get number of threads for current filter instance.
364  * This number is always same or less than graph->nb_threads.
365  */
367 
368 /**
369  * Generic processing of user supplied commands that are set
370  * in the same way as the filter options.
371  * NOTE: 'enable' option is handled separately, and not by
372  * this function.
373  */
374 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
375  const char *arg, char *res, int res_len, int flags);
376 
377 /**
378  * Perform any additional setup required for hardware frames.
379  *
380  * link->hw_frames_ctx must be set before calling this function.
381  * Inside link->hw_frames_ctx, the fields format, sw_format, width and
382  * height must be set. If dynamically allocated pools are not supported,
383  * then initial_pool_size must also be set, to the minimum hardware frame
384  * pool size necessary for the filter to work (taking into account any
385  * frames which need to stored for use in operations as appropriate). If
386  * default_pool_size is nonzero, then it will be used as the pool size if
387  * no other modification takes place (this can be used to preserve
388  * compatibility).
389  */
391  int default_pool_size);
392 
393 #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:1340
AVFilterGraphInternal::frame_queues
FFFrameQueueGlobal frame_queues
Definition: internal.h:132
ff_tlog_link
void ff_tlog_link(void *ctx, AVFilterLink *link, int end)
Definition: avfilter.c:384
thread.h
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:318
w
uint8_t w
Definition: llviddspenc.c:39
internal.h
AVFilterGraphInternal
Definition: internal.h:129
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
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:408
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:211
formats.h
AVFilterGraphInternal::thread
void * thread
Definition: internal.h:130
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:240
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:663
AVFilterCommand::flags
int flags
Definition: internal.h:42
ff_filter_activate
int ff_filter_activate(AVFilterContext *filter)
Definition: avfilter.c:1434
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:652
AVFilterPad
A filter pad used for either input or output.
Definition: internal.h:54
AVFilterPad::request_frame
int(* request_frame)(AVFilterLink *link)
Frame request callback.
Definition: internal.h:102
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:224
FF_QSCALE_TYPE_MPEG2
#define FF_QSCALE_TYPE_MPEG2
Definition: internal.h:103
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:1653
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:882
ff_command_queue_pop
void ff_command_queue_pop(AVFilterContext *filter)
Definition: avfilter.c:94
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:644
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:66
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:617
framequeue.h
AVFilterInternal
Definition: internal.h:135
ff_update_link_current_pts
void ff_update_link_current_pts(AVFilterLink *link, int64_t pts)
Definition: avfilter.c:529
AVFilterPad::filter_frame
int(* filter_frame)(AVFilterLink *link, AVFrame *frame)
Filtering callback.
Definition: internal.h:93
AVFilterGraph
Definition: avfilter.h:850
index
int index
Definition: gxfenc.c:89
ff_filter_get_nb_threads
int ff_filter_get_nb_threads(AVFilterContext *ctx)
Get number of threads for current filter instance.
Definition: avfilter.c:802
AVFilterPad::config_props
int(* config_props)(AVFilterLink *link)
Link configuration callback.
Definition: internal.h:118
AVMediaType
AVMediaType
Definition: avutil.h:199
FF_QSCALE_TYPE_MPEG1
#define FF_QSCALE_TYPE_MPEG1
Definition: internal.h:102
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:847
AVFilterCommand::next
struct AVFilterCommand * next
Definition: internal.h:43
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:351
AVFilterGraphInternal::thread_execute
avfilter_execute_func * thread_execute
Definition: internal.h:131
AVFilterPad::needs_writable
int needs_writable
The filter expects writable frames from its input link, duplicating data buffers if needed.
Definition: internal.h:126
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:1391
FF_QSCALE_TYPE_H264
#define FF_QSCALE_TYPE_H264
Definition: internal.h:104
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:632
internal.h
AVFilterCommand
Definition: internal.h:38
AVFilterPad::name
const char * name
Pad name.
Definition: internal.h:60
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:65
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
framepool.h
AVFilterInternal::execute
avfilter_execute_func * execute
Definition: internal.h:136
ff_filter_frame
int ff_filter_frame(AVFilterLink *link, AVFrame *frame)
Send a frame of data to the next filter.
Definition: avfilter.c:1096
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:248
ff_tlog_ref
void ff_tlog_ref(void *ctx, AVFrame *ref, int end)
Definition: avfilter.c:49
avfilter.h
version.h
AVFilterCommand::command
char * command
command
Definition: internal.h:40
ref
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:107
AVFilterCommand::arg
char * arg
optional argument for the command
Definition: internal.h:41
FF_QSCALE_TYPE_VP56
#define FF_QSCALE_TYPE_VP56
Definition: internal.h:105
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:103
AVFilterContext
An instance of a filter.
Definition: avfilter.h:341
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:170
AVFilterCommand::time
double time
time expressed in seconds
Definition: internal.h:39