Difference between revisions of "Sound"

From AGI Wiki
Jump to navigationJump to search
Line 1: Line 1:
Sound
+
The '''sound''' command plays a loaded [[sound resource]].
  
 
+
== Syntax ==
  
== <br />Syntax ==
+
sound([[number|byt]] SOUNDNUM, [[flag|flg]] fDONE);
  
<blockquote><code>sound(SOUND_NUM,fDONE_FLAG);</code></blockquote>
+
== Remarks ==
  
== <br />Description ==
+
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.
  
Sound SOUND_NUM is played. fDONE_FLAG is reset when the command is issued, and set when the sound finishes playing or is stopped with the <code>[[stop.sound]]</code> command.
+
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]]).
  
The sound must be loaded before it is played. This can be done with the <code>[[load.sound]]</code> command.
+
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.
  
== <br />Sources ==
+
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.
  
[[AGI Studio Help File]]
+
== Possible Errors ==
  
== <br />See also ==
+
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.
  
* <code>[[load.sound]]</code>
+
== Example ==
* <code>[[stop.sound]]</code>
 
  
&nbsp;
+
<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>
  
[[Category:AGI Sound Resources]]
+
== Technical Information ==
[[Category:Logic]]
+
 
[[Category:AGI Logic]]
+
{| 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 />

Revision as of 21:44, 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' flagto 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

Code:

<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)

See Also

Sound Commands