sound.h

Go to the documentation of this file.

/*! \file
  \brief  The SoundSystem class for playback of audio files.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef INCLUDED_DISTI_SOUND_H
#define INCLUDED_DISTI_SOUND_H

#include "gls_cpp_lang_support.h"
#include "scoped_ptr.h"

namespace disti
{
///////////////////////////////////////////////////////////////////////////////////////////////////
class SoundSystem
{
public:
    /** Constructor
      * \param maxSounds  Maximum number of soundfiles in the sound system
      * \throw std::bad_alloc if unable to allocate memory.
      */
    DISTI_EXPORT explicit SoundSystem( int maxSounds );

    /** Destructor */
    DISTI_EXPORT ~SoundSystem();

    /** Returns whether the sound device was initialized sucessfully */
    DISTI_EXPORT bool IsValid() const;

    /** Plays the sound at the given index
      * \param which The zero based index of the sound to play
      */
    DISTI_EXPORT void Play( int which );

    /** Plays the sound at the given index,  attenuated for distancec
      * \param which The zero based index of the sound to play
      * \param volumeOrDistance The volume of the sound, from 0.0 (min) to FLT_MAX (max) or the
      *                         distance in meters of the sound, depending on the platform.
      */
    DISTI_EXPORT void Play( int which, float volumeOrDistance );

    /** Loads the sound from a file into a slot in the sound system
      * \param fn The name of the file to load from
      * \param index The zero based index to load the file into
      * \throw std::bad_alloc if unable to allocate memory
      */
    DISTI_EXPORT void LoadSound( const char* fn, int index );

    /** Loads a number of sounds from files into the sound system
      * The sounds are loaded sequentially starting at slot zero
      * \param firstArg Filenames to load, followed by a NULL
      * \throw std::bad_alloc if unable to allocate memory
      */
    DISTI_EXPORT void LoadSounds( const char* firstArg, ... );

    /** Deletes the sound from the given index
      * \param index Zero based index to clear
      */
    DISTI_EXPORT void ClearSound( int index );

    /** Sets the master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
     * \param volume The master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
     */
    DISTI_EXPORT void SetMasterVolume( float volume );

    /** Gets the master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
     * \return The master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
     */
    DISTI_EXPORT float GetMasterVolume() const;

    ///////////////////////////////////////////////////////////////////////////////////////////
    /// Base class for all platform-specific implementations of the sound system
    class ISoundSystemImpl
    {
    public:
        DISTI_EXPORT virtual bool IsValid() const = 0;
        DISTI_EXPORT virtual void LoadSound( const char* fileName, int index ) = 0;
        DISTI_EXPORT virtual void ClearSound( int index )         = 0;
        DISTI_EXPORT virtual void SetMasterVolume( float volume ) = 0;
        DISTI_EXPORT virtual float GetMasterVolume() const        = 0;
        DISTI_EXPORT virtual void Play( int index )               = 0;
        DISTI_EXPORT virtual void Play( int index, float volume ) = 0;

        DISTI_EXPORT virtual ~ISoundSystemImpl() {}

    protected:
        DISTI_EXPORT ISoundSystemImpl() {}

    private:
        // Disabled
        ISoundSystemImpl( const ISoundSystemImpl& ) DISTI_SPECIAL_MEM_FUN_DELETE;
        void operator=( const ISoundSystemImpl& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    };

private:
    // Pimpl idiom for platform-specific overrides
    // Note: The abstract base class + pimpl is an unusual construction, but it allows us to keep
    //       backwards compatibility with our existing code while swapping out the internals.
    ScopedPtr<ISoundSystemImpl> _impl;

    // The following are to be defined by the platform implementation. 
    // Only one should be present in any build of the GL Studio runtime.
    static ISoundSystemImpl* CreateSoundSystemImpl( int maxSounds );
    static const char* const s_errorMsg;

    // Copying/moving is disabled
    SoundSystem( const SoundSystem& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const SoundSystem& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
} // namespace disti

#endif