X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=libavutil%2Fframe.h;h=12624d797f022c6d8755f4317bb3842b178e9cae;hb=5a1d605ceae448b476a525f7368ec452000d1f26;hp=b02516592ff73e03de0c22c283f823041fb54ce4;hpb=5b4797a21db900b7d509660b7a4d49829089b004;p=ffmpeg diff --git a/libavutil/frame.h b/libavutil/frame.h index b02516592ff..12624d797f0 100644 --- a/libavutil/frame.h +++ b/libavutil/frame.h @@ -1,5 +1,4 @@ /* - * * This file is part of Libav. * * Libav is free software; you can redistribute it and/or @@ -17,18 +16,33 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ +/** + * @file + * @ingroup lavu_frame + * reference-counted frame API + */ + #ifndef AVUTIL_FRAME_H #define AVUTIL_FRAME_H #include -#include "libavcodec/version.h" - #include "avutil.h" #include "buffer.h" #include "dict.h" #include "rational.h" #include "samplefmt.h" +#include "pixfmt.h" +#include "version.h" + + +/** + * @defgroup lavu_frame AVFrame + * @ingroup lavu_data + * + * @{ + * AVFrame is an abstraction for reference-counted raw multimedia data. + */ enum AVFrameSideDataType { /** @@ -50,6 +64,44 @@ enum AVFrameSideDataType { * The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h. */ AV_FRAME_DATA_MATRIXENCODING, + /** + * Metadata relevant to a downmix procedure. + * The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h. + */ + AV_FRAME_DATA_DOWNMIX_INFO, + /** + * ReplayGain information in the form of the AVReplayGain struct. + */ + AV_FRAME_DATA_REPLAYGAIN, + /** + * This side data contains a 3x3 transformation matrix describing an affine + * transformation that needs to be applied to the frame for correct + * presentation. + * + * See libavutil/display.h for a detailed description of the data. + */ + AV_FRAME_DATA_DISPLAYMATRIX, + /** + * Active Format Description data consisting of a single byte as specified + * in ETSI TS 101 154 using enum AVActiveFormatDescription. + */ + AV_FRAME_DATA_AFD, + + /** + * This side data must be associated with an audio frame and corresponds to + * enum AVAudioServiceType defined in avcodec.h. + */ + AV_FRAME_DATA_AUDIO_SERVICE_TYPE, +}; + +enum AVActiveFormatDescription { + AV_AFD_SAME = 8, + AV_AFD_4_3 = 9, + AV_AFD_16_9 = 10, + AV_AFD_14_9 = 11, + AV_AFD_4_3_SP_14_9 = 13, + AV_AFD_16_9_SP_14_9 = 14, + AV_AFD_SP_4_3 = 15, }; typedef struct AVFrameSideData { @@ -148,11 +200,6 @@ typedef struct AVFrame { */ enum AVPictureType pict_type; -#if FF_API_AVFRAME_LAVC - attribute_deprecated - uint8_t *base[AV_NUM_DATA_POINTERS]; -#endif - /** * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified. */ @@ -163,10 +210,14 @@ typedef struct AVFrame { */ int64_t pts; +#if FF_API_PKT_PTS /** * PTS copied from the AVPacket that was decoded to produce this frame. + * @deprecated use the pts field instead */ + attribute_deprecated int64_t pkt_pts; +#endif /** * DTS copied from the AVPacket that triggered returning this frame. @@ -187,78 +238,17 @@ typedef struct AVFrame { */ int quality; -#if FF_API_AVFRAME_LAVC - attribute_deprecated - int reference; - - /** - * QP table - */ - attribute_deprecated - int8_t *qscale_table; - /** - * QP store stride - */ - attribute_deprecated - int qstride; - - attribute_deprecated - int qscale_type; - - /** - * mbskip_table[mb]>=1 if MB didn't change - * stride= mb_width = (width+15)>>4 - */ - attribute_deprecated - uint8_t *mbskip_table; - - /** - * motion vector table - * @code - * example: - * int mv_sample_log2= 4 - motion_subsample_log2; - * int mb_width= (width+15)>>4; - * int mv_stride= (mb_width << mv_sample_log2) + 1; - * motion_val[direction][x + y*mv_stride][0->mv_x, 1->mv_y]; - * @endcode - */ - attribute_deprecated - int16_t (*motion_val[2])[2]; - - /** - * macroblock type table - * mb_type_base + mb_width + 2 - */ - attribute_deprecated - uint32_t *mb_type; - - /** - * DCT coefficients - */ - attribute_deprecated - short *dct_coeff; - - /** - * motion reference frame index - * the order in which these are stored can depend on the codec. - */ - attribute_deprecated - int8_t *ref_index[2]; -#endif - /** * for some private data of the user */ void *opaque; +#if FF_API_ERROR_FRAME /** - * error + * @deprecated unused */ - uint64_t error[AV_NUM_DATA_POINTERS]; - -#if FF_API_AVFRAME_LAVC attribute_deprecated - int type; + uint64_t error[AV_NUM_DATA_POINTERS]; #endif /** @@ -282,19 +272,8 @@ typedef struct AVFrame { */ int palette_has_changed; -#if FF_API_AVFRAME_LAVC - attribute_deprecated - int buffer_hints; - - /** - * Pan scan. - */ - attribute_deprecated - struct AVPanScan *pan_scan; -#endif - /** - * reordered opaque 64bit (generally an integer or a double precision float + * reordered opaque 64 bits (generally an integer or a double precision float * PTS but can be anything). * The user sets AVCodecContext.reordered_opaque to represent the input at * that time, @@ -304,25 +283,6 @@ typedef struct AVFrame { */ int64_t reordered_opaque; -#if FF_API_AVFRAME_LAVC - /** - * @deprecated this field is unused - */ - attribute_deprecated void *hwaccel_picture_private; - - attribute_deprecated - struct AVCodecContext *owner; - attribute_deprecated - void *thread_opaque; - - /** - * log2 of the size of the block which a single vector in motion_val represents: - * (4->16x16, 3->8x8, 2-> 4x4, 1-> 2x2) - */ - attribute_deprecated - uint8_t motion_subsample_log2; -#endif - /** * Sample rate of the audio data. */ @@ -335,7 +295,9 @@ typedef struct AVFrame { /** * AVBuffer references backing the data for this frame. If all elements of - * this array are NULL, then this frame is not reference counted. + * this array are NULL, then this frame is not reference counted. This array + * must be filled contiguously -- if buf[i] is non-NULL then buf[j] must + * also be non-NULL for all j < i. * * There may be at most one AVBuffer per data plane, so for video this array * always contains all the references. For planar audio with more than @@ -366,15 +328,41 @@ typedef struct AVFrame { AVFrameSideData **side_data; int nb_side_data; +/** + * @defgroup lavu_frame_flags AV_FRAME_FLAGS + * Flags describing additional frame properties. + * + * @{ + */ + /** * The frame data may be corrupted, e.g. due to decoding errors. */ #define AV_FRAME_FLAG_CORRUPT (1 << 0) +/** + * @} + */ /** - * Frame flags, a combination of AV_FRAME_FLAG_* + * Frame flags, a combination of @ref lavu_frame_flags */ int flags; + + enum AVColorRange color_range; + + enum AVColorPrimaries color_primaries; + + enum AVColorTransferCharacteristic color_trc; + + enum AVColorSpace colorspace; + + enum AVChromaLocation chroma_location; + + /** + * For hwaccel-format frames, this should be a reference to the + * AVHWFramesContext describing the frame. + */ + AVBufferRef *hw_frames_ctx; } AVFrame; /** @@ -399,7 +387,7 @@ AVFrame *av_frame_alloc(void); void av_frame_free(AVFrame **frame); /** - * Setup a new reference to the data described by an given frame. + * Set up a new reference to the data described by the source frame. * * Copy frame properties from src to dst and create a new reference for each * AVBufferRef from src. @@ -407,6 +395,10 @@ void av_frame_free(AVFrame **frame); * If src is not reference counted, new buffers are allocated and the data is * copied. * + * @warning: dst MUST have been either unreferenced with av_frame_unref(dst), + * or newly allocated with av_frame_alloc() before calling this + * function, or undefined behavior will occur. + * * @return 0 on success, a negative AVERROR on error */ int av_frame_ref(AVFrame *dst, const AVFrame *src); @@ -426,7 +418,11 @@ AVFrame *av_frame_clone(const AVFrame *src); void av_frame_unref(AVFrame *frame); /** - * Move everythnig contained in src to dst and reset src. + * Move everything contained in src to dst and reset src. + * + * @warning: dst is not unreferenced, but directly overwritten without reading + * or deallocating its contents. Call av_frame_unref(dst) manually + * before calling this function to ensure that no memory is leaked. */ void av_frame_move_ref(AVFrame *dst, AVFrame *src); @@ -442,6 +438,10 @@ void av_frame_move_ref(AVFrame *dst, AVFrame *src); * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf. * For planar formats, one buffer will be allocated for each plane. * + * @warning: if frame already has been allocated, calling this function will + * leak memory. In addition, undefined behavior can occur in certain + * cases. + * * @param frame frame in which to store the new buffers. * @param align required buffer size alignment * @@ -476,6 +476,19 @@ int av_frame_is_writable(AVFrame *frame); */ int av_frame_make_writable(AVFrame *frame); +/** + * Copy the frame data from src to dst. + * + * This function does not allocate anything, dst must be already initialized and + * allocated with the same parameters as src. + * + * This function only copies the frame data (i.e. the contents of the data / + * extended data arrays), not any other properties. + * + * @return >= 0 on success, a negative AVERROR on error. + */ +int av_frame_copy(AVFrame *dst, const AVFrame *src); + /** * Copy only "metadata" fields from src to dst. * @@ -516,4 +529,14 @@ AVFrameSideData *av_frame_new_side_data(AVFrame *frame, AVFrameSideData *av_frame_get_side_data(const AVFrame *frame, enum AVFrameSideDataType type); +/** + * If side data of the supplied type exists in the frame, free it and remove it + * from the frame. + */ +void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type); + +/** + * @} + */ + #endif /* AVUTIL_FRAME_H */