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_channel_layout(), 50 * - av_buffersink_get_sample_rate(). 51 * 52 * The format can be constrained by setting options, using av_opt_set() and 53 * related functions with the AV_OPT_SEARCH_CHILDREN flag. 54 * - pix_fmts (int list), 55 * - sample_fmts (int list), 56 * - sample_rates (int list), 57 * - channel_layouts (int64_t), 58 * - channel_counts (int list), 59 * - all_channel_counts (bool). 60 * Most of these options are of type binary, and should be set using 61 * av_opt_set_int_list() or av_opt_set_bin(). If they are not set, all 62 * corresponding formats are accepted. 63 * 64 * As a special case, if neither channel_layouts nor channel_counts is set, 65 * all valid channel layouts are accepted, but channel counts without a 66 * layout are not, unless all_channel_counts is set. 67 * Also, channel_layouts must not contain a channel layout already accepted 68 * by a value in channel_counts; for example, if channel_counts contains 2, 69 * then channel_layouts must not contain stereo. 70 */ 71 72 /** 73 * Get a frame with filtered data from sink and put it in frame. 74 * 75 * @param ctx pointer to a buffersink or abuffersink filter context. 76 * @param frame pointer to an allocated frame that will be filled with data. 77 * The data must be freed using av_frame_unref() / av_frame_free() 78 * @param flags a combination of AV_BUFFERSINK_FLAG_* flags 79 * 80 * @return >= 0 in for success, a negative AVERROR code for failure. 81 */ 82 int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags); 83 84 /** 85 * Tell av_buffersink_get_buffer_ref() to read video/samples buffer 86 * reference, but not remove it from the buffer. This is useful if you 87 * need only to read a video/samples buffer, without to fetch it. 88 */ 89 #define AV_BUFFERSINK_FLAG_PEEK 1 90 91 /** 92 * Tell av_buffersink_get_buffer_ref() not to request a frame from its input. 93 * If a frame is already buffered, it is read (and removed from the buffer), 94 * but if no frame is present, return AVERROR(EAGAIN). 95 */ 96 #define AV_BUFFERSINK_FLAG_NO_REQUEST 2 97 98 #if FF_API_BUFFERSINK_ALLOC 99 /** 100 * Deprecated and unused struct to use for initializing a buffersink context. 101 */ 102 typedef struct AVBufferSinkParams { 103 const enum AVPixelFormat *pixel_fmts; ///< list of allowed pixel formats, terminated by AV_PIX_FMT_NONE 104 } AVBufferSinkParams; 105 106 /** 107 * Create an AVBufferSinkParams structure. 108 * 109 * Must be freed with av_free(). 110 */ 111 attribute_deprecated 112 AVBufferSinkParams *av_buffersink_params_alloc(void); 113 114 /** 115 * Deprecated and unused struct to use for initializing an abuffersink context. 116 */ 117 typedef struct AVABufferSinkParams { 118 const enum AVSampleFormat *sample_fmts; ///< list of allowed sample formats, terminated by AV_SAMPLE_FMT_NONE 119 const int64_t *channel_layouts; ///< list of allowed channel layouts, terminated by -1 120 const int *channel_counts; ///< list of allowed channel counts, terminated by -1 121 int all_channel_counts; ///< if not 0, accept any channel count or layout 122 int *sample_rates; ///< list of allowed sample rates, terminated by -1 123 } AVABufferSinkParams; 124 125 /** 126 * Create an AVABufferSinkParams structure. 127 * 128 * Must be freed with av_free(). 129 */ 130 attribute_deprecated 131 AVABufferSinkParams *av_abuffersink_params_alloc(void); 132 #endif 133 134 /** 135 * Set the frame size for an audio buffer sink. 136 * 137 * All calls to av_buffersink_get_buffer_ref will return a buffer with 138 * exactly the specified number of samples, or AVERROR(EAGAIN) if there is 139 * not enough. The last buffer at EOF will be padded with 0. 140 */ 141 void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size); 142 143 /** 144 * @defgroup lavfi_buffersink_accessors Buffer sink accessors 145 * Get the properties of the stream 146 * @{ 147 */ 148 149 enum AVMediaType av_buffersink_get_type (const AVFilterContext *ctx); 150 AVRational av_buffersink_get_time_base (const AVFilterContext *ctx); 151 int av_buffersink_get_format (const AVFilterContext *ctx); 152 153 AVRational av_buffersink_get_frame_rate (const AVFilterContext *ctx); 154 int av_buffersink_get_w (const AVFilterContext *ctx); 155 int av_buffersink_get_h (const AVFilterContext *ctx); 156 AVRational av_buffersink_get_sample_aspect_ratio (const AVFilterContext *ctx); 157 158 int av_buffersink_get_channels (const AVFilterContext *ctx); 159 uint64_t av_buffersink_get_channel_layout (const AVFilterContext *ctx); 160 int av_buffersink_get_sample_rate (const AVFilterContext *ctx); 161 162 AVBufferRef * av_buffersink_get_hw_frames_ctx (const AVFilterContext *ctx); 163 164 /** @} */ 165 166 /** 167 * Get a frame with filtered data from sink and put it in frame. 168 * 169 * @param ctx pointer to a context of a buffersink or abuffersink AVFilter. 170 * @param frame pointer to an allocated frame that will be filled with data. 171 * The data must be freed using av_frame_unref() / av_frame_free() 172 * 173 * @return 174 * - >= 0 if a frame was successfully returned. 175 * - AVERROR(EAGAIN) if no frames are available at this point; more 176 * input frames must be added to the filtergraph to get more output. 177 * - AVERROR_EOF if there will be no more output frames on this sink. 178 * - A different negative AVERROR code in other failure cases. 179 */ 180 int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame); 181 182 /** 183 * Same as av_buffersink_get_frame(), but with the ability to specify the number 184 * of samples read. This function is less efficient than 185 * av_buffersink_get_frame(), because it copies the data around. 186 * 187 * @param ctx pointer to a context of the abuffersink AVFilter. 188 * @param frame pointer to an allocated frame that will be filled with data. 189 * The data must be freed using av_frame_unref() / av_frame_free() 190 * frame will contain exactly nb_samples audio samples, except at 191 * the end of stream, when it can contain less than nb_samples. 192 * 193 * @return The return codes have the same meaning as for 194 * av_buffersink_get_frame(). 195 * 196 * @warning do not mix this function with av_buffersink_get_frame(). Use only one or 197 * the other with a single sink, not both. 198 */ 199 int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples); 200 201 /** 202 * @} 203 */ 204 205 #endif /* AVFILTER_BUFFERSINK_H */ 206