Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

SoundEngine.h

Go to the documentation of this file.
00001 /*********************************************************************************
00002  *
00003  * Razor! Engine - A modular C++ presentation engine
00004  *
00005  * $Id: SoundEngine.h,v 1.1 2003/01/26 10:46:47 teacy Exp $
00006  *
00007  * Copyright (c) 2000-2003 Tilo Christ. All Rights Reserved.
00008  * 
00009  * Permission is hereby granted, free of charge, to any person obtaining a 
00010  * copy of this software and associated documentation files (the  "Software"), 
00011  * to deal in the Software without restriction, including without limitation 
00012  * the rights to use, copy, modify, merge, publish, distribute, sublicense, 
00013  * and/or sell copies of the Software, and to permit persons to whom the Software 
00014  * is furnished to do so, subject to the following conditions:
00015  *
00016  * The above copyright notice and this permission notice shall be included in all 
00017  * copies or substantial portions of the Software.
00018  *
00019  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
00020  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
00021  * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
00022  * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
00023  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00024  *
00025  **********************************************************************************/
00026 
00027 
00028 
00029 #ifndef SOUND_ENGINE_H
00030 #define SOUND_ENGINE_H
00031 
00032 #include <PalmOS.h>
00033 #include "Sections.h"
00034 #include "Customization.h"
00035 
00036 
00037 namespace prvrazor
00038 {
00039 class MusicEngine;
00040 class FxEngine;
00041 }
00042 
00043 
00044 
00045 /**
00046  * SoundEngine is a facade for sound output from two different sources (music, FX).
00047  */
00048 class SoundEngine
00049 {
00050     public:     
00051     /**
00052      * Play a sound effect which is stored in a resource of type 'Tsfx' with the
00053      * specified resource ID.
00054      *
00055      * @param resID the ID of the 'Tsfx' resource
00056      */
00057     static void playFx(DmResID resID);
00058     
00059     /**
00060      * Play a song where the sequence of patterns is stored in a resource of type
00061      * 'Ttrk' with the specified resource ID. 
00062      * The patterns themselves are stored in resources of type 'Tpat' where the 
00063      * pattern ID is the resource ID.
00064      *
00065      * @param resID the ID of the 'Ttrk' resource
00066      */
00067     static void playSong(DmResID resID);
00068     
00069     
00070     /**
00071      * Stop the currently playing song.
00072      */
00073     static void stopSong();
00074     
00075 
00076     /**
00077      * This method needs to be invoked periodically, in order for SoundEngine
00078      * to work.
00079      */
00080     static void timeTick();
00081 
00082 
00083     private:    
00084     // SoundEngine cannot be instantiated or destroyed.
00085     SoundEngine() {}    
00086     ~SoundEngine() {}
00087 
00088     static void init() SEC_RAZOR_INIT;
00089     static void destroy() SEC_RAZOR_INIT;
00090 
00091     static prvrazor::FxEngine *fxEngine;
00092     static prvrazor::MusicEngine *musicEngine;
00093 
00094     static UInt16 baseAmplitude;
00095     static Boolean mute;
00096     static UInt32 nextTimer;
00097 
00098 
00099     friend class Presentation;
00100 };
00101 
00102 
00103 
00104 namespace prvrazor
00105 {
00106 
00107 /**
00108  * FxEngine can play sound fx.
00109  */
00110 class FxEngine
00111 {
00112     private:
00113     
00114     FxEngine(UInt16 baseAmplitude) SEC_RAZOR_INIT;
00115     ~FxEngine() SEC_RAZOR_INIT;
00116     
00117     /**
00118      * Play the next portion of the sound.
00119      *
00120      * @return true = sound has been played, false = no sound has been played
00121      */
00122     Boolean timeTick();
00123     
00124     void playFx(DmResID resID);
00125 
00126 
00127     Boolean playing;
00128     DmResID fxResID;
00129     UInt16 fxPosition;
00130     UInt16 baseAmplitude;
00131 
00132     /// A frequency with value FREQ_END means, that the end of the sound effect has been reached.
00133     static const UInt16 FREQ_END = 0x0000;
00134     /// A duration with value DURATION_YIELD means, that timeTick() shall return control to the caller.
00135     static const UInt8 DURATION_YIELD = 0x00;
00136 
00137     friend class SoundEngine;
00138 };
00139 
00140 
00141 /**
00142  * MusicEngine can playback music. It is based on a pattern model,
00143  * comparable to that of MOD players, and it can fake three channels.
00144  */
00145 class MusicEngine
00146 {
00147     private:
00148 
00149     MusicEngine(UInt16 baseAmplitude) SEC_RAZOR_INIT;
00150     ~MusicEngine() SEC_RAZOR_INIT;
00151 
00152 
00153     /**
00154      * Play the next portion of the sound.
00155      *
00156      * @return true = sound has been played, false = no sound has been played
00157      */
00158     Boolean timeTick();
00159 
00160     void playSong(DmResID resID) SEC_RAZOR_INIT;
00161     void stopSong() SEC_RAZOR_INIT;
00162 
00163     void setPatternFromTrack();
00164     void releasePattern();
00165 
00166     void playNote(UInt16 note, UInt16 octave, UInt16 amplitude, UInt16 duration, Boolean wait) const;
00167     void playMute(UInt16 duration, Boolean wait) const;
00168 
00169     void hitIt(UInt16 channel, UInt16 amplitude, UInt16 duration, Boolean wait) const;
00170 
00171 
00172     DmResID trackResID;
00173     UInt16 trackPosition;
00174     
00175     UInt16 pattern;
00176     UInt16 patternPosition;
00177     Char* patternString;
00178     MemHandle patternResH;
00179 
00180     Boolean playing;
00181     Boolean channel1Playing;
00182     Boolean channel2Playing;
00183     Boolean channel3Playing;
00184     UInt16 playingChannel;
00185 
00186     UInt16 baseDuration;
00187     UInt16 baseAmplitude;
00188 
00189     static const UInt8 CHANNEL1_MUTE = 0x01;
00190     static const UInt8 CHANNEL2_MUTE = 0x02;
00191     static const UInt8 CHANNEL3_MUTE = 0x04;
00192     static const UInt8 TRACK_REPEAT = 0xFE;
00193     static const UInt8 TRACK_END    = 0xFF;
00194 
00195     friend class SoundEngine;
00196 };
00197 }
00198 
00199 #endif

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 31 May 2003