FFmpeg
decode.h
Go to the documentation of this file.
1 /*
2  * generic decoding-related code
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 #ifndef AVCODEC_DECODE_H
22 #define AVCODEC_DECODE_H
23 
24 #include "libavutil/frame.h"
25 #include "libavutil/hwcontext.h"
26 
27 #include "avcodec.h"
28 
29 /**
30  * This struct stores per-frame lavc-internal data and is attached to it via
31  * private_ref.
32  */
33 typedef struct FrameDecodeData {
34  /**
35  * The callback to perform some delayed processing on the frame right
36  * before it is returned to the caller.
37  *
38  * @note This code is called at some unspecified point after the frame is
39  * returned from the decoder's decode/receive_frame call. Therefore it cannot rely
40  * on AVCodecContext being in any specific state, so it does not get to
41  * access AVCodecContext directly at all. All the state it needs must be
42  * stored in the post_process_opaque object.
43  */
44  int (*post_process)(void *logctx, AVFrame *frame);
46  void (*post_process_opaque_free)(void *opaque);
47 
48  /**
49  * Per-frame private data for hwaccels.
50  */
51  void *hwaccel_priv;
52  void (*hwaccel_priv_free)(void *priv);
54 
55 /**
56  * Called by decoders to get the next packet for decoding.
57  *
58  * @param pkt An empty packet to be filled with data.
59  * @return 0 if a new reference has been successfully written to pkt
60  * AVERROR(EAGAIN) if no data is currently available
61  * AVERROR_EOF if and end of stream has been reached, so no more data
62  * will be available
63  */
65 
66 /**
67  * Set various frame properties from the provided packet.
68  */
70  AVFrame *frame, const AVPacket *pkt);
71 
72 /**
73  * Set various frame properties from the codec context / packet data.
74  */
76 
77 /**
78  * Make sure avctx.hw_frames_ctx is set. If it's not set, the function will
79  * try to allocate it from hw_device_ctx. If that is not possible, an error
80  * message is printed, and an error code is returned.
81  */
83  enum AVHWDeviceType dev_type);
84 
86 
87 /**
88  * Check whether the side-data of src contains a palette of
89  * size AVPALETTE_SIZE; if so, copy it to dst and return 1;
90  * else return 0.
91  * Also emit an error message upon encountering a palette
92  * with invalid size.
93  */
94 int ff_copy_palette(void *dst, const AVPacket *src, void *logctx);
95 
96 /**
97  * Check that the provided frame dimensions are valid and set them on the codec
98  * context.
99  */
101 
102 /**
103  * Check that the provided sample aspect ratio is valid and set it on the codec
104  * context.
105  */
106 int ff_set_sar(AVCodecContext *avctx, AVRational sar);
107 
108 /**
109  * Select the (possibly hardware accelerated) pixel format.
110  * This is a wrapper around AVCodecContext.get_format() and should be used
111  * instead of calling get_format() directly.
112  *
113  * The list of pixel formats must contain at least one valid entry, and is
114  * terminated with AV_PIX_FMT_NONE. If it is possible to decode to software,
115  * the last entry in the list must be the most accurate software format.
116  * If it is not possible to decode to software, AVCodecContext.sw_pix_fmt
117  * must be set before calling this function.
118  */
119 int ff_get_format(AVCodecContext *avctx, const enum AVPixelFormat *fmt);
120 
121 /**
122  * Get a buffer for a frame. This is a wrapper around
123  * AVCodecContext.get_buffer() and should be used instead calling get_buffer()
124  * directly.
125  */
126 int ff_get_buffer(AVCodecContext *avctx, AVFrame *frame, int flags);
127 
128 #define FF_REGET_BUFFER_FLAG_READONLY 1 ///< the returned buffer does not need to be writable
129 /**
130  * Identical in function to ff_get_buffer(), except it reuses the existing buffer
131  * if available.
132  */
134 
135 /**
136  * Add or update AV_FRAME_DATA_MATRIXENCODING side data.
137  */
139  enum AVMatrixEncoding matrix_encoding);
140 
141 /**
142  * Allocate a hwaccel frame private data if the provided avctx
143  * uses a hwaccel method that needs it. The returned data is
144  * a RefStruct reference (if allocated).
145  *
146  * @param avctx The codec context
147  * @param hwaccel_picture_private Pointer to return hwaccel_picture_private
148  * @return 0 on success, < 0 on error
149  */
150 int ff_hwaccel_frame_priv_alloc(AVCodecContext *avctx, void **hwaccel_picture_private);
151 
152 /**
153  * Get side data of the given type from a decoding context.
154  */
157 
158 /**
159  * Wrapper around av_frame_new_side_data, which rejects side data overridden by
160  * the demuxer. Returns 0 on success, and a negative error code otherwise.
161  * If successful and sd is not NULL, *sd may either contain a pointer to the new
162  * side data, or NULL in case the side data was already present.
163  */
165  enum AVFrameSideDataType type, size_t size,
166  AVFrameSideData **sd);
167 
168 /**
169  * Similar to `ff_frame_new_side_data`, but using an existing buffer ref.
170  *
171  * *buf is ALWAYS consumed by this function and NULL written in its place, even
172  * on failure.
173  */
176  AVBufferRef **buf, AVFrameSideData **sd);
177 
178 /**
179  * Same as `ff_frame_new_side_data_from_buf`, but taking a AVFrameSideData
180  * array directly instead of an AVFrame.
181  */
183  AVFrameSideData ***sd, int *nb_sd,
185  AVBufferRef **buf);
186 
189 
190 /**
191  * Wrapper around av_mastering_display_metadata_create_side_data(), which
192  * rejects side data overridden by the demuxer. Returns 0 on success, and a
193  * negative error code otherwise. If successful, *mdm may either be a pointer to
194  * the new side data, or NULL in case the side data was already present.
195  */
197  struct AVMasteringDisplayMetadata **mdm);
198 
199 /**
200  * Same as `ff_decode_mastering_display_new`, but taking a AVFrameSideData
201  * array directly instead of an AVFrame.
202  */
204  AVFrameSideData ***sd, int *nb_sd,
205  struct AVMasteringDisplayMetadata **mdm);
206 
207 /**
208  * Wrapper around av_content_light_metadata_create_side_data(), which
209  * rejects side data overridden by the demuxer. Returns 0 on success, and a
210  * negative error code otherwise. If successful, *clm may either be a pointer to
211  * the new side data, or NULL in case the side data was already present.
212  */
214  struct AVContentLightMetadata **clm);
215 
216 /**
217  * Same as `ff_decode_content_light_new`, but taking a AVFrameSideData
218  * array directly instead of an AVFrame.
219  */
221  AVFrameSideData ***sd, int *nb_sd,
222  struct AVContentLightMetadata **clm);
223 #endif /* AVCODEC_DECODE_H */
ff_get_format
int ff_get_format(AVCodecContext *avctx, const enum AVPixelFormat *fmt)
Select the (possibly hardware accelerated) pixel format.
Definition: decode.c:1241
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:71
ff_hwaccel_frame_priv_alloc
int ff_hwaccel_frame_priv_alloc(AVCodecContext *avctx, void **hwaccel_picture_private)
Allocate a hwaccel frame private data if the provided avctx uses a hwaccel method that needs it.
Definition: decode.c:2111
FrameDecodeData
This struct stores per-frame lavc-internal data and is attached to it via private_ref.
Definition: decode.h:33
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:374
AVPacketSideData
This structure stores auxiliary information for decoding, presenting, or otherwise processing the cod...
Definition: packet.h:375
FrameDecodeData::hwaccel_priv_free
void(* hwaccel_priv_free)(void *priv)
Definition: decode.h:52
ff_set_dimensions
int ff_set_dimensions(AVCodecContext *s, int width, int height)
Check that the provided frame dimensions are valid and set them on the codec context.
Definition: utils.c:94
ff_frame_new_side_data_from_buf
int ff_frame_new_side_data_from_buf(const AVCodecContext *avctx, AVFrame *frame, enum AVFrameSideDataType type, AVBufferRef **buf, AVFrameSideData **sd)
Similar to ff_frame_new_side_data, but using an existing buffer ref.
Definition: decode.c:1997
AVContentLightMetadata
Content light level needed by to transmit HDR over HDMI (CTA-861.3).
Definition: mastering_display_metadata.h:107
FrameDecodeData::post_process_opaque_free
void(* post_process_opaque_free)(void *opaque)
Definition: decode.h:46
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
AVFrameSideDataType
AVFrameSideDataType
Definition: frame.h:49
ff_decode_frame_props
int ff_decode_frame_props(AVCodecContext *avctx, AVFrame *frame)
Set various frame properties from the codec context / packet data.
Definition: decode.c:1467
pkt
AVPacket * pkt
Definition: movenc.c:60
ff_side_data_update_matrix_encoding
int ff_side_data_update_matrix_encoding(AVFrame *frame, enum AVMatrixEncoding matrix_encoding)
Add or update AV_FRAME_DATA_MATRIXENCODING side data.
Definition: utils.c:124
width
#define width
s
#define s(width, name)
Definition: cbs_vp9.c:198
FrameDecodeData::post_process_opaque
void * post_process_opaque
Definition: decode.h:45
AVHWDeviceType
AVHWDeviceType
Definition: hwcontext.h:27
ff_attach_decode_data
int ff_attach_decode_data(AVFrame *frame)
Definition: decode.c:1551
ff_decode_frame_props_from_pkt
int ff_decode_frame_props_from_pkt(const AVCodecContext *avctx, AVFrame *frame, const AVPacket *pkt)
Set various frame properties from the provided packet.
Definition: decode.c:1401
ff_get_buffer
int ff_get_buffer(AVCodecContext *avctx, AVFrame *frame, int flags)
Get a buffer for a frame.
Definition: decode.c:1575
AVMatrixEncoding
AVMatrixEncoding
Definition: channel_layout.h:244
ff_frame_new_side_data_from_buf_ext
int ff_frame_new_side_data_from_buf_ext(const AVCodecContext *avctx, AVFrameSideData ***sd, int *nb_sd, enum AVFrameSideDataType type, AVBufferRef **buf)
Same as ff_frame_new_side_data_from_buf, but taking a AVFrameSideData array directly instead of an AV...
Definition: decode.c:1978
ff_decode_get_hw_frames_ctx
int ff_decode_get_hw_frames_ctx(AVCodecContext *avctx, enum AVHWDeviceType dev_type)
Make sure avctx.hw_frames_ctx is set.
Definition: decode.c:1085
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
ff_set_sar
int ff_set_sar(AVCodecContext *avctx, AVRational sar)
Check that the provided sample aspect ratio is valid and set it on the codec context.
Definition: utils.c:109
ff_decode_mastering_display_new
int ff_decode_mastering_display_new(const AVCodecContext *avctx, AVFrame *frame, struct AVMasteringDisplayMetadata **mdm)
Wrapper around av_mastering_display_metadata_create_side_data(), which rejects side data overridden b...
Definition: decode.c:2038
ff_decode_get_packet
int ff_decode_get_packet(AVCodecContext *avctx, AVPacket *pkt)
Called by decoders to get the next packet for decoding.
Definition: decode.c:237
ff_decode_content_light_new
int ff_decode_content_light_new(const AVCodecContext *avctx, AVFrame *frame, struct AVContentLightMetadata **clm)
Wrapper around av_content_light_metadata_create_side_data(), which rejects side data overridden by th...
Definition: decode.c:2083
FrameDecodeData::post_process
int(* post_process)(void *logctx, AVFrame *frame)
The callback to perform some delayed processing on the frame right before it is returned to the calle...
Definition: decode.h:44
size
int size
Definition: twinvq_data.h:10344
frame.h
height
#define height
ff_reget_buffer
int ff_reget_buffer(AVCodecContext *avctx, AVFrame *frame, int flags)
Identical in function to ff_get_buffer(), except it reuses the existing buffer if available.
Definition: decode.c:1684
ff_copy_palette
int ff_copy_palette(void *dst, const AVPacket *src, void *logctx)
Check whether the side-data of src contains a palette of size AVPALETTE_SIZE; if so,...
Definition: decode.c:2096
ff_decode_content_light_new_ext
int ff_decode_content_light_new_ext(const AVCodecContext *avctx, AVFrameSideData ***sd, int *nb_sd, struct AVContentLightMetadata **clm)
Same as ff_decode_content_light_new, but taking a AVFrameSideData array directly instead of an AVFram...
Definition: decode.c:2051
ff_get_coded_side_data
const AVPacketSideData * ff_get_coded_side_data(const AVCodecContext *avctx, enum AVPacketSideDataType type)
Get side data of the given type from a decoding context.
Definition: decode.c:1379
AVMasteringDisplayMetadata
Mastering display metadata capable of representing the color volume of the display used to master the...
Definition: mastering_display_metadata.h:38
avcodec.h
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
AVCodecContext
main external API structure.
Definition: avcodec.h:445
ff_decode_mastering_display_new_ext
int ff_decode_mastering_display_new_ext(const AVCodecContext *avctx, AVFrameSideData ***sd, int *nb_sd, struct AVMasteringDisplayMetadata **mdm)
Same as ff_decode_mastering_display_new, but taking a AVFrameSideData array directly instead of an AV...
Definition: decode.c:2006
ff_frame_new_side_data
int ff_frame_new_side_data(const AVCodecContext *avctx, AVFrame *frame, enum AVFrameSideDataType type, size_t size, AVFrameSideData **sd)
Wrapper around av_frame_new_side_data, which rejects side data overridden by the demuxer.
Definition: decode.c:1959
AVPacketSideDataType
AVPacketSideDataType
Definition: packet.h:41
AVBufferRef
A reference to a data buffer.
Definition: buffer.h:82
AVFrameSideData
Structure to hold side data for an AVFrame.
Definition: frame.h:250
AVPacket
This structure stores compressed data.
Definition: packet.h:501
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
FrameDecodeData::hwaccel_priv
void * hwaccel_priv
Per-frame private data for hwaccels.
Definition: decode.h:51
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:474
hwcontext.h
int
int
Definition: ffmpeg_filter.c:424