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 */ 81 int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags); 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 */ 110 attribute_deprecated 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 */ 129 attribute_deprecated 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 */ 140 void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size); 141 142 /** 143 * @defgroup lavfi_buffersink_accessors Buffer sink accessors 144 * Get the properties of the stream 145 * @{ 146 */ 147 148 enum AVMediaType av_buffersink_get_type (const AVFilterContext *ctx); 149 AVRational av_buffersink_get_time_base (const AVFilterContext *ctx); 150 int av_buffersink_get_format (const AVFilterContext *ctx); 151 152 AVRational av_buffersink_get_frame_rate (const AVFilterContext *ctx); 153 int av_buffersink_get_w (const AVFilterContext *ctx); 154 int av_buffersink_get_h (const AVFilterContext *ctx); 155 AVRational av_buffersink_get_sample_aspect_ratio (const AVFilterContext *ctx); 156 157 int av_buffersink_get_channels (const AVFilterContext *ctx); 158 #if FF_API_OLD_CHANNEL_LAYOUT 159 attribute_deprecated 160 uint64_t av_buffersink_get_channel_layout (const AVFilterContext *ctx); 161 #endif 162 int av_buffersink_get_ch_layout (const AVFilterContext *ctx, 163 AVChannelLayout *ch_layout); 164 int av_buffersink_get_sample_rate (const AVFilterContext *ctx); 165 166 AVBufferRef * av_buffersink_get_hw_frames_ctx (const AVFilterContext *ctx); 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 */ 184 int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame); 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 */ 203 int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples); 204 205 /** 206 * @} 207 */ 208 209 #endif /* AVFILTER_BUFFERSINK_H */ 210