d3c977a7e28dc9e7b2b514e41013db7067bf7243
[libav.git] / libavfilter / avfilter.h
1 /*
2 * filter layer
3 * Copyright (c) 2007 Bobby Bingham
4 *
5 * This file is part of Libav.
6 *
7 * Libav is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * Libav is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with Libav; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22 #ifndef AVFILTER_AVFILTER_H
23 #define AVFILTER_AVFILTER_H
24
25 #include "libavutil/avutil.h"
26 #include "libavutil/samplefmt.h"
27 #include "libavutil/pixfmt.h"
28 #include "libavutil/rational.h"
29
30 #define LIBAVFILTER_VERSION_MAJOR 2
31 #define LIBAVFILTER_VERSION_MINOR 4
32 #define LIBAVFILTER_VERSION_MICRO 0
33
34 #define LIBAVFILTER_VERSION_INT AV_VERSION_INT(LIBAVFILTER_VERSION_MAJOR, \
35 LIBAVFILTER_VERSION_MINOR, \
36 LIBAVFILTER_VERSION_MICRO)
37 #define LIBAVFILTER_VERSION AV_VERSION(LIBAVFILTER_VERSION_MAJOR, \
38 LIBAVFILTER_VERSION_MINOR, \
39 LIBAVFILTER_VERSION_MICRO)
40 #define LIBAVFILTER_BUILD LIBAVFILTER_VERSION_INT
41
42 #include <stddef.h>
43
44 /**
45 * Return the LIBAVFILTER_VERSION_INT constant.
46 */
47 unsigned avfilter_version(void);
48
49 /**
50 * Return the libavfilter build-time configuration.
51 */
52 const char *avfilter_configuration(void);
53
54 /**
55 * Return the libavfilter license.
56 */
57 const char *avfilter_license(void);
58
59
60 typedef struct AVFilterContext AVFilterContext;
61 typedef struct AVFilterLink AVFilterLink;
62 typedef struct AVFilterPad AVFilterPad;
63
64 /**
65 * A reference-counted buffer data type used by the filter system. Filters
66 * should not store pointers to this structure directly, but instead use the
67 * AVFilterBufferRef structure below.
68 */
69 typedef struct AVFilterBuffer {
70 uint8_t *data[8]; ///< buffer data for each plane/channel
71 int linesize[8]; ///< number of bytes per line
72
73 unsigned refcount; ///< number of references to this buffer
74
75 /** private data to be used by a custom free function */
76 void *priv;
77 /**
78 * A pointer to the function to deallocate this buffer if the default
79 * function is not sufficient. This could, for example, add the memory
80 * back into a memory pool to be reused later without the overhead of
81 * reallocating it from scratch.
82 */
83 void (*free)(struct AVFilterBuffer *buf);
84
85 int format; ///< media format
86 int w, h; ///< width and height of the allocated buffer
87 } AVFilterBuffer;
88
89 #define AV_PERM_READ 0x01 ///< can read from the buffer
90 #define AV_PERM_WRITE 0x02 ///< can write to the buffer
91 #define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer
92 #define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times, with the same contents each time
93 #define AV_PERM_REUSE2 0x10 ///< can output the buffer multiple times, modified each time
94 #define AV_PERM_NEG_LINESIZES 0x20 ///< the buffer requested can have negative linesizes
95
96 /**
97 * Audio specific properties in a reference to an AVFilterBuffer. Since
98 * AVFilterBufferRef is common to different media formats, audio specific
99 * per reference properties must be separated out.
100 */
101 typedef struct AVFilterBufferRefAudioProps {
102 int64_t channel_layout; ///< channel layout of audio buffer
103 int nb_samples; ///< number of audio samples
104 int size; ///< audio buffer size
105 uint32_t sample_rate; ///< audio buffer sample rate
106 int planar; ///< audio buffer - planar or packed
107 } AVFilterBufferRefAudioProps;
108
109 /**
110 * Video specific properties in a reference to an AVFilterBuffer. Since
111 * AVFilterBufferRef is common to different media formats, video specific
112 * per reference properties must be separated out.
113 */
114 typedef struct AVFilterBufferRefVideoProps {
115 int w; ///< image width
116 int h; ///< image height
117 AVRational pixel_aspect; ///< pixel aspect ratio
118 int interlaced; ///< is frame interlaced
119 int top_field_first; ///< field order
120 enum AVPictureType pict_type; ///< picture type of the frame
121 int key_frame; ///< 1 -> keyframe, 0-> not
122 } AVFilterBufferRefVideoProps;
123
124 /**
125 * A reference to an AVFilterBuffer. Since filters can manipulate the origin of
126 * a buffer to, for example, crop image without any memcpy, the buffer origin
127 * and dimensions are per-reference properties. Linesize is also useful for
128 * image flipping, frame to field filters, etc, and so is also per-reference.
129 *
130 * TODO: add anything necessary for frame reordering
131 */
132 typedef struct AVFilterBufferRef {
133 AVFilterBuffer *buf; ///< the buffer that this is a reference to
134 uint8_t *data[8]; ///< picture/audio data for each plane
135 int linesize[8]; ///< number of bytes per line
136 int format; ///< media format
137
138 /**
139 * presentation timestamp. The time unit may change during
140 * filtering, as it is specified in the link and the filter code
141 * may need to rescale the PTS accordingly.
142 */
143 int64_t pts;
144 int64_t pos; ///< byte position in stream, -1 if unknown
145
146 int perms; ///< permissions, see the AV_PERM_* flags
147
148 enum AVMediaType type; ///< media type of buffer data
149 AVFilterBufferRefVideoProps *video; ///< video buffer specific properties
150 AVFilterBufferRefAudioProps *audio; ///< audio buffer specific properties
151 } AVFilterBufferRef;
152
153 /**
154 * Copy properties of src to dst, without copying the actual data
155 */
156 static inline void avfilter_copy_buffer_ref_props(AVFilterBufferRef *dst, AVFilterBufferRef *src)
157 {
158 // copy common properties
159 dst->pts = src->pts;
160 dst->pos = src->pos;
161
162 switch (src->type) {
163 case AVMEDIA_TYPE_VIDEO: *dst->video = *src->video; break;
164 case AVMEDIA_TYPE_AUDIO: *dst->audio = *src->audio; break;
165 }
166 }
167
168 /**
169 * Add a new reference to a buffer.
170 *
171 * @param ref an existing reference to the buffer
172 * @param pmask a bitmask containing the allowable permissions in the new
173 * reference
174 * @return a new reference to the buffer with the same properties as the
175 * old, excluding any permissions denied by pmask
176 */
177 AVFilterBufferRef *avfilter_ref_buffer(AVFilterBufferRef *ref, int pmask);
178
179 /**
180 * Remove a reference to a buffer. If this is the last reference to the
181 * buffer, the buffer itself is also automatically freed.
182 *
183 * @param ref reference to the buffer, may be NULL
184 */
185 void avfilter_unref_buffer(AVFilterBufferRef *ref);
186
187 /**
188 * A list of supported formats for one end of a filter link. This is used
189 * during the format negotiation process to try to pick the best format to
190 * use to minimize the number of necessary conversions. Each filter gives a
191 * list of the formats supported by each input and output pad. The list
192 * given for each pad need not be distinct - they may be references to the
193 * same list of formats, as is often the case when a filter supports multiple
194 * formats, but will always output the same format as it is given in input.
195 *
196 * In this way, a list of possible input formats and a list of possible
197 * output formats are associated with each link. When a set of formats is
198 * negotiated over a link, the input and output lists are merged to form a
199 * new list containing only the common elements of each list. In the case
200 * that there were no common elements, a format conversion is necessary.
201 * Otherwise, the lists are merged, and all other links which reference
202 * either of the format lists involved in the merge are also affected.
203 *
204 * For example, consider the filter chain:
205 * filter (a) --> (b) filter (b) --> (c) filter
206 *
207 * where the letters in parenthesis indicate a list of formats supported on
208 * the input or output of the link. Suppose the lists are as follows:
209 * (a) = {A, B}
210 * (b) = {A, B, C}
211 * (c) = {B, C}
212 *
213 * First, the first link's lists are merged, yielding:
214 * filter (a) --> (a) filter (a) --> (c) filter
215 *
216 * Notice that format list (b) now refers to the same list as filter list (a).
217 * Next, the lists for the second link are merged, yielding:
218 * filter (a) --> (a) filter (a) --> (a) filter
219 *
220 * where (a) = {B}.
221 *
222 * Unfortunately, when the format lists at the two ends of a link are merged,
223 * we must ensure that all links which reference either pre-merge format list
224 * get updated as well. Therefore, we have the format list structure store a
225 * pointer to each of the pointers to itself.
226 */
227 typedef struct AVFilterFormats {
228 unsigned format_count; ///< number of formats
229 int *formats; ///< list of media formats
230
231 unsigned refcount; ///< number of references to this list
232 struct AVFilterFormats ***refs; ///< references to this list
233 } AVFilterFormats;
234
235 /**
236 * Create a list of supported formats. This is intended for use in
237 * AVFilter->query_formats().
238 *
239 * @param fmts list of media formats, terminated by -1
240 * @return the format list, with no existing references
241 */
242 AVFilterFormats *avfilter_make_format_list(const int *fmts);
243
244 /**
245 * Add fmt to the list of media formats contained in *avff.
246 * If *avff is NULL the function allocates the filter formats struct
247 * and puts its pointer in *avff.
248 *
249 * @return a non negative value in case of success, or a negative
250 * value corresponding to an AVERROR code in case of error
251 */
252 int avfilter_add_format(AVFilterFormats **avff, int fmt);
253
254 /**
255 * Return a list of all formats supported by Libav for the given media type.
256 */
257 AVFilterFormats *avfilter_all_formats(enum AVMediaType type);
258
259 /**
260 * Return a format list which contains the intersection of the formats of
261 * a and b. Also, all the references of a, all the references of b, and
262 * a and b themselves will be deallocated.
263 *
264 * If a and b do not share any common formats, neither is modified, and NULL
265 * is returned.
266 */
267 AVFilterFormats *avfilter_merge_formats(AVFilterFormats *a, AVFilterFormats *b);
268
269 /**
270 * Add *ref as a new reference to formats.
271 * That is the pointers will point like in the ascii art below:
272 * ________
273 * |formats |<--------.
274 * | ____ | ____|___________________
275 * | |refs| | | __|_
276 * | |* * | | | | | | AVFilterLink
277 * | |* *--------->|*ref|
278 * | |____| | | |____|
279 * |________| |________________________
280 */
281 void avfilter_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref);
282
283 /**
284 * If *ref is non-NULL, remove *ref as a reference to the format list
285 * it currently points to, deallocates that list if this was the last
286 * reference, and sets *ref to NULL.
287 *
288 * Before After
289 * ________ ________ NULL
290 * |formats |<--------. |formats | ^
291 * | ____ | ____|________________ | ____ | ____|________________
292 * | |refs| | | __|_ | |refs| | | __|_
293 * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
294 * | |* *--------->|*ref| | |* | | | |*ref|
295 * | |____| | | |____| | |____| | | |____|
296 * |________| |_____________________ |________| |_____________________
297 */
298 void avfilter_formats_unref(AVFilterFormats **ref);
299
300 /**
301 *
302 * Before After
303 * ________ ________
304 * |formats |<---------. |formats |<---------.
305 * | ____ | ___|___ | ____ | ___|___
306 * | |refs| | | | | | |refs| | | | | NULL
307 * | |* *--------->|*oldref| | |* *--------->|*newref| ^
308 * | |* * | | |_______| | |* * | | |_______| ___|___
309 * | |____| | | |____| | | | |
310 * |________| |________| |*oldref|
311 * |_______|
312 */
313 void avfilter_formats_changeref(AVFilterFormats **oldref,
314 AVFilterFormats **newref);
315
316 /**
317 * A filter pad used for either input or output.
318 */
319 struct AVFilterPad {
320 /**
321 * Pad name. The name is unique among inputs and among outputs, but an
322 * input may have the same name as an output. This may be NULL if this
323 * pad has no need to ever be referenced by name.
324 */
325 const char *name;
326
327 /**
328 * AVFilterPad type. Only video supported now, hopefully someone will
329 * add audio in the future.
330 */
331 enum AVMediaType type;
332
333 /**
334 * Minimum required permissions on incoming buffers. Any buffer with
335 * insufficient permissions will be automatically copied by the filter
336 * system to a new buffer which provides the needed access permissions.
337 *
338 * Input pads only.
339 */
340 int min_perms;
341
342 /**
343 * Permissions which are not accepted on incoming buffers. Any buffer
344 * which has any of these permissions set will be automatically copied
345 * by the filter system to a new buffer which does not have those
346 * permissions. This can be used to easily disallow buffers with
347 * AV_PERM_REUSE.
348 *
349 * Input pads only.
350 */
351 int rej_perms;
352
353 /**
354 * Callback called before passing the first slice of a new frame. If
355 * NULL, the filter layer will default to storing a reference to the
356 * picture inside the link structure.
357 *
358 * Input video pads only.
359 */
360 void (*start_frame)(AVFilterLink *link, AVFilterBufferRef *picref);
361
362 /**
363 * Callback function to get a video buffer. If NULL, the filter system will
364 * use avfilter_default_get_video_buffer().
365 *
366 * Input video pads only.
367 */
368 AVFilterBufferRef *(*get_video_buffer)(AVFilterLink *link, int perms, int w, int h);
369
370 /**
371 * Callback function to get an audio buffer. If NULL, the filter system will
372 * use avfilter_default_get_audio_buffer().
373 *
374 * Input audio pads only.
375 */
376 AVFilterBufferRef *(*get_audio_buffer)(AVFilterLink *link, int perms,
377 enum AVSampleFormat sample_fmt, int size,
378 int64_t channel_layout, int planar);
379
380 /**
381 * Callback called after the slices of a frame are completely sent. If
382 * NULL, the filter layer will default to releasing the reference stored
383 * in the link structure during start_frame().
384 *
385 * Input video pads only.
386 */
387 void (*end_frame)(AVFilterLink *link);
388
389 /**
390 * Slice drawing callback. This is where a filter receives video data
391 * and should do its processing.
392 *
393 * Input video pads only.
394 */
395 void (*draw_slice)(AVFilterLink *link, int y, int height, int slice_dir);
396
397 /**
398 * Samples filtering callback. This is where a filter receives audio data
399 * and should do its processing.
400 *
401 * Input audio pads only.
402 */
403 void (*filter_samples)(AVFilterLink *link, AVFilterBufferRef *samplesref);
404
405 /**
406 * Frame poll callback. This returns the number of immediately available
407 * samples. It should return a positive value if the next request_frame()
408 * is guaranteed to return one frame (with no delay).
409 *
410 * Defaults to just calling the source poll_frame() method.
411 *
412 * Output video pads only.
413 */
414 int (*poll_frame)(AVFilterLink *link);
415
416 /**
417 * Frame request callback. A call to this should result in at least one
418 * frame being output over the given link. This should return zero on
419 * success, and another value on error.
420 *
421 * Output video pads only.
422 */
423 int (*request_frame)(AVFilterLink *link);
424
425 /**
426 * Link configuration callback.
427 *
428 * For output pads, this should set the link properties such as
429 * width/height. This should NOT set the format property - that is
430 * negotiated between filters by the filter system using the
431 * query_formats() callback before this function is called.
432 *
433 * For input pads, this should check the properties of the link, and update
434 * the filter's internal state as necessary.
435 *
436 * For both input and output filters, this should return zero on success,
437 * and another value on error.
438 */
439 int (*config_props)(AVFilterLink *link);
440 };
441
442 /** default handler for start_frame() for video inputs */
443 void avfilter_default_start_frame(AVFilterLink *link, AVFilterBufferRef *picref);
444
445 /** default handler for draw_slice() for video inputs */
446 void avfilter_default_draw_slice(AVFilterLink *link, int y, int h, int slice_dir);
447
448 /** default handler for end_frame() for video inputs */
449 void avfilter_default_end_frame(AVFilterLink *link);
450
451 /** default handler for filter_samples() for audio inputs */
452 void avfilter_default_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref);
453
454 /** default handler for config_props() for audio/video outputs */
455 int avfilter_default_config_output_link(AVFilterLink *link);
456
457 /** default handler for config_props() for audio/video inputs */
458 int avfilter_default_config_input_link (AVFilterLink *link);
459
460 /** default handler for get_video_buffer() for video inputs */
461 AVFilterBufferRef *avfilter_default_get_video_buffer(AVFilterLink *link,
462 int perms, int w, int h);
463
464 /** default handler for get_audio_buffer() for audio inputs */
465 AVFilterBufferRef *avfilter_default_get_audio_buffer(AVFilterLink *link, int perms,
466 enum AVSampleFormat sample_fmt, int size,
467 int64_t channel_layout, int planar);
468
469 /**
470 * A helper for query_formats() which sets all links to the same list of
471 * formats. If there are no links hooked to this filter, the list of formats is
472 * freed.
473 */
474 void avfilter_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats);
475
476 /** Default handler for query_formats() */
477 int avfilter_default_query_formats(AVFilterContext *ctx);
478
479 /** start_frame() handler for filters which simply pass video along */
480 void avfilter_null_start_frame(AVFilterLink *link, AVFilterBufferRef *picref);
481
482 /** draw_slice() handler for filters which simply pass video along */
483 void avfilter_null_draw_slice(AVFilterLink *link, int y, int h, int slice_dir);
484
485 /** end_frame() handler for filters which simply pass video along */
486 void avfilter_null_end_frame(AVFilterLink *link);
487
488 /** filter_samples() handler for filters which simply pass audio along */
489 void avfilter_null_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref);
490
491 /** get_video_buffer() handler for filters which simply pass video along */
492 AVFilterBufferRef *avfilter_null_get_video_buffer(AVFilterLink *link,
493 int perms, int w, int h);
494
495 /** get_audio_buffer() handler for filters which simply pass audio along */
496 AVFilterBufferRef *avfilter_null_get_audio_buffer(AVFilterLink *link, int perms,
497 enum AVSampleFormat sample_fmt, int size,
498 int64_t channel_layout, int planar);
499
500 /**
501 * Filter definition. This defines the pads a filter contains, and all the
502 * callback functions used to interact with the filter.
503 */
504 typedef struct AVFilter {
505 const char *name; ///< filter name
506
507 int priv_size; ///< size of private data to allocate for the filter
508
509 /**
510 * Filter initialization function. Args contains the user-supplied
511 * parameters. FIXME: maybe an AVOption-based system would be better?
512 * opaque is data provided by the code requesting creation of the filter,
513 * and is used to pass data to the filter.
514 */
515 int (*init)(AVFilterContext *ctx, const char *args, void *opaque);
516
517 /**
518 * Filter uninitialization function. Should deallocate any memory held
519 * by the filter, release any buffer references, etc. This does not need
520 * to deallocate the AVFilterContext->priv memory itself.
521 */
522 void (*uninit)(AVFilterContext *ctx);
523
524 /**
525 * Queries formats supported by the filter and its pads, and sets the
526 * in_formats for links connected to its output pads, and out_formats
527 * for links connected to its input pads.
528 *
529 * @return zero on success, a negative value corresponding to an
530 * AVERROR code otherwise
531 */
532 int (*query_formats)(AVFilterContext *);
533
534 const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if none
535 const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none
536
537 /**
538 * A description for the filter. You should use the
539 * NULL_IF_CONFIG_SMALL() macro to define it.
540 */
541 const char *description;
542 } AVFilter;
543
544 /** An instance of a filter */
545 struct AVFilterContext {
546 const AVClass *av_class; ///< needed for av_log()
547
548 AVFilter *filter; ///< the AVFilter of which this is an instance
549
550 char *name; ///< name of this filter instance
551
552 unsigned input_count; ///< number of input pads
553 AVFilterPad *input_pads; ///< array of input pads
554 AVFilterLink **inputs; ///< array of pointers to input links
555
556 unsigned output_count; ///< number of output pads
557 AVFilterPad *output_pads; ///< array of output pads
558 AVFilterLink **outputs; ///< array of pointers to output links
559
560 void *priv; ///< private data for use by the filter
561 };
562
563 /**
564 * A link between two filters. This contains pointers to the source and
565 * destination filters between which this link exists, and the indexes of
566 * the pads involved. In addition, this link also contains the parameters
567 * which have been negotiated and agreed upon between the filter, such as
568 * image dimensions, format, etc.
569 */
570 struct AVFilterLink {
571 AVFilterContext *src; ///< source filter
572 AVFilterPad *srcpad; ///< output pad on the source filter
573
574 AVFilterContext *dst; ///< dest filter
575 AVFilterPad *dstpad; ///< input pad on the dest filter
576
577 /** stage of the initialization of the link properties (dimensions, etc) */
578 enum {
579 AVLINK_UNINIT = 0, ///< not started
580 AVLINK_STARTINIT, ///< started, but incomplete
581 AVLINK_INIT ///< complete
582 } init_state;
583
584 enum AVMediaType type; ///< filter media type
585
586 /* These parameters apply only to video */
587 int w; ///< agreed upon image width
588 int h; ///< agreed upon image height
589 AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio
590 /* These two parameters apply only to audio */
591 int64_t channel_layout; ///< channel layout of current buffer (see libavutil/audioconvert.h)
592 int64_t sample_rate; ///< samples per second
593
594 int format; ///< agreed upon media format
595
596 /**
597 * Lists of formats supported by the input and output filters respectively.
598 * These lists are used for negotiating the format to actually be used,
599 * which will be loaded into the format member, above, when chosen.
600 */
601 AVFilterFormats *in_formats;
602 AVFilterFormats *out_formats;
603
604 /**
605 * The buffer reference currently being sent across the link by the source
606 * filter. This is used internally by the filter system to allow
607 * automatic copying of buffers which do not have sufficient permissions
608 * for the destination. This should not be accessed directly by the
609 * filters.
610 */
611 AVFilterBufferRef *src_buf;
612
613 AVFilterBufferRef *cur_buf;
614 AVFilterBufferRef *out_buf;
615
616 /**
617 * Define the time base used by the PTS of the frames/samples
618 * which will pass through this link.
619 * During the configuration stage, each filter is supposed to
620 * change only the output timebase, while the timebase of the
621 * input link is assumed to be an unchangeable property.
622 */
623 AVRational time_base;
624 };
625
626 /**
627 * Link two filters together.
628 *
629 * @param src the source filter
630 * @param srcpad index of the output pad on the source filter
631 * @param dst the destination filter
632 * @param dstpad index of the input pad on the destination filter
633 * @return zero on success
634 */
635 int avfilter_link(AVFilterContext *src, unsigned srcpad,
636 AVFilterContext *dst, unsigned dstpad);
637
638 /**
639 * Negotiate the media format, dimensions, etc of all inputs to a filter.
640 *
641 * @param filter the filter to negotiate the properties for its inputs
642 * @return zero on successful negotiation
643 */
644 int avfilter_config_links(AVFilterContext *filter);
645
646 /**
647 * Request a picture buffer with a specific set of permissions.
648 *
649 * @param link the output link to the filter from which the buffer will
650 * be requested
651 * @param perms the required access permissions
652 * @param w the minimum width of the buffer to allocate
653 * @param h the minimum height of the buffer to allocate
654 * @return A reference to the buffer. This must be unreferenced with
655 * avfilter_unref_buffer when you are finished with it.
656 */
657 AVFilterBufferRef *avfilter_get_video_buffer(AVFilterLink *link, int perms,
658 int w, int h);
659
660 /**
661 * Create a buffer reference wrapped around an already allocated image
662 * buffer.
663 *
664 * @param data pointers to the planes of the image to reference
665 * @param linesize linesizes for the planes of the image to reference
666 * @param perms the required access permissions
667 * @param w the width of the image specified by the data and linesize arrays
668 * @param h the height of the image specified by the data and linesize arrays
669 * @param format the pixel format of the image specified by the data and linesize arrays
670 */
671 AVFilterBufferRef *
672 avfilter_get_video_buffer_ref_from_arrays(uint8_t *data[4], int linesize[4], int perms,
673 int w, int h, enum PixelFormat format);
674
675 /**
676 * Request an audio samples buffer with a specific set of permissions.
677 *
678 * @param link the output link to the filter from which the buffer will
679 * be requested
680 * @param perms the required access permissions
681 * @param sample_fmt the format of each sample in the buffer to allocate
682 * @param size the buffer size in bytes
683 * @param channel_layout the number and type of channels per sample in the buffer to allocate
684 * @param planar audio data layout - planar or packed
685 * @return A reference to the samples. This must be unreferenced with
686 * avfilter_unref_buffer when you are finished with it.
687 */
688 AVFilterBufferRef *avfilter_get_audio_buffer(AVFilterLink *link, int perms,
689 enum AVSampleFormat sample_fmt, int size,
690 int64_t channel_layout, int planar);
691
692 /**
693 * Request an input frame from the filter at the other end of the link.
694 *
695 * @param link the input link
696 * @return zero on success
697 */
698 int avfilter_request_frame(AVFilterLink *link);
699
700 /**
701 * Poll a frame from the filter chain.
702 *
703 * @param link the input link
704 * @return the number of immediately available frames, a negative
705 * number in case of error
706 */
707 int avfilter_poll_frame(AVFilterLink *link);
708
709 /**
710 * Notifie the next filter of the start of a frame.
711 *
712 * @param link the output link the frame will be sent over
713 * @param picref A reference to the frame about to be sent. The data for this
714 * frame need only be valid once draw_slice() is called for that
715 * portion. The receiving filter will free this reference when
716 * it no longer needs it.
717 */
718 void avfilter_start_frame(AVFilterLink *link, AVFilterBufferRef *picref);
719
720 /**
721 * Notifie the next filter that the current frame has finished.
722 *
723 * @param link the output link the frame was sent over
724 */
725 void avfilter_end_frame(AVFilterLink *link);
726
727 /**
728 * Send a slice to the next filter.
729 *
730 * Slices have to be provided in sequential order, either in
731 * top-bottom or bottom-top order. If slices are provided in
732 * non-sequential order the behavior of the function is undefined.
733 *
734 * @param link the output link over which the frame is being sent
735 * @param y offset in pixels from the top of the image for this slice
736 * @param h height of this slice in pixels
737 * @param slice_dir the assumed direction for sending slices,
738 * from the top slice to the bottom slice if the value is 1,
739 * from the bottom slice to the top slice if the value is -1,
740 * for other values the behavior of the function is undefined.
741 */
742 void avfilter_draw_slice(AVFilterLink *link, int y, int h, int slice_dir);
743
744 /**
745 * Send a buffer of audio samples to the next filter.
746 *
747 * @param link the output link over which the audio samples are being sent
748 * @param samplesref a reference to the buffer of audio samples being sent. The
749 * receiving filter will free this reference when it no longer
750 * needs it or pass it on to the next filter.
751 */
752 void avfilter_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref);
753
754 /** Initialize the filter system. Register all builtin filters. */
755 void avfilter_register_all(void);
756
757 /** Uninitialize the filter system. Unregister all filters. */
758 void avfilter_uninit(void);
759
760 /**
761 * Register a filter. This is only needed if you plan to use
762 * avfilter_get_by_name later to lookup the AVFilter structure by name. A
763 * filter can still by instantiated with avfilter_open even if it is not
764 * registered.
765 *
766 * @param filter the filter to register
767 * @return 0 if the registration was succesfull, a negative value
768 * otherwise
769 */
770 int avfilter_register(AVFilter *filter);
771
772 /**
773 * Get a filter definition matching the given name.
774 *
775 * @param name the filter name to find
776 * @return the filter definition, if any matching one is registered.
777 * NULL if none found.
778 */
779 AVFilter *avfilter_get_by_name(const char *name);
780
781 /**
782 * If filter is NULL, returns a pointer to the first registered filter pointer,
783 * if filter is non-NULL, returns the next pointer after filter.
784 * If the returned pointer points to NULL, the last registered filter
785 * was already reached.
786 */
787 AVFilter **av_filter_next(AVFilter **filter);
788
789 /**
790 * Create a filter instance.
791 *
792 * @param filter_ctx put here a pointer to the created filter context
793 * on success, NULL on failure
794 * @param filter the filter to create an instance of
795 * @param inst_name Name to give to the new instance. Can be NULL for none.
796 * @return >= 0 in case of success, a negative error code otherwise
797 */
798 int avfilter_open(AVFilterContext **filter_ctx, AVFilter *filter, const char *inst_name);
799
800 /**
801 * Initialize a filter.
802 *
803 * @param filter the filter to initialize
804 * @param args A string of parameters to use when initializing the filter.
805 * The format and meaning of this string varies by filter.
806 * @param opaque Any extra non-string data needed by the filter. The meaning
807 * of this parameter varies by filter.
808 * @return zero on success
809 */
810 int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
811
812 /**
813 * Free a filter context.
814 *
815 * @param filter the filter to free
816 */
817 void avfilter_free(AVFilterContext *filter);
818
819 /**
820 * Insert a filter in the middle of an existing link.
821 *
822 * @param link the link into which the filter should be inserted
823 * @param filt the filter to be inserted
824 * @param filt_srcpad_idx the input pad on the filter to connect
825 * @param filt_dstpad_idx the output pad on the filter to connect
826 * @return zero on success
827 */
828 int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt,
829 unsigned filt_srcpad_idx, unsigned filt_dstpad_idx);
830
831 /**
832 * Insert a new pad.
833 *
834 * @param idx Insertion point. Pad is inserted at the end if this point
835 * is beyond the end of the list of pads.
836 * @param count Pointer to the number of pads in the list
837 * @param padidx_off Offset within an AVFilterLink structure to the element
838 * to increment when inserting a new pad causes link
839 * numbering to change
840 * @param pads Pointer to the pointer to the beginning of the list of pads
841 * @param links Pointer to the pointer to the beginning of the list of links
842 * @param newpad The new pad to add. A copy is made when adding.
843 */
844 void avfilter_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
845 AVFilterPad **pads, AVFilterLink ***links,
846 AVFilterPad *newpad);
847
848 /** Insert a new input pad for the filter. */
849 static inline void avfilter_insert_inpad(AVFilterContext *f, unsigned index,
850 AVFilterPad *p)
851 {
852 avfilter_insert_pad(index, &f->input_count, offsetof(AVFilterLink, dstpad),
853 &f->input_pads, &f->inputs, p);
854 }
855
856 /** Insert a new output pad for the filter. */
857 static inline void avfilter_insert_outpad(AVFilterContext *f, unsigned index,
858 AVFilterPad *p)
859 {
860 avfilter_insert_pad(index, &f->output_count, offsetof(AVFilterLink, srcpad),
861 &f->output_pads, &f->outputs, p);
862 }
863
864 #endif /* AVFILTER_AVFILTER_H */