Difference between revisions of "Sound"
| (4 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | The '''sound''' command plays a loaded [[sound resource]]. | |
| − | + | == Syntax == | |
| − | + | sound([[number|byt]] SOUNDNUM, [[flag|flg]] fDONE); | |
| − | + | == Remarks == | |
| − | + | When the '''sound''' command is called, AGI first checks to see if another [[Sound Resource (AGI)|sound]] is already playing. If so, AGI stops that sound (setting its 'done' [[flag]] to TRUE). Then [[flag]] '''fDONE''' is reset to FALSE. | |
| − | Sound | + | If the [[Sound Resource (AGI)|sound]] is valid, AGI then activates a vector function that begins asynchronously playing the sound (meaning it plays in the background while AGI continues to run through [[interpreter cycles]]). |
| − | + | If [[reserved flag]] [[f9 (sound enabled)]] is false, the [[Sound Resource (AGI)|sound]] won't play, but the check for f9 does not occur until after the vector function tries to play the sound; it immediately cancels playback of sound and then sets [[flag]] '''fDONE''' to true. | |
| − | + | When the [[Sound Resource (AGI)|sound]] stops playing for any reason (usually by reaching the end of the resource, or by issuing the '''[[stop.sound]]''' command) flag '''fDONE''' is set to TRUE. Other situations that will stop a sound from playing and set the 'done' flag are resetting [[f9 (sound enabled)]] to FALSE or using a '''[[pause]]''', '''[[quit]]''', '''[[new.room]]''', '''[[new.room.v]]''', '''[[restart.game]]''', '''[[restore.game]]''' or '''[[save.game]]''' command. If any [[trappable error]] is raised, the sound will also stop and have [[flag]] '''fDONE''' set to TRUE. | |
| − | + | == Possible Errors == | |
| − | + | After resetting '''fDONE''', AGI validates that sound resource '''SOUNDNUM''' is loaded. If it is not, AGI raises [[trappable error #9]] and the command ends without doing anything else. | |
| − | + | == Example == | |
| − | |||
| − | + | <div class="CodeBlockHeader">Code:</div> | |
| + | <syntaxhighlight lang="agi"> | ||
| + | load.sound(22); | ||
| + | sound(22, f99); | ||
| + | if(isset(f99)) | ||
| + | { | ||
| + | print("sound is done playing."); | ||
| + | reset(f99); | ||
| + | } | ||
| + | </syntaxhighlight> | ||
| − | [[ | + | == Technical Information == |
| − | [[Category: | + | |
| + | {| border="1" cellpadding="2" | ||
| + | | style="background-color: #efefef" width="200" | '''Required Interpreter Version:''' | ||
| + | | width="175" | Available in all AGI versions. | ||
| + | |- | ||
| + | | style="background-color: #efefef" | '''Byte-Code Value:''' | ||
| + | | 99 (0x63 hex) | ||
| + | |} | ||
| + | |||
| + | == See Also == | ||
| + | |||
| + | [[Sound Commands]]<br /> | ||
| + | [[Category:Commands]]<br /> | ||
Latest revision as of 21:49, 22 April 2019
The sound command plays a loaded sound resource.
Syntax
sound(byt SOUNDNUM, flg fDONE);
Remarks
When the sound command is called, AGI first checks to see if another sound is already playing. If so, AGI stops that sound (setting its 'done' flag to TRUE). Then flag fDONE is reset to FALSE.
If the sound is valid, AGI then activates a vector function that begins asynchronously playing the sound (meaning it plays in the background while AGI continues to run through interpreter cycles).
If reserved flag f9 (sound enabled) is false, the sound won't play, but the check for f9 does not occur until after the vector function tries to play the sound; it immediately cancels playback of sound and then sets flag fDONE to true.
When the sound stops playing for any reason (usually by reaching the end of the resource, or by issuing the stop.sound command) flag fDONE is set to TRUE. Other situations that will stop a sound from playing and set the 'done' flag are resetting f9 (sound enabled) to FALSE or using a pause, quit, new.room, new.room.v, restart.game, restore.game or save.game command. If any trappable error is raised, the sound will also stop and have flag fDONE set to TRUE.
Possible Errors
After resetting fDONE, AGI validates that sound resource SOUNDNUM is loaded. If it is not, AGI raises trappable error #9 and the command ends without doing anything else.
Example
<syntaxhighlight lang="agi"> load.sound(22); sound(22, f99); if(isset(f99))
{
print("sound is done playing.");
reset(f99);
}
</syntaxhighlight>
Technical Information
| Required Interpreter Version: | Available in all AGI versions. |
| Byte-Code Value: | 99 (0x63 hex) |
