FFmpeg
buffersrc.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_BUFFERSRC_H
20 #define AVFILTER_BUFFERSRC_H
21 
22 /**
23  * @file
24  * @ingroup lavfi_buffersrc
25  * Memory buffer source API.
26  */
27 
28 #include "avfilter.h"
29 
30 /**
31  * @defgroup lavfi_buffersrc Buffer source API
32  * @ingroup lavfi
33  * @{
34  */
35 
36 enum {
37 
38  /**
39  * Do not check for format changes.
40  */
42 
43  /**
44  * Immediately push the frame to the output.
45  */
47 
48  /**
49  * Keep a reference to the frame.
50  * If the frame if reference-counted, create a new reference; otherwise
51  * copy the frame data.
52  */
54 
55 };
56 
57 /**
58  * Get the number of failed requests.
59  *
60  * A failed request is when the request_frame method is called while no
61  * frame is present in the buffer.
62  * The number is reset when a frame is added.
63  */
65 
66 /**
67  * This structure contains the parameters describing the frames that will be
68  * passed to this filter.
69  *
70  * It should be allocated with av_buffersrc_parameters_alloc() and freed with
71  * av_free(). All the allocated fields in it remain owned by the caller.
72  */
73 typedef struct AVBufferSrcParameters {
74  /**
75  * video: the pixel format, value corresponds to enum AVPixelFormat
76  * audio: the sample format, value corresponds to enum AVSampleFormat
77  */
78  int format;
79  /**
80  * The timebase to be used for the timestamps on the input frames.
81  */
83 
84  /**
85  * Video only, the display dimensions of the input frames.
86  */
87  int width, height;
88 
89  /**
90  * Video only, the sample (pixel) aspect ratio.
91  */
93 
94  /**
95  * Video only, the frame rate of the input video. This field must only be
96  * set to a non-zero value if input stream has a known constant framerate
97  * and should be left at its initial value if the framerate is variable or
98  * unknown.
99  */
101 
102  /**
103  * Video with a hwaccel pixel format only. This should be a reference to an
104  * AVHWFramesContext instance describing the input frames.
105  */
107 
108  /**
109  * Audio only, the audio sampling rate in samples per second.
110  */
112 
113  /**
114  * Audio only, the audio channel layout
115  */
116  uint64_t channel_layout;
118 
119 /**
120  * Allocate a new AVBufferSrcParameters instance. It should be freed by the
121  * caller with av_free().
122  */
124 
125 /**
126  * Initialize the buffersrc or abuffersrc filter with the provided parameters.
127  * This function may be called multiple times, the later calls override the
128  * previous ones. Some of the parameters may also be set through AVOptions, then
129  * whatever method is used last takes precedence.
130  *
131  * @param ctx an instance of the buffersrc or abuffersrc filter
132  * @param param the stream parameters. The frames later passed to this filter
133  * must conform to those parameters. All the allocated fields in
134  * param remain owned by the caller, libavfilter will make internal
135  * copies or references when necessary.
136  * @return 0 on success, a negative AVERROR code on failure.
137  */
139 
140 /**
141  * Add a frame to the buffer source.
142  *
143  * @param ctx an instance of the buffersrc filter
144  * @param frame frame to be added. If the frame is reference counted, this
145  * function will make a new reference to it. Otherwise the frame data will be
146  * copied.
147  *
148  * @return 0 on success, a negative AVERROR on error
149  *
150  * This function is equivalent to av_buffersrc_add_frame_flags() with the
151  * AV_BUFFERSRC_FLAG_KEEP_REF flag.
152  */
155 
156 /**
157  * Add a frame to the buffer source.
158  *
159  * @param ctx an instance of the buffersrc filter
160  * @param frame frame to be added. If the frame is reference counted, this
161  * function will take ownership of the reference(s) and reset the frame.
162  * Otherwise the frame data will be copied. If this function returns an error,
163  * the input frame is not touched.
164  *
165  * @return 0 on success, a negative AVERROR on error.
166  *
167  * @note the difference between this function and av_buffersrc_write_frame() is
168  * that av_buffersrc_write_frame() creates a new reference to the input frame,
169  * while this function takes ownership of the reference passed to it.
170  *
171  * This function is equivalent to av_buffersrc_add_frame_flags() without the
172  * AV_BUFFERSRC_FLAG_KEEP_REF flag.
173  */
176 
177 /**
178  * Add a frame to the buffer source.
179  *
180  * By default, if the frame is reference-counted, this function will take
181  * ownership of the reference(s) and reset the frame. This can be controlled
182  * using the flags.
183  *
184  * If this function returns an error, the input frame is not touched.
185  *
186  * @param buffer_src pointer to a buffer source context
187  * @param frame a frame, or NULL to mark EOF
188  * @param flags a combination of AV_BUFFERSRC_FLAG_*
189  * @return >= 0 in case of success, a negative AVERROR code
190  * in case of failure
191  */
194  AVFrame *frame, int flags);
195 
196 /**
197  * Close the buffer source after EOF.
198  *
199  * This is similar to passing NULL to av_buffersrc_add_frame_flags()
200  * except it takes the timestamp of the EOF, i.e. the timestamp of the end
201  * of the last frame.
202  */
203 int av_buffersrc_close(AVFilterContext *ctx, int64_t pts, unsigned flags);
204 
205 /**
206  * @}
207  */
208 
209 #endif /* AVFILTER_BUFFERSRC_H */
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:317
av_buffersrc_add_frame
av_warn_unused_result int av_buffersrc_add_frame(AVFilterContext *ctx, AVFrame *frame)
Add a frame to the buffer source.
Definition: buffersrc.c:146
AVBufferSrcParameters::height
int height
Definition: buffersrc.h:87
AVBufferSrcParameters::sample_aspect_ratio
AVRational sample_aspect_ratio
Video only, the sample (pixel) aspect ratio.
Definition: buffersrc.h:92
pts
static int64_t pts
Definition: transcode_aac.c:653
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVBufferSrcParameters::channel_layout
uint64_t channel_layout
Audio only, the audio channel layout.
Definition: buffersrc.h:116
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AV_BUFFERSRC_FLAG_NO_CHECK_FORMAT
@ AV_BUFFERSRC_FLAG_NO_CHECK_FORMAT
Do not check for format changes.
Definition: buffersrc.h:41
AVBufferSrcParameters::frame_rate
AVRational frame_rate
Video only, the frame rate of the input video.
Definition: buffersrc.h:100
av_buffersrc_close
int av_buffersrc_close(AVFilterContext *ctx, int64_t pts, unsigned flags)
Close the buffer source after EOF.
Definition: buffersrc.c:232
av_buffersrc_parameters_alloc
AVBufferSrcParameters * av_buffersrc_parameters_alloc(void)
Allocate a new AVBufferSrcParameters instance.
Definition: buffersrc.c:86
AVBufferSrcParameters::hw_frames_ctx
AVBufferRef * hw_frames_ctx
Video with a hwaccel pixel format only.
Definition: buffersrc.h:106
AVBufferSrcParameters::sample_rate
int sample_rate
Audio only, the audio sampling rate in samples per second.
Definition: buffersrc.h:111
AVBufferSrcParameters::time_base
AVRational time_base
The timebase to be used for the timestamps on the input frames.
Definition: buffersrc.h:82
av_warn_unused_result
#define av_warn_unused_result
Definition: attributes.h:64
AV_BUFFERSRC_FLAG_PUSH
@ AV_BUFFERSRC_FLAG_PUSH
Immediately push the frame to the output.
Definition: buffersrc.h:46
av_buffersrc_parameters_set
int av_buffersrc_parameters_set(AVFilterContext *ctx, AVBufferSrcParameters *param)
Initialize the buffersrc or abuffersrc filter with the provided parameters.
Definition: buffersrc.c:97
AVBufferSrcParameters::width
int width
Video only, the display dimensions of the input frames.
Definition: buffersrc.h:87
av_buffersrc_add_frame_flags
av_warn_unused_result int av_buffersrc_add_frame_flags(AVFilterContext *buffer_src, AVFrame *frame, int flags)
Add a frame to the buffer source.
Definition: buffersrc.c:165
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
AVBufferSrcParameters
This structure contains the parameters describing the frames that will be passed to this filter.
Definition: buffersrc.h:73
AVBufferSrcParameters::format
int format
video: the pixel format, value corresponds to enum AVPixelFormat audio: the sample format,...
Definition: buffersrc.h:78
avfilter.h
AVFilterContext
An instance of a filter.
Definition: avfilter.h:402
av_buffersrc_get_nb_failed_requests
unsigned av_buffersrc_get_nb_failed_requests(AVFilterContext *buffer_src)
Get the number of failed requests.
Definition: buffersrc.c:264
AVBufferRef
A reference to a data buffer.
Definition: buffer.h:82
av_buffersrc_write_frame
av_warn_unused_result int av_buffersrc_write_frame(AVFilterContext *ctx, const AVFrame *frame)
Add a frame to the buffer source.
Definition: buffersrc.c:140
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
AV_BUFFERSRC_FLAG_KEEP_REF
@ AV_BUFFERSRC_FLAG_KEEP_REF
Keep a reference to the frame.
Definition: buffersrc.h:53