decode.h (8605B)
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); 45 void *post_process_opaque; 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); 53 } FrameDecodeData; 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 */ 64 int ff_decode_get_packet(AVCodecContext *avctx, AVPacket *pkt); 65 66 /** 67 * Set various frame properties from the provided packet. 68 */ 69 int ff_decode_frame_props_from_pkt(const AVCodecContext *avctx, 70 AVFrame *frame, const AVPacket *pkt); 71 72 /** 73 * Set various frame properties from the codec context / packet data. 74 */ 75 int ff_decode_frame_props(AVCodecContext *avctx, AVFrame *frame); 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 */ 82 int ff_decode_get_hw_frames_ctx(AVCodecContext *avctx, 83 enum AVHWDeviceType dev_type); 84 85 int ff_attach_decode_data(AVFrame *frame); 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 */ 100 int ff_set_dimensions(AVCodecContext *s, int width, int height); 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 */ 133 int ff_reget_buffer(AVCodecContext *avctx, AVFrame *frame, int flags); 134 135 /** 136 * Add or update AV_FRAME_DATA_MATRIXENCODING side data. 137 */ 138 int ff_side_data_update_matrix_encoding(AVFrame *frame, 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 */ 155 const AVPacketSideData *ff_get_coded_side_data(const AVCodecContext *avctx, 156 enum AVPacketSideDataType type); 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 */ 164 int ff_frame_new_side_data(const AVCodecContext *avctx, AVFrame *frame, 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 */ 174 int ff_frame_new_side_data_from_buf(const AVCodecContext *avctx, 175 AVFrame *frame, enum AVFrameSideDataType type, 176 AVBufferRef **buf); 177 178 /** 179 * Same as `ff_frame_new_side_data_from_buf`, but taking a AVFrameSideData 180 * array directly instead of an AVFrame. 181 */ 182 int ff_frame_new_side_data_from_buf_ext(const AVCodecContext *avctx, 183 AVFrameSideData ***sd, int *nb_sd, 184 enum AVFrameSideDataType type, 185 AVBufferRef **buf); 186 187 struct AVMasteringDisplayMetadata; 188 struct AVContentLightMetadata; 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 */ 196 int ff_decode_mastering_display_new(const AVCodecContext *avctx, AVFrame *frame, 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 */ 203 int ff_decode_mastering_display_new_ext(const AVCodecContext *avctx, 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 */ 213 int ff_decode_content_light_new(const AVCodecContext *avctx, AVFrame *frame, 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 */ 220 int ff_decode_content_light_new_ext(const AVCodecContext *avctx, 221 AVFrameSideData ***sd, int *nb_sd, 222 struct AVContentLightMetadata **clm); 223 #endif /* AVCODEC_DECODE_H */