1 /*
2 * Copyright (c) 2010 The WebM project authors. All Rights Reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
11
12 /*!\file
13 * \brief Describes the decoder algorithm interface for algorithm
14 * implementations.
15 *
16 * This file defines the private structures and data types that are only
17 * relevant to implementing an algorithm, as opposed to using it.
18 *
19 * To create a decoder algorithm class, an interface structure is put
20 * into the global namespace:
21 * <pre>
22 * my_codec.c:
23 * vpx_codec_iface_t my_codec = {
24 * "My Codec v1.0",
25 * VPX_CODEC_ALG_ABI_VERSION,
26 * ...
27 * };
28 * </pre>
29 *
30 * An application instantiates a specific decoder instance by using
31 * vpx_codec_init() and a pointer to the algorithm's interface structure:
32 * <pre>
33 * my_app.c:
34 * extern vpx_codec_iface_t my_codec;
35 * {
36 * vpx_codec_ctx_t algo;
37 * res = vpx_codec_init(&algo, &my_codec);
38 * }
39 * </pre>
40 *
41 * Once initialized, the instance is manged using other functions from
42 * the vpx_codec_* family.
43 */
44 #ifndef VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
45 #define VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
46 #include "../vpx_decoder.h"
47 #include "../vpx_encoder.h"
48 #include <stdarg.h>
49
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53
54 /*!\brief Current ABI version number
55 *
56 * \internal
57 * If this file is altered in any way that changes the ABI, this value
58 * must be bumped. Examples include, but are not limited to, changing
59 * types, removing or reassigning enums, adding/removing/rearranging
60 * fields to structures
61 */
62 #define VPX_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/
63
64 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t;
65 typedef struct vpx_codec_priv_enc_mr_cfg vpx_codec_priv_enc_mr_cfg_t;
66
67 /*!\brief init function pointer prototype
68 *
69 * Performs algorithm-specific initialization of the decoder context. This
70 * function is called by the generic vpx_codec_init() wrapper function, so
71 * plugins implementing this interface may trust the input parameters to be
72 * properly initialized.
73 *
74 * \param[in] ctx Pointer to this instance's context
75 * \retval #VPX_CODEC_OK
76 * The input stream was recognized and decoder initialized.
77 * \retval #VPX_CODEC_MEM_ERROR
78 * Memory operation failed.
79 */
80 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx,
81 vpx_codec_priv_enc_mr_cfg_t *data);
82
83 /*!\brief destroy function pointer prototype
84 *
85 * Performs algorithm-specific destruction of the decoder context. This
86 * function is called by the generic vpx_codec_destroy() wrapper function,
87 * so plugins implementing this interface may trust the input parameters
88 * to be properly initialized.
89 *
90 * \param[in] ctx Pointer to this instance's context
91 * \retval #VPX_CODEC_OK
92 * The input stream was recognized and decoder initialized.
93 * \retval #VPX_CODEC_MEM_ERROR
94 * Memory operation failed.
95 */
96 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx);
97
98 /*!\brief parse stream info function pointer prototype
99 *
100 * Performs high level parsing of the bitstream. This function is called by the
101 * generic vpx_codec_peek_stream_info() wrapper function, so plugins
102 * implementing this interface may trust the input parameters to be properly
103 * initialized.
104 *
105 * \param[in] data Pointer to a block of data to parse
106 * \param[in] data_sz Size of the data buffer
107 * \param[in,out] si Pointer to stream info to update. The size member
108 * \ref MUST be properly initialized, but \ref MAY be
109 * clobbered by the algorithm. This parameter \ref MAY
110 * be NULL.
111 *
112 * \retval #VPX_CODEC_OK
113 * Bitstream is parsable and stream information updated
114 */
115 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data,
116 unsigned int data_sz,
117 vpx_codec_stream_info_t *si);
118
119 /*!\brief Return information about the current stream.
120 *
121 * Returns information about the stream that has been parsed during decoding.
122 *
123 * \param[in] ctx Pointer to this instance's context
124 * \param[in,out] si Pointer to stream info to update. The size member
125 * \ref MUST be properly initialized, but \ref MAY be
126 * clobbered by the algorithm. This parameter \ref MAY
127 * be NULL.
128 *
129 * \retval #VPX_CODEC_OK
130 * Bitstream is parsable and stream information updated
131 */
132 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx,
133 vpx_codec_stream_info_t *si);
134
135 /*!\brief control function pointer prototype
136 *
137 * This function is used to exchange algorithm specific data with the decoder
138 * instance. This can be used to implement features specific to a particular
139 * algorithm.
140 *
141 * This function is called by the generic vpx_codec_control() wrapper
142 * function, so plugins implementing this interface may trust the input
143 * parameters to be properly initialized. However, this interface does not
144 * provide type safety for the exchanged data or assign meanings to the
145 * control codes. Those details should be specified in the algorithm's
146 * header file. In particular, the ctrl_id parameter is guaranteed to exist
147 * in the algorithm's control mapping table, and the data parameter may be NULL.
148 *
149 *
150 * \param[in] ctx Pointer to this instance's context
151 * \param[in] ctrl_id Algorithm specific control identifier
152 * \param[in,out] data Data to exchange with algorithm instance.
153 *
154 * \retval #VPX_CODEC_OK
155 * The internal state data was deserialized.
156 */
157 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx,
158 int ctrl_id,
159 va_list ap);
160
161 /*!\brief control function pointer mapping
162 *
163 * This structure stores the mapping between control identifiers and
164 * implementing functions. Each algorithm provides a list of these
165 * mappings. This list is searched by the vpx_codec_control() wrapper
166 * function to determine which function to invoke. The special
167 * value {0, NULL} is used to indicate end-of-list, and must be
168 * present. The special value {0, <non-null>} can be used as a catch-all
169 * mapping. This implies that ctrl_id values chosen by the algorithm
170 * \ref MUST be non-zero.
171 */
172 typedef const struct vpx_codec_ctrl_fn_map {
173 int ctrl_id;
174 vpx_codec_control_fn_t fn;
175 } vpx_codec_ctrl_fn_map_t;
176
177 /*!\brief decode data function pointer prototype
178 *
179 * Processes a buffer of coded data. If the processing results in a new
180 * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and
181 * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This
182 * function is called by the generic vpx_codec_decode() wrapper function,
183 * so plugins implementing this interface may trust the input parameters
184 * to be properly initialized.
185 *
186 * \param[in] ctx Pointer to this instance's context
187 * \param[in] data Pointer to this block of new coded data. If
188 * NULL, a #VPX_CODEC_CB_PUT_FRAME event is posted
189 * for the previously decoded frame.
190 * \param[in] data_sz Size of the coded data, in bytes.
191 *
192 * \return Returns #VPX_CODEC_OK if the coded data was processed completely
193 * and future pictures can be decoded without error. Otherwise,
194 * see the descriptions of the other error codes in ::vpx_codec_err_t
195 * for recoverability capabilities.
196 */
197 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t *ctx,
198 const uint8_t *data,
199 unsigned int data_sz,
200 void *user_priv,
201 long deadline);
202
203 /*!\brief Decoded frames iterator
204 *
205 * Iterates over a list of the frames available for display. The iterator
206 * storage should be initialized to NULL to start the iteration. Iteration is
207 * complete when this function returns NULL.
208 *
209 * The list of available frames becomes valid upon completion of the
210 * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
211 *
212 * \param[in] ctx Pointer to this instance's context
213 * \param[in out] iter Iterator storage, initialized to NULL
214 *
215 * \return Returns a pointer to an image, if one is ready for display. Frames
216 * produced will always be in PTS (presentation time stamp) order.
217 */
218 typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx,
219 vpx_codec_iter_t *iter);
220
221 /*!\brief Pass in external frame buffers for the decoder to use.
222 *
223 * Registers functions to be called when libvpx needs a frame buffer
224 * to decode the current frame and a function to be called when libvpx does
225 * not internally reference the frame buffer. This set function must
226 * be called before the first call to decode or libvpx will assume the
227 * default behavior of allocating frame buffers internally.
228 *
229 * \param[in] ctx Pointer to this instance's context
230 * \param[in] cb_get Pointer to the get callback function
231 * \param[in] cb_release Pointer to the release callback function
232 * \param[in] cb_priv Callback's private data
233 *
234 * \retval #VPX_CODEC_OK
235 * External frame buffers will be used by libvpx.
236 * \retval #VPX_CODEC_INVALID_PARAM
237 * One or more of the callbacks were NULL.
238 * \retval #VPX_CODEC_ERROR
239 * Decoder context not initialized, or algorithm not capable of
240 * using external frame buffers.
241 *
242 * \note
243 * When decoding VP9, the application may be required to pass in at least
244 * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame
245 * buffers.
246 */
247 typedef vpx_codec_err_t (*vpx_codec_set_fb_fn_t)(
248 vpx_codec_alg_priv_t *ctx,
249 vpx_get_frame_buffer_cb_fn_t cb_get,
250 vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
251
252 /*\brief eXternal Memory Allocation memory map get iterator
253 *
254 * Iterates over a list of the memory maps requested by the decoder. The
255 * iterator storage should be initialized to NULL to start the iteration.
256 * Iteration is complete when this function returns NULL.
257 *
258 * \param[in out] iter Iterator storage, initialized to NULL
259 *
260 * \return Returns a pointer to an memory segment descriptor, or NULL to
261 * indicate end-of-list.
262 */
263 typedef vpx_codec_err_t (*vpx_codec_get_mmap_fn_t)(const vpx_codec_ctx_t *ctx,
264 vpx_codec_mmap_t *mmap,
265 vpx_codec_iter_t *iter);
266
267
268 /*\brief eXternal Memory Allocation memory map set iterator
269 *
270 * Sets a memory descriptor inside the decoder instance.
271 *
272 * \param[in] ctx Pointer to this instance's context
273 * \param[in] mmap Memory map to store.
274 *
275 * \retval #VPX_CODEC_OK
276 * The memory map was accepted and stored.
277 * \retval #VPX_CODEC_MEM_ERROR
278 * The memory map was rejected.
279 */
280 typedef vpx_codec_err_t (*vpx_codec_set_mmap_fn_t)(vpx_codec_ctx_t *ctx,
281 const vpx_codec_mmap_t *mmap);
282
283
284 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx,
285 const vpx_image_t *img,
286 vpx_codec_pts_t pts,
287 unsigned long duration,
288 vpx_enc_frame_flags_t flags,
289 unsigned long deadline);
290 typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx,
291 vpx_codec_iter_t *iter);
292
293 typedef vpx_codec_err_t
294 (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t *ctx,
295 const vpx_codec_enc_cfg_t *cfg);
296 typedef vpx_fixed_buf_t *
297 (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t *ctx);
298
299 typedef vpx_image_t *
300 (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t *ctx);
301
302 typedef vpx_codec_err_t
303 (*vpx_codec_enc_mr_get_mem_loc_fn_t)(const vpx_codec_enc_cfg_t *cfg,
304 void **mem_loc);
305
306 /*!\brief usage configuration mapping
307 *
308 * This structure stores the mapping between usage identifiers and
309 * configuration structures. Each algorithm provides a list of these
310 * mappings. This list is searched by the vpx_codec_enc_config_default()
311 * wrapper function to determine which config to return. The special value
312 * {-1, {0}} is used to indicate end-of-list, and must be present. At least
313 * one mapping must be present, in addition to the end-of-list.
314 *
315 */
316 typedef const struct vpx_codec_enc_cfg_map {
317 int usage;
318 vpx_codec_enc_cfg_t cfg;
319 } vpx_codec_enc_cfg_map_t;
320
321 #define NOT_IMPLEMENTED 0
322
323 /*!\brief Decoder algorithm interface interface
324 *
325 * All decoders \ref MUST expose a variable of this type.
326 */
327 struct vpx_codec_iface {
328 const char *name; /**< Identification String */
329 int abi_version; /**< Implemented ABI version */
330 vpx_codec_caps_t caps; /**< Decoder capabilities */
331 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */
332 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */
333 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */
334 vpx_codec_get_mmap_fn_t get_mmap; /**< \copydoc ::vpx_codec_get_mmap_fn_t */
335 vpx_codec_set_mmap_fn_t set_mmap; /**< \copydoc ::vpx_codec_set_mmap_fn_t */
336 struct vpx_codec_dec_iface {
337 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */
338 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_get_si_fn_t */
339 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */
340 vpx_codec_get_frame_fn_t get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */
341 vpx_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::vpx_codec_set_fb_fn_t */
342 } dec;
343 struct vpx_codec_enc_iface {
344 vpx_codec_enc_cfg_map_t *cfg_maps; /**< \copydoc ::vpx_codec_enc_cfg_map_t */
345 vpx_codec_encode_fn_t encode; /**< \copydoc ::vpx_codec_encode_fn_t */
346 vpx_codec_get_cx_data_fn_t get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */
347 vpx_codec_enc_config_set_fn_t cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */
348 vpx_codec_get_global_headers_fn_t get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */
349 vpx_codec_get_preview_frame_fn_t get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */
350 vpx_codec_enc_mr_get_mem_loc_fn_t mr_get_mem_loc; /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */
351 } enc;
352 };
353
354 /*!\brief Callback function pointer / user data pair storage */
355 typedef struct vpx_codec_priv_cb_pair {
356 union {
357 vpx_codec_put_frame_cb_fn_t put_frame;
358 vpx_codec_put_slice_cb_fn_t put_slice;
359 } u;
360 void *user_priv;
361 } vpx_codec_priv_cb_pair_t;
362
363
364 /*!\brief Instance private storage
365 *
366 * This structure is allocated by the algorithm's init function. It can be
367 * extended in one of two ways. First, a second, algorithm specific structure
368 * can be allocated and the priv member pointed to it. Alternatively, this
369 * structure can be made the first member of the algorithm specific structure,
370 * and the pointer cast to the proper type.
371 */
372 struct vpx_codec_priv {
373 unsigned int sz;
374 vpx_codec_iface_t *iface;
375 struct vpx_codec_alg_priv *alg_priv;
376 const char *err_detail;
377 vpx_codec_flags_t init_flags;
378 struct {
379 vpx_codec_priv_cb_pair_t put_frame_cb;
380 vpx_codec_priv_cb_pair_t put_slice_cb;
381 } dec;
382 struct {
383 int tbd;
384 struct vpx_fixed_buf cx_data_dst_buf;
385 unsigned int cx_data_pad_before;
386 unsigned int cx_data_pad_after;
387 vpx_codec_cx_pkt_t cx_data_pkt;
388 unsigned int total_encoders;
389 } enc;
390 };
391
392 /*
393 * Multi-resolution encoding internal configuration
394 */
395 struct vpx_codec_priv_enc_mr_cfg
396 {
397 unsigned int mr_total_resolutions;
398 unsigned int mr_encoder_id;
399 struct vpx_rational mr_down_sampling_factor;
400 void* mr_low_res_mode_info;
401 };
402
403 #undef VPX_CTRL_USE_TYPE
404 #define VPX_CTRL_USE_TYPE(id, typ) \
405 static typ id##__value(va_list args) {return va_arg(args, typ);} \
406 static typ id##__convert(void *x)\
407 {\
408 union\
409 {\
410 void *x;\
411 typ d;\
412 } u;\
413 u.x = x;\
414 return u.d;\
415 }
416
417
418 #undef VPX_CTRL_USE_TYPE_DEPRECATED
419 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
420 static typ id##__value(va_list args) {return va_arg(args, typ);} \
421 static typ id##__convert(void *x)\
422 {\
423 union\
424 {\
425 void *x;\
426 typ d;\
427 } u;\
428 u.x = x;\
429 return u.d;\
430 }
431
432 #define CAST(id, arg) id##__value(arg)
433 #define RECAST(id, x) id##__convert(x)
434
435
436 /* CODEC_INTERFACE convenience macro
437 *
438 * By convention, each codec interface is a struct with extern linkage, where
439 * the symbol is suffixed with _algo. A getter function is also defined to
440 * return a pointer to the struct, since in some cases it's easier to work
441 * with text symbols than data symbols (see issue #169). This function has
442 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
443 * macro is provided to define this getter function automatically.
444 */
445 #define CODEC_INTERFACE(id)\
446 vpx_codec_iface_t* id(void) { return &id##_algo; }\
447 vpx_codec_iface_t id##_algo
448
449
450 /* Internal Utility Functions
451 *
452 * The following functions are intended to be used inside algorithms as
453 * utilities for manipulating vpx_codec_* data structures.
454 */
455 struct vpx_codec_pkt_list {
456 unsigned int cnt;
457 unsigned int max;
458 struct vpx_codec_cx_pkt pkts[1];
459 };
460
461 #define vpx_codec_pkt_list_decl(n)\
462 union {struct vpx_codec_pkt_list head;\
463 struct {struct vpx_codec_pkt_list head;\
464 struct vpx_codec_cx_pkt pkts[n];} alloc;}
465
466 #define vpx_codec_pkt_list_init(m)\
467 (m)->alloc.head.cnt = 0,\
468 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
469
470 int
471 vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *,
472 const struct vpx_codec_cx_pkt *);
473
474 const vpx_codec_cx_pkt_t *
475 vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list,
476 vpx_codec_iter_t *iter);
477
478
479 #include <stdio.h>
480 #include <setjmp.h>
481
482 struct vpx_internal_error_info {
483 vpx_codec_err_t error_code;
484 int has_detail;
485 char detail[80];
486 int setjmp;
487 jmp_buf jmp;
488 };
489
vpx_internal_error(struct vpx_internal_error_info * info,vpx_codec_err_t error,const char * fmt,...)490 static void vpx_internal_error(struct vpx_internal_error_info *info,
491 vpx_codec_err_t error,
492 const char *fmt,
493 ...) {
494 va_list ap;
495
496 info->error_code = error;
497 info->has_detail = 0;
498
499 if (fmt) {
500 size_t sz = sizeof(info->detail);
501
502 info->has_detail = 1;
503 va_start(ap, fmt);
504 vsnprintf(info->detail, sz - 1, fmt, ap);
505 va_end(ap);
506 info->detail[sz - 1] = '\0';
507 }
508
509 if (info->setjmp)
510 longjmp(info->jmp, info->error_code);
511 }
512
513 //------------------------------------------------------------------------------
514 // mmap interface
515
516 typedef struct {
517 unsigned int id;
518 unsigned long sz;
519 unsigned int align;
520 unsigned int flags;
521 unsigned long (*calc_sz)(const vpx_codec_dec_cfg_t *, vpx_codec_flags_t);
522 } mem_req_t;
523
524 // Allocates mmap.priv and sets mmap.base based on mmap.sz/align/flags
525 // requirements.
526 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise.
527 vpx_codec_err_t vpx_mmap_alloc(vpx_codec_mmap_t *mmap);
528
529 // Frees mmap.base allocated by a call to vpx_mmap_alloc().
530 void vpx_mmap_dtor(vpx_codec_mmap_t *mmap);
531
532 // Checks each mmap has the size requirement specificied by mem_reqs.
533 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise.
534 vpx_codec_err_t vpx_validate_mmaps(const vpx_codec_stream_info_t *si,
535 const vpx_codec_mmap_t *mmaps,
536 const mem_req_t *mem_reqs, int nreqs,
537 vpx_codec_flags_t init_flags);
538 #ifdef __cplusplus
539 } // extern "C"
540 #endif
541
542 #endif // VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
543