media_sound_SoundChannel.js.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Source: media/sound/SoundChannel.js</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Source: media/sound/SoundChannel.js</h1>

    
    <section>
        <article>
            <pre class="prettyprint source linenums"><code>//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------

/**
 * Creates a new sound channel. 
 *
 * @constructor
 * @package
 *
 * @param {boolean} [shared=false] Whether the channel should only use shared audio objects (true) or not (false).
 *
 * @class
 * @classdesc
 * 
 * The SoundChannel class represents an sound channel for playing sound effects 
 * and / or music. The class is used to create and bind Sound objects to the 
 * channel. Each Sound object must be connected to an audio channel in order to 
 * be played. There are two types of Sound objects; unique and shared. With 
 * shared Sound objects, it is possible to reuse the same object for several 
 * different sound sources. Note that there can be no multiple playbacks of a 
 * shared audio object at one time, in which case a unique object must be used.
 */
rune.media.SoundChannel = function(shared) {
    
    //--------------------------------------------------------------------------
    // Private properties
    //--------------------------------------------------------------------------
    
    /**
     * The audio context that represents the audio channel.
     *
     * @type {AudioContext}
     * @private
     */
    this.m_context = null;

    /**
     * Used for volume control.
     *
     * @type {GainNode}
     * @private
     */
    this.m_gain = null;
    
    /**
     * create stereo panner
     *
     * @type {StereoPannerNode}
     * @private
     */
    this.m_panner = null;
    
    /**
     * Playback rate.
     *
     * @type {number}
     * @private
     */
    this.m_rate = 1.0;
    
    /**
     * Whether the object is shared or not.
     *
     * @type {boolean}
     * @private
     */
    this.m_shared = Boolean(shared);

    /**
     * Register of created sound objects. 
     *
     * @type {Array.&lt;rune.media.Sound>}
     * @private
     */
    this.m_sounds = [];
    
    /**
     * Tween system.
     *
     * @type {rune.tween.Tweens}
     * @private
     */
    this.m_tweens = null;

    //--------------------------------------------------------------------------
    // Constructor call
    //--------------------------------------------------------------------------

    /**
     * Invokes secondary class constructor.
     */
    this.m_construct();
};

//------------------------------------------------------------------------------
// Public prototype getter and setter methods
//------------------------------------------------------------------------------

/**
 * Returns the number of Sound objects registered in the sound channel.
 *
 * @member {number} length
 * @memberof rune.media.SoundChannel
 * @instance
 * @readonly
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "length", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return this.m_sounds.length;
    }
});

/**
 * Whether all sounds in the sound channel are paused (true) or not (false).
 *
 * @member {boolean} paused
 * @memberof rune.media.SoundChannel
 * @instance
 * @readonly
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "paused", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return (this.m_context.state === "suspended");
    }
});

/**
 * Sets the rate at which the audio is being played back. The normal playback 
 * rate is multiplied by this value to obtain the current rate, so a value of 
 * 1.0 indicates normal speed.
 *
 * @member {number} rate
 * @memberof rune.media.SoundChannel
 * @instance
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "rate", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return this.m_rate;
    },
    
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    set : function(value) {
        this.m_rate = value;
        /*
        var i = this.m_sounds.length;
        while (i--) {
            this.m_sounds[i].rate = this.m_sounds[i].rate;
        }
        */
    }
});

/**
 * Returns whether the sound channel is limited to shared Sound objects only 
 * (true) or not (false). If the channel is "shared", all requests for unique 
 * Sound objects are denied.
 *
 * @member {boolean} shared
 * @memberof rune.media.SoundChannel
 * @instance
 * @readonly
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "shared", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return this.m_shared;
    }
});


/**
 * The global sound level for all Sound objects requested by this channel.
 *
 * @member {number} volume
 * @memberof rune.media.SoundChannel
 * @instance
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "volume", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return this.m_gain.gain.value;
    },
    
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    set : function(value) {
        this.m_gain.gain.value = rune.util.Math.clamp(value, 0.0, 1.0);
    }
});

//------------------------------------------------------------------------------
// Internal prototype getter and setter methods
//------------------------------------------------------------------------------

/**
 * The audio context.
 *
 * @member {boolean} context
 * @memberof rune.media.SoundChannel
 * @instance
 * @readonly
 * @package
 * @ignore
 */
Object.defineProperty(rune.media.SoundChannel.prototype, "context", {
    /**
     * @this rune.media.SoundChannel
     * @ignore
     */
    get : function() {
        return this.m_context;
    }
});

//------------------------------------------------------------------------------
// Public prototype methods (API)
//------------------------------------------------------------------------------

/**
 * Clears the current audio channel on Sound objects. This means that ongoing 
 * playback of Sound objects is stopped and all object references are destroyed.
 *
 * @returns {undefined}
 */
rune.media.SoundChannel.prototype.clear = function() {
    while (this.m_sounds.length) {
        this.remove(this.m_sounds[0], true);
    }
};

/**
 * Adjust the volume of the audio channel to a certain level.
 *
 * @param {number} to Target volume.
 * @param {number} duration Fade duration.
 *
 * @returns {undefined}
 */
rune.media.SoundChannel.prototype.fade = function(to, duration) {
    this.m_tweens.clear();
    this.m_tweens.create({
        target: this,
        transition: rune.tween.Sine.easeIn,
        duration: duration || 2500,
        args: {
            volume: to || 0
        }
    });
};

/**
 * Gets (and binds) a Sound object to the channel. The returned Sound object 
 * contains an interface for handling that particular sound, but all playback 
 * will be tied to the channel from which the object was created.
 *
 * @param {string} name The name of the resource file that the Sound object will use.
 * @param {boolean} [unique=false] Whether the object should be unique (true) or shared (false). 
 *
 * @returns {rune.media.Sound}
 */
rune.media.SoundChannel.prototype.get = function(name, unique) {
    if (this.m_shared) unique = false;
    if (!unique) {
        for (var i = 0; i &lt; this.m_sounds.length; i++) {
            if (this.m_sounds[i]['name'] == name &amp;&amp; !this.m_sounds[i]['unique']) {
                return this.m_sounds[i];
            }
        }   
    }
    
    var sound = new rune.media.Sound(this, name, unique);
    sound.connect(this.m_panner);
    this.m_sounds.push(sound);
    
    return sound;
};

/**
 * Pauses playback of all Sound objects on this channel.
 *
 * @returns {undefined}
 */
rune.media.SoundChannel.prototype.pause = function() {
    if (this.m_context &amp;&amp; this.m_context.state === "running") {
        this.m_context.suspend();
    }
};

/**
 * Removes a Sound object from the channel. By default, objects are removed 
 * from the channel, but retained in memory. Set the dispose argument to true 
 * to destroy the object as it is removed from the channel. If the object is 
 * destroyed, a null reference is returned.
 *
 * @param {rune.media.Sound} sound Sound object to remove.
 * @param {boolean} dispose Whether the object should be deallocated.
 *
 * @returns {rune.media.Sound}
 */
rune.media.SoundChannel.prototype.remove = function(sound, dispose) {
    var index = this.m_sounds.indexOf(sound);
    if (index > -1) {
        this.m_sounds.splice(index, 1);
        if (dispose) {
            sound.dispose();
            sound = null;
        }
    } 
    
    return sound; 
};

/**
 * Resumes playback of all Sound objects on this channel.
 *
 * @returns {undefined}
 */
rune.media.SoundChannel.prototype.resume = function() {
    if (this.m_context &amp;&amp; this.m_context.state === "suspended") {
        this.m_context.resume();
    }
};

//------------------------------------------------------------------------------
// Internal prototype methods
//------------------------------------------------------------------------------

/**
 * Updating the sound channel.
 *
 * @param {number} step Current time stamp.
 *
 * @returns {undefined}
 * @package
 * @ignore
 */
rune.media.SoundChannel.prototype.update = function(step) {
    this.m_updateSounds(step);
    this.m_updateTweens(step);
};

/**
 * Removes the sound channel and clears memory allocated by it.
 *
 * @returns {undefined}
 * @package
 * @ignore
 */
rune.media.SoundChannel.prototype.dispose = function() {
    this.m_disposeSounds();
    this.m_disposePanner();
    this.m_disposeGain();
    this.m_disposeContext();
};

//------------------------------------------------------------------------------
// Protected prototype methods
//------------------------------------------------------------------------------

/**
 * The class constructor.
 *
 * @returns {undefined}
 * @protected
 * @ignore
 */
rune.media.SoundChannel.prototype.m_construct = function() {
    this.m_constructContext();
    this.m_constructGain();
    this.m_constructPanner();
    this.m_constructTweens();
};

//------------------------------------------------------------------------------
// Private prototype methods
//------------------------------------------------------------------------------

/**
 * Creates the audio context.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_constructContext = function() {
    this.m_disposeContext();
    if (this.m_context == null) {
        this.m_context = new AudioContext();
    } else throw new Error();
};

/**
 * Creates the gain node.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_constructGain = function() {
    this.m_disposeGain();
    if (this.m_gain == null &amp;&amp; this.m_context != null) {
        this.m_gain = this.m_context.createGain();
        this.m_gain.connect(this.m_context.destination);
    } else throw new Error();
};

/**
 * Creates the panner node.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_constructPanner = function() {
    this.m_disposePanner();
    if (this.m_panner == null &amp;&amp; this.m_gain != null) {
        this.m_panner = this.m_context.createStereoPanner();
        this.m_panner.connect(this.m_gain);
    } else throw new Error();
};

/**
 * Creates the Tween system.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_constructTweens = function() {
    this.m_disposeTweens();
    if (this.m_tweens == null) {
        this.m_tweens = new rune.tween.Tweens();
    } else throw new Error();
};

/**
 * Updates Sound objects.
 *
 * @param {number} step Current time stamp.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_updateSounds = function(step) {
    var i = this.m_sounds.length;
    while (i--) {
        this.m_sounds[i].update(step);
    }
};

/**
 * Updates the Tween system.
 *
 * @param {number} step Current time stamp.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_updateTweens = function(step) {
    if (this.m_tweens) {
        this.m_tweens.update(step);
    }
};

/**
 * Removes the Tween system.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_disposeTweens = function() {
    if (this.m_tweens instanceof rune.tween.Tweens) {
        this.m_tweens.dispose();
        this.m_tweens = null;
    }
};

/**
 * Removes registered Sound objects.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_disposeSounds = function() {
    while (this.m_sounds.length) {
        this.remove(this.m_sounds[0], true);
    }
    
    this.m_sounds = null;
};

/**
 * Removes the panner node.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_disposePanner = function() {
    if (this.m_panner != null) {
        this.m_panner.disconnect();
        this.m_panner = null;
    }
};

/**
 * Removes the gain node.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_disposeGain = function() {
    if (this.m_gain != null) {
        this.m_gain.disconnect();
        this.m_gain = null;
    }
};

/**
 * Removes the audio context.
 *
 * @returns {undefined}
 * @private
 */
rune.media.SoundChannel.prototype.m_disposeContext = function() {
    if (this.m_context != null) {
        this.m_context.close();
        this.m_context = null;
    }
};</code></pre>
        </article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="rune.html">rune</a></li><li><a href="rune.animation.html">animation</a></li><li><a href="rune.camera.html">camera</a></li><li><a href="rune.color.html">color</a></li><li><a href="rune.console.html">console</a></li><li><a href="rune.data.html">data</a></li><li><a href="rune.debug.html">debug</a></li><li><a href="rune.display.html">display</a></li><li><a href="rune.geom.html">geom</a></li><li><a href="rune.input.html">input</a></li><li><a href="rune.media.html">media</a></li><li><a href="rune.net.html">net</a></li><li><a href="rune.particle.html">particle</a></li><li><a href="rune.physics.html">physics</a></li><li><a href="rune.resource.html">resource</a></li><li><a href="rune.scene.html">scene</a></li><li><a href="rune.state.html">state</a></li><li><a href="rune.system.html">system</a></li><li><a href="rune.text.html">text</a></li><li><a href="rune.tilemap.html">tilemap</a></li><li><a href="rune.timer.html">timer</a></li><li><a href="rune.tween.html">tween</a></li><li><a href="rune.ui.html">ui</a></li><li><a href="rune.util.html">util</a></li></ul><h3>Classes</h3><ul><li><a href="rune.animation.Animation.html">Animation</a></li><li><a href="rune.animation.Animations.html">Animations</a></li><li><a href="rune.animation.AnimationScripts.html">AnimationScripts</a></li><li><a href="rune.camera.Camera.html">Camera</a></li><li><a href="rune.camera.CameraFade.html">CameraFade</a></li><li><a href="rune.camera.CameraFlash.html">CameraFlash</a></li><li><a href="rune.camera.Cameras.html">Cameras</a></li><li><a href="rune.camera.CameraShake.html">CameraShake</a></li><li><a href="rune.camera.CameraTargets.html">CameraTargets</a></li><li><a href="rune.camera.CameraTint.html">CameraTint</a></li><li><a href="rune.camera.CameraTintTween.html">CameraTintTween</a></li><li><a href="rune.camera.CameraViewport.html">CameraViewport</a></li><li><a href="rune.color.Color24.html">Color24</a></li><li><a href="rune.color.Color32.html">Color32</a></li><li><a href="rune.color.ColorComponent.html">ColorComponent</a></li><li><a href="rune.console.Console.html">Console</a></li><li><a href="rune.console.ConsoleCommand.html">ConsoleCommand</a></li><li><a href="rune.console.ConsoleCommands.html">ConsoleCommands</a></li><li><a href="rune.console.ConsoleCursor.html">ConsoleCursor</a></li><li><a href="rune.console.ConsoleHistory.html">ConsoleHistory</a></li><li><a href="rune.console.ConsoleInput.html">ConsoleInput</a></li><li><a href="rune.console.ConsoleManager.html">ConsoleManager</a></li><li><a href="rune.console.ConsoleOutput.html">ConsoleOutput</a></li><li><a href="rune.data.Highscores.html">Highscores</a></li><li><a href="rune.data.Loader.html">Loader</a></li><li><a href="rune.data.LoaderDebug.html">LoaderDebug</a></li><li><a href="rune.data.Logo.html">Logo</a></li><li><a href="rune.data.Requests.html">Requests</a></li><li><a href="rune.debug.Debugger.html">Debugger</a></li><li><a href="rune.debug.Framerate.html">Framerate</a></li><li><a href="rune.debug.Histogram.html">Histogram</a></li><li><a href="rune.debug.Master.html">Master</a></li><li><a href="rune.debug.Memory.html">Memory</a></li><li><a href="rune.debug.Music.html">Music</a></li><li><a href="rune.debug.Render.html">Render</a></li><li><a href="rune.debug.Sound.html">Sound</a></li><li><a href="rune.debug.Update.html">Update</a></li><li><a href="rune.display.Artboard.html">Artboard</a></li><li><a href="rune.display.Canvas.html">Canvas</a></li><li><a href="rune.display.DisplayGroup.html">DisplayGroup</a></li><li><a href="rune.display.DisplayGroups.html">DisplayGroups</a></li><li><a href="rune.display.DisplayObject.html">DisplayObject</a></li><li><a href="rune.display.DisplayObjectContainer.html">DisplayObjectContainer</a></li><li><a href="rune.display.Flicker.html">Flicker</a></li><li><a href="rune.display.Frame.html">Frame</a></li><li><a href="rune.display.Graphic.html">Graphic</a></li><li><a href="rune.display.Graphics.html">Graphics</a></li><li><a href="rune.display.Hitbox.html">Hitbox</a></li><li><a href="rune.display.InteractiveObject.html">InteractiveObject</a></li><li><a href="rune.display.Quadtree.html">Quadtree</a></li><li><a href="rune.display.RepeatedGraphic.html">RepeatedGraphic</a></li><li><a href="rune.display.Screen.html">Screen</a></li><li><a href="rune.display.Sprite.html">Sprite</a></li><li><a href="rune.display.Stage.html">Stage</a></li><li><a href="rune.display.Texture.html">Texture</a></li><li><a href="rune.geom.Point.html">Point</a></li><li><a href="rune.geom.Rectangle.html">Rectangle</a></li><li><a href="rune.geom.Vector2D.html">Vector2D</a></li><li><a href="rune.input.Gamepad.html">Gamepad</a></li><li><a href="rune.input.Gamepads.html">Gamepads</a></li><li><a href="rune.input.GamepadsOptions.html">GamepadsOptions</a></li><li><a href="rune.input.Inputs.html">Inputs</a></li><li><a href="rune.input.Keyboard.html">Keyboard</a></li><li><a href="rune.input.KeyboardKey.html">KeyboardKey</a></li><li><a href="rune.input.KeyboardOptions.html">KeyboardOptions</a></li><li><a href="rune.media.Sound.html">Sound</a></li><li><a href="rune.media.SoundChannel.html">SoundChannel</a></li><li><a href="rune.media.Sounds.html">Sounds</a></li><li><a href="rune.net.URLLoader.html">URLLoader</a></li><li><a href="rune.net.URLRequest.html">URLRequest</a></li><li><a href="rune.net.URLResponse.html">URLResponse</a></li><li><a href="rune.particle.Emitter.html">Emitter</a></li><li><a href="rune.particle.EmitterOptions.html">EmitterOptions</a></li><li><a href="rune.particle.Particle.html">Particle</a></li><li><a href="rune.physics.Space.html">Space</a></li><li><a href="rune.physics.Velocity.html">Velocity</a></li><li><a href="rune.resource.Request.html">Request</a></li><li><a href="rune.resource.Requester.html">Requester</a></li><li><a href="rune.resource.RequesterOptions.html">RequesterOptions</a></li><li><a href="rune.resource.Requests.html">Requests</a></li><li><a href="rune.resource.Resource.html">Resource</a></li><li><a href="rune.resource.Resources.html">Resources</a></li><li><a href="rune.scene.Scene.html">Scene</a></li><li><a href="rune.scene.Scenes.html">Scenes</a></li><li><a href="rune.state.State.html">State</a></li><li><a href="rune.state.States.html">States</a></li><li><a href="rune.system.Application.html">Application</a></li><li><a href="rune.system.Config.html">Config</a></li><li><a href="rune.system.Time.html">Time</a></li><li><a href="rune.text.BitmapField.html">BitmapField</a></li><li><a href="rune.text.BitmapFormat.html">BitmapFormat</a></li><li><a href="rune.tilemap.Block.html">Block</a></li><li><a href="rune.tilemap.Tile.html">Tile</a></li><li><a href="rune.tilemap.Tilemap.html">Tilemap</a></li><li><a href="rune.tilemap.TilemapLayer.html">TilemapLayer</a></li><li><a href="rune.timer.Timer.html">Timer</a></li><li><a href="rune.timer.TimerOptions.html">TimerOptions</a></li><li><a href="rune.timer.Timers.html">Timers</a></li><li><a href="rune.tween.Circular.html">Circular</a></li><li><a href="rune.tween.Cubic.html">Cubic</a></li><li><a href="rune.tween.Expo.html">Expo</a></li><li><a href="rune.tween.Linear.html">Linear</a></li><li><a href="rune.tween.Quad.html">Quad</a></li><li><a href="rune.tween.Quart.html">Quart</a></li><li><a href="rune.tween.Quint.html">Quint</a></li><li><a href="rune.tween.Sine.html">Sine</a></li><li><a href="rune.tween.Tween.html">Tween</a></li><li><a href="rune.tween.Tweens.html">Tweens</a></li><li><a href="rune.tween.TweenValue.html">TweenValue</a></li><li><a href="rune.ui.Counter.html">Counter</a></li><li><a href="rune.ui.CounterDigit.html">CounterDigit</a></li><li><a href="rune.ui.Progressbar.html">Progressbar</a></li><li><a href="rune.ui.VTList.html">VTList</a></li><li><a href="rune.ui.VTListElement.html">VTListElement</a></li><li><a href="rune.ui.VTMenu.html">VTMenu</a></li><li><a href="rune.ui.VTMenuPointer.html">VTMenuPointer</a></li><li><a href="rune.util.Executable.html">Executable</a></li><li><a href="rune.util.Filter.html">Filter</a></li><li><a href="rune.util.Math.html">Math</a></li><li><a href="rune.util.Palette.html">Palette</a></li><li><a href="rune.util.Path.html">Path</a></li><li><a href="rune.util.Paths.html">Paths</a></li><li><a href="rune.util.Stack.html">Stack</a></li><li><a href="rune.util.URL.html">URL</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com./jsdoc/jsdoc">JSDoc 3.6.11</a> on Tue Apr 01 2025 09:55:09 GMT+0200 (Central European Summer Time)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>