API Guide Home (Online version only) |

# PmSoundLibAudioGroup.h

Go to the documentation of this file.

    00001 /*******************************************************************************
    00002  * Copyright (c) 2004-2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  ******************************************************************************/
    00005 /**
    00006  * @ingroup Sound
    00007  *
    00008  */
    00009
    00010 /**
    00011  *
    00012  * @file    PmSoundLibAudioGroup.h
    00013  * @brief   Public 68K header file used to associate sound channels with Audio
    00014  *          groups on Treo 600 and Treo 650 smartphones.
    00015  *
    00016  *   We define the concept of Audio Groups to classify sounds depending
    00017  *   on the relative importance to the user:
    00018  *
    00019  *        pmAudioGroupApp    Audio normally generated by user applications
    00020  *                           such as games, MP3 players, and others. This is the default
    00021  *                           classification even if no audio group is assigned.
    00022  *
    00023  *        pmAudioGroupSystem Typical audio events generated by the system to
    00024  *                           give audible feedback to the user about system events.
    00025  *                           Most of the sounds produced through SndPlaySystemSound are
    00026  *                           classified internally as System.
    00027  *
    00028  *        pmAudioGroupAlert  Alerts, Alarms, and Ringtones should be given this classification.
    00029  *                           If you depend on the Attention Manager to make a sound, it will also
    00030  *                           use this classification. The constant sndAlarm when calling
    00031  *                           SndPlaySystemSound is classified as an Alert.
    00032  *
    00033  *        pmAudioGroupHighPriority
    00034  *                           Sounds of great importance to the
    00035  *                           user and that are routed with the highest priority.
    00036  *                           We currently define hsSndBatLow and hsSndBatShutdown constants,
    00037  *                           when calling SndPlaySystemSound, as high priority sounds.
    00038  *
    00039  *  If you depend on PalmOS Attention Manager for audio alerts, or use PalmOS
    00040  *  SndPlaySystemSound, then the audio group is automatically assigned, and there
    00041  *  is nothing else you need to do.
    00042  *
    00043  *  However, if you directly play audio events using other PalmOS APIs such
    00044  *  as SndPlayResource, or SndStreamCreate, for example, then you may want
    00045  *  to assign the audio group, unless the default pmAudioGroupApp is
    00046  *  sufficient for your purposes.
    00047  *
    00048  *  To assign an audio group we attach that additional information
    00049  *  to the PalmOS volume parameter associated with many of the Sound Manager
    00050  *  API calls. We have found this is the most effective way to associate
    00051  *  the audio group to a sound channel, and have that information filter down,
    00052  *  through PalmOS, to our Audio Driver in the Hardware Abstraction Layer (HAL).
    00053  *  In this way, there is no need to modify PalmOS, and we can allow a variety
    00054  *  of components and applications to take advantage of the behavior and custom
    00055  *  routing we assign to the different audio group classifications.
    00056  *
    00057  *  The drawback is that when the audio group is attached to the volume parameter,
    00058  *  then the volume is limited to a maximum of 8K - 1, in steps of 8 (which
    00059  *  represents 128 levels to unity). In contrast PalmOS 5.x volume parameter
    00060  *  is defined with a maximum of 32K - 1, in steps of 1 (which represents
    00061  *  1024 levels to unity). Our constrain is generally acceptable, since it
    00062  *  represents granularity of about 1 dB step changes, with up to 8X amplification
    00063  *  We currently use less precise granularity of > 10 db step changes, and a
    00064  *  maximum of 6X amplification for the case of QCELP/AMR playback.
    00065  *
    00066  *  There is a risk that an existing application using the PalmOS API may
    00067  *  apply a volume parameter that could be mistaken for a volume plus audio
    00068  *  group designation, but this risk is fairly minimal as explained next.
    00069  *
    00070  *  The Audio Group uses a mark in the upper 3-bits of the volume parameter.
    00071  *  If this mark is binary '011' which means a positive number >= 24K, then
    00072  *  we will interpret the lower three bits as the audio group. The risk of
    00073  *  mistaken interpretation from existing PalmOS applications will happen
    00074  *  when the application request amplifications of 24X to 32X. In our
    00075  *  experience we have Not seen any application going beyond the range of
    00076  *  2X to 8X amplification. In case such extremely rare condition do
    00077  *  occurs, the effect would be that the range 24X to 32X will be treated
    00078  *  as the lower range of 0X to 8X, and there is a chance the sound will
    00079  *  be routed/treated as other than application audio.
    00080  *
    00081  *  One more thing to note is that PalmOS allows negative numbers in the
    00082  *  volume parameter to mean one of the usual volume parameters the
    00083  *  user may adjust through the preferences panel: system volume, game
    00084  *  volume, and alarm volume. In our current implementation we do NOT
    00085  *  change these values, and we do NOT assign any audio group designation
    00086  *  to these preferences driven volume settings. In other words, they
    00087  *  will be treated as application audio group.
    00088  *
    00089  *  The use of Audio Group in a device will be present when the feature
    00090  *  is registered with the PalmOS Feature Manager. This feature will
    00091  *  be available when:
    00092  *
    00093  *     FtrGet( pmSoundLibCreatorID, pmSoundLibAudioGroupFtr, &value );
    00094  *
    00095  *  return no error, and the UInt32 value is NOT:
    00096  *
    00097  *     pmSoundLibAudioGroupFtr_Off
    00098  *
    00099  *  It is important to always check for this feature, since this is
    00100  *  a custom enhancement which could be turned off for some future
    00101  *  device, or platform.
    00102  *
    00103  *  To assign an audio group to your volume parameter you will invoke
    00104  *  the function PmSndAddAudioGroupToVolume (currently implemented as
    00105  *  a macro for simplicity). Here is an example on how to use this:
    00106  *
    00107  *  @code
    00108  *
    00109  *      // Includes
    00110  *      #include <FeatureMgr.h>
    00111  *      #include <Common/Libraries/HsSoundLib/PmSoundLibAudioGroup.h>
    00112  *
    00113  *      // Declarations
    00114  *      UInt32 value  = 0;    // temporary variable for FtrGet
    00115  *      Int32  volume = 1024; // default max amplitude in PalmOS 5.x, can also use sndMaxAmp with earlier PalmOS
    00116  *
    00117  *      // Code Snippet
    00118  *      if (   ( !FtrGet( pmSoundLibCreatorID, pmSoundLibAudioGroupFtr, &value ) ) // is the Audio Group feature supported?
    00119  *          && ( value != pmSoundLibAudioGroupFtr_Off ) ) // is the Audio Group feature active?
    00120  *      {
    00121  *          volume = PmSndAddAudioGroupToVolume( volume, pmAudioGroupAlert ); // then, mark this sound as an alert
    00122  *      }
    00123  *      SndPlayResource( mySound, volume, sndFlagNormal );
    00124  *
    00125  *  @endcode
    00126  *  <hr>
    00127  */
    00128
    00129
    00130 #ifndef PMSOUNDLIBAUDIOGROUP_H_
    00131 #define PMSOUNDLIBAUDIOGROUP_H_
    00132
    00133 /***********************************************************************
    00134  * Palm OS common definitions
    00135  ***********************************************************************/
    00136 #include <HsSoundLibCommon.h> /**<Included for hsSoundLibCreatorID. */
    00137
    00138 /**
    00139  * @name PmSoundLibAudioGroup information
    00140  *
    00141  */
    00142 /*@{*/
    00143 #define pmSoundLibCreatorID         hsSoundLibCreatorID /**<Pass this as the creator ID used in FtrGet. */
    00144 #define pmSoundLibAudioGroupFtr     0x0001 /**<Use this as the featureNum passed to FtrGet. */
    00145 #define pmSoundLibAudioGroupFtr_Off 0      /**<Value returned in *valueP of FtrGet when Audio Group is disabled. */
    00146 #define pmSoundLibAudioGroupFtr_On  1      /**<Value returned in *valueP of FtrGet when Audio Group is enabled */
    00147 /*@}*/
    00148
    00149 #define PM_AUDIOGROUP_MASK     0xE007 /**<No definition. */
    00150
    00151 /**
    00152  * Holds audio group information.
    00153  */
    00154 typedef enum PmAudioGroupEnum
    00155 {
    00156     pmAudioGroupNone         = 0x0000, /**<Default audio group when volume is less than 24K. */
    00157     pmAudioGroupApp          = 0x6000, /**<Application audio, treated as pmAudioGroupNone, but group type saved. */
    00158     pmAudioGroupSystem       = 0x6001, /**<System audio (as in SndPlaySystemSound). */
    00159     pmAudioGroupAlert        = 0x6002, /**<Alert, alarms, ringtones that notify user of an event. */
    00160     pmAudioGroupHighPriority = 0x6003, /**<Extremely important event such as low battery shutdown. */
    00161
    00162     pmAudioGroupInteractive  = 0x6004, /**<Application audio to be used for interactive playback (eg: games). */
    00163     pmAudioGroupStreaming    = 0x6005, /**<Application audio to be used for streaming (eg: MP3, video, broadcast). */
    00164     pmAudioGroupCall         = 0x6006, /**<Intended for digital phone call audio only. Used for internal purposes. */
    00165     pmAudioGroupAlertRingOff = 0x6007  /**<Same as pmAudioGroupAlert, but ignores Ringer switch position */
    00166
    00167 } PmAudioGroupEnum;
    00168
    00169 /** @see PmAudioGroupEnum */
    00170 typedef UInt16 PmAudioGroup;
    00171
    00172
    00173 /**
    00174  * @name Audio Group API functions
    00175  *
    00176  * Implemented as macros.
    00177  */
    00178 /*@{*/
    00179 #define PmSndAddAudioGroupToVolume(volume,audioGroup)  (Int32)       (((!audioGroup) || (((Int32)(volume)) <= -1))? (volume) : ((((((volume) & 0xE000) == 0x6000)? (volume):(volume)+7) & ~PM_AUDIOGROUP_MASK) | (audioGroup)))/**<Attaches an audio group designation to a PalmOS volume parameter.
    00180
    00181  Use this macro if you want your sound channel to be designated differently
    00182  than application sound.
    00183
    00184  If this macro were implemented as a function, the prototype would be:
    00185
    00186  Int32 //returned volume // PmSndAddAudioGroupToVolume  ( Int32 volume, PmAudioGroup audioGroup );
    00187 */
    00188 #define PmSndRemoveAudioGroupFromVolume(volume)         (Int32)       ((((Int32)(volume)) < 0x6000)? (volume) : ((volume) & ~PM_AUDIOGROUP_MASK ))
    00189 /**<Removes the audio group designation from a PalmOS volume parameter.
    00190
    00191  Use this if you previously attached a sound group designation and
    00192  retrieve that volume again using PalmOS APIs. Or if you need to
    00193  manipulate the overloaded volume parameter, as a volume only value.
    00194
    00195  If this macro were implemented as a function, the prototype would be:
    00196
    00197  Int32 //returned volume // PmSndRemoveAudioGroupFromVolume ( Int32 volume );
    00198 */
    00199
    00200 #define PmSndGetAudioGroupFromVolume(volume)            (PmAudioGroup)((((Int32)(volume)) < 0x6000)? (pmAudioGroupNone) : ((volume) & PM_AUDIOGROUP_MASK))
    00201 /**<Removes the volume component of a PalmOS volume parameter, leaving
    00202  a pure audio group component.
    00203
    00204  Use this if you have already attached the audio group to a volume
    00205  parameter and need to identify the audio group designation.
    00206
    00207  If this macro were implemented as a function, the prototype would be:
    00208
    00209  PmAudioGroup PmSndGetAudioGroupFromVolume ( Int32 volume );
    00210 */
    00211 /*@}*/
    00212
    00213 #endif /* #ifndef PMSOUNDLIBAUDIOGROUP_H_ */

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:55 2008 for Palm API Guide