Changes between Version 13 and Version 14 of Audio_Dev_API


Ignore:
Timestamp:
Mar 11, 2009 6:27:37 PM (16 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Audio_Dev_API

    v13 v14  
    2727 The new API has been designed to be extensible, it will support new API's as well as new features that may be introduced in the future without breaking compatibility with applications that use this API as well as compatibility with existing device implementations. 
    2828 
     29 '''Backward compatibility:''' :: 
     30 While this is a completely new audio API and implementation, compatibility layers have been implemented for existing applications or sound device implementations that make use of the old API. More will be explained later. 
     31 
    2932 '''Device capabilities:''' :: 
    3033 At the heart of the API is device capabilities management, where all possible audio capabilities of audio devices should be able to be handled in a generic manner. With this framework, new capabilities that may be discovered in the future can be handled in manner without breaking existing applications. 
    … …  
    5053 
    5154The following audio device backends have been ported to the new API: 
    52  - !PortAudio (previously pasound.c) 
    53  - WMME (previously wmme_sound.c) 
    54  - Null implementation (previously nullsound.c) 
    55  - APS (previously symbian_sound_aps.cpp) 
     55 - !PortAudio 
     56 - Windows Multimedia/WMME 
     57 - Nokia APS for S60 
     58 - Symbian MMF/MDA 
    5659 
    5760=== Compatibility settings === 
    5861 
    59 The following compile time settings/macros have introduced to manage compatibility between old and new API and to assist migration of application and/or sound device implementation to the new API. 
    60  
    61  '''Setting 1) {{{PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_NEW_ONLY}}}''' :: 
    62 This setting will completely deprecate the use of old API, and inclusion of {{{<pjmedia/sound.h>}}} in the code will raise compilation error.  
    63  
    64 Use this setting if: 
    65   - you are accessing sound devices which have been implemented using the '''new''' API 
    66   - you have completely ported your application to use the new API 
    67  
    68  '''Setting 2) {{{PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_HAS_OLD_API}}}''' :: 
    69 With this setting (this is the default setting), application can use the old sound device API to access audio devices provided by the new audio device API. 
    70  
    71 Use this setting if: 
    72  - you are accessing sound devices which have been ported to the new API 
    73  - you want to access the sound device using '''both''' old or new API's. 
    74  
    75 What this setting does: 
    76  - it creates a sound device implementation based on the old API, but the implementation uses/accesses the new audio device API. 
    77  
    78  '''Setting 3) {{{PJMEDIA_AUDIO_API = PJMEDIA_AUDIO_API_HAS_OLD_DEVICE}}}''' :: 
    79 This setting enables old sound device implementation to be accessed via '''both''' old and new API's. 
    80  
    81 Use this setting if: 
    82  - you have your own sound device implementation, using the old API 
    83  - you want to access the sound device using '''both''' old or new API's. 
    84  
    85 What this setting does: 
    86  - the new audio device API will create a wrapper for the old sound device implementation, effectively enabling the sound device implementation to be accessed via old or new API. 
     62Two compile-time macros have been introduced to enable or disable the compatibility layers. The default values for the settings enable existing application to work unchanged,  
     63 
     64 '''{{{PJMEDIA_HAS_LEGACY_SOUND_API}}}''' :: 
     65 
     66Location: pjmedia/config.h 
     67Default: 1 
     68Purpose: to enable application to access the sound device using the old (sound.h) API. 
     69Description: This macro controls whether the legacy sound device API is to be supported, for applications that still use the old sound device API (sound.h). If this macro is set to non-zero, the sound_legacy.c will be included in the compilation. The sound_legacy.c is an implementation of old sound device (sound.h) using the new Audio Device API. 
     70 
     71 '''{{{PJMEDIA_AUDIO_DEV_HAS_LEGACY_DEVICE}}}''' 
     72 
     73Location: pjmedia-audiodev/config.h 
     74Default: 0 
     75Purpose: to enable sound device implemented using the old API to be accessed using the new API. 
     76Description: This setting controls whether the Audio Device API should support device implementation that is based on the old sound device API (sound.h).  
     77 
    8778 
    8879 
    … …  
    9384 1. I use sound devices provided by PJMEDIA (I don't have my own sound device implementation), or I have ported my sound device implementation to the new API 
    9485    a. I haven't changed my application to use the new API 
    95        - use setting 2 (the default) 
     86       - the default settings should be okay 
    9687    a. I have changed my application to use the new API 
    97        - you may use setting 1 to make sure that everything has been ported to the new API, or otherwise use setting 2. 
     88       - the default settings should be okay. You may disable {{{PJMEDIA_HAS_LEGACY_SOUND_API}}} to make sure that all codes are using the new API (as well as to reduce footprint slightly). 
    9889 1. I have my own sound device implementation, based on old API 
    9990    a. I haven't changed my application to use the new API 
    100        - use setting 3 
     91       - disable both {{{PJMEDIA_HAS_LEGACY_SOUND_API}}} and {{{PJMEDIA_AUDIO_DEV_HAS_LEGACY_DEVICE}}}. Note that with this setting, you cannot use the new API to access your device implementation. PJSUA-LIB will not work either as PJSUA-LIB uses the new API. 
    10192    a. I have changed my application to use the new API 
    102        - also use setting 3 
     93       - disable {{{PJMEDIA_HAS_LEGACY_SOUND_API}}} and enable {{{PJMEDIA_AUDIO_DEV_HAS_LEGACY_DEVICE}}}. 
    10394 
    10495[[BR]] 
    … …  
    148139PJSUA-LIB applications that only make use of the API in {{{<pjsua.h>}}} should require minimum changes. 
    149140 
    150  1. Change in {{{pjsua_enum_snd_devs()}}} signature. Old API: 
    151     {{{ 
    152 PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[], unsigned *count); 
    153     }}} 
    154  New API (notice the type difference in the ''info'' argument): 
    155     {{{ 
    156 PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_aud_dev_info info[], unsigned *count); 
    157     }}} 
    158  
    159  2. Add '''pjmedia-audiodev''' library to the link specifications of your application. 
    160  3. '''Latency''' setting. Old code may set latency directly accessing PJMEDIA API: 
     141 1. Add '''pjmedia-audiodev''' library to the link specifications of your application. 
     142 2. '''Latency''' setting. Old code may set latency directly accessing PJMEDIA API: 
    161143    {{{ 
    162144pjmedia_snd_set_latency(rec_latency, play_latency); 
    … …  
    170152media_cfg.snd_play_latency = ..; 
    171153    }}} 
     154    Call to {{{pjmedia_snd_set_latency()}}} will only set the latency if the sound device is opened using the old API. 
     155 3. '''New API:''' 
     156   - {{{pjsua_snd_is_active()}}}: to query if sound device is currently active 
     157   - {{{pjsua_snd_set_setting()}}}/{{{pjsua_snd_get_setting()}}}: to set or retrieve the value of sound device capability (example of capabilities are audio routing and volume control) 
    172158 
    173159