1 /**
  2  * The Render Engine
  3  * SoundSystem
  4  *
  5  * @fileoverview An abstraction class for the engine sound system.  Pluggable
  6  *                      architecture for linking in different sound managers.
  7  *
  8  * @author: Brett Fattori (brettf@renderengine.com)
  9  * @author: $Author: bfattori $
 10  * @version: $Revision: 1555 $
 11  *
 12  * Copyright (c) 2011 Brett Fattori (brettf@renderengine.com)
 13  *
 14  * Permission is hereby granted, free of charge, to any person obtaining a copy
 15  * of this software and associated documentation files (the "Software"), to deal
 16  * in the Software without restriction, including without limitation the rights
 17  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 18  * copies of the Software, and to permit persons to whom the Software is
 19  * furnished to do so, subject to the following conditions:
 20  *
 21  * The above copyright notice and this permission notice shall be included in
 22  * all copies or substantial portions of the Software.
 23  *
 24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 29  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 30  * THE SOFTWARE.
 31  *
 32  */
 33 
 34 // The class this file defines and its required classes
 35 R.Engine.define({
 36     "class":"R.sound.AbstractSoundSystem",
 37     "requires":[
 38         "R.lang.Timeout",
 39         "R.resources.types.Sound"
 40     ]
 41 });
 42 
 43 /**
 44  * @class Sound system abstraction class for pluggable sound architecture.  The <tt>
 45  *             R.sound.AbstractSoundSystem</tt> class is used to separate the sound manager from the resource
 46  *             loader and sound objects.
 47  *
 48  * @constructor
 49  */
 50 R.sound.AbstractSoundSystem = function () {
 51     return Base.extend(/** @scope R.sound.AbstractSoundSystem.prototype */{
 52 
 53         ready:false,
 54         queuedSounds:null,
 55         loadingSounds:null,
 56 
 57         /** @private */
 58         constructor:function () {
 59             this.ready = false, this.queuedSounds = [];
 60             this.loadingSounds = {};
 61         },
 62 
 63         /**
 64          * [ABSTRACT] Shut down the sound system
 65          */
 66         shutdown:function () {
 67         },
 68 
 69         /**
 70          * Returns a flag indicating if the sound system is ready
 71          * @return {Boolean}
 72          */
 73         isReady:function () {
 74             return this.ready;
 75         },
 76 
 77         /**
 78          * Sets the ready state of the sound system.
 79          * @private
 80          */
 81         makeReady:function () {
 82             // Retrieve queued sounds
 83             var self = this;
 84             R.lang.Timeout.create("loadQueuedSounds", 100, function () {
 85                 if (self.queuedSounds.length > 0) {
 86                     while (self.queuedSounds.length > 0) {
 87                         var s = self.queuedSounds.shift();
 88                         self.retrieveSound(s.sLoader, s.sName, s.sUrl);
 89                     }
 90                 }
 91 
 92                 this.destroy();
 93             });
 94             this.ready = true;
 95         },
 96 
 97         /**
 98          * Load a sound using the sound system.  If the sound system isn't ready,
 99          * sounds will be queued until it is ready.
100          *
101          * @param resourceLoader {R.resources.loades.SoundLoader} The sound resource loader
102          * @param name {String} The name of the sound object
103          * @param url {String} The URL of the sound to load
104          * @return {R.resources.types.Sound} The sound object
105          */
106         loadSound:function (resourceLoader, name, url) {
107             if (!this.ready) {
108                 this.queuedSounds.push({
109                     sLoader:resourceLoader,
110                     sName:name,
111                     sUrl:url
112                 });
113                 return R.resources.types.Sound.create(this, null);
114             }
115             else {
116                 return this.retrieveSound(resourceLoader, name, url);
117             }
118         },
119 
120         /**
121          * Retrieve the sound from the network, when the sound system is ready, and create the sound object.
122          * @param resourceLoader {R.resources.loades.SoundLoader} The sound resource loader
123          * @param name {String} The name of the sound object
124          * @param url {String} The URL of the sound to load
125          * @return {R.resources.types.Sound} The sound object
126          * @private
127          */
128         retrieveSound:function (resourceLoader, name, url) {
129             // See if the resource loader has a sound object for us already
130             var sound = resourceLoader.get(name);
131             if (sound == null) {
132                 // No, return an empty sound object
133                 return R.sound.Sound.create(this, null);
134             }
135             else {
136                 // Yep, return the existing sound object
137                 return sound;
138             }
139         },
140 
141         /**
142          * [ABSTRACT] Destroy the given sound object
143          * @param sound {R.resources.types.Sound} The sound object
144          */
145         destroySound:function (sound) {
146         },
147 
148         /**
149          * [ABSTRACT] Play the given sound object
150          * @param sound {R.resources.types.Sound} The sound object
151          */
152         playSound:function (sound) {
153         },
154 
155         /**
156          * [ABSTRACT] Stop the given sound object
157          * @param sound {R.resources.types.Sound} The sound object
158          */
159         stopSound:function (sound) {
160         },
161 
162         /**
163          * [ABSTRACT] Pause the given sound object
164          * @param sound {R.resources.types.Sound} The sound object
165          */
166         pauseSound:function (sound) {
167         },
168 
169         /**
170          * [ABSTRACT] Resume the given sound object
171          * @param sound {R.resources.types.Sound} The sound object
172          */
173         resumeSound:function (sound) {
174         },
175 
176         /**
177          * [ABSTRACT] Mute the given sound object
178          * @param sound {R.resources.types.Sound} The sound object
179          */
180         muteSound:function (sound) {
181         },
182 
183         /**
184          * [ABSTRACT] Unmute the given sound object
185          * @param sound {R.resources.types.Sound} The sound object
186          */
187         unmuteSound:function (sound) {
188         },
189 
190         /**
191          * [ABSTRACT] Set the volume of the given sound object
192          * @param sound {R.resources.types.Sound} The sound object
193          * @param volume {Number} A value between 0 and 100, with 0 being muted
194          */
195         setSoundVolume:function (sound, volume) {
196         },
197 
198         /**
199          * [ABSTRACT] Pan the given sound object from left to right
200          * @param sound {R.resources.types.Sound} The sound object
201          * @param pan {Number} A value between -100 and 100, with -100 being full left
202          *         and zero being center
203          */
204         setSoundPan:function (sound, pan) {
205         },
206 
207         /**
208          * [ABSTRACT] Set the position, within the sound's length, to play at
209          * @param sound {R.resources.types.Sound} The sound object
210          * @param millisecondOffset {Number} The millisecond offset from the start of
211          *         the sounds duration
212          */
213         setSoundPosition:function (sound, millisecondOffset) {
214         },
215 
216         /**
217          * [ABSTRACT] Get the position, in milliseconds, within a playing or paused sound
218          * @param sound {R.resources.types.Sound} The sound object
219          * @return {Number}
220          */
221         getSoundPosition:function (sound) {
222             return 0;
223         },
224 
225         /**
226          * [ABSTRACT] Get the size of the sound object, in bytes
227          * @param sound {R.resources.types.Sound} The sound object
228          * @return {Number}
229          */
230         getSoundSize:function (sound) {
231             return 0;
232         },
233 
234         /**
235          * [ABSTRACT] Get the length (duration) of the sound object, in milliseconds
236          * @param sound {R.resources.types.Sound} The sound object
237          * @return {Number}
238          */
239         getSoundDuration:function (sound) {
240             return 0;
241         },
242 
243         /**
244          * [ABSTRACT] Determine if the sound object is ready to be used
245          * @param sound {R.resources.types.Sound} The sound object
246          * @return {Boolean} <code>true</code> if the sound is ready
247          */
248         getSoundReadyState:function (sound) {
249             return false;
250         }
251 
252     });
253 }