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