(Online version only)
|
API Guide Home (Online version only) |
|
We define the concept of Audio Groups to classify sounds depending on the relative importance to the user:
pmAudioGroupApp Audio normally generated by user applications such as games, MP3 players, and others. This is the default classification even if no audio group is assigned.
pmAudioGroupSystem Typical audio events generated by the system to give audible feedback to the user about system events. Most of the sounds produced through SndPlaySystemSound are classified internally as System.
pmAudioGroupAlert Alerts, Alarms, and Ringtones should be given this classification. If you depend on the Attention Manager to make a sound, it will also use this classification. The constant sndAlarm when calling SndPlaySystemSound is classified as an Alert.
pmAudioGroupHighPriority Sounds of great importance to the user and that are routed with the highest priority. We currently define hsSndBatLow and hsSndBatShutdown constants, when calling SndPlaySystemSound, as high priority sounds.
If you depend on PalmOS Attention Manager for audio alerts, or use PalmOS SndPlaySystemSound, then the audio group is automatically assigned, and there is nothing else you need to do.
However, if you directly play audio events using other PalmOS APIs such as SndPlayResource, or SndStreamCreate, for example, then you may want to assign the audio group, unless the default pmAudioGroupApp is sufficient for your purposes.
To assign an audio group we attach that additional information to the PalmOS volume parameter associated with many of the Sound Manager API calls. We have found this is the most effective way to associate the audio group to a sound channel, and have that information filter down, through PalmOS, to our Audio Driver in the Hardware Abstraction Layer (HAL). In this way, there is no need to modify PalmOS, and we can allow a variety of components and applications to take advantage of the behavior and custom routing we assign to the different audio group classifications.
The drawback is that when the audio group is attached to the volume parameter, then the volume is limited to a maximum of 8K - 1, in steps of 8 (which represents 128 levels to unity). In contrast PalmOS 5.x volume parameter is defined with a maximum of 32K - 1, in steps of 1 (which represents 1024 levels to unity). Our constrain is generally acceptable, since it represents granularity of about 1 dB step changes, with up to 8X amplification We currently use less precise granularity of > 10 db step changes, and a maximum of 6X amplification for the case of QCELP/AMR playback.
There is a risk that an existing application using the PalmOS API may apply a volume parameter that could be mistaken for a volume plus audio group designation, but this risk is fairly minimal as explained next.
The Audio Group uses a mark in the upper 3-bits of the volume parameter. If this mark is binary '011' which means a positive number >= 24K, then we will interpret the lower three bits as the audio group. The risk of mistaken interpretation from existing PalmOS applications will happen when the application request amplifications of 24X to 32X. In our experience we have Not seen any application going beyond the range of 2X to 8X amplification. In case such extremely rare condition do occurs, the effect would be that the range 24X to 32X will be treated as the lower range of 0X to 8X, and there is a chance the sound will be routed/treated as other than application audio.
One more thing to note is that PalmOS allows negative numbers in the volume parameter to mean one of the usual volume parameters the user may adjust through the preferences panel: system volume, game volume, and alarm volume. In our current implementation we do NOT change these values, and we do NOT assign any audio group designation to these preferences driven volume settings. In other words, they will be treated as application audio group.
The use of Audio Group in a device will be present when the feature is registered with the PalmOS Feature Manager. This feature will be available when:
FtrGet( pmSoundLibCreatorID, pmSoundLibAudioGroupFtr, &value );
return no error, and the UInt32 value is NOT:
pmSoundLibAudioGroupFtr_Off
It is important to always check for this feature, since this is a custom enhancement which could be turned off for some future device, or platform.
To assign an audio group to your volume parameter you will invoke the function PmSndAddAudioGroupToVolume (currently implemented as a macro for simplicity). Here is an example on how to use this:
// Includes #include <FeatureMgr.h> #include <Common/Libraries/HsSoundLib/PmSoundLibAudioGroup.h> // Declarations UInt32 value = 0; // temporary variable for FtrGet Int32 volume = 1024; // default max amplitude in PalmOS 5.x, can also use sndMaxAmp with earlier PalmOS // Code Snippet if ( ( !FtrGet( pmSoundLibCreatorID, pmSoundLibAudioGroupFtr, &value ) ) // is the Audio Group feature supported? && ( value != pmSoundLibAudioGroupFtr_Off ) ) // is the Audio Group feature active? { volume = PmSndAddAudioGroupToVolume( volume, pmAudioGroupAlert ); // then, mark this sound as an alert } SndPlayResource( mySound, volume, sndFlagNormal );
Definition in file PmSoundLibAudioGroup.h.
Include dependency graph for PmSoundLibAudioGroup.h:
Go to the source code of this file.
| #define PM_AUDIOGROUP_MASK 0xE007 |
No definition.
Definition at line 149 of file PmSoundLibAudioGroup.h.
| #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.
Use this macro if you want your sound channel to be designated differently than application sound.
If this macro were implemented as a function, the prototype would be:
Int32 //returned volume // PmSndAddAudioGroupToVolume ( Int32 volume, PmAudioGroup audioGroup );
Definition at line 179 of file PmSoundLibAudioGroup.h.
| #define PmSndGetAudioGroupFromVolume | ( | volume | ) | (PmAudioGroup)((((Int32)(volume)) < 0x6000)? (pmAudioGroupNone) : ((volume) & PM_AUDIOGROUP_MASK)) |
Removes the volume component of a PalmOS volume parameter, leaving a pure audio group component.
Use this if you have already attached the audio group to a volume parameter and need to identify the audio group designation.
If this macro were implemented as a function, the prototype would be:
PmAudioGroup PmSndGetAudioGroupFromVolume ( Int32 volume );
Definition at line 201 of file PmSoundLibAudioGroup.h.
| #define PmSndRemoveAudioGroupFromVolume | ( | volume | ) | (Int32) ((((Int32)(volume)) < 0x6000)? (volume) : ((volume) & ~PM_AUDIOGROUP_MASK )) |
Removes the audio group designation from a PalmOS volume parameter.
Use this if you previously attached a sound group designation and retrieve that volume again using PalmOS APIs. Or if you need to manipulate the overloaded volume parameter, as a volume only value.
If this macro were implemented as a function, the prototype would be:
Int32 //returned volume // PmSndRemoveAudioGroupFromVolume ( Int32 volume );
Definition at line 188 of file PmSoundLibAudioGroup.h.
| #define pmSoundLibAudioGroupFtr 0x0001 |
Use this as the featureNum passed to FtrGet.
Definition at line 144 of file PmSoundLibAudioGroup.h.
| #define pmSoundLibAudioGroupFtr_Off 0 |
Value returned in *valueP of FtrGet when Audio Group is disabled.
Definition at line 145 of file PmSoundLibAudioGroup.h.
| #define pmSoundLibAudioGroupFtr_On 1 |
Value returned in *valueP of FtrGet when Audio Group is enabled
Definition at line 146 of file PmSoundLibAudioGroup.h.
| #define pmSoundLibCreatorID hsSoundLibCreatorID |
Pass this as the creator ID used in FtrGet.
Definition at line 143 of file PmSoundLibAudioGroup.h.
| typedef UInt16 PmAudioGroup |
| enum PmAudioGroupEnum |
Holds audio group information.
Definition at line 154 of file PmSoundLibAudioGroup.h.
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;
| Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:08:02 2008 for Palm API Guide |