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 #if FF_API_OLD_CHANNEL_LAYOUT
114  /**
115  * Audio only, the audio channel layout
116  * @deprecated use ch_layout
117  */
119  uint64_t channel_layout;
120 #endif
121 
122  /**
123  * Audio only, the audio channel layout
124  */
127 
128 /**
129  * Allocate a new AVBufferSrcParameters instance. It should be freed by the
130  * caller with av_free().
131  */
133 
134 /**
135  * Initialize the buffersrc or abuffersrc filter with the provided parameters.
136  * This function may be called multiple times, the later calls override the
137  * previous ones. Some of the parameters may also be set through AVOptions, then
138  * whatever method is used last takes precedence.
139  *
140  * @param ctx an instance of the buffersrc or abuffersrc filter
141  * @param param the stream parameters. The frames later passed to this filter
142  * must conform to those parameters. All the allocated fields in
143  * param remain owned by the caller, libavfilter will make internal
144  * copies or references when necessary.
145  * @return 0 on success, a negative AVERROR code on failure.
146  */
148 
149 /**
150  * Add a frame to the buffer source.
151  *
152  * @param ctx an instance of the buffersrc filter
153  * @param frame frame to be added. If the frame is reference counted, this
154  * function will make a new reference to it. Otherwise the frame data will be
155  * copied.
156  *
157  * @return 0 on success, a negative AVERROR on error
158  *
159  * This function is equivalent to av_buffersrc_add_frame_flags() with the
160  * AV_BUFFERSRC_FLAG_KEEP_REF flag.
161  */
164 
165 /**
166  * Add a frame to the buffer source.
167  *
168  * @param ctx an instance of the buffersrc filter
169  * @param frame frame to be added. If the frame is reference counted, this
170  * function will take ownership of the reference(s) and reset the frame.
171  * Otherwise the frame data will be copied. If this function returns an error,
172  * the input frame is not touched.
173  *
174  * @return 0 on success, a negative AVERROR on error.
175  *
176  * @note the difference between this function and av_buffersrc_write_frame() is
177  * that av_buffersrc_write_frame() creates a new reference to the input frame,
178  * while this function takes ownership of the reference passed to it.
179  *
180  * This function is equivalent to av_buffersrc_add_frame_flags() without the
181  * AV_BUFFERSRC_FLAG_KEEP_REF flag.
182  */
185 
186 /**
187  * Add a frame to the buffer source.
188  *
189  * By default, if the frame is reference-counted, this function will take
190  * ownership of the reference(s) and reset the frame. This can be controlled
191  * using the flags.
192  *
193  * If this function returns an error, the input frame is not touched.
194  *
195  * @param buffer_src pointer to a buffer source context
196  * @param frame a frame, or NULL to mark EOF
197  * @param flags a combination of AV_BUFFERSRC_FLAG_*
198  * @return >= 0 in case of success, a negative AVERROR code
199  * in case of failure
200  */
203  AVFrame *frame, int flags);
204 
205 /**
206  * Close the buffer source after EOF.
207  *
208  * This is similar to passing NULL to av_buffersrc_add_frame_flags()
209  * except it takes the timestamp of the EOF, i.e. the timestamp of the end
210  * of the last frame.
211  */
212 int av_buffersrc_close(AVFilterContext *ctx, int64_t pts, unsigned flags);
213 
214 /**
215  * @}
216  */
217 
218 #endif /* AVFILTER_BUFFERSRC_H */
AV_BUFFERSRC_FLAG_KEEP_REF
@ AV_BUFFERSRC_FLAG_KEEP_REF
Keep a reference to the frame.
Definition: buffersrc.h:53
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:330
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:156
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
AVBufferSrcParameters::ch_layout
AVChannelLayout ch_layout
Audio only, the audio channel layout.
Definition: buffersrc.h:125
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AV_BUFFERSRC_FLAG_PUSH
@ AV_BUFFERSRC_FLAG_PUSH
Immediately push the frame to the output.
Definition: buffersrc.h:46
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:263
AVChannelLayout
An AVChannelLayout holds information about the channel layout of audio data.
Definition: channel_layout.h:301
av_buffersrc_parameters_alloc
AVBufferSrcParameters * av_buffersrc_parameters_alloc(void)
Allocate a new AVBufferSrcParameters instance.
Definition: buffersrc.c:83
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
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
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_parameters_set
int av_buffersrc_parameters_set(AVFilterContext *ctx, AVBufferSrcParameters *param)
Initialize the buffersrc or abuffersrc filter with the provided parameters.
Definition: buffersrc.c:94
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:175
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
AV_BUFFERSRC_FLAG_NO_CHECK_FORMAT
@ AV_BUFFERSRC_FLAG_NO_CHECK_FORMAT
Do not check for format changes.
Definition: buffersrc.h:41
AVFilterContext
An instance of a filter.
Definition: avfilter.h:392
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:290
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:150
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561