FFMPEG-WIN32-LIB-4.2.2.zip

/* * copyright (c) 2001 Fabrice Bellard * * This file is part of FFmpeg. * * FFmpeg is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * FFmpeg is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef AVCODEC_AVCODEC_H #define AVCODEC_AVCODEC_H /** * @file * @ingroup libavc * Libavcodec external API header */ #include <errno.h> #include "libavutil/samplefmt.h" #include "libavutil/attributes.h" #include "libavutil/avutil.h" #include "libavutil/buffer.h" #include "libavutil/cpu.h" #include "libavutil/channel_layout.h" #include "libavutil/dict.h" #include "libavutil/frame.h" #include "libavutil/hwcontext.h" #include "libavutil/log.h" #include "libavutil/pixfmt.h" #include "libavutil/rational.h" #include "version.h" /** * @defgroup libavc libavcodec * Encoding/Decoding Library * * @{ * * @defgroup lavc_decoding Decoding * @{ * @} * * @defgroup lavc_encoding Encoding * @{ * @} * * @defgroup lavc_codec Codecs * @{ * @defgroup lavc_codec_native Native Codecs * @{ * @} * @defgroup lavc_codec_wrappers External library wrappers * @{ * @} * @defgroup lavc_codec_hwaccel Hardware Accelerators bridge * @{ * @} * @} * @defgroup lavc_internal Internal * @{ * @} * @} */ /** * @ingroup libavc * @defgroup lavc_encdec send/receive encoding and decoding API overview * @{ * * The avcodec_send_packet()/avcodec_receive_frame()/avcodec_send_frame()/ * avcodec_receive_packet() functions provide an encode/decode API, which * decouples input and output. * * The API is very similar for encoding/decoding and audio/video, and works as * follows: * - Set up and open the AVCodecContext as usual. * - Send valid input: * - For decoding, call avcodec_send_packet() to give the decoder raw * compressed data in an AVPacket. * - For encoding, call avcodec_send_frame() to give the encoder an AVFrame * containing uncompressed audio or video. * In both cases, it is recommended that AVPackets and AVFrames are * refcounted, or libavcodec might have to copy the input data. (libavformat * always returns refcounted AVPackets, and av_frame_get_buffer() allocates * refcounted AVFrames.) * - Receive output in a loop. Periodically call one of the avcodec_receive_*() * functions and process their output: * - For decoding, call avcodec_receive_frame(). On success, it will return * an AVFrame containing uncompressed audio or video data. * - For encoding, call avcodec_receive_packet(). On success, it will return * an AVPacket with a compressed frame. * Repeat this call until it returns AVERROR(EAGAIN) or an error. The * AVERROR(EAGAIN) return value means that new input data is required to * return new output. In this case, continue with sending input. For each * input frame/packet, the codec will typically return 1 output frame/packet, * but it can also be 0 or more than 1. * * At the beginning of decoding or encoding, the codec might accept multiple * input frames/packets without returning a frame, until its internal buffers * are filled. This situation is handled transparently if you follow the steps * outlined above. * * In theory, sending input can result in EAGAIN - this should happen only if * not all output was received. You can use this to structure alternative decode * or encode loops other than the one suggested above. For example, you could * try sending new input on each iteration, and try to receive output if that * returns EAGAIN. * * End of stream situations. These require "flushing" (aka draining) the codec, * as the codec might buffer multiple frames or packets internally for * performance or out of necessity (consider B-frames). * This is handled as follows: * - Instead of valid input, send NULL to the avcodec_send_packet() (decoding) * or avcodec_send_frame() (encoding) functions. This will enter draining * mode. * - Call avcodec_receive_frame() (decoding) or avcodec_receive_packet() * (encoding) in a loop until AVERROR_EOF is returned. The functions will * not return AVERROR(EAGAIN), unless you forgot to enter draining mode. * - Before decoding can be resumed again, the codec has to be reset with * avcodec_flush_buffers(). * * Using the API as outlined above is highly recommended. But it is also * possible to call functions outside of this rigid schema. For example, you can * call avcodec_send_packet() repeatedly without calling * avcodec_receive_frame(). In this case, avcodec_send_packet() will succeed * until the codec's internal buffer has been filled up (which is typically of * size 1 per output frame, after initial input), and then reject input with * AVERROR(EAGAIN). Once it starts rejecting input, you have no choice but to * read at least some output. * * Not all codecs will follow a rigid and predictable dataflow; the only * guarantee is that an AVERROR(EAGAIN) return value on a send/receive call on * one end implies that a receive/send call on the other end will succeed, or * at least will not fail with AVERROR(EAGAIN). In general, no codec will * permit unlimited buffering of input or output. * * This API replaces the following legacy functions: * - avcodec_decode_video2() and avcodec_decode_audio4(): * Use avcodec_send_packet() to feed input to the decoder, then use * avcodec_receive_frame() to receive decoded frames after each packet. * Unlike with the old video decoding API, multiple frames might result from * a packet. For audio, splitting the input packet into frames by partially * decoding packets becomes transparent to the API user. You never need to * feed an AVPacket to the API twice (unless it is rejected with AVERROR(EAGAIN) - then * no data was read from the packet). * Additionally, sending a flush/draining packet is required only once. * - avcodec_encode_video2()/avcodec_encode_audio2(): * Use avcodec_send_frame() to feed input to the encoder, then use * avcodec_receive_packet() to receive encoded packets. * Providing user-allocated buffers for avcodec_receive_packet() is not * possible. * - The new API does not handle subtitles yet. * * Mixing new and old function calls on the same AVCodecContext is not allowed, * and will result in undefined behavior. * * Some codecs might require using the new API; using the old API will return * an error when calling it. All codecs support the new API. * * A codec is not allowed to return AVERROR(EAGAIN) for both sending and receiving. This * would be an invalid state, which could put the codec user into an endless * loop. The API has no concept of time either: it cannot happen that trying to * do avcodec_send_packet() results in AVERROR(EAGAIN), but a repeated call 1 second * later accepts the packet (with no other receive/flush API calls involved). * The API is a strict state machine, and the passage of time is not supposed * to influence it. Some timing-dependent behavior might still be deemed * acceptable in certain cases. But it must never result in both send/receive * returning EAGAIN at the same time at any point. It must also absolutely be * avoided that the current state is "unstable" and can "flip-flop" between * the send/receive APIs allowing progress. For example, it's not allowed that * the codec randomly decides that it actually wants to consume a packet now * instead of returning a frame, a