libavfilter/buffersink.h

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