/*
- *
* This file is part of Libav.
*
* Libav is free software; you can redistribute it and/or
* 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 <stdint.h>
-#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 {
/**
* The data is the AVPanScan struct defined in libavcodec.
*/
AV_FRAME_DATA_PANSCAN,
+ /**
+ * ATSC A53 Part 4 Closed Captions.
+ * A53 CC bitstream is stored as uint8_t in AVFrameSideData.data.
+ * The number of bytes of CC data is AVFrameSideData.size.
+ */
+ AV_FRAME_DATA_A53_CC,
+ /**
+ * Stereoscopic 3d metadata.
+ * The data is the AVStereo3D struct defined in libavutil/stereo3d.h.
+ */
+ AV_FRAME_DATA_STEREO3D,
+ /**
+ * 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 {
/**
* This structure describes decoded (raw) audio or video data.
*
- * AVFrame must be allocated using av_frame_alloc(). Not that this only
+ * AVFrame must be allocated using av_frame_alloc(). Note that this only
* allocates the AVFrame itself, the buffers for the data must be managed
* through other means (see below).
* AVFrame must be freed with av_frame_free().
*/
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.
*/
*/
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.
*/
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
/**
*/
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,
*/
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.
*/
/**
* 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
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;
/**
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.
* 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);
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);
* 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
*
*/
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.
*
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 */