FFmpeg coverage


Directory: ../../../ffmpeg/
File: src/libavfilter/internal.h
Date: 2024-04-19 17:50:32
Exec Total Coverage
Lines: 4 4 100.0%
Functions: 2 2 100.0%
Branches: 0 0 -%

Line Branch Exec Source
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
30 /**
31 * A filter pad used for either input or output.
32 */
33 struct AVFilterPad {
34 /**
35 * Pad name. The name is unique among inputs and among outputs, but an
36 * input may have the same name as an output. This may be NULL if this
37 * pad has no need to ever be referenced by name.
38 */
39 const char *name;
40
41 /**
42 * AVFilterPad type.
43 */
44 enum AVMediaType type;
45
46 /**
47 * The filter expects writable frames from its input link,
48 * duplicating data buffers if needed.
49 *
50 * input pads only.
51 */
52 #define AVFILTERPAD_FLAG_NEEDS_WRITABLE (1 << 0)
53
54 /**
55 * The pad's name is allocated and should be freed generically.
56 */
57 #define AVFILTERPAD_FLAG_FREE_NAME (1 << 1)
58
59 /**
60 * A combination of AVFILTERPAD_FLAG_* flags.
61 */
62 int flags;
63
64 /**
65 * Callback functions to get a video/audio buffers. If NULL,
66 * the filter system will use ff_default_get_video_buffer() for video
67 * and ff_default_get_audio_buffer() for audio.
68 *
69 * The state of the union is determined by type.
70 *
71 * Input pads only.
72 */
73 union {
74 AVFrame *(*video)(AVFilterLink *link, int w, int h);
75 AVFrame *(*audio)(AVFilterLink *link, int nb_samples);
76 } get_buffer;
77
78 /**
79 * Filtering callback. This is where a filter receives a frame with
80 * audio/video data and should do its processing.
81 *
82 * Input pads only.
83 *
84 * @return >= 0 on success, a negative AVERROR on error. This function
85 * must ensure that frame is properly unreferenced on error if it
86 * hasn't been passed on to another filter.
87 */
88 int (*filter_frame)(AVFilterLink *link, AVFrame *frame);
89
90 /**
91 * Frame request callback. A call to this should result in some progress
92 * towards producing output over the given link. This should return zero
93 * on success, and another value on error.
94 *
95 * Output pads only.
96 */
97 int (*request_frame)(AVFilterLink *link);
98
99 /**
100 * Link configuration callback.
101 *
102 * For output pads, this should set the link properties such as
103 * width/height. This should NOT set the format property - that is
104 * negotiated between filters by the filter system using the
105 * query_formats() callback before this function is called.
106 *
107 * For input pads, this should check the properties of the link, and update
108 * the filter's internal state as necessary.
109 *
110 * For both input and output filters, this should return zero on success,
111 * and another value on error.
112 */
113 int (*config_props)(AVFilterLink *link);
114 };
115
116 typedef struct FFFilterContext {
117 /**
118 * The public AVFilterContext. See avfilter.h for it.
119 */
120 AVFilterContext p;
121
122 avfilter_execute_func *execute;
123
124 // 1 when avfilter_init_*() was successfully called on this filter
125 // 0 otherwise
126 int initialized;
127 } FFFilterContext;
128
129 140083 static inline FFFilterContext *fffilterctx(AVFilterContext *ctx)
130 {
131 140083 return (FFFilterContext*)ctx;
132 }
133
134 4164 static av_always_inline int ff_filter_execute(AVFilterContext *ctx, avfilter_action_func *func,
135 void *arg, int *ret, int nb_jobs)
136 {
137 4164 return fffilterctx(ctx)->execute(ctx, func, arg, ret, nb_jobs);
138 }
139
140 enum FilterFormatsState {
141 /**
142 * The default value meaning that this filter supports all formats
143 * and (for audio) sample rates and channel layouts/counts as long
144 * as these properties agree for all inputs and outputs.
145 * This state is only allowed in case all inputs and outputs actually
146 * have the same type.
147 * The union is unused in this state.
148 *
149 * This value must always be zero (for default static initialization).
150 */
151 FF_FILTER_FORMATS_PASSTHROUGH = 0,
152 FF_FILTER_FORMATS_QUERY_FUNC, ///< formats.query active.
153 FF_FILTER_FORMATS_PIXFMT_LIST, ///< formats.pixels_list active.
154 FF_FILTER_FORMATS_SAMPLEFMTS_LIST, ///< formats.samples_list active.
155 FF_FILTER_FORMATS_SINGLE_PIXFMT, ///< formats.pix_fmt active
156 FF_FILTER_FORMATS_SINGLE_SAMPLEFMT, ///< formats.sample_fmt active.
157 };
158
159 #define FILTER_QUERY_FUNC(func) \
160 .formats.query_func = func, \
161 .formats_state = FF_FILTER_FORMATS_QUERY_FUNC
162 #define FILTER_PIXFMTS_ARRAY(array) \
163 .formats.pixels_list = array, \
164 .formats_state = FF_FILTER_FORMATS_PIXFMT_LIST
165 #define FILTER_SAMPLEFMTS_ARRAY(array) \
166 .formats.samples_list = array, \
167 .formats_state = FF_FILTER_FORMATS_SAMPLEFMTS_LIST
168 #define FILTER_PIXFMTS(...) \
169 FILTER_PIXFMTS_ARRAY(((const enum AVPixelFormat []) { __VA_ARGS__, AV_PIX_FMT_NONE }))
170 #define FILTER_SAMPLEFMTS(...) \
171 FILTER_SAMPLEFMTS_ARRAY(((const enum AVSampleFormat[]) { __VA_ARGS__, AV_SAMPLE_FMT_NONE }))
172 #define FILTER_SINGLE_PIXFMT(pix_fmt_) \
173 .formats.pix_fmt = pix_fmt_, \
174 .formats_state = FF_FILTER_FORMATS_SINGLE_PIXFMT
175 #define FILTER_SINGLE_SAMPLEFMT(sample_fmt_) \
176 .formats.sample_fmt = sample_fmt_, \
177 .formats_state = FF_FILTER_FORMATS_SINGLE_SAMPLEFMT
178
179 #define FILTER_INOUTPADS(inout, array) \
180 .inout = array, \
181 .nb_ ## inout = FF_ARRAY_ELEMS(array)
182 #define FILTER_INPUTS(array) FILTER_INOUTPADS(inputs, (array))
183 #define FILTER_OUTPUTS(array) FILTER_INOUTPADS(outputs, (array))
184
185 /**
186 * Tell if an integer is contained in the provided -1-terminated list of integers.
187 * This is useful for determining (for instance) if an AVPixelFormat is in an
188 * array of supported formats.
189 *
190 * @param fmt provided format
191 * @param fmts -1-terminated list of formats
192 * @return 1 if present, 0 if absent
193 */
194 int ff_fmt_is_in(int fmt, const int *fmts);
195
196 /**
197 * Returns true if a pixel format is "regular YUV", which includes all pixel
198 * formats that are affected by YUV colorspace negotiation.
199 */
200 int ff_fmt_is_regular_yuv(enum AVPixelFormat fmt);
201
202 /* Functions to parse audio format arguments */
203
204 /**
205 * Parse a pixel format.
206 *
207 * @param ret pixel format 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 */
212 av_warn_unused_result
213 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
214
215 /**
216 * Parse a sample rate.
217 *
218 * @param ret unsigned integer pointer to where the value should be written
219 * @param arg string to parse
220 * @param log_ctx log context
221 * @return >= 0 in case of success, a negative AVERROR code on error
222 */
223 av_warn_unused_result
224 int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx);
225
226 /**
227 * Parse a channel layout or a corresponding integer representation.
228 *
229 * @param ret 64bit integer pointer to where the value should be written.
230 * @param nret integer pointer to the number of channels;
231 * if not NULL, then unknown channel layouts are accepted
232 * @param arg string to parse
233 * @param log_ctx log context
234 * @return >= 0 in case of success, a negative AVERROR code on error
235 */
236 av_warn_unused_result
237 int ff_parse_channel_layout(AVChannelLayout *ret, int *nret, const char *arg,
238 void *log_ctx);
239
240 /**
241 * Set the status field of a link from the source filter.
242 * The pts should reflect the timestamp of the status change,
243 * in link time base and relative to the frames timeline.
244 * In particular, for AVERROR_EOF, it should reflect the
245 * end time of the last frame.
246 */
247 void ff_avfilter_link_set_in_status(AVFilterLink *link, int status, int64_t pts);
248
249 /**
250 * Negotiate the media format, dimensions, etc of all inputs to a filter.
251 *
252 * @param filter the filter to negotiate the properties for its inputs
253 * @return zero on successful negotiation
254 */
255 int ff_filter_config_links(AVFilterContext *filter);
256
257 #define D2TS(d) (isnan(d) ? AV_NOPTS_VALUE : (int64_t)(d))
258 #define TS2D(ts) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts))
259 #define TS2T(ts, tb) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts) * av_q2d(tb))
260
261 /* misc trace functions */
262
263 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
264
265 #ifdef TRACE
266 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
267 #else
268 #define ff_tlog_link(ctx, link, end) do { } while(0)
269 #endif
270
271 /**
272 * Append a new input/output pad to the filter's list of such pads.
273 *
274 * The *_free_name versions will set the AVFILTERPAD_FLAG_FREE_NAME flag
275 * ensuring that the name will be freed generically (even on insertion error).
276 */
277 int ff_append_inpad (AVFilterContext *f, AVFilterPad *p);
278 int ff_append_outpad(AVFilterContext *f, AVFilterPad *p);
279 int ff_append_inpad_free_name (AVFilterContext *f, AVFilterPad *p);
280 int ff_append_outpad_free_name(AVFilterContext *f, AVFilterPad *p);
281
282 /**
283 * Request an input frame from the filter at the other end of the link.
284 *
285 * This function must not be used by filters using the activate callback,
286 * use ff_link_set_frame_wanted() instead.
287 *
288 * The input filter may pass the request on to its inputs, fulfill the
289 * request from an internal buffer or any other means specific to its function.
290 *
291 * When the end of a stream is reached AVERROR_EOF is returned and no further
292 * frames are returned after that.
293 *
294 * When a filter is unable to output a frame for example due to its sources
295 * being unable to do so or because it depends on external means pushing data
296 * into it then AVERROR(EAGAIN) is returned.
297 * It is important that a AVERROR(EAGAIN) return is returned all the way to the
298 * caller (generally eventually a user application) as this step may (but does
299 * not have to be) necessary to provide the input with the next frame.
300 *
301 * If a request is successful then some progress has been made towards
302 * providing a frame on the link (through ff_filter_frame()). A filter that
303 * needs several frames to produce one is allowed to return success if one
304 * more frame has been processed but no output has been produced yet. A
305 * filter is also allowed to simply forward a success return value.
306 *
307 * @param link the input link
308 * @return zero on success
309 * AVERROR_EOF on end of file
310 * AVERROR(EAGAIN) if the previous filter cannot output a frame
311 * currently and can neither guarantee that EOF has been reached.
312 */
313 int ff_request_frame(AVFilterLink *link);
314
315 #define AVFILTER_DEFINE_CLASS_EXT(name, desc, options) \
316 static const AVClass name##_class = { \
317 .class_name = desc, \
318 .item_name = av_default_item_name, \
319 .option = options, \
320 .version = LIBAVUTIL_VERSION_INT, \
321 .category = AV_CLASS_CATEGORY_FILTER, \
322 }
323 #define AVFILTER_DEFINE_CLASS(fname) \
324 AVFILTER_DEFINE_CLASS_EXT(fname, #fname, fname##_options)
325
326 /**
327 * Find the index of a link.
328 *
329 * I.e. find i such that link == ctx->(in|out)puts[i]
330 */
331 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
332 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
333
334 /**
335 * Send a frame of data to the next filter.
336 *
337 * @param link the output link over which the data is being sent
338 * @param frame a reference to the buffer of data being sent. The
339 * receiving filter will free this reference when it no longer
340 * needs it or pass it on to the next filter.
341 *
342 * @return >= 0 on success, a negative AVERROR on error. The receiving filter
343 * is responsible for unreferencing frame in case of error.
344 */
345 int ff_filter_frame(AVFilterLink *link, AVFrame *frame);
346
347 /**
348 * The filter is aware of hardware frames, and any hardware frame context
349 * should not be automatically propagated through it.
350 */
351 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
352
353 /**
354 * Run one round of processing on a filter graph.
355 */
356 int ff_filter_graph_run_once(AVFilterGraph *graph);
357
358 /**
359 * Get number of threads for current filter instance.
360 * This number is always same or less than graph->nb_threads.
361 */
362 int ff_filter_get_nb_threads(AVFilterContext *ctx) av_pure;
363
364 /**
365 * Generic processing of user supplied commands that are set
366 * in the same way as the filter options.
367 * NOTE: 'enable' option is handled separately, and not by
368 * this function.
369 */
370 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
371 const char *arg, char *res, int res_len, int flags);
372
373 /**
374 * Perform any additional setup required for hardware frames.
375 *
376 * link->hw_frames_ctx must be set before calling this function.
377 * Inside link->hw_frames_ctx, the fields format, sw_format, width and
378 * height must be set. If dynamically allocated pools are not supported,
379 * then initial_pool_size must also be set, to the minimum hardware frame
380 * pool size necessary for the filter to work (taking into account any
381 * frames which need to stored for use in operations as appropriate). If
382 * default_pool_size is nonzero, then it will be used as the pool size if
383 * no other modification takes place (this can be used to preserve
384 * compatibility).
385 */
386 int ff_filter_init_hw_frames(AVFilterContext *avctx, AVFilterLink *link,
387 int default_pool_size);
388
389 #endif /* AVFILTER_INTERNAL_H */
390