path: root/libavfilter/buffersink.h (plain)
blob: f51fa7c1dd14ec1a9235f14cf27dccfd7ba2f1e0

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
36	/**
37	* Get a frame with filtered data from sink and put it in frame.
38	*
39	* @param ctx pointer to a buffersink or abuffersink filter context.
40	* @param frame pointer to an allocated frame that will be filled with data.
41	* The data must be freed using av_frame_unref() / av_frame_free()
42	* @param flags a combination of AV_BUFFERSINK_FLAG_* flags
43	*
44	* @return >= 0 in for success, a negative AVERROR code for failure.
45	*/
46	int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags);
47
48	/**
49	* Tell av_buffersink_get_buffer_ref() to read video/samples buffer
50	* reference, but not remove it from the buffer. This is useful if you
51	* need only to read a video/samples buffer, without to fetch it.
52	*/
53	#define AV_BUFFERSINK_FLAG_PEEK 1
54
55	/**
56	* Tell av_buffersink_get_buffer_ref() not to request a frame from its input.
57	* If a frame is already buffered, it is read (and removed from the buffer),
58	* but if no frame is present, return AVERROR(EAGAIN).
59	*/
60	#define AV_BUFFERSINK_FLAG_NO_REQUEST 2
61
62	/**
63	* Struct to use for initializing a buffersink context.
64	*/
65	typedef struct {
66	const enum AVPixelFormat *pixel_fmts; ///< list of allowed pixel formats, terminated by AV_PIX_FMT_NONE
67	} AVBufferSinkParams;
68
69	/**
70	* Create an AVBufferSinkParams structure.
71	*
72	* Must be freed with av_free().
73	*/
74	AVBufferSinkParams *av_buffersink_params_alloc(void);
75
76	/**
77	* Struct to use for initializing an abuffersink context.
78	*/
79	typedef struct {
80	const enum AVSampleFormat *sample_fmts; ///< list of allowed sample formats, terminated by AV_SAMPLE_FMT_NONE
81	const int64_t *channel_layouts; ///< list of allowed channel layouts, terminated by -1
82	const int *channel_counts; ///< list of allowed channel counts, terminated by -1
83	int all_channel_counts; ///< if not 0, accept any channel count or layout
84	int *sample_rates; ///< list of allowed sample rates, terminated by -1
85	} AVABufferSinkParams;
86
87	/**
88	* Create an AVABufferSinkParams structure.
89	*
90	* Must be freed with av_free().
91	*/
92	AVABufferSinkParams *av_abuffersink_params_alloc(void);
93
94	/**
95	* Set the frame size for an audio buffer sink.
96	*
97	* All calls to av_buffersink_get_buffer_ref will return a buffer with
98	* exactly the specified number of samples, or AVERROR(EAGAIN) if there is
99	* not enough. The last buffer at EOF will be padded with 0.
100	*/
101	void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size);
102
103	/**
104	* @defgroup lavfi_buffersink_accessors Buffer sink accessors
105	* Get the properties of the stream
106	* @{
107	*/
108
109	enum AVMediaType av_buffersink_get_type (const AVFilterContext *ctx);
110	AVRational av_buffersink_get_time_base (const AVFilterContext *ctx);
111	int av_buffersink_get_format (const AVFilterContext *ctx);
112
113	AVRational av_buffersink_get_frame_rate (const AVFilterContext *ctx);
114	int av_buffersink_get_w (const AVFilterContext *ctx);
115	int av_buffersink_get_h (const AVFilterContext *ctx);
116	AVRational av_buffersink_get_sample_aspect_ratio (const AVFilterContext *ctx);
117
118	int av_buffersink_get_channels (const AVFilterContext *ctx);
119	uint64_t av_buffersink_get_channel_layout (const AVFilterContext *ctx);
120	int av_buffersink_get_sample_rate (const AVFilterContext *ctx);
121
122	AVBufferRef * av_buffersink_get_hw_frames_ctx (const AVFilterContext *ctx);
123
124	/** @} */
125
126	/**
127	* Get a frame with filtered data from sink and put it in frame.
128	*
129	* @param ctx pointer to a context of a buffersink or abuffersink AVFilter.
130	* @param frame pointer to an allocated frame that will be filled with data.
131	* The data must be freed using av_frame_unref() / av_frame_free()
132	*
133	* @return
134	* - >= 0 if a frame was successfully returned.
135	* - AVERROR(EAGAIN) if no frames are available at this point; more
136	* input frames must be added to the filtergraph to get more output.
137	* - AVERROR_EOF if there will be no more output frames on this sink.
138	* - A different negative AVERROR code in other failure cases.
139	*/
140	int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame);
141
142	/**
143	* Same as av_buffersink_get_frame(), but with the ability to specify the number
144	* of samples read. This function is less efficient than
145	* av_buffersink_get_frame(), because it copies the data around.
146	*
147	* @param ctx pointer to a context of the abuffersink AVFilter.
148	* @param frame pointer to an allocated frame that will be filled with data.
149	* The data must be freed using av_frame_unref() / av_frame_free()
150	* frame will contain exactly nb_samples audio samples, except at
151	* the end of stream, when it can contain less than nb_samples.
152	*
153	* @return The return codes have the same meaning as for
154	* av_buffersink_get_samples().
155	*
156	* @warning do not mix this function with av_buffersink_get_frame(). Use only one or
157	* the other with a single sink, not both.
158	*/
159	int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples);
160
161	/**
162	* @}
163	*/
164
165	#endif /* AVFILTER_BUFFERSINK_H */
166