cocos2d-X 节点（SimpleAudioEngine.h）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

cocos2d-X 节点（SimpleAudioEngine.h）API

温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记

///cocos2d-x-3.0alpha0/CocosDenshion/include


#ifndef _SIMPLE_AUDIO_ENGINE_H_
#define _SIMPLE_AUDIO_ENGINE_H_

#include <stddef.h>
#include "Export.h"
#include <typeinfo>
#include <ctype.h>
#include <string.h>

#if defined(__GNUC__) && ((__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1)))
#define CC_DEPRECATED_ATTRIBUTE __attribute__((deprecated))
#elif _MSC_VER >= 1400 //vs 2005 or higher
#define CC_DEPRECATED_ATTRIBUTE __declspec(deprecated)
#else
#define CC_DEPRECATED_ATTRIBUTE
#endif

namespace CocosDenshion {

/**
  @class          SimpleAudioEngine
  @brief          提供了非常简单的接口，播放背景音乐和声音效果。
  @note           确保调用 SimpleAudioEngine::end() 释放分配的资源时声音引擎不再需要.
 */

class EXPORT_DLL SimpleAudioEngine
{
public:
    /**
     @brief 获取共享的引擎对象,第一次调用时是会返回一个新的对象
     */
    static SimpleAudioEngine* getInstance();
    /**
     * @js NA
     * @lua NA
     */
    CC_DEPRECATED_ATTRIBUTE static SimpleAudioEngine* sharedEngine() { return SimpleAudioEngine::getInstance(); }

    /**
     @brief 释放共享的引擎对象
     @warning 他必须在应用退出前调用, 否则会造成一个内存泄漏.
     */
    static void end();

protected:
    SimpleAudioEngine();
    virtual ~SimpleAudioEngine();

public:

    /**
     @brief 预先加载背景音乐
     @param pszFilePath 背景音乐文件的路径.
     * @js preloadMusic
     * @lua preloadMusic
     */
    virtual void preloadBackgroundMusic(const char* pszFilePath);
    
    /**
     @brief 播放背景音乐
     @param pszFilePath 背景音乐文件的路径,或者 T_SoundResInfo 文件名
     @param bLoop 背景音乐是否循环播放
     * @js playMusic
     * @lua playMusic
     */
    virtual void playBackgroundMusic(const char* pszFilePath, bool bLoop = false);

    /**
     @brief 停止播放背景音乐
     @param bReleaseData 如果释放了背景音乐数据或没有背景音乐数据.默认值是 false
     * @js stopMusic
     * @lua stopMusic
     */
    virtual void stopBackgroundMusic(bool bReleaseData = false);

    /**
     @brief 暂停播放背景音乐 
     * @js pauseMusic
     * @lua pauseMusic
     */
    virtual void pauseBackgroundMusic();

    /**
     @brief 恢复播放背景音乐
     * @js resumeMusic
     * @lua resumeMusic
     */
    virtual void resumeBackgroundMusic();

    /**
     @brief Rewind 播放背景音乐       //快退
     * @js rewindMusic
     * @lua rewindMusic
     */
    virtual void rewindBackgroundMusic();

    /**
     @brief 是否可以播放背景音乐.
     @return true 可以播放背景音乐, otherwise false.
     * @js willPlayMusic
     * @lua willPlayMusic
     */
    virtual bool willPlayBackgroundMusic();

    /**
     @brief 表明是否正在播放背景音乐.
     @return true 如果背景音乐正在播放, otherwise false.
     * @js isMusicPlaying
     * @lua isMusicPlaying
     */
    virtual bool isBackgroundMusicPlaying();

    // 
    // properties
    //

    /**
     @brief 背景音乐的音量大小： 0.0 是极小值，1.0 是最大值.
     * @js getMusicVolume
     * @lua getMusicVolume
     */
    virtual float getBackgroundMusicVolume();

    /**
     @brief 设置背景音乐的音量
     @param 必须在 0.0 最小值，1.0 最大值之间.
     * @js setMusicVolume
     * @lua setMusicVolume
     */
    virtual void setBackgroundMusicVolume(float volume);

    /**
    @brief 获取音量大小（必须在 0.0 最小值，1.0 最大值之间.）.
    */
    virtual float getEffectsVolume();

    /**
    @brief 设置音量的声音效果 
    @param 必须在 0.0 最小值，1.0 最大值之间.
    */
    virtual void setEffectsVolume(float volume);

    // 
    // for sound effects

    /**
    @brief 使用 a file path, pitch, pan 、 gain 播放声音
    @param pszFilePath 效果文件的路径
    @param bLoop 确定是否循环播放. 默认值是 false
    @param pitch Frequency（音调频率）, 正常值是1.0.将改变效果的播放时间.
    @param pan   Stereo effect, in the range of [-1..1] where -1 enables only left channel.
    @param gain  Volume, 必须在 [0..1]的范围内. 正常值是 1.
    @return the OpenAL source id

    @note 在开发模式下都支持, 现在也有一些局限性:
        - OpenSL 启用后三星Galaxy S2无音调效果;
        - no pitch/pan/gain on emscrippten, win32, marmalade.
    */
    virtual unsigned int playEffect(const char* pszFilePath, bool bLoop = false,
                                    float pitch = 1.0f, float pan = 0.0f, float gain = 1.0f);

    /**
    @brief 暂停播放声音效果 
    @param nSoundId  playEffect 函数的返回值
    */
    virtual void pauseEffect(unsigned int nSoundId);

    /**
    @brief 暂停所有播放的声音效果
    */
    virtual void pauseAllEffects();

    /**
    @brief 恢复播放的声音效果
    @param nSoundId playEffect 函数的返回值
    */
    virtual void resumeEffect(unsigned int nSoundId);

    /**
    @brief 恢复所有播放的声音效果
    */
    virtual void resumeAllEffects();

    /**
    @brief 停止播放声音效果
    @param nSoundId playEffect 函数的返回值
    */
    virtual void stopEffect(unsigned int nSoundId);

    /**
    @brief 停止所有播放的声音效果
    */
    virtual void stopAllEffects();

    /**
    @brief          预先加载压缩声音文件
    @details        解压缩声音文件，并将他们写入到 SimpleAudioEngine 的内部缓冲区
    @param pszFilePath 音效文件的路径 
    */
    virtual void preloadEffect(const char* pszFilePath);

    /**
    @brief          从内部缓冲区卸载预装的音效 
    @param pszFilePath        音效文件的路径 
    */
    virtual void unloadEffect(const char* pszFilePath);
};

} // end of namespace CocosDenshion

#endif // _SIMPLE_AUDIO_ENGINE_H_