FFmpeg
codec_internal.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVCODEC_CODEC_INTERNAL_H
20 #define AVCODEC_CODEC_INTERNAL_H
21 
22 #include <stdint.h>
23 
24 #include "libavutil/attributes.h"
25 #include "codec.h"
26 #include "config.h"
27 
28 /**
29  * The codec is not known to be init-threadsafe (i.e. it might be unsafe
30  * to initialize this codec and another codec concurrently, typically because
31  * the codec calls external APIs that are not known to be thread-safe).
32  * Therefore calling the codec's init function needs to be guarded with a lock.
33  */
34 #define FF_CODEC_CAP_NOT_INIT_THREADSAFE (1 << 0)
35 /**
36  * The codec allows calling the close function for deallocation even if
37  * the init function returned a failure. Without this capability flag, a
38  * codec does such cleanup internally when returning failures from the
39  * init function and does not expect the close function to be called at
40  * all.
41  */
42 #define FF_CODEC_CAP_INIT_CLEANUP (1 << 1)
43 /**
44  * Decoders marked with FF_CODEC_CAP_SETS_PKT_DTS want to set
45  * AVFrame.pkt_dts manually. If the flag is set, decode.c won't overwrite
46  * this field. If it's unset, decode.c tries to guess the pkt_dts field
47  * from the input AVPacket.
48  */
49 #define FF_CODEC_CAP_SETS_PKT_DTS (1 << 2)
50 /**
51  * The decoder extracts and fills its parameters even if the frame is
52  * skipped due to the skip_frame setting.
53  */
54 #define FF_CODEC_CAP_SKIP_FRAME_FILL_PARAM (1 << 3)
55 /**
56  * The decoder sets the cropping fields in the output frames manually.
57  * If this cap is set, the generic code will initialize output frame
58  * dimensions to coded rather than display values.
59  */
60 #define FF_CODEC_CAP_EXPORTS_CROPPING (1 << 4)
61 /**
62  * Codec initializes slice-based threading with a main function
63  */
64 #define FF_CODEC_CAP_SLICE_THREAD_HAS_MF (1 << 5)
65 /*
66  * The codec supports frame threading and has inter-frame dependencies, so it
67  * uses ff_thread_report/await_progress().
68  */
69 #define FF_CODEC_CAP_ALLOCATE_PROGRESS (1 << 6)
70 /**
71  * Codec handles avctx->thread_count == 0 (auto) internally.
72  */
73 #define FF_CODEC_CAP_AUTO_THREADS (1 << 7)
74 /**
75  * Codec handles output frame properties internally instead of letting the
76  * internal logic derive them from AVCodecInternal.last_pkt_props.
77  */
78 #define FF_CODEC_CAP_SETS_FRAME_PROPS (1 << 8)
79 /**
80  * Codec supports embedded ICC profiles (AV_FRAME_DATA_ICC_PROFILE).
81  */
82 #define FF_CODEC_CAP_ICC_PROFILES (1 << 9)
83 /**
84  * The encoder has AV_CODEC_CAP_DELAY set, but does not actually have delay - it
85  * only wants to be flushed at the end to update some context variables (e.g.
86  * 2pass stats) or produce a trailing packet. Besides that it immediately
87  * produces exactly one output packet per each input frame, just as no-delay
88  * encoders do.
89  */
90 #define FF_CODEC_CAP_EOF_FLUSH (1 << 10)
91 
92 /**
93  * FFCodec.codec_tags termination value
94  */
95 #define FF_CODEC_TAGS_END -1
96 
97 typedef struct FFCodecDefault {
98  const char *key;
99  const char *value;
101 
102 struct AVCodecContext;
103 struct AVSubtitle;
104 struct AVPacket;
105 
107  /* The codec is a decoder using the decode callback;
108  * audio and video codecs only. */
110  /* The codec is a decoder using the decode_sub callback;
111  * subtitle codecs only. */
113  /* The codec is a decoder using the receive_frame callback;
114  * audio and video codecs only. */
116  /* The codec is an encoder using the encode callback;
117  * audio and video codecs only. */
119  /* The codec is an encoder using the encode_sub callback;
120  * subtitle codecs only. */
122  /* The codec is an encoder using the receive_packet callback;
123  * audio and video codecs only. */
125 };
126 
127 typedef struct FFCodec {
128  /**
129  * The public AVCodec. See codec.h for it.
130  */
132 
133  /**
134  * Internal codec capabilities FF_CODEC_CAP_*.
135  */
136  unsigned caps_internal:29;
137 
138  /**
139  * This field determines the type of the codec (decoder/encoder)
140  * and also the exact callback cb implemented by the codec.
141  * cb_type uses enum FFCodecType values.
142  */
143  unsigned cb_type:3;
144 
146  /**
147  * @name Frame-level threading support functions
148  * @{
149  */
150  /**
151  * Copy necessary context variables from a previous thread context to the current one.
152  * If not defined, the next thread will start automatically; otherwise, the codec
153  * must call ff_thread_finish_setup().
154  *
155  * dst and src will (rarely) point to the same context, in which case memcpy should be skipped.
156  */
158 
159  /**
160  * Copy variables back to the user-facing context
161  */
163  /** @} */
164 
165  /**
166  * Private codec-specific defaults.
167  */
169 
170  /**
171  * Initialize codec static data, called from av_codec_iterate().
172  *
173  * This is not intended for time consuming operations as it is
174  * run for every codec regardless of that codec being used.
175  */
176  void (*init_static_data)(struct FFCodec *codec);
177 
178  int (*init)(struct AVCodecContext *);
179 
180  union {
181  /**
182  * Decode to an AVFrame.
183  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_DECODE.
184  *
185  * @param avctx codec context
186  * @param[out] frame AVFrame for output
187  * @param[out] got_frame_ptr decoder sets to 0 or 1 to indicate that
188  * a non-empty frame was returned in frame.
189  * @param[in] avpkt AVPacket containing the data to be decoded
190  * @return amount of bytes read from the packet on success,
191  * negative error code on failure
192  */
193  int (*decode)(struct AVCodecContext *avctx, struct AVFrame *frame,
194  int *got_frame_ptr, struct AVPacket *avpkt);
195  /**
196  * Decode subtitle data to an AVSubtitle.
197  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_DECODE_SUB.
198  *
199  * Apart from that this is like the decode callback.
200  */
201  int (*decode_sub)(struct AVCodecContext *avctx, struct AVSubtitle *sub,
202  int *got_frame_ptr, const struct AVPacket *avpkt);
203  /**
204  * Decode API with decoupled packet/frame dataflow.
205  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_RECEIVE_FRAME.
206  *
207  * This function is called to get one output frame. It should call
208  * ff_decode_get_packet() to obtain input data.
209  */
210  int (*receive_frame)(struct AVCodecContext *avctx, struct AVFrame *frame);
211  /**
212  * Encode data to an AVPacket.
213  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_ENCODE
214  *
215  * @param avctx codec context
216  * @param[out] avpkt output AVPacket
217  * @param[in] frame AVFrame containing the input to be encoded
218  * @param[out] got_packet_ptr encoder sets to 0 or 1 to indicate that a
219  * non-empty packet was returned in avpkt.
220  * @return 0 on success, negative error code on failure
221  */
222  int (*encode)(struct AVCodecContext *avctx, struct AVPacket *avpkt,
223  const struct AVFrame *frame, int *got_packet_ptr);
224  /**
225  * Encode subtitles to a raw buffer.
226  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_ENCODE_SUB.
227  */
228  int (*encode_sub)(struct AVCodecContext *avctx, uint8_t *buf,
229  int buf_size, const struct AVSubtitle *sub);
230  /**
231  * Encode API with decoupled frame/packet dataflow.
232  * cb is in this state if cb_type is FF_CODEC_CB_TYPE_RECEIVE_PACKET.
233  *
234  * This function is called to get one output packet.
235  * It should call ff_encode_get_frame() to obtain input data.
236  */
237  int (*receive_packet)(struct AVCodecContext *avctx, struct AVPacket *avpkt);
238  } cb;
239 
240  int (*close)(struct AVCodecContext *);
241 
242  /**
243  * Flush buffers.
244  * Will be called when seeking
245  */
246  void (*flush)(struct AVCodecContext *);
247 
248  /**
249  * Decoding only, a comma-separated list of bitstream filters to apply to
250  * packets before decoding.
251  */
252  const char *bsfs;
253 
254  /**
255  * Array of pointers to hardware configurations supported by the codec,
256  * or NULL if no hardware supported. The array is terminated by a NULL
257  * pointer.
258  *
259  * The user can only access this field via avcodec_get_hw_config().
260  */
261  const struct AVCodecHWConfigInternal *const *hw_configs;
262 
263  /**
264  * List of supported codec_tags, terminated by FF_CODEC_TAGS_END.
265  */
266  const uint32_t *codec_tags;
267 } FFCodec;
268 
269 #if CONFIG_SMALL
270 #define CODEC_LONG_NAME(str) .p.long_name = NULL
271 #else
272 #define CODEC_LONG_NAME(str) .p.long_name = str
273 #endif
274 
275 #if HAVE_THREADS
276 #define UPDATE_THREAD_CONTEXT(func) \
277  .update_thread_context = (func)
278 #define UPDATE_THREAD_CONTEXT_FOR_USER(func) \
279  .update_thread_context_for_user = (func)
280 #else
281 #define UPDATE_THREAD_CONTEXT(func) \
282  .update_thread_context = NULL
283 #define UPDATE_THREAD_CONTEXT_FOR_USER(func) \
284  .update_thread_context_for_user = NULL
285 #endif
286 
287 #if FF_API_OLD_CHANNEL_LAYOUT
288 #define CODEC_OLD_CHANNEL_LAYOUTS(...) CODEC_OLD_CHANNEL_LAYOUTS_ARRAY(((const uint64_t[]) { __VA_ARGS__, 0 }))
289 #if defined(__clang__)
290 #define CODEC_OLD_CHANNEL_LAYOUTS_ARRAY(array) \
291  FF_DISABLE_DEPRECATION_WARNINGS \
292  .p.channel_layouts = (array), \
293  FF_ENABLE_DEPRECATION_WARNINGS
294 #else
295 #define CODEC_OLD_CHANNEL_LAYOUTS_ARRAY(array) .p.channel_layouts = (array),
296 #endif
297 #else
298 /* This is only provided to allow to test disabling FF_API_OLD_CHANNEL_LAYOUT
299  * without removing all the FF_API_OLD_CHANNEL_LAYOUT codeblocks.
300  * It is of course still expected to be removed when FF_API_OLD_CHANNEL_LAYOUT
301  * will be finally removed (along with all usages of these macros). */
302 #define CODEC_OLD_CHANNEL_LAYOUTS(...)
303 #define CODEC_OLD_CHANNEL_LAYOUTS_ARRAY(array)
304 #endif
305 
306 #define FF_CODEC_DECODE_CB(func) \
307  .cb_type = FF_CODEC_CB_TYPE_DECODE, \
308  .cb.decode = (func)
309 #define FF_CODEC_DECODE_SUB_CB(func) \
310  .cb_type = FF_CODEC_CB_TYPE_DECODE_SUB, \
311  .cb.decode_sub = (func)
312 #define FF_CODEC_RECEIVE_FRAME_CB(func) \
313  .cb_type = FF_CODEC_CB_TYPE_RECEIVE_FRAME, \
314  .cb.receive_frame = (func)
315 #define FF_CODEC_ENCODE_CB(func) \
316  .cb_type = FF_CODEC_CB_TYPE_ENCODE, \
317  .cb.encode = (func)
318 #define FF_CODEC_ENCODE_SUB_CB(func) \
319  .cb_type = FF_CODEC_CB_TYPE_ENCODE_SUB, \
320  .cb.encode_sub = (func)
321 #define FF_CODEC_RECEIVE_PACKET_CB(func) \
322  .cb_type = FF_CODEC_CB_TYPE_RECEIVE_PACKET, \
323  .cb.receive_packet = (func)
324 
325 static av_always_inline const FFCodec *ffcodec(const AVCodec *codec)
326 {
327  return (const FFCodec*)codec;
328 }
329 
330 #endif /* AVCODEC_CODEC_INTERNAL_H */
AVSubtitle
Definition: avcodec.h:2330
FFCodec::update_thread_context
int(* update_thread_context)(struct AVCodecContext *dst, const struct AVCodecContext *src)
Copy necessary context variables from a previous thread context to the current one.
Definition: codec_internal.h:157
AVCodec
AVCodec.
Definition: codec.h:184
FFCodec::receive_frame
int(* receive_frame)(struct AVCodecContext *avctx, struct AVFrame *frame)
Decode API with decoupled packet/frame dataflow.
Definition: codec_internal.h:210
FFCodec::defaults
const FFCodecDefault * defaults
Private codec-specific defaults.
Definition: codec_internal.h:168
FF_CODEC_CB_TYPE_RECEIVE_PACKET
@ FF_CODEC_CB_TYPE_RECEIVE_PACKET
Definition: codec_internal.h:124
sub
static float sub(float src0, float src1)
Definition: dnn_backend_native_layer_mathbinary.c:31
FFCodecDefault::key
const char * key
Definition: codec_internal.h:98
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:330
FFCodec
Definition: codec_internal.h:127
FFCodec::encode
int(* encode)(struct AVCodecContext *avctx, struct AVPacket *avpkt, const struct AVFrame *frame, int *got_packet_ptr)
Encode data to an AVPacket.
Definition: codec_internal.h:222
FF_CODEC_CB_TYPE_ENCODE_SUB
@ FF_CODEC_CB_TYPE_ENCODE_SUB
Definition: codec_internal.h:121
FFCodec::priv_data_size
int priv_data_size
Definition: codec_internal.h:145
FFCodecDefault
Definition: codec_internal.h:97
FFCodec::p
AVCodec p
The public AVCodec.
Definition: codec_internal.h:131
codec.h
FF_CODEC_CB_TYPE_DECODE
@ FF_CODEC_CB_TYPE_DECODE
Definition: codec_internal.h:109
FFCodec::update_thread_context_for_user
int(* update_thread_context_for_user)(struct AVCodecContext *dst, const struct AVCodecContext *src)
Copy variables back to the user-facing context.
Definition: codec_internal.h:162
FF_CODEC_CB_TYPE_ENCODE
@ FF_CODEC_CB_TYPE_ENCODE
Definition: codec_internal.h:118
FFCodec::flush
void(* flush)(struct AVCodecContext *)
Flush buffers.
Definition: codec_internal.h:246
FFCodec::encode_sub
int(* encode_sub)(struct AVCodecContext *avctx, uint8_t *buf, int buf_size, const struct AVSubtitle *sub)
Encode subtitles to a raw buffer.
Definition: codec_internal.h:228
FFCodec::decode
int(* decode)(struct AVCodecContext *avctx, struct AVFrame *frame, int *got_frame_ptr, struct AVPacket *avpkt)
Decode to an AVFrame.
Definition: codec_internal.h:193
FFCodec::init
int(* init)(struct AVCodecContext *)
Definition: codec_internal.h:178
FF_CODEC_CB_TYPE_DECODE_SUB
@ FF_CODEC_CB_TYPE_DECODE_SUB
Definition: codec_internal.h:112
FFCodec::cb
union FFCodec::@50 cb
FFCodec::receive_packet
int(* receive_packet)(struct AVCodecContext *avctx, struct AVPacket *avpkt)
Encode API with decoupled frame/packet dataflow.
Definition: codec_internal.h:237
ffcodec
static const av_always_inline FFCodec * ffcodec(const AVCodec *codec)
Definition: codec_internal.h:325
AVCodecHWConfigInternal
Definition: hwconfig.h:29
attributes.h
FFCodec::hw_configs
const struct AVCodecHWConfigInternal *const * hw_configs
Array of pointers to hardware configurations supported by the codec, or NULL if no hardware supported...
Definition: codec_internal.h:261
FFCodec::caps_internal
unsigned caps_internal
Internal codec capabilities FF_CODEC_CAP_*.
Definition: codec_internal.h:136
FFCodecDefault::value
const char * value
Definition: codec_internal.h:99
av_always_inline
#define av_always_inline
Definition: attributes.h:49
FFCodec::decode_sub
int(* decode_sub)(struct AVCodecContext *avctx, struct AVSubtitle *sub, int *got_frame_ptr, const struct AVPacket *avpkt)
Decode subtitle data to an AVSubtitle.
Definition: codec_internal.h:201
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:426
FFCodec::codec_tags
const uint32_t * codec_tags
List of supported codec_tags, terminated by FF_CODEC_TAGS_END.
Definition: codec_internal.h:266
FF_CODEC_CB_TYPE_RECEIVE_FRAME
@ FF_CODEC_CB_TYPE_RECEIVE_FRAME
Definition: codec_internal.h:115
FFCodecType
FFCodecType
Definition: codec_internal.h:106
FFCodec::cb_type
unsigned cb_type
This field determines the type of the codec (decoder/encoder) and also the exact callback cb implemen...
Definition: codec_internal.h:143
FFCodec::close
int(* close)(struct AVCodecContext *)
Definition: codec_internal.h:240
FFCodec::bsfs
const char * bsfs
Decoding only, a comma-separated list of bitstream filters to apply to packets before decoding.
Definition: codec_internal.h:252
AVPacket
This structure stores compressed data.
Definition: packet.h:351
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
FFCodec::init_static_data
void(* init_static_data)(struct FFCodec *codec)
Initialize codec static data, called from av_codec_iterate().
Definition: codec_internal.h:176
int
int
Definition: ffmpeg_filter.c:156