frame.h

Go to the documentation of this file.

/*
 * 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 AVUTIL_FRAME_H
#define AVUTIL_FRAME_H

#include <stddef.h>
#include <stdint.h>

#include "avutil.h"
#include "buffer.h"
#include "dict.h"
#include "rational.h"
#include "samplefmt.h"
#include "pixfmt.h"
#include "version.h"


enum AVFrameSideDataType {
    AV_FRAME_DATA_PANSCAN,
    AV_FRAME_DATA_A53_CC,
    AV_FRAME_DATA_STEREO3D,
    AV_FRAME_DATA_MATRIXENCODING,
    AV_FRAME_DATA_DOWNMIX_INFO,
    AV_FRAME_DATA_REPLAYGAIN,
    AV_FRAME_DATA_DISPLAYMATRIX,
    AV_FRAME_DATA_AFD,
    AV_FRAME_DATA_MOTION_VECTORS,
    AV_FRAME_DATA_SKIP_SAMPLES,
    AV_FRAME_DATA_AUDIO_SERVICE_TYPE,
    AV_FRAME_DATA_MASTERING_DISPLAY_METADATA,
    AV_FRAME_DATA_GOP_TIMECODE,

    AV_FRAME_DATA_SPHERICAL,

    AV_FRAME_DATA_CONTENT_LIGHT_LEVEL,

    AV_FRAME_DATA_ICC_PROFILE,

#if FF_API_FRAME_QP

    AV_FRAME_DATA_QP_TABLE_PROPERTIES,

    AV_FRAME_DATA_QP_TABLE_DATA,
#endif

    AV_FRAME_DATA_S12M_TIMECODE,

    AV_FRAME_DATA_DYNAMIC_HDR_PLUS,

    AV_FRAME_DATA_REGIONS_OF_INTEREST,
};

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 {
    enum AVFrameSideDataType type;
    uint8_t *data;
    int      size;
    AVDictionary *metadata;
    AVBufferRef *buf;
} AVFrameSideData;

typedef struct AVRegionOfInterest {
    uint32_t self_size;
    int top;
    int bottom;
    int left;
    int right;
    AVRational qoffset;
} AVRegionOfInterest;

typedef struct AVFrame {
#define AV_NUM_DATA_POINTERS 8

    uint8_t *data[AV_NUM_DATA_POINTERS];

    int linesize[AV_NUM_DATA_POINTERS];

    uint8_t **extended_data;

    int width, height;
    int nb_samples;

    int format;

    int key_frame;

    enum AVPictureType pict_type;

    AVRational sample_aspect_ratio;

    int64_t pts;

#if FF_API_PKT_PTS

    attribute_deprecated
    int64_t pkt_pts;
#endif

    int64_t pkt_dts;

    int coded_picture_number;
    int display_picture_number;

    int quality;

    void *opaque;

#if FF_API_ERROR_FRAME

    attribute_deprecated
    uint64_t error[AV_NUM_DATA_POINTERS];
#endif

    int repeat_pict;

    int interlaced_frame;

    int top_field_first;

    int palette_has_changed;

    int64_t reordered_opaque;

    int sample_rate;

    uint64_t channel_layout;

    AVBufferRef *buf[AV_NUM_DATA_POINTERS];

    AVBufferRef **extended_buf;
    int        nb_extended_buf;

    AVFrameSideData **side_data;
    int            nb_side_data;

#define AV_FRAME_FLAG_CORRUPT       (1 << 0)

#define AV_FRAME_FLAG_DISCARD   (1 << 2)

    int flags;

    enum AVColorRange color_range;

    enum AVColorPrimaries color_primaries;

    enum AVColorTransferCharacteristic color_trc;

    enum AVColorSpace colorspace;

    enum AVChromaLocation chroma_location;

    int64_t best_effort_timestamp;

    int64_t pkt_pos;

    int64_t pkt_duration;

    AVDictionary *metadata;

    int decode_error_flags;
#define FF_DECODE_ERROR_INVALID_BITSTREAM   1
#define FF_DECODE_ERROR_MISSING_REFERENCE   2

    int channels;

    int pkt_size;

#if FF_API_FRAME_QP

    attribute_deprecated
    int8_t *qscale_table;
    attribute_deprecated
    int qstride;

    attribute_deprecated
    int qscale_type;

    attribute_deprecated
    AVBufferRef *qp_table_buf;
#endif

    AVBufferRef *hw_frames_ctx;

    AVBufferRef *opaque_ref;

    size_t crop_top;
    size_t crop_bottom;
    size_t crop_left;
    size_t crop_right;
    AVBufferRef *private_ref;
} AVFrame;

#if FF_API_FRAME_GET_SET

attribute_deprecated
int64_t av_frame_get_best_effort_timestamp(const AVFrame *frame);
attribute_deprecated
void    av_frame_set_best_effort_timestamp(AVFrame *frame, int64_t val);
attribute_deprecated
int64_t av_frame_get_pkt_duration         (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_pkt_duration         (AVFrame *frame, int64_t val);
attribute_deprecated
int64_t av_frame_get_pkt_pos              (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_pkt_pos              (AVFrame *frame, int64_t val);
attribute_deprecated
int64_t av_frame_get_channel_layout       (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_channel_layout       (AVFrame *frame, int64_t val);
attribute_deprecated
int     av_frame_get_channels             (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_channels             (AVFrame *frame, int     val);
attribute_deprecated
int     av_frame_get_sample_rate          (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_sample_rate          (AVFrame *frame, int     val);
attribute_deprecated
AVDictionary *av_frame_get_metadata       (const AVFrame *frame);
attribute_deprecated
void          av_frame_set_metadata       (AVFrame *frame, AVDictionary *val);
attribute_deprecated
int     av_frame_get_decode_error_flags   (const AVFrame *frame);
attribute_deprecated
void    av_frame_set_decode_error_flags   (AVFrame *frame, int     val);
attribute_deprecated
int     av_frame_get_pkt_size(const AVFrame *frame);
attribute_deprecated
void    av_frame_set_pkt_size(AVFrame *frame, int val);
#if FF_API_FRAME_QP
attribute_deprecated
int8_t *av_frame_get_qp_table(AVFrame *f, int *stride, int *type);
attribute_deprecated
int av_frame_set_qp_table(AVFrame *f, AVBufferRef *buf, int stride, int type);
#endif
attribute_deprecated
enum AVColorSpace av_frame_get_colorspace(const AVFrame *frame);
attribute_deprecated
void    av_frame_set_colorspace(AVFrame *frame, enum AVColorSpace val);
attribute_deprecated
enum AVColorRange av_frame_get_color_range(const AVFrame *frame);
attribute_deprecated
void    av_frame_set_color_range(AVFrame *frame, enum AVColorRange val);
#endif

const char *av_get_colorspace_name(enum AVColorSpace val);

AVFrame *av_frame_alloc(void);

void av_frame_free(AVFrame **frame);

int av_frame_ref(AVFrame *dst, const AVFrame *src);

AVFrame *av_frame_clone(const AVFrame *src);

void av_frame_unref(AVFrame *frame);

void av_frame_move_ref(AVFrame *dst, AVFrame *src);

int av_frame_get_buffer(AVFrame *frame, int align);

int av_frame_is_writable(AVFrame *frame);

int av_frame_make_writable(AVFrame *frame);

int av_frame_copy(AVFrame *dst, const AVFrame *src);

int av_frame_copy_props(AVFrame *dst, const AVFrame *src);

AVBufferRef *av_frame_get_plane_buffer(AVFrame *frame, int plane);

AVFrameSideData *av_frame_new_side_data(AVFrame *frame,
                                        enum AVFrameSideDataType type,
                                        int size);

AVFrameSideData *av_frame_new_side_data_from_buf(AVFrame *frame,
                                                 enum AVFrameSideDataType type,
                                                 AVBufferRef *buf);

AVFrameSideData *av_frame_get_side_data(const AVFrame *frame,
                                        enum AVFrameSideDataType type);

void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type);


enum {
    AV_FRAME_CROP_UNALIGNED     = 1 << 0,
};

int av_frame_apply_cropping(AVFrame *frame, int flags);

const char *av_frame_side_data_name(enum AVFrameSideDataType type);

#endif /* AVUTIL_FRAME_H */