ＦＭＯＤ
三、音樂播放
Ａ、FMUSIC_PlaySong
例子：FMUSIC_MODULE *mod = 0;／／初始化
。。。
mod = FMUSIC_LoadSong("canyon.mid");／／加載音樂 。。。
FMUSIC_PlaySong(mod); ／／播放
以下是此函數詳細資料
／／／／／／／／／／／／／／／／／
Starts a song playing.
signed char F_API FMUSIC_PlaySong(
FMUSIC_MODULE *mod
);
Parameters
| mod | Pointer to the song to be played.
／／要播放歌曲指針 |
Return Value
TRUE song succeeded playing
FALSE song failed playing
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
Ｂ、FSOUND_PlaySound
例子：FSOUND_SAMPLE * notre_son；／／初始化
。。。。
notre_son = FSOUND_Sample_Load(FSOUND_FREE, "sound\\bgsound.mp3", FSOUND_NORMAL, 0, 0);／／加載
。。。。
FSOUND_PlaySound(0, notre_son);／／播放
以下是關于此函數的詳細說明
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
Plays a sample in a specified channel, using the sample's default frequency, volume
and pan settings.
／／用一個指定通道來播放例子，使用默認的頻率，音量，pan設置
int F_API FSOUND_PlaySound(
int channel,
FSOUND_SAMPLE *sptr
);
Parameters
| channel | 0+
The absolute channel number in the channel pool. ／／通道pool里的絕對通道號。
Remember software channels come first, followed by hardware channels. ／／記住軟通道使用在前，再接才是硬通道
You cannot play a software sample on a hardware channel and vice versa. ／／你不可以用一個硬通道來播放一個軟例子，反過來也一樣。
FSOUND_FREE
Chooses a free channel to play in. ／／選擇一個空閑通道來播放 If all channels are used then it
selects a channel with a sample playing that has an EQUAL or LOWER priority
than the sample to be played. ／／如果所有通道都被使用，則會選擇一個有EQUAL（平等）?或 LOWER（更低）優先權的通道來播放。
FSOUND_ALL
Passing this will cause ALL channels to play. (note this will make things
VERY noisy!) ／／使用它會導致所以通道播放。（這樣會很噪音）
If FSOUND_ALL is used the last channel success flag will be returned.
／／如果使用的是FSOUND_ALL ，返回的會是最后一個通道的成功標志。 |
| sptr | Pointer to the sample to be played.
／／要播放例子的指針 |
Return Value
On success, the channel handle that was selected is returned.
On failure, -1 is returned.
Remarks
If you play a FSOUND_HW3D declared sample with this function, then the position and velocity
are set to those of the listener.
／／如果用這個函數播放一個FSOUND_HW3D聲明例子，位置和速度被設置給傾聽者
Other attributes such as volume, frequency and pan are taken
from the sample's default volume, frequency, pan etc.
／／其他屬性如音量，頻率和pan從默認中獲取。
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
Basically
it means the only sound you can change the attributes (ie
volume/pan/frequency/3d position) for are the one you specifically
called playsound for. If another sound steals that channel, and you
keep trying to change its attributes (ie volume/pan/frequency/3d
position), it will do nothing.
This is great if you have sounds being updated from tasks and you just forget about it.
You
can keep updating the sound attributes and if another task steals that
channel, your original task wont change the attributes of the new
sound!!!
The lower 12 bits contain the channel number. (yes this means a 4096 channel limit for FMOD :)
The upper 19 bits contain the reference count.
The top 1 bit is the sign bit.
ie
S RRRRRRRRRRRRRRRRRRR CCCCCCCCCCCC
----------
Remember if not using FSOUND_FREE, then the channel pool is split up into software and hardware channels.
／／記住如果沒有正在使用FSOUND_FREE，之后通道pool會被分為軟件和硬件通道。
Software channels occupy the first n indicies specified by the value passed into FSOUND_Init.
Hardware channels occupy the next n indicies after this, and can be a variable amount, depending on the hardware.
／／軟通道占據用FSOUND_Init指定的Ｎ個 indicies 。硬通道分到之后Ｎ個 indicies ，可以有個有效量，取決于硬件
Use FSOUND_GetNumHardwareChannels to query how many channels are available in hardware.
／／可以使用FSOUND_GetNumHardwareChannels 去質問有多少通道在硬件中有效。
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
另：FSOUND_PlaySoundEx
例如：
channel = FSOUND_PlaySoundEx(FSOUND_FREE, samp2, NULL, TRUE);
以下是此函數的詳細資料
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
Extended featured version of FSOUND_PlaySound.
／／FSOUND_PlaySound的擴展版本
New functionality includes the ability to start the sound paused.
／／新函數包含開始聲音暫停的功能。
This allows attributes of a channel to be set
freely before the sound actually starts playing, until
FSOUND_SetPaused(FALSE) is used.
／／這個通道允許屬性在聲音真正播放前被設為自由。直到使用FSOUND_SetPaused(FALSE)。
Also added is the ability to associate the channel to a specified DSP unit.
／／同樣增加了分配通道到一個指定ＤＳＰ單元的功能。
This allows the user to 'group' channels into seperate DSP units,
which allows effects to be inserted between these 'groups', and allow
various things like having one group affected by reverb (wet mix) and
another group of channels unaffected (dry).
／／允許用戶把 'group' 通道分到可以把效果插入這些'group' 中的ＤＳＰ單元中，允許像有一組濕聲和另一組干聲明通道的各種方式。
This is useful to seperate things like music from being affected by DSP effects, while other sound effects are.
／／通常把如音樂的東西從ＤＳＰ效果分離。
int F_API FSOUND_PlaySoundEx(
int channel,
FSOUND_SAMPLE *sptr,
FSOUND_DSPUNIT *dspunit,
signed char startpaused
);
Parameters
| channel | 0+
The absolute channel number in the channel pool.
Remember software channels come first, followed by hardware channels.
You cannot play a software sample on a hardware channel and vice versa.
FSOUND_FREE
Chooses a free channel to play in. If all channels are used then it
selects a channel with a sample playing that has an EQUAL or LOWER priority
than the sample to be played.
FSOUND_ALL
Plays the sound on all channels.
／／同上 |
| sptr | Pointer to the sample to be played.
／／同上 |
| dspunit | Optional. NULL by default. Pointer to a dsp unit to attach the
channel to for channel grouping. Only attach a sound to a user created
DSP unit, and not a system DSP unit.
／／可選。默認為空。把一個dsp單元附加在通道上的指針。只有把聲音附加在一個用戶自建DSP單元，不是一個系統ＤＳＰ單元。 |
| paused | Start the sound paused or not. Pausing the sound allows attributes to be set before the sound starts.
／／是否開始聲音暫停。在聲音開始之前可以設置是否允許暫停。 |
Return Value
On success, the channel handle that was selected is returned.
On failure, -1 is returned.
Remarks
FSOUND_ALL is supported. Passing this will cause ALL channels to play. (note this could make things VERY noisy!)／／同上
If
FSOUND_ALL is used the last channel success flag will be returned. This
return value is not useful in most circumstances.／／如果是使用FSOUND_ALL
，返回的是最后通道值。返回值在大多情況下都沒有用。
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
This means the only sound you can change the attributes (ie volume/pan/frequency/3d position) for are the
one you specifically called playsound for. If another sound steals that channel, and you keep trying to
change its attributes (ie volume/pan/frequency/3d position), it will do nothing.
This is great if you have sounds being updated from tasks and you just forget about it.
You can keep updating the sound attributes and if another task steals that channel, your original task
wont change the attributes of the new sound!!!
The lower 12 bits contain the channel number. (yes this means a 4096 channel limit for FMOD :)
The upper 19 bits contain the reference count.
The top 1 bit is the sign bit.
ie
S RRRRRRRRRRRRRRRRRRR CCCCCCCCCCCC
----------
Remember if not using FSOUND_FREE, then the channel pool is split up into software and hardware channels.
Software channels occupy the first n indicies specified by the value passed into FSOUND_Init.
Hardware channels occupy the next n indicies after this, and can be a variable amount, depending on the hardware.
Use FSOUND_GetNumHardwareChannels to query how many channels are available in hardware.
／／同上
----------
If you attach a sound to a DSP unit (for
grouping purposes), the callback for the DSP unit will be overwritten
with fmod's internal mixer callback, so the callback the user supplied
is rendered obsolete and is not called.
Also, do not attach sounds to system DSP units, the assignment will be ignored if you do.
／／如果你把一個聲音附加在一個ＤＳＰ單元上，ＤＳＰ單元的回調將會被fmod的內在混合回調覆蓋，所以用戶提供的回調會作廢和不被調用，同時，不把聲音附加在系統ＤＳＰ單元，這個任務將會忽略。
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
Ｃ、FSOUND_Stream_Play
例子：FSOUND_Stream_Play(FSOUND_FREE, stream)
以下是此函數的詳細說明
／／／／／／／／／／／／／／／／／／／／／／／／／／／／／／
Starts a pre-opened stream playing.
int F_API FSOUND_Stream_Play(
int channel,
FSOUND_STREAM *stream
);
Parameters
| channel | 0+ The channel index in the channel pool. This must not exceed the maximum number of channels allocated with FSOUND_Init
FSOUND_FREE
Chooses a free channel to play in. If all channels are used then it
selects a channel with a sample playing that has a lower priority than the
sample to be played.
／／同上 |
| stream | Pointer to the already opened stream to be played.
／／要播放的已經打開的指針 |
Return Value
On success, the channel handle the stream is playing in is returned.
On failure, -1 is returned.
Remarks
When a stream starts to play, it inherits a special high priority (256).
／／當一個stream開始播放時，它繼承一個特別高的優先權（２５６）。
It cannot be rejected by
other sound effect channels in the normal fashion as the user can never
set a priority above 255 normally.
／／當用戶沒有設置一個低于256的正常優先權時，它不能被其他聲效通道以正常方式拒絕。
--------------
If the stream has been opened with FSOUND_NONBLOCKING, this function will not succeed until the stream is ready.
--------------
FSB
streaming is not supported if the format from FSBank is 'Retain
original format'. On PC platforms, only PCM and ADPCM FSB files are
allowed.
／／同前
--------------
FSOUND_STEREOPAN is recommended for stereo
streams if you call FSOUND_SetPan. This puts the left and right channel
to full volume.
／／如果你調用FSOUND_SetPan，FSOUND_STEREOPAN會被推薦給立體聲。他可以把左右聲道都調為最大音量。
Otherwise a normal pan will give half volume for left and right. See FSOUND_SetPan for more information on this.
／／相反一個正常pan會帶一半音量給左和右。查看FSOUND_SetPan 去了解更多信息。
--------------
You can use normal channel based commands (such as FSOUND_SetVolume etc) on the return handle, as it is a channel handle.
／／你可以用正常通道的基本命令到返回句柄上，當它是一個通道句柄時
另：FSOUND_Stream_PlayEx
例如：? channel = FSOUND_Stream_PlayEx(FSOUND_FREE, stream, NULL, TRUE);
以下是此函數的詳細說明
／／／／／／／／／／／／／／／／／／／／／／／
Extended featured version of FSOUND_Stream_Play.
Added functionality includes the ability to start the stream paused. This allows attributes
of a stream channel to be set freely before the stream actually starts playing, until FSOUND_SetPaused(FALSE) is used.
Also added is the ability to associate the stream channel to a specified DSP unit. This allows
the user to 'group' channels into seperate DSP units, which allows effects to be inserted
between these 'groups', and allow various things like having one group affected by reverb (wet mix) and another group of
channels unaffected (dry). This is useful to seperate things like music from being affected
by DSP effects, while other sound effects are.
／／同上
int F_API FSOUND_Stream_PlayEx(
int channel,
FSOUND_STREAM *stream,
FSOUND_DSPUNIT *dspunit,
signed char paused
);
Parameters
| channel | 0+
The absolute channel number in the channel pool.
Remember software channels come first, followed by hardware channels.
You cannot play a software sample on a hardware channel and vice versa.
FSOUND_FREE
Chooses a free channel to play in. If all channels are used then it
selects a channel with a sample playing that has an EQUAL or LOWER priority
than the sample to be played.
／／同上 |
| stream | Pointer to the already opened stream to be played.
／／同上 |
| dspunit | Pointer to a dsp unit to attach the channel to.
／／同上 |
| paused | Start the stream paused or not. Pausing the stream channel allows attributes to be set before it is unpaused.
／／同上 |
Return Value
On success, a channel handle the stream is playing in is returned.
On failure, -1 is returned.
Remarks
When a stream starts to play, it inherits a special high priority (256).
／／同上
It cannot be rejected by other sound effect channels in the
normal fashion as the user can never set a priority above 255 normally.
／／同上
--------
FSOUND_STEREOPAN is recommended for stereo
streams if you call FSOUND_SetPan. This puts the left and right channel
to full volume.
Otherwise a normal pan will give half volume for left and right. See FSOUND_SetPan for more information on this.
／／同上
--------
You can use normal channel based commands (such as FSOUND_SetVolume etc) on the return handle, as it is a channel handle.
／／同上