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  */
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 */
This structure describes decoded (raw) audio or video data.
Definition: frame.h:308
int ff_filter_frame(AVFilterLink *link, AVFrame *frame)
Send a frame of data to the next filter.
Definition: avfilter.c:1091
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:94
Libavfilter version macros.
int ff_filter_activate(AVFilterContext *filter)
Definition: avfilter.c:1429
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:349
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:352
#define f(width, name)
Definition: cbs_vp9.c:255
static av_cold int end(AVCodecContext *avctx)
Definition: avrndec.c:92
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:258
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:852
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:1648
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:885
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:348
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:800
unsigned nb_outputs
number of output pads
Definition: avfilter.h:354
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:618
unsigned nb_inputs
number of input pads
Definition: avfilter.h:350
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:126
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:645
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 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:145
int index
Definition: gxfenc.c:89
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:95
AVFilterLink ** outputs
array of pointers to output links
Definition: avfilter.h:353
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
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:62
#define FF_QSCALE_TYPE_MPEG2
Definition: internal.h:93
int
common internal api header.
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:633
avfilter_execute_func * execute
Definition: internal.h:136
void ff_tlog_ref(void *ctx, AVFrame *ref, int end)
Definition: avfilter.c:49
avfilter_execute_func * thread_execute
Definition: internal.h:131
void ff_tlog_link(void *ctx, AVFilterLink *link, int end)
Definition: avfilter.c:383
An instance of a filter.
Definition: avfilter.h:341
AVFilterContext * ff_filter_alloc(const AVFilter *filter, const char *inst_name)
Allocate a new filter context and return it.
Definition: avfilter.c:661
FFFrameQueueGlobal frame_queues
Definition: internal.h:132
double time
time expressed in seconds
Definition: internal.h:39
#define FF_QSCALE_TYPE_MPEG1
Definition: internal.h:92
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:248
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:240
char * arg
optional argument for the command
Definition: internal.h:41