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