buffersink.h (6923B)
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 * - color_spaces (int list), 59 * - color_ranges (int list), 60 * - sample_fmts (int list), 61 * - sample_rates (int list), 62 * - ch_layouts (string), 63 * - channel_counts (int list), 64 * - all_channel_counts (bool). 65 * Most of these options are of type binary, and should be set using 66 * av_opt_set_int_list() or av_opt_set_bin(). If they are not set, all 67 * corresponding formats are accepted. 68 * 69 * As a special case, if ch_layouts is not set, all valid channel layouts are 70 * accepted except for UNSPEC layouts, unless all_channel_counts is set. 71 */ 72 73 /** 74 * Get a frame with filtered data from sink and put it in frame. 75 * 76 * @param ctx pointer to a buffersink or abuffersink filter context. 77 * @param frame pointer to an allocated frame that will be filled with data. 78 * The data must be freed using av_frame_unref() / av_frame_free() 79 * @param flags a combination of AV_BUFFERSINK_FLAG_* flags 80 * 81 * @return >= 0 in for success, a negative AVERROR code for failure. 82 */ 83 int av_buffersink_get_frame_flags(AVFilterContext *ctx, AVFrame *frame, int flags); 84 85 /** 86 * Tell av_buffersink_get_buffer_ref() to read video/samples buffer 87 * reference, but not remove it from the buffer. This is useful if you 88 * need only to read a video/samples buffer, without to fetch it. 89 */ 90 #define AV_BUFFERSINK_FLAG_PEEK 1 91 92 /** 93 * Tell av_buffersink_get_buffer_ref() not to request a frame from its input. 94 * If a frame is already buffered, it is read (and removed from the buffer), 95 * but if no frame is present, return AVERROR(EAGAIN). 96 */ 97 #define AV_BUFFERSINK_FLAG_NO_REQUEST 2 98 99 /** 100 * Set the frame size for an audio buffer sink. 101 * 102 * All calls to av_buffersink_get_buffer_ref will return a buffer with 103 * exactly the specified number of samples, or AVERROR(EAGAIN) if there is 104 * not enough. The last buffer at EOF will be padded with 0. 105 */ 106 void av_buffersink_set_frame_size(AVFilterContext *ctx, unsigned frame_size); 107 108 /** 109 * @defgroup lavfi_buffersink_accessors Buffer sink accessors 110 * Get the properties of the stream 111 * @{ 112 */ 113 114 enum AVMediaType av_buffersink_get_type (const AVFilterContext *ctx); 115 AVRational av_buffersink_get_time_base (const AVFilterContext *ctx); 116 int av_buffersink_get_format (const AVFilterContext *ctx); 117 118 AVRational av_buffersink_get_frame_rate (const AVFilterContext *ctx); 119 int av_buffersink_get_w (const AVFilterContext *ctx); 120 int av_buffersink_get_h (const AVFilterContext *ctx); 121 AVRational av_buffersink_get_sample_aspect_ratio (const AVFilterContext *ctx); 122 enum AVColorSpace av_buffersink_get_colorspace (const AVFilterContext *ctx); 123 enum AVColorRange av_buffersink_get_color_range (const AVFilterContext *ctx); 124 125 int av_buffersink_get_channels (const AVFilterContext *ctx); 126 int av_buffersink_get_ch_layout (const AVFilterContext *ctx, 127 AVChannelLayout *ch_layout); 128 int av_buffersink_get_sample_rate (const AVFilterContext *ctx); 129 130 AVBufferRef * av_buffersink_get_hw_frames_ctx (const AVFilterContext *ctx); 131 132 /** @} */ 133 134 /** 135 * Get a frame with filtered data from sink and put it in frame. 136 * 137 * @param ctx pointer to a context of a buffersink or abuffersink AVFilter. 138 * @param frame pointer to an allocated frame that will be filled with data. 139 * The data must be freed using av_frame_unref() / av_frame_free() 140 * 141 * @return 142 * - >= 0 if a frame was successfully returned. 143 * - AVERROR(EAGAIN) if no frames are available at this point; more 144 * input frames must be added to the filtergraph to get more output. 145 * - AVERROR_EOF if there will be no more output frames on this sink. 146 * - A different negative AVERROR code in other failure cases. 147 */ 148 int av_buffersink_get_frame(AVFilterContext *ctx, AVFrame *frame); 149 150 /** 151 * Same as av_buffersink_get_frame(), but with the ability to specify the number 152 * of samples read. This function is less efficient than 153 * av_buffersink_get_frame(), because it copies the data around. 154 * 155 * @param ctx pointer to a context of the abuffersink AVFilter. 156 * @param frame pointer to an allocated frame that will be filled with data. 157 * The data must be freed using av_frame_unref() / av_frame_free() 158 * frame will contain exactly nb_samples audio samples, except at 159 * the end of stream, when it can contain less than nb_samples. 160 * 161 * @return The return codes have the same meaning as for 162 * av_buffersink_get_frame(). 163 * 164 * @warning do not mix this function with av_buffersink_get_frame(). Use only one or 165 * the other with a single sink, not both. 166 */ 167 int av_buffersink_get_samples(AVFilterContext *ctx, AVFrame *frame, int nb_samples); 168 169 /** 170 * @} 171 */ 172 173 #endif /* AVFILTER_BUFFERSINK_H */