X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=libavcodec%2Favcodec.h;h=bb545651ae99c59d2210ce9ffce4aaae391e840f;hb=31f6a4b4b83aca1d73f3cfc99ce2b39331970bf3;hp=0ff31a0b94a5bb277bc99506d0a1bff195f05599;hpb=33d18982fa03feb061c8f744a4f0a9175c1f63ab;p=ffmpeg diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 0ff31a0b94a..bb545651ae9 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -76,6 +76,95 @@ * @} */ +/** + * @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 decoder 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. + * + * 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. 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. + * 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 arbitrary behavior. + * + * Some codecs might require using the new API; using the old API will return + * an error when calling it. + * @} + */ + /** * @defgroup lavc_core Core functions/structures. * @ingroup libavc @@ -694,7 +783,7 @@ typedef struct RcOverride{ * Use only bitexact stuff (except (I)DCT). */ #define AV_CODEC_FLAG_BITEXACT (1 << 23) -/* Fx : Flag for h263+ extra options */ +/* Fx : Flag for H.263+ extra options */ /** * H.263 advanced intra coding / MPEG-4 AC prediction */ @@ -780,7 +869,7 @@ typedef struct RcOverride{ * are connected to a parser to split what they return into proper frames. * This flag is reserved to the very rare category of codecs which have a * bitstream that cannot be split into frames without timeconsuming - * operations like full decoding. Demuxers carring such bitstreams thus + * operations like full decoding. Demuxers carrying such bitstreams thus * may return multiple frames in a packet. This has many disadvantages like * prohibiting stream copy in many cases thus it should only be considered * as a last resort. @@ -870,7 +959,7 @@ typedef struct RcOverride{ #define CODEC_FLAG_LOW_DELAY 0x00080000 ///< Force low delay. #define CODEC_FLAG_GLOBAL_HEADER 0x00400000 ///< Place global headers in extradata instead of every keyframe. #define CODEC_FLAG_BITEXACT 0x00800000 ///< Use only bitexact stuff (except (I)DCT). -/* Fx : Flag for h263+ extra options */ +/* Fx : Flag for H.263+ extra options */ #define CODEC_FLAG_AC_PRED 0x01000000 ///< H.263 advanced intra coding / MPEG-4 AC prediction #define CODEC_FLAG_LOOP_FILTER 0x00000800 ///< loop filter #define CODEC_FLAG_INTERLACED_ME 0x20000000 ///< interlaced motion estimation @@ -942,7 +1031,7 @@ typedef struct RcOverride{ * are connected to a parser to split what they return into proper frames. * This flag is reserved to the very rare category of codecs which have a * bitstream that cannot be split into frames without timeconsuming - * operations like full decoding. Demuxers carring such bitstreams thus + * operations like full decoding. Demuxers carrying such bitstreams thus * may return multiple frames in a packet. This has many disadvantages like * prohibiting stream copy in many cases thus it should only be considered * as a last resort. @@ -1008,7 +1097,7 @@ typedef struct RcOverride{ #define MB_TYPE_L0L1 (MB_TYPE_L0 | MB_TYPE_L1) #define MB_TYPE_QUANT 0x00010000 #define MB_TYPE_CBP 0x00020000 -//Note bits 24-31 are reserved for codec specific use (h264 ref0, mpeg1 0mv, ...) +// Note bits 24-31 are reserved for codec specific use (H.264 ref0, MPEG-1 0mv, ...) #endif /** @@ -1411,11 +1500,11 @@ typedef struct AVCodecContext { /** * some codecs need / can use extradata like Huffman tables. - * mjpeg: Huffman tables + * MJPEG: Huffman tables * rv10: additional flags - * mpeg4: global headers (they can be in the bitstream or here) + * MPEG-4: global headers (they can be in the bitstream or here) * The allocated memory should be AV_INPUT_BUFFER_PADDING_SIZE bytes larger - * than extradata_size to avoid prolems if it is read with the bitstream reader. + * than extradata_size to avoid problems if it is read with the bitstream reader. * The bytewise contents of extradata must not depend on the architecture or CPU endianness. * - encoding: Set/allocated/freed by libavcodec. * - decoding: Set/allocated/freed by user. @@ -1468,7 +1557,7 @@ typedef struct AVCodecContext { * picture width / height. * * @note Those fields may not match the values of the last - * AVFrame outputted by avcodec_decode_video2 due frame + * AVFrame output by avcodec_decode_video2 due frame * reordering. * * - encoding: MUST be set by user. @@ -1484,7 +1573,7 @@ typedef struct AVCodecContext { * the decoded frame is cropped before being output. * * @note Those field may not match the value of the last - * AVFrame outputted by avcodec_decode_video2 due frame + * AVFrame output by avcodec_receive_frame() due frame * reordering. * * - encoding: unused @@ -1508,10 +1597,10 @@ typedef struct AVCodecContext { /** * Pixel format, see AV_PIX_FMT_xxx. * May be set by the demuxer if known from headers. - * May be overriden by the decoder if it knows better. + * May be overridden by the decoder if it knows better. * * @note This field may not match the value of the last - * AVFrame outputted by avcodec_decode_video2 due frame + * AVFrame output by avcodec_receive_frame() due frame * reordering. * * - encoding: Set by user. @@ -1621,8 +1710,8 @@ typedef struct AVCodecContext { #endif /** - * qscale factor between P and I-frames - * If > 0 then the last p frame quantizer will be used (q= lastp_q*factor+offset). + * qscale factor between P- and I-frames + * If > 0 then the last P-frame quantizer will be used (q = lastp_q * factor + offset). * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset). * - encoding: Set by user. * - decoding: unused @@ -1832,7 +1921,7 @@ typedef struct AVCodecContext { */ int slice_flags; #define SLICE_FLAG_CODED_ORDER 0x0001 ///< draw_horiz_band() is called in coded order instead of display -#define SLICE_FLAG_ALLOW_FIELD 0x0002 ///< allow draw_horiz_band() with field slices (MPEG2 field pics) +#define SLICE_FLAG_ALLOW_FIELD 0x0002 ///< allow draw_horiz_band() with field slices (MPEG-2 field pics) #define SLICE_FLAG_ALLOW_PLANE 0x0004 ///< allow draw_horiz_band() with 1 component at a time (SVQ1) #if FF_API_XVMC @@ -1923,14 +2012,14 @@ typedef struct AVCodecContext { #endif /** - * minimum MB lagrange multipler + * minimum MB Lagrange multiplier * - encoding: Set by user. * - decoding: unused */ int mb_lmin; /** - * maximum MB lagrange multipler + * maximum MB Lagrange multiplier * - encoding: Set by user. * - decoding: unused */ @@ -2149,7 +2238,7 @@ typedef struct AVCodecContext { * to all data planes. data[] must hold as many pointers as it can. * extended_data must be allocated with av_malloc() and will be freed in * av_frame_unref(). - * * otherwise exended_data must point to data + * * otherwise extended_data must point to data * - buf[] must contain one or more pointers to AVBufferRef structures. Each of * the frame's data and extended_data pointers must be contained in these. That * is, one AVBufferRef for each allocated chunk of memory, not necessarily one @@ -2211,6 +2300,8 @@ typedef struct AVCodecContext { * Otherwise, the decoded frames must not be freed by the caller and are * only valid until the next decode call. * + * This is always automatically enabled if avcodec_receive_frame() is used. + * * - encoding: unused * - decoding: set by the caller before avcodec_open2(). */ @@ -2489,7 +2580,7 @@ typedef struct AVCodecContext { #define FF_BUG_TRUNCATED 16384 /** - * strictly follow the standard (MPEG4, ...). + * strictly follow the standard (MPEG-4, ...). * - encoding: Set by user. * - decoding: Set by user. * Setting this to STRICT or higher means the encoder and decoder will @@ -2555,9 +2646,9 @@ typedef struct AVCodecContext { */ attribute_deprecated int debug_mv; -#define FF_DEBUG_VIS_MV_P_FOR 0x00000001 //visualize forward predicted MVs of P frames -#define FF_DEBUG_VIS_MV_B_FOR 0x00000002 //visualize forward predicted MVs of B frames -#define FF_DEBUG_VIS_MV_B_BACK 0x00000004 //visualize backward predicted MVs of B frames +#define FF_DEBUG_VIS_MV_P_FOR 0x00000001 // visualize forward predicted MVs of P-frames +#define FF_DEBUG_VIS_MV_B_FOR 0x00000002 // visualize forward predicted MVs of B-frames +#define FF_DEBUG_VIS_MV_B_BACK 0x00000004 // visualize backward predicted MVs of B-frames #endif /** @@ -2579,7 +2670,7 @@ typedef struct AVCodecContext { #define AV_EF_EXPLODE (1<<3) /** - * opaque 64bit number (generally a PTS) that will be reordered and + * opaque 64-bit number (generally a PTS) that will be reordered and * output in AVFrame.reordered_opaque * - encoding: unused * - decoding: Set by user. @@ -2764,7 +2855,7 @@ typedef struct AVCodecContext { int (*execute2)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg, int jobnr, int threadnr), void *arg2, int *ret, int count); /** - * noise vs. sse weight for the nsse comparsion function + * noise vs. sse weight for the nsse comparison function * - encoding: Set by user. * - decoding: unused */ @@ -2953,7 +3044,8 @@ typedef struct AVCodecContext { * - decoding: For codecs that store a framerate value in the compressed * bitstream, the decoder may export it here. { 0, 1} when * unknown. - * - encoding: unused + * - encoding: May be used to signal the framerate of CFR content to an + * encoder. */ AVRational framerate; @@ -3089,6 +3181,21 @@ typedef struct AVCodec { int *got_packet_ptr); int (*decode)(AVCodecContext *, void *outdata, int *outdata_size, AVPacket *avpkt); int (*close)(AVCodecContext *); + /** + * Decode/encode API with decoupled packet/frame dataflow. The API is the + * same as the avcodec_ prefixed APIs (avcodec_send_frame() etc.), except + * that: + * - never called if the codec is closed or the wrong type, + * - AVPacket parameter change side data is applied right before calling + * AVCodec->send_packet, + * - if AV_CODEC_CAP_DELAY is not set, drain packets or frames are never sent, + * - only one drain packet is ever passed down (until the next flush()), + * - a drain AVPacket is always NULL (no need to check for avpkt->size). + */ + int (*send_frame)(AVCodecContext *avctx, const AVFrame *frame); + int (*send_packet)(AVCodecContext *avctx, const AVPacket *avpkt); + int (*receive_frame)(AVCodecContext *avctx, AVFrame *frame); + int (*receive_packet)(AVCodecContext *avctx, AVPacket *avpkt); /** * Flush buffers. * Will be called when seeking @@ -3319,7 +3426,7 @@ typedef struct AVSubtitleRect { /** * 0 terminated ASS/SSA compatible event line. - * The pressentation of this is unaffected by the other values in this + * The presentation of this is unaffected by the other values in this * struct. */ char *ass; @@ -3607,7 +3714,7 @@ int avcodec_parameters_to_context(AVCodecContext *codec, * @warning This function is not thread safe! * * @note Always call this function before using decoding routines (such as - * @ref avcodec_decode_video2()). + * @ref avcodec_receive_frame()). * * @code * avcodec_register_all(); @@ -4005,7 +4112,10 @@ void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height, * @return A negative error code is returned if an error occurred during * decoding, otherwise the number of bytes consumed from the input * AVPacket is returned. + * +* @deprecated Use avcodec_send_packet() and avcodec_receive_frame(). */ +attribute_deprecated int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame, int *got_frame_ptr, AVPacket *avpkt); @@ -4043,7 +4153,7 @@ int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame, * next call to this function or until closing or flushing the * decoder. The caller may not write to it. * - * @param[in] avpkt The input AVpacket containing the input buffer. + * @param[in] avpkt The input AVPacket containing the input buffer. * You can create such packet with av_init_packet() and by then setting * data and size, some decoders might in addition need other fields like * flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least @@ -4051,7 +4161,10 @@ int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame, * @param[in,out] got_picture_ptr Zero if no frame could be decompressed, otherwise, it is nonzero. * @return On error a negative value is returned, otherwise the number of bytes * used or zero if no frame could be decompressed. + * + * @deprecated Use avcodec_send_packet() and avcodec_receive_frame(). */ +attribute_deprecated int avcodec_decode_video2(AVCodecContext *avctx, AVFrame *picture, int *got_picture_ptr, AVPacket *avpkt); @@ -4079,6 +4192,129 @@ int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub, int *got_sub_ptr, AVPacket *avpkt); +/** + * Supply raw packet data as input to a decoder. + * + * Internally, this call will copy relevant AVCodecContext fields, which can + * influence decoding per-packet, and apply them when the packet is actually + * decoded. (For example AVCodecContext.skip_frame, which might direct the + * decoder to drop the frame contained by the packet sent with this function.) + * + * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE + * larger than the actual read bytes because some optimized bitstream + * readers read 32 or 64 bits at once and could read over the end. + * + * @warning Do not mix this API with the legacy API (like avcodec_decode_video2()) + * on the same AVCodecContext. It will return unexpected results now + * or in future libavcodec versions. + * + * @note The AVCodecContext MUST have been opened with @ref avcodec_open2() + * before packets may be fed to the decoder. + * + * @param avctx codec context + * @param[in] avpkt The input AVPacket. Usually, this will be a single video + * frame, or several complete audio frames. + * Ownership of the packet remains with the caller, and the + * decoder will not write to the packet. The decoder may create + * a reference to the packet data (or copy it if the packet is + * not reference-counted). + * Unlike with older APIs, the packet is always fully consumed, + * and if it contains multiple frames (e.g. some audio codecs), + * will require you to call avcodec_receive_frame() multiple + * times afterwards before you can send a new packet. + * It can be NULL (or an AVPacket with data set to NULL and + * size set to 0); in this case, it is considered a flush + * packet, which signals the end of the stream. Sending the + * first flush packet will return success. Subsequent ones are + * unnecessary and will return AVERROR_EOF. If the decoder + * still has frames buffered, it will return them after sending + * a flush packet. + * + * @return 0 on success, otherwise negative error code: + * AVERROR(EAGAIN): input is not accepted right now - the packet must be + * resent after trying to read output + * AVERROR_EOF: the decoder has been flushed, and no new packets can + * be sent to it (also returned if more than 1 flush + * packet is sent) + * AVERROR(EINVAL): codec not opened, it is an encoder, or requires flush + * AVERROR(ENOMEM): failed to add packet to internal queue, or similar + * other errors: legitimate decoding errors + */ +int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt); + +/** + * Return decoded output data from a decoder. + * + * @param avctx codec context + * @param frame This will be set to a reference-counted video or audio + * frame (depending on the decoder type) allocated by the + * decoder. Note that the function will always call + * av_frame_unref(frame) before doing anything else. + * + * @return + * 0: success, a frame was returned + * AVERROR(EAGAIN): output is not available right now - user must try + * to send new input + * AVERROR_EOF: the decoder has been fully flushed, and there will be + * no more output frames + * AVERROR(EINVAL): codec not opened, or it is an encoder + * other negative values: legitimate decoding errors + */ +int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame); + +/** + * Supply a raw video or audio frame to the encoder. Use avcodec_receive_packet() + * to retrieve buffered output packets. + * + * @param avctx codec context + * @param[in] frame AVFrame containing the raw audio or video frame to be encoded. + * Ownership of the frame remains with the caller, and the + * encoder will not write to the frame. The encoder may create + * a reference to the frame data (or copy it if the frame is + * not reference-counted). + * It can be NULL, in which case it is considered a flush + * packet. This signals the end of the stream. If the encoder + * still has packets buffered, it will return them after this + * call. Once flushing mode has been entered, additional flush + * packets are ignored, and sending frames will return + * AVERROR_EOF. + * + * For audio: + * If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame + * can have any number of samples. + * If it is not set, frame->nb_samples must be equal to + * avctx->frame_size for all frames except the last. + * The final frame may be smaller than avctx->frame_size. + * @return 0 on success, otherwise negative error code: + * AVERROR(EAGAIN): input is not accepted right now - the frame must be + * resent after trying to read output packets + * AVERROR_EOF: the encoder has been flushed, and no new frames can + * be sent to it + * AVERROR(EINVAL): codec not opened, refcounted_frames not set, it is a + * decoder, or requires flush + * AVERROR(ENOMEM): failed to add packet to internal queue, or similar + * other errors: legitimate decoding errors + */ +int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame); + +/** + * Read encoded data from the encoder. + * + * @param avctx codec context + * @param avpkt This will be set to a reference-counted packet allocated by the + * encoder. Note that the function will always call + * av_frame_unref(frame) before doing anything else. + * @return 0 on success, otherwise negative error code: + * AVERROR(EAGAIN): output is not available right now - user must try + * to send input + * AVERROR_EOF: the encoder has been fully flushed, and there will be + * no more output packets + * AVERROR(EINVAL): codec not opened, or it is an encoder + * other errors: legitimate decoding errors + */ +int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt); + + /** * @defgroup lavc_parsing Frame parsing * @{ @@ -4384,7 +4620,10 @@ AVCodec *avcodec_find_encoder_by_name(const char *name); * value of got_packet_ptr is undefined and should * not be used. * @return 0 on success, negative error code on failure + * + * @deprecated use avcodec_send_frame()/avcodec_receive_packet() instead */ +attribute_deprecated int avcodec_encode_audio2(AVCodecContext *avctx, AVPacket *avpkt, const AVFrame *frame, int *got_packet_ptr); @@ -4420,7 +4659,10 @@ int avcodec_encode_audio2(AVCodecContext *avctx, AVPacket *avpkt, * value of got_packet_ptr is undefined and should * not be used. * @return 0 on success, negative error code on failure + * + * @deprecated use avcodec_send_frame()/avcodec_receive_packet() instead */ +attribute_deprecated int avcodec_encode_video2(AVCodecContext *avctx, AVPacket *avpkt, const AVFrame *frame, int *got_packet_ptr); @@ -4936,7 +5178,7 @@ unsigned int av_xiphlacing(unsigned char *s, unsigned int v); * a pointer to an AVClass struct * @param[in] feature string containing the name of the missing feature * @param[in] want_sample indicates if samples are wanted which exhibit this feature. - * If want_sample is non-zero, additional verbage will be added to the log + * If want_sample is non-zero, additional verbiage will be added to the log * message which tells the user how to report samples to the development * mailing list. * @deprecated Use avpriv_report_missing_feature() instead.