• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 /*!\defgroup codec Common Algorithm Interface
12  * This abstraction allows applications to easily support multiple video
13  * formats with minimal code duplication. This section describes the interface
14  * common to all codecs (both encoders and decoders).
15  * @{
16  */
17 
18 /*!\file
19  * \brief Describes the codec algorithm interface to applications.
20  *
21  * This file describes the interface between an application and a
22  * video codec algorithm.
23  *
24  * An application instantiates a specific codec instance by using
25  * vpx_codec_init() and a pointer to the algorithm's interface structure:
26  *     <pre>
27  *     my_app.c:
28  *       extern vpx_codec_iface_t my_codec;
29  *       {
30  *           vpx_codec_ctx_t algo;
31  *           res = vpx_codec_init(&algo, &my_codec);
32  *       }
33  *     </pre>
34  *
35  * Once initialized, the instance is manged using other functions from
36  * the vpx_codec_* family.
37  */
38 #ifndef VPX_VPX_CODEC_H_
39 #define VPX_VPX_CODEC_H_
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 #include "./vpx_image.h"
46 #include "./vpx_integer.h"
47 
48 /*!\brief Decorator indicating a function is deprecated */
49 #ifndef DEPRECATED
50 #if defined(__GNUC__) && __GNUC__
51 #define DEPRECATED __attribute__((deprecated))
52 #elif defined(_MSC_VER)
53 #define DEPRECATED
54 #else
55 #define DEPRECATED
56 #endif
57 #endif /* DEPRECATED */
58 
59 #ifndef DECLSPEC_DEPRECATED
60 #if defined(__GNUC__) && __GNUC__
61 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
62 #elif defined(_MSC_VER)
63 /*!\brief \copydoc #DEPRECATED */
64 #define DECLSPEC_DEPRECATED __declspec(deprecated)
65 #else
66 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
67 #endif
68 #endif /* DECLSPEC_DEPRECATED */
69 
70 /*!\brief Decorator indicating a function is potentially unused */
71 #ifdef UNUSED
72 #elif defined(__GNUC__) || defined(__clang__)
73 #define UNUSED __attribute__((unused))
74 #else
75 #define UNUSED
76 #endif
77 
78 /*!\brief Current ABI version number
79  *
80  * \internal
81  * If this file is altered in any way that changes the ABI, this value
82  * must be bumped.  Examples include, but are not limited to, changing
83  * types, removing or reassigning enums, adding/removing/rearranging
84  * fields to structures
85  */
86 #define VPX_CODEC_ABI_VERSION (4 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
87 
88 /*!\brief Algorithm return codes */
89 typedef enum {
90   /*!\brief Operation completed without error */
91   VPX_CODEC_OK,
92 
93   /*!\brief Unspecified error */
94   VPX_CODEC_ERROR,
95 
96   /*!\brief Memory operation failed */
97   VPX_CODEC_MEM_ERROR,
98 
99   /*!\brief ABI version mismatch */
100   VPX_CODEC_ABI_MISMATCH,
101 
102   /*!\brief Algorithm does not have required capability */
103   VPX_CODEC_INCAPABLE,
104 
105   /*!\brief The given bitstream is not supported.
106    *
107    * The bitstream was unable to be parsed at the highest level. The decoder
108    * is unable to proceed. This error \ref SHOULD be treated as fatal to the
109    * stream. */
110   VPX_CODEC_UNSUP_BITSTREAM,
111 
112   /*!\brief Encoded bitstream uses an unsupported feature
113    *
114    * The decoder does not implement a feature required by the encoder. This
115    * return code should only be used for features that prevent future
116    * pictures from being properly decoded. This error \ref MAY be treated as
117    * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
118    */
119   VPX_CODEC_UNSUP_FEATURE,
120 
121   /*!\brief The coded data for this stream is corrupt or incomplete
122    *
123    * There was a problem decoding the current frame.  This return code
124    * should only be used for failures that prevent future pictures from
125    * being properly decoded. This error \ref MAY be treated as fatal to the
126    * stream or \ref MAY be treated as fatal to the current GOP. If decoding
127    * is continued for the current GOP, artifacts may be present.
128    */
129   VPX_CODEC_CORRUPT_FRAME,
130 
131   /*!\brief An application-supplied parameter is not valid.
132    *
133    */
134   VPX_CODEC_INVALID_PARAM,
135 
136   /*!\brief An iterator reached the end of list.
137    *
138    */
139   VPX_CODEC_LIST_END
140 
141 } vpx_codec_err_t;
142 
143 /*! \brief Codec capabilities bitfield
144  *
145  *  Each codec advertises the capabilities it supports as part of its
146  *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
147  *  or functionality, and are not required to be supported.
148  *
149  *  The available flags are specified by VPX_CODEC_CAP_* defines.
150  */
151 typedef long vpx_codec_caps_t;
152 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
153 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
154 
155 /*! Can support images at greater than 8 bitdepth.
156  */
157 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4
158 
159 /*! \brief Initialization-time Feature Enabling
160  *
161  *  Certain codec features must be known at initialization time, to allow for
162  *  proper memory allocation.
163  *
164  *  The available flags are specified by VPX_CODEC_USE_* defines.
165  */
166 typedef long vpx_codec_flags_t;
167 
168 /*!\brief Codec interface structure.
169  *
170  * Contains function pointers and other data private to the codec
171  * implementation. This structure is opaque to the application.
172  */
173 typedef const struct vpx_codec_iface vpx_codec_iface_t;
174 
175 /*!\brief Codec private data structure.
176  *
177  * Contains data private to the codec implementation. This structure is opaque
178  * to the application.
179  */
180 typedef struct vpx_codec_priv vpx_codec_priv_t;
181 
182 /*!\brief Iterator
183  *
184  * Opaque storage used for iterating over lists.
185  */
186 typedef const void *vpx_codec_iter_t;
187 
188 /*!\brief Codec context structure
189  *
190  * All codecs \ref MUST support this context structure fully. In general,
191  * this data should be considered private to the codec algorithm, and
192  * not be manipulated or examined by the calling application. Applications
193  * may reference the 'name' member to get a printable description of the
194  * algorithm.
195  */
196 typedef struct vpx_codec_ctx {
197   const char *name;             /**< Printable interface name */
198   vpx_codec_iface_t *iface;     /**< Interface pointers */
199   vpx_codec_err_t err;          /**< Last returned error */
200   const char *err_detail;       /**< Detailed info, if available */
201   vpx_codec_flags_t init_flags; /**< Flags passed at init time */
202   union {
203     /**< Decoder Configuration Pointer */
204     const struct vpx_codec_dec_cfg *dec;
205     /**< Encoder Configuration Pointer */
206     const struct vpx_codec_enc_cfg *enc;
207     const void *raw;
208   } config;               /**< Configuration pointer aliasing union */
209   vpx_codec_priv_t *priv; /**< Algorithm private storage */
210 } vpx_codec_ctx_t;
211 
212 /*!\brief Bit depth for codec
213  * *
214  * This enumeration determines the bit depth of the codec.
215  */
216 typedef enum vpx_bit_depth {
217   VPX_BITS_8 = 8,   /**<  8 bits */
218   VPX_BITS_10 = 10, /**< 10 bits */
219   VPX_BITS_12 = 12, /**< 12 bits */
220 } vpx_bit_depth_t;
221 
222 /*
223  * Library Version Number Interface
224  *
225  * For example, see the following sample return values:
226  *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
227  *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
228  *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
229  */
230 
231 /*!\brief Return the version information (as an integer)
232  *
233  * Returns a packed encoding of the library version number. This will only
234  * include
235  * the major.minor.patch component of the version number. Note that this encoded
236  * value should be accessed through the macros provided, as the encoding may
237  * change
238  * in the future.
239  *
240  */
241 int vpx_codec_version(void);
242 #define VPX_VERSION_MAJOR(v) \
243   ((v >> 16) & 0xff) /**< extract major from packed version */
244 #define VPX_VERSION_MINOR(v) \
245   ((v >> 8) & 0xff) /**< extract minor from packed version */
246 #define VPX_VERSION_PATCH(v) \
247   ((v >> 0) & 0xff) /**< extract patch from packed version */
248 
249 /*!\brief Return the version major number */
250 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff)
251 
252 /*!\brief Return the version minor number */
253 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff)
254 
255 /*!\brief Return the version patch number */
256 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff)
257 
258 /*!\brief Return the version information (as a string)
259  *
260  * Returns a printable string containing the full library version number. This
261  * may
262  * contain additional text following the three digit version number, as to
263  * indicate
264  * release candidates, prerelease versions, etc.
265  *
266  */
267 const char *vpx_codec_version_str(void);
268 
269 /*!\brief Return the version information (as a string)
270  *
271  * Returns a printable "extra string". This is the component of the string
272  * returned
273  * by vpx_codec_version_str() following the three digit version number.
274  *
275  */
276 const char *vpx_codec_version_extra_str(void);
277 
278 /*!\brief Return the build configuration
279  *
280  * Returns a printable string containing an encoded version of the build
281  * configuration. This may be useful to vpx support.
282  *
283  */
284 const char *vpx_codec_build_config(void);
285 
286 /*!\brief Return the name for a given interface
287  *
288  * Returns a human readable string for name of the given codec interface.
289  *
290  * \param[in]    iface     Interface pointer
291  *
292  */
293 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
294 
295 /*!\brief Convert error number to printable string
296  *
297  * Returns a human readable string for the last error returned by the
298  * algorithm. The returned error will be one line and will not contain
299  * any newline characters.
300  *
301  *
302  * \param[in]    err     Error number.
303  *
304  */
305 const char *vpx_codec_err_to_string(vpx_codec_err_t err);
306 
307 /*!\brief Retrieve error synopsis for codec context
308  *
309  * Returns a human readable string for the last error returned by the
310  * algorithm. The returned error will be one line and will not contain
311  * any newline characters.
312  *
313  *
314  * \param[in]    ctx     Pointer to this instance's context.
315  *
316  */
317 const char *vpx_codec_error(vpx_codec_ctx_t *ctx);
318 
319 /*!\brief Retrieve detailed error information for codec context
320  *
321  * Returns a human readable string providing detailed information about
322  * the last error.
323  *
324  * \param[in]    ctx     Pointer to this instance's context.
325  *
326  * \retval NULL
327  *     No detailed information is available.
328  */
329 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx);
330 
331 /* REQUIRED FUNCTIONS
332  *
333  * The following functions are required to be implemented for all codecs.
334  * They represent the base case functionality expected of all codecs.
335  */
336 
337 /*!\brief Destroy a codec instance
338  *
339  * Destroys a codec context, freeing any associated memory buffers.
340  *
341  * \param[in] ctx   Pointer to this instance's context
342  *
343  * \retval #VPX_CODEC_OK
344  *     The codec algorithm initialized.
345  * \retval #VPX_CODEC_MEM_ERROR
346  *     Memory allocation failed.
347  */
348 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
349 
350 /*!\brief Get the capabilities of an algorithm.
351  *
352  * Retrieves the capabilities bitfield from the algorithm's interface.
353  *
354  * \param[in] iface   Pointer to the algorithm interface
355  *
356  */
357 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
358 
359 /*!\brief Control algorithm
360  *
361  * This function is used to exchange algorithm specific data with the codec
362  * instance. This can be used to implement features specific to a particular
363  * algorithm.
364  *
365  * This wrapper function dispatches the request to the helper function
366  * associated with the given ctrl_id. It tries to call this function
367  * transparently, but will return #VPX_CODEC_ERROR if the request could not
368  * be dispatched.
369  *
370  * Note that this function should not be used directly. Call the
371  * #vpx_codec_control wrapper macro instead.
372  *
373  * \param[in]     ctx              Pointer to this instance's context
374  * \param[in]     ctrl_id          Algorithm specific control identifier
375  *
376  * \retval #VPX_CODEC_OK
377  *     The control request was processed.
378  * \retval #VPX_CODEC_ERROR
379  *     The control request was not processed.
380  * \retval #VPX_CODEC_INVALID_PARAM
381  *     The data was not valid.
382  */
383 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...);
384 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
385 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data)
386 #define VPX_CTRL_USE_TYPE(id, typ)
387 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
388 #define VPX_CTRL_VOID(id, typ)
389 
390 #else
391 /*!\brief vpx_codec_control wrapper macro
392  *
393  * This macro allows for type safe conversions across the variadic parameter
394  * to vpx_codec_control_().
395  *
396  * \internal
397  * It works by dispatching the call to the control function through a wrapper
398  * function named with the id parameter.
399  */
400 #define vpx_codec_control(ctx, id, data) \
401   vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
402 
403 /*!\brief vpx_codec_control type definition macro
404  *
405  * This macro allows for type safe conversions across the variadic parameter
406  * to vpx_codec_control_(). It defines the type of the argument for a given
407  * control identifier.
408  *
409  * \internal
410  * It defines a static function with
411  * the correctly typed arguments as a wrapper to the type-unsafe internal
412  * function.
413  */
414 #define VPX_CTRL_USE_TYPE(id, typ)                                           \
415   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \
416       UNUSED;                                                                \
417                                                                              \
418   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,        \
419                                                 int ctrl_id, typ data) {     \
420     return vpx_codec_control_(ctx, ctrl_id, data);                           \
421   } /**<\hideinitializer*/
422 
423 /*!\brief vpx_codec_control deprecated type definition macro
424  *
425  * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
426  * deprecated and should not be used. Consult the documentation for your
427  * codec for more information.
428  *
429  * \internal
430  * It defines a static function with the correctly typed arguments as a
431  * wrapper to the type-unsafe internal function.
432  */
433 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)                        \
434   DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
435       vpx_codec_ctx_t *, int, typ) DEPRECATED UNUSED;                \
436                                                                      \
437   DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
438       vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {                 \
439     return vpx_codec_control_(ctx, ctrl_id, data);                   \
440   } /**<\hideinitializer*/
441 
442 /*!\brief vpx_codec_control void type definition macro
443  *
444  * This macro allows for type safe conversions across the variadic parameter
445  * to vpx_codec_control_(). It indicates that a given control identifier takes
446  * no argument.
447  *
448  * \internal
449  * It defines a static function without a data argument as a wrapper to the
450  * type-unsafe internal function.
451  */
452 #define VPX_CTRL_VOID(id)                                               \
453   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \
454       UNUSED;                                                           \
455                                                                         \
456   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,   \
457                                                 int ctrl_id) {          \
458     return vpx_codec_control_(ctx, ctrl_id);                            \
459   } /**<\hideinitializer*/
460 
461 #endif
462 
463 /*!@} - end defgroup codec*/
464 #ifdef __cplusplus
465 }
466 #endif
467 #endif  // VPX_VPX_CODEC_H_
468