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:2273
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:187
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
FFCodecDefault::key
const char * key
Definition: codec_internal.h:98
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:340
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
FFCodec::cb
union FFCodec::@63 cb
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
frame
static AVFrame * frame
Definition: demux_decode.c:54
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::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:25
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
AVCodecContext
main external API structure.
Definition: avcodec.h:445
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:499
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:424