diff options
Diffstat (limited to 'pjmedia/include/pjmedia/converter.h')
| -rw-r--r-- | pjmedia/include/pjmedia/converter.h | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/pjmedia/include/pjmedia/converter.h b/pjmedia/include/pjmedia/converter.h new file mode 100644 index 00000000..8a9dd11a --- /dev/null +++ b/pjmedia/include/pjmedia/converter.h @@ -0,0 +1,322 @@ +/* $Id$ */ +/* + * Copyright (C) 2010-2011 Teluu Inc. (http://www.teluu.com) + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJMEDIA_CONVERTER_H__ +#define __PJMEDIA_CONVERTER_H__ + + +/** + * @file pjmedia/converter.h Format conversion utilities + * @brief Format conversion utilities + */ + +#include <pjmedia/frame.h> +#include <pjmedia/format.h> +#include <pj/list.h> +#include <pj/pool.h> + + +/** + * @defgroup PJMEDIA_CONVERTER Format converter + * @ingroup PJMEDIA_FRAME_OP + * @brief Audio and video converter utilities + * @{ + */ + +PJ_BEGIN_DECL + +/** + * This describes conversion parameter. It specifies the source and + * destination formats of the conversion. + */ +typedef struct pjmedia_conversion_param +{ + pjmedia_format src; /**< Source format. */ + pjmedia_format dst; /**< Destination format. */ +} pjmedia_conversion_param; + + +/** Forward declaration of factory operation structure */ +typedef struct pjmedia_converter_factory_op pjmedia_converter_factory_op; + +/** + * Converter priority guides. Converter priority determines which converter + * instance to be used if more than one converters are able to perform the + * requested conversion. Converter implementor can use this value to order + * the preference based on attributes such as quality or performance. Higher + * number indicates higher priority. + */ +typedef enum pjmedia_converter_priority_guide +{ + /** Lowest priority. */ + PJMEDIA_CONVERTER_PRIORITY_LOWEST = 0, + + /** Normal priority. */ + PJMEDIA_CONVERTER_PRIORITY_NORMAL = 15000, + + /** Highest priority. */ + PJMEDIA_CONVERTER_PRIORITY_HIGHEST = 32000 +} pjmedia_converter_priority_guide; + +/** + * Converter factory. The converter factory registers a callback function + * to create converters. + */ +typedef struct pjmedia_converter_factory +{ + /** + * Standard list members. + */ + PJ_DECL_LIST_MEMBER(struct pjmedia_converter_factory); + + /** + * Factory name. + */ + const char *name; + + /** + * Converter priority determines which converter instance to be used if + * more than one converters are able to perform the requested conversion. + * Converter implementor can use this value to order the preference based + * on attributes such as quality or performance. Higher number indicates + * higher priority. The pjmedia_converter_priority_guide enumeration shall + * be used as the base value to set the priority. + */ + int priority; + + /** + * Pointer to factory operation. + */ + pjmedia_converter_factory_op *op; + +} pjmedia_converter_factory; + +/** Forward declaration for converter operation. */ +typedef struct pjmedia_converter_op pjmedia_converter_op; + +/** + * This structure describes a converter instance. + */ +typedef struct pjmedia_converter +{ + /** + * Pointer to converter operation. + */ + pjmedia_converter_op *op; + +} pjmedia_converter; + + +/** + * Converter factory operation. + */ +struct pjmedia_converter_factory_op +{ + /** + * This function creates a converter with the specified conversion format, + * if such format is supported. + * + * @param cf The converter factory. + * @param pool Pool to allocate memory from. + * @param prm Conversion parameter. + * @param p_cv Pointer to hold the created converter instance. + * + * @return PJ_SUCCESS if converter has been created successfully. + */ + pj_status_t (*create_converter)(pjmedia_converter_factory *cf, + pj_pool_t *pool, + const pjmedia_conversion_param *prm, + pjmedia_converter **p_cv); + + /** + * Destroy the factory. + * + * @param cf The converter factory. + */ + void (*destroy_factory)(pjmedia_converter_factory *cf); +}; + +/** + * Converter operation. + */ +struct pjmedia_converter_op +{ + /** + * Convert the buffer in the source frame and save the result in the + * buffer of the destination frame, according to conversion format that + * was specified when the converter was created. + * + * Note that application should use #pjmedia_converter_convert() instead + * of calling this function directly. + * + * @param cv The converter instance. + * @param src_frame The source frame. + * @param dst_frame The destination frame. + * + * @return PJ_SUCCESS if conversion has been performed + * successfully. + */ + pj_status_t (*convert)(pjmedia_converter *cv, + pjmedia_frame *src_frame, + pjmedia_frame *dst_frame); + + /** + * Destroy the converter instance. + * + * Note that application should use #pjmedia_converter_destroy() instead + * of calling this function directly. + * + * @param cv The converter. + */ + void (*destroy)(pjmedia_converter *cv); + +}; + + +/** + * Opaque data type for conversion manager. Typically, the conversion manager + * is a singleton instance, although application may instantiate more than one + * instances of this if required. + */ +typedef struct pjmedia_converter_mgr pjmedia_converter_mgr; + + +/** + * Create a new conversion manager instance. This will also set the pointer + * to the singleton instance if the value is still NULL. + * + * @param pool Pool to allocate memory from. + * @param mgr Pointer to hold the created instance of the + * conversion manager. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjmedia_converter_mgr_create(pj_pool_t *pool, + pjmedia_converter_mgr **mgr); + +/** + * Get the singleton instance of the conversion manager. + * + * @return The instance. + */ +PJ_DECL(pjmedia_converter_mgr*) pjmedia_converter_mgr_instance(void); + +/** + * Manually assign a specific video manager instance as the singleton + * instance. Normally this is not needed if only one instance is ever + * going to be created, as the library automatically assign the singleton + * instance. + * + * @param mgr The instance to be used as the singleton instance. + * Application may specify NULL to clear the singleton + * singleton instance. + */ +PJ_DECL(void) pjmedia_converter_mgr_set_instance(pjmedia_converter_mgr *mgr); + +/** + * Destroy a converter manager. If the manager happens to be the singleton + * instance, the singleton instance will be set to NULL. + * + * @param mgr The converter manager. Specify NULL to use + * the singleton instance. + */ +PJ_DECL(void) pjmedia_converter_mgr_destroy(pjmedia_converter_mgr *mgr); + +/** + * Register a converter factory to the converter manager. + * + * @param mgr The converter manager. Specify NULL to use + * the singleton instance. + * @param f The converter factory to be registered. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pjmedia_converter_mgr_register_factory(pjmedia_converter_mgr *mgr, + pjmedia_converter_factory *f); + +/** + * Unregister a previously registered converter factory from the converter + * manager. + * + * @param mgr The converter manager. Specify NULL to use + * the singleton instance. + * @param f The converter factory to be unregistered. + * @param call_destroy If this is set to non-zero, the \a destroy_factory() + * callback of the factory will be called while + * unregistering the factory from the manager. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pjmedia_converter_mgr_unregister_factory(pjmedia_converter_mgr *mgr, + pjmedia_converter_factory *f, + pj_bool_t call_destroy); + +/** + * Create a converter instance to perform the specified format conversion + * as specified in \a param. + * + * @param mgr The converter manager. Specify NULL to use + * the singleton instance. + * @param pool Pool to allocate the memory from. + * @param param Conversion parameter. + * @param p_cv Pointer to hold the created converter. + * + * @return PJ_SUCCESS if a converter has been created successfully + * or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjmedia_converter_create(pjmedia_converter_mgr *mgr, + pj_pool_t *pool, + pjmedia_conversion_param *param, + pjmedia_converter **p_cv); + +/** + * Convert the buffer in the source frame and save the result in the + * buffer of the destination frame, according to conversion format that + * was specified when the converter was created. + * + * @param cv The converter instance. + * @param src_frame The source frame. + * @param dst_frame The destination frame. + * + * @return PJ_SUCCESS if conversion has been performed + * successfully. + */ +PJ_DECL(pj_status_t) pjmedia_converter_convert(pjmedia_converter *cv, + pjmedia_frame *src_frame, + pjmedia_frame *dst_frame); + +/** + * Destroy the converter. + * + * @param cv The converter instance. + */ +PJ_DECL(void) pjmedia_converter_destroy(pjmedia_converter *cv); + + +PJ_END_DECL + +/** + * @} + */ + + +#endif /* __PJMEDIA_CONVERTER_H__ */ + + |