FFmpeg
buffersink.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_BUFFERSINK_H
20 #define AVFILTER_BUFFERSINK_H
21 
22 /**
23  * @file
24  * @ingroup lavfi_buffersink
25  * memory buffer sink API for audio and video
26  */
27 
28 #include "avfilter.h"
29 
30 /**
31  * @defgroup lavfi_buffersink Buffer sink API
32  * @ingroup lavfi
33  * @{
34  *
35  * The buffersink and abuffersink filters are there to connect filter graphs
36  * to applications. They have a single input, connected to the graph, and no
37  * output. Frames must be extracted using av_buffersink_get_frame() or
38  * av_buffersink_get_samples().
39  *
40  * The format negotiated by the graph during configuration can be obtained
41  * using the accessor functions:
42  * - av_buffersink_get_time_base(),
43  * - av_buffersink_get_format(),
44  * - av_buffersink_get_frame_rate(),
45  * - av_buffersink_get_w(),
46  * - av_buffersink_get_h(),
47  * - av_buffersink_get_sample_aspect_ratio(),
48  * - av_buffersink_get_channels(),
49  * - av_buffersink_get_ch_layout(),
50  * - av_buffersink_get_sample_rate().
51  *
52  * The layout returned by av_buffersink_get_ch_layout() must de uninitialized
53  * by the caller.
54  *
55  * The format can be constrained by setting options, using av_opt_set() and
56  * related functions with the AV_OPT_SEARCH_CHILDREN flag.
57  * - pix_fmts (int list),
58  * - sample_fmts (int list),
59  * - sample_rates (int list),
60  * - ch_layouts (string),
61  * - channel_counts (int list),
62  * - all_channel_counts (bool).
63  * Most of these options are of type binary, and should be set using
64  * av_opt_set_int_list() or av_opt_set_bin(). If they are not set, all
65  * corresponding formats are accepted.
66  *
67  * As a special case, if ch_layouts is not set, all valid channel layouts are
68  * accepted except for UNSPEC layouts, unless all_channel_counts is set.
69  */
70 
71 /**
72  * Get a frame with filtered data from sink and put it in frame.
73  *
74  * @param ctx pointer to a buffersink or abuffersink filter context.
75  * @param frame pointer to an allocated frame that will be filled with data.
76  * The data must be freed using av_frame_unref() / av_frame_free()
77  * @param flags a combination of AV_BUFFERSINK_FLAG_* flags
78  *
79  * @return >= 0 in for success, a negative AVERROR code for failure.
80  */
82 
83 /**
84  * Tell av_buffersink_get_buffer_ref() to read video/samples buffer
85  * reference, but not remove it from the buffer. This is useful if you
86  * need only to read a video/samples buffer, without to fetch it.
87  */
88 #define AV_BUFFERSINK_FLAG_PEEK 1
89 
90 /**
91  * Tell av_buffersink_get_buffer_ref() not to request a frame from its input.
92  * If a frame is already buffered, it is read (and removed from the buffer),
93  * but if no frame is present, return AVERROR(EAGAIN).
94  */
95 #define AV_BUFFERSINK_FLAG_NO_REQUEST 2
96 
97 #if FF_API_BUFFERSINK_ALLOC
98 /**
99  * Deprecated and unused struct to use for initializing a buffersink context.
100  */
101 typedef struct AVBufferSinkParams {
102  const enum AVPixelFormat *pixel_fmts; ///< list of allowed pixel formats, terminated by AV_PIX_FMT_NONE
103 } AVBufferSinkParams;
104 
105 /**
106  * Create an AVBufferSinkParams structure.
107  *
108  * Must be freed with av_free().
109  */
111 AVBufferSinkParams *av_buffersink_params_alloc(void);
112 
113 /**
114  * Deprecated and unused struct to use for initializing an abuffersink context.
115  */
116 typedef struct AVABufferSinkParams {
117  const enum AVSampleFormat *sample_fmts; ///< list of allowed sample formats, terminated by AV_SAMPLE_FMT_NONE
118  const int64_t *channel_layouts; ///< list of allowed channel layouts, terminated by -1
119  const int *channel_counts; ///< list of allowed channel counts, terminated by -1
120  int all_channel_counts; ///< if not 0, accept any channel count or layout
121  int *sample_rates; ///< list of allowed sample rates, terminated by -1
122 } AVABufferSinkParams;
123 
124 /**
125  * Create an AVABufferSinkParams structure.
126  *
127  * Must be freed with av_free().
128  */
130 AVABufferSinkParams *av_abuffersink_params_alloc(void);
131 #endif
132 
133 /**
134  * Set the frame size for an audio buffer sink.
135  *
136  * All calls to av_buffersink_get_buffer_ref will return a buffer with
137  * exactly the specified number of samples, or AVERROR(EAGAIN) if there is
138  * not enough. The last buffer at EOF will be padded with 0.
139  */
141 
142 /**
143  * @defgroup lavfi_buffersink_accessors Buffer sink accessors
144  * Get the properties of the stream
145  * @{
146  */
147 
151 
156 
158 #if FF_API_OLD_CHANNEL_LAYOUT
160 uint64_t av_buffersink_get_channel_layout (const AVFilterContext *ctx);
161 #endif
163  AVChannelLayout *ch_layout);
165 
167 
168 /** @} */
169 
170 /**
171  * Get a frame with filtered data from sink and put it in frame.
172  *
173  * @param ctx pointer to a context of a buffersink or abuffersink AVFilter.
174  * @param frame pointer to an allocated frame that will be filled with data.
175  * The data must be freed using av_frame_unref() / av_frame_free()
176  *
177  * @return
178  * - >= 0 if a frame was successfully returned.
179  * - AVERROR(EAGAIN) if no frames are available at this point; more
180  * input frames must be added to the filtergraph to get more output.
181  * - AVERROR_EOF if there will be no more output frames on this sink.
182  * - A different negative AVERROR code in other failure cases.
183  */
185 
186 /**
187  * Same as av_buffersink_get_frame(), but with the ability to specify the number
188  * of samples read. This function is less efficient than
189  * av_buffersink_get_frame(), because it copies the data around.
190  *
191  * @param ctx pointer to a context of the abuffersink AVFilter.
192  * @param frame pointer to an allocated frame that will be filled with data.
193  * The data must be freed using av_frame_unref() / av_frame_free()
194  * frame will contain exactly nb_samples audio samples, except at
195  * the end of stream, when it can contain less than nb_samples.
196  *
197  * @return The return codes have the same meaning as for
198  * av_buffersink_get_frame().
199  *
200  * @warning do not mix this function with av_buffersink_get_frame(). Use only one or
201  * the other with a single sink, not both.
202  */
204 
205 /**
206  * @}
207  */
208 
209 #endif /* AVFILTER_BUFFERSINK_H */
av_buffersink_get_ch_layout
int av_buffersink_get_ch_layout(const AVFilterContext *ctx, AVChannelLayout *ch_layout)
Definition: buffersink.c:241
av_buffersink_get_samples
int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples)
Same as av_buffersink_get_frame(), but with the ability to specify the number of samples read.
Definition: buffersink.c:151
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
av_buffersink_get_sample_aspect_ratio
AVRational av_buffersink_get_sample_aspect_ratio(const AVFilterContext *ctx)
sample_fmts
static enum AVSampleFormat sample_fmts[]
Definition: adpcmenc.c:947
av_buffersink_get_frame_flags
int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags)
Get a frame with filtered data from sink and put it in frame.
Definition: buffersink.c:146
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:325
pixel_fmts
static enum AVPixelFormat pixel_fmts[]
Definition: vf_amplify.c:53
av_buffersink_get_hw_frames_ctx
AVBufferRef * av_buffersink_get_hw_frames_ctx(const AVFilterContext *ctx)
av_buffersink_set_frame_size
void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size)
Set the frame size for an audio buffer sink.
Definition: buffersink.c:204
av_buffersink_get_frame_rate
AVRational av_buffersink_get_frame_rate(const AVFilterContext *ctx)
frame_size
int frame_size
Definition: mxfenc.c:2201
av_buffersink_get_frame
int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame)
Get a frame with filtered data from sink and put it in frame.
Definition: buffersink.c:94
av_buffersink_get_format
int av_buffersink_get_format(const AVFilterContext *ctx)
av_buffersink_get_time_base
AVRational av_buffersink_get_time_base(const AVFilterContext *ctx)
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVMediaType
AVMediaType
Definition: avutil.h:199
AVChannelLayout
An AVChannelLayout holds information about the channel layout of audio data.
Definition: channel_layout.h:290
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
av_buffersink_get_type
enum AVMediaType av_buffersink_get_type(const AVFilterContext *ctx)
sample_rates
sample_rates
Definition: ffmpeg_filter.c:155
av_buffersink_get_w
int av_buffersink_get_w(const AVFilterContext *ctx)
AVSampleFormat
AVSampleFormat
Audio sample formats.
Definition: samplefmt.h:55
av_buffersink_get_h
int av_buffersink_get_h(const AVFilterContext *ctx)
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
av_buffersink_get_sample_rate
int av_buffersink_get_sample_rate(const AVFilterContext *ctx)
avfilter.h
av_buffersink_get_channels
int av_buffersink_get_channels(const AVFilterContext *ctx)
Definition: buffersink.c:235
AVFilterContext
An instance of a filter.
Definition: avfilter.h:408
AVBufferRef
A reference to a data buffer.
Definition: buffer.h:82
channel_layouts
static const uint16_t channel_layouts[7]
Definition: dca_lbr.c:111
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561