| /* $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__ */ |
| |
| |