Skip to content

Commit

Permalink
Merge pull request #224 from YoYoGames/develop.bart
Browse files Browse the repository at this point in the history 
Clarifications on playing audio queues, sound mixer volume, event order, CE2 shortcuts, debug_mode undeprecated
  • Loading branch information
@gurpreetsinghmatharoo
gurpreetsinghmatharoo authored Dec 6, 2024
2 parents 24d9c4e + 3e3f93e commit d8d6e04
Show file tree
Hide file tree
Showing 49 changed files with 706 additions and 284 deletions.
20 changes: 10 additions & 10 deletions ...ontents/GameMaker_Language/GML_Overview/Variables/Builtin_Global_Variables/async_load.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>async_load</title>
<meta name="generator" content="Adobe RoboHelp 2020" />
<meta name="generator" content="Adobe RoboHelp 2022" />
<link rel="stylesheet" href="../../../../assets/css/default.css" type="text/css" />
<script src="../../../../assets/scripts/main_script.js" type="module"></script>
<meta name="rh-authors" content="Mark Alexander" />
Expand All @@ -14,37 +14,37 @@
</head>
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>async_load</h1>
<p>This variable is <b>global</b> in scope and is used to hold a <a href="../../../GML_Reference/Data_Structures/DS_Maps/DS_Maps.htm">DS map</a> when used in the <a href="../../../../The_Asset_Editors/Object_Properties/Async_Events.htm">Asynchronous Events</a>, and -1 at all other times. The actual contents of the DS map will depend on the type of asynchronous event <a class="glossterm" data-glossterm="callback" href="#">callback</a>, as well as the function that was used to trigger the event, so refer to the individual pages for those events for full details of all the possible DS map contents.</p>
<h1><span data-field="title" data-format="default">async_load</span></h1>
<p>This variable is <b>global</b> in scope and is used to hold a <span data-keyref="Type_ID_DS_Map"><a href="../../../GML_Reference/Data_Structures/DS_Maps/ds_map_create.htm" target="_blank">DS Map</a></span> when used in the <a href="../../../../The_Asset_Editors/Object_Properties/Async_Events.htm">Asynchronous Events</a>, and -1 at all other times. The actual contents of the DS map will depend on the type of asynchronous event <a class="glossterm" data-glossterm="callback" href="#">callback</a>, as well as the function that was used to trigger the event, so refer to the individual pages for those events for full details of all the possible DS map contents.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">async_load;</p>
<p class="code"><span data-field="title" data-format="default">async_load</span></p>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_ID_DS_Map">DS Map ID</span></p>
<p class="code"><span data-keyref="Type_ID_DS_Map"><a href="../../../GML_Reference/Data_Structures/DS_Maps/ds_map_create.htm" target="_blank">DS Map</a></span></p>
<p> </p>
<h4>Extended Example:</h4>
<p class="code">sprite =  sprite_add(&quot;site.com/path/image.png&quot;, 16, true, true, 0, 0);</p>
<p>The above code would be called in an event to load a sprite from an external URL. This would then trigger the <strong>Image Loaded</strong> Asynchronous Event, where you would parse the <span class="inline">async_load</span> map:</p>
<p class="code">if (ds_map_find_value(async_load, &quot;id&quot;) == sprite) <br />
<p>The above code would be called in an event to load a sprite from an external URL. This would then trigger the <strong>Image Loaded</strong> Asynchronous Event, where you would parse the <span class="inline2"><span data-field="title" data-format="default">async_load</span></span> map:</p>
<p class="code">if (ds_map_find_value(async_load, &quot;id&quot;) == sprite)<br />
{<br />
    if (ds_map_find_value(async_load, &quot;status&quot;) &gt;= 0)<br />
    {<br />
        sprite_index = sprite;<br />
    }<br />
}</p>
<p>The above code will first check the ID of the <span class="inline">async_load</span> map, then check the status of the callback. If the value is greater than or equal to 0 (signalling success) the result from the callback will then be used to set the sprite index of the instance to the newly loaded image.</p>
<p>The above code will first check the ID of the <span class="inline2"><span data-field="title" data-format="default">async_load</span></span> map, then check the status of the callback. If the value is greater than or equal to 0 (signalling success) the result from the callback will then be used to set the sprite index of the instance to the newly loaded image.</p>
<p> </p>
<p> </p>
<p> </p>
<div class="footer">
<div class="buttons">
<div class="clear">
<div style="float:left">Back: <a href="../Global_Variables.htm">Global Variables</a></div>
<div style="float:left">Back: <a data-xref="{title}" href="../Global_Variables.htm">Global Variables</a></div>
<div style="float:right">Next: <a data-xref="{title}" href="../../../GML_Reference/Game_Input/Gesture_Input/event_data.htm">event_data</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2022 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
async_load
Expand Down
33 changes: 16 additions & 17 deletions ...s/GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio_Buffers/Audio_Buffers.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,37 +14,36 @@
</head>
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>Audio Buffers</h1>
<h1><span data-field="title" data-format="default">Audio Buffers</span></h1>
<p>You can use <b>audio buffers</b> to load, save and manipulate audio files within your games. These buffers are created beforehand using the appropriate <a href="../../../Buffers/Buffers.htm">buffer functions</a> and then you can use the following functions to create a sound to use in your project:</p>
<ul class="colour">
<li><a href="audio_create_buffer_sound.htm">audio_create_buffer_sound</a></li>
<li><a href="audio_free_buffer_sound.htm">audio_free_buffer_sound</a></li>
<li><a data-xref="{title}" href="audio_create_buffer_sound.htm">audio_create_buffer_sound</a></li>
<li><a data-xref="{title}" href="audio_free_buffer_sound.htm">audio_free_buffer_sound</a></li>
</ul>
<p> </p>
<p>Note that once you have created a sound from an audio buffer, you are <i>not</i> creating a new sound in memory, but rather pointing to the position within the buffer where the sound is stored. You should not change this buffer after a sound has been associated with it otherwise you will get unexpected results, and you cannot delete the buffer while a sound is associated with it. Instead, free the sound (or sounds) first then delete the buffer.</p>
<p>Once you have created your new audio resource from a buffer, you can use its handle in any of the regular audio functions to play it, change its gain or pitch, pause it, etc. Note that the buffer used to load the audio <b>can only support PCM sounds</b>, so formats like OGG will not be supported.</p>
<p>When you create a sound from an audio buffer, you are <i>not</i> creating a new sound in memory, but rather pointing to the position within the buffer where the sound is stored. You should not change this buffer after a sound has been associated with it otherwise you will get unexpected results, and you cannot delete the buffer while a sound is associated with it. Instead, free the sound (or sounds) first then delete the buffer.</p>
<p>Once you have created your new audio resource from a buffer, you can use its handle in any of the regular audio functions to play it, change its gain or pitch, pause it, etc.</p>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_note.hts"> </span> The buffer used to load the audio <b>can only support PCM sounds</b>, so formats like OGG are not supported.</p>
<h2>Audio Buffer Queues</h2>
<p>Another feature of buffered audio is that you can use a buffer to create a queue of audio which can then be streamed to the device running your project. An audio queue takes a regular buffer which you have previously filled with audio data, and enables you to &quot;point&quot; to parts of it and tell <span data-keyref="GameMaker Name">GameMaker</span> to stream the audio in a given order from that buffer. The available functions for audio queues are:</p>
<ul class="colour">
<li><a href="audio_create_play_queue.htm">audio_create_play_queue</a></li>
<li><a href="audio_free_play_queue.htm">audio_free_play_queue</a></li>
<li><a href="audio_queue_sound.htm">audio_queue_sound</a></li>
<li><a data-xref="{title}" href="audio_create_play_queue.htm">audio_create_play_queue</a></li>
<li><a data-xref="{title}" href="audio_free_play_queue.htm">audio_free_play_queue</a></li>
<li><a data-xref="{title}" href="audio_queue_sound.htm">audio_queue_sound</a></li>
</ul>
<p>Once a queue has been created, you can then use the returned queue index just as you would the sound index for any normal sound to play it, pause it, restart it, or change it&#39;s gain and pitch. The only thing you cannot do is get the track length or set the track position, but other than that, an audio queue can be used just like any other sound. You should also note that some of the audio queue functions will also trigger an <a href="../../../../../The_Asset_Editors/Object_Properties/Async_Events/Audio_Playback.htm">Audio Playback Asynchronous Event</a>.</p>
<p>Once a queue has been created, you can then use the returned queue index just as you would the sound index for any normal sound to play it, pause it, or change its gain and pitch. The few things you cannot do are get the track length, set the track position or use the loop functions, but other than that, an audio queue can be used just like any other sound. You should also note that some of the audio queue functions will also trigger an <a href="../../../../../The_Asset_Editors/Object_Properties/Async_Events/Audio_Playback.htm">Audio Playback Asynchronous Event</a>.</p>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_note.hts"> </span> Attempting to play an empty queue using the <span class="inline">audio_play_sound*</span> functions will not play anything and return a sound instance index of -1. You can queue new audio data after a queue has become empty and then play a new sound from the queue (creating a new sound instance).</p>
<h2>Recording</h2>
<p>Audio buffers will also permit you to record sound from any of the available sources (like microphones), which can then be queued and streamed using the above functions (for example). Recording audio will trigger an <a href="../../../../../The_Asset_Editors/Object_Properties/Async_Events/Audio_Recording.htm">Audio Recording Asynchronous Event</a> which will contain specific information about what is being recorded.<br />
<br />
For recording audio, the following functions are available:
</p>
<ul class="colour">
<li><a href="audio_start_recording.htm">audio_start_recording</a></li>
<li><a href="audio_stop_recording.htm">audio_stop_recording</a></li>
<li><a href="audio_get_recorder_count.htm">audio_get_recorder_count</a></li>
<li><a href="audio_get_recorder_info.htm">audio_get_recorder_info</a></li>
<li><a data-xref="{title}" href="audio_start_recording.htm">audio_start_recording</a></li>
<li><a data-xref="{title}" href="audio_stop_recording.htm">audio_stop_recording</a></li>
<li><a data-xref="{title}" href="audio_get_recorder_count.htm">audio_get_recorder_count</a></li>
<li><a data-xref="{title}" href="audio_get_recorder_info.htm">audio_get_recorder_info</a></li>
</ul>
<p> </p>
<p class="note"><b><span class="note">NOTE</span> </b>Most platforms <b>except HTML5</b> support recording audio in some form, but that does not mean that all devices will permit it, even if the platform does, so you should always check that the <span style="font-size:1px;"><a href="audio_get_recorder_count.htm"><span class="inline">audio_get_recorder_count()</span></a></span> function returns a value greater than 0 to verify that recording devices are available before using the rest of the recording functions.</p>
<p> </p>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_note.hts"> </span> Most platforms <b>except HTML5</b> support recording audio in some form, but that does not mean that all devices will permit it, even if the platform does, so you should always check that the <span style="font-size:1px;"><a href="audio_get_recorder_count.htm"><span class="inline">audio_get_recorder_count()</span></a></span> function returns a value greater than 0 to verify that recording devices are available before using the rest of the recording functions.</p>
<p> </p>
<p> </p>
<div class="footer">
Expand Down
2 changes: 1 addition & 1 deletion ...r_Language/GML_Reference/Asset_Management/Audio/Audio_Buffers/audio_create_play_queue.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>audio_create_play_queue</h1>
<p>This function prepares a buffer queue for audio. You pass data format (only <span class="inline">buffer_u8</span> or <span class="inline">buffer_s16</span> are currently supported), the sample rate (which can be between 1000hz and 48000hz), and the channels that the audio requires from one of the constants listed below:</p>
<p>This function prepares a buffer queue for audio. You pass the data format (only <span class="inline">buffer_u8</span> or <span class="inline">buffer_s16</span> are currently supported), the sample rate (which can be between 1000Hz and 48000Hz), and the channels that the audio requires from one of the constants listed below:</p>
<table>
<tbody>
<tr>
Expand Down
6 changes: 3 additions & 3 deletions ...ker_Language/GML_Reference/Asset_Management/Audio/Audio_Buffers/audio_free_play_queue.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>audio_free_play_queue</h1>
<p>This function is used to free up the memory associated with the given audio queue. The queue index is the value returned when you created the queue using the function <a href="audio_create_play_queue.htm"><span class="inline">audio_create_play_queue()</span></a>, and this function should be called when the queue is no longer required to prevent memory leaks. Freeing the queue will stop any sound that is be playing, and you cannot delete the buffer that a sound is being streamed from until the queue it is assigned to has been freed.</p>
<p>This function is used to free up the memory associated with the given audio queue. The queue index is the value returned when you created the queue using the function <a href="audio_create_play_queue.htm"><span class="inline">audio_create_play_queue()</span></a>, and this function should be called when the queue is no longer required to prevent memory leaks. Freeing the queue will stop any sound that is playing, and you cannot delete the buffer that a sound is being streamed from until the queue it is assigned to has been freed.</p>
<p>This function will trigger an <a href="../../../../../The_Asset_Editors/Object_Properties/Async_Events/Audio_Playback.htm">Audio Playback Asynchronous Event</a>, and in this event a special <a href="../../../Data_Structures/DS_Maps/DS_Maps.htm">DS map</a> will be created in the variable <a href="../../../../GML_Overview/Variables/Builtin_Global_Variables/async_load.htm"><span class="inline">async_load</span></a> with the following key/value pairs:</p>
<ul class="colour">
<li>&quot;<strong>queue_id</strong>&quot; - the queue that has finished playing data</li>
Expand All @@ -34,7 +34,7 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>queueIndex</td>
<td><span data-keyref="Type_ID_Audio_Queue"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio_Buffers/audio_create_play_queue.htm" target="_blank">Audio Queue ID</a></span></td>
<td><span data-keyref="Type_ID_Audio_Queue"><a href="audio_create_play_queue.htm" target="_blank">Audio Queue ID</a></span></td>
<td>The index of the queue to free.</td>
</tr>
</tbody>
Expand All @@ -61,7 +61,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="audio_queue_sound.htm">audio_queue_sound</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
audio_free_play_queue
Expand Down
2 changes: 1 addition & 1 deletion ...aker_Language/GML_Reference/Asset_Management/Audio/Audio_Emitters/audio_play_sound_on.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ <h4>Syntax:</h4>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="../audio_play_sound.htm" target="_blank">Sound Instance ID</a></span></p>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="../audio_play_sound.htm" target="_blank">Sound Instance ID</a></span> (or -1 if the sound could not be played)</p>
<p> </p>
<h4>Example 1:</h4>
<p class="code">if (global.SFX)<br />
Expand Down
5 changes: 3 additions & 2 deletions ...nts/GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio_Groups/Audio_Groups.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Audio Groups</title>
<meta name="generator" content="Adobe RoboHelp 2020" />
<meta name="generator" content="Adobe RoboHelp 2022" />
<link rel="stylesheet" href="../../../../../assets/css/default.css" type="text/css" />
<script src="../../../../../assets/scripts/main_script.js" type="module"></script>
<meta name="rh-authors" content="Mark Alexander" />
Expand All @@ -19,6 +19,7 @@ <h1><span data-field="title" data-format="default">Audio Groups</span></h1>
<p>You can create these <strong>audio groups</strong> from the <a data-xref="{title}" href="../../../../../Settings/Audio_Groups.htm">Audio Groups</a> window - which can be opened from <a data-xref="{title}" href="../../../../../IDE_Navigation/Menus/The_Tools_Menu.htm">The Tools Menu</a> at the top of the IDE - and you can assign your audio assets to a specific group from the <a href="../../../../../The_Asset_Editors/Sounds.htm">Sound Properties Window</a>.</p>
<p>Each audio group has its own gain. The gain of all sounds in an audio group is multiplied by that audio group&#39;s gain. The default value is 1 but it can be changed using <span class="inline2"><a data-xref="{title}" href="audio_group_set_gain.htm">audio_group_set_gain</a></span> and retrieved using <span class="inline2"><a data-xref="{title}" href="audio_group_get_gain.htm">audio_group_get_gain</a></span> respectively.</p>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_note.hts"> </span> All audio groups can be accessed in code through a constant that <span data-keyref="GameMaker Name">GameMaker</span> defines for each of the groups. The default audio group is <span class="inline2"><a data-xref="{title}" href="audiogroup_default.htm">audiogroup_default</a></span>. To get the name of the group as a string you can use <span class="inline2"><a data-xref="{title}" href="audio_group_name.htm">audio_group_name</a></span>.</p>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_note.hts"> </span> Trying to play a sound using the <span class="inline">audio_play_sound*</span> functions from an audio group that&#39;s not loaded will not play anything and return a sound instance index of -1. An error message is also output to the console.</p>
<h2>Function Reference</h2>
<h3>Group Info</h3>
<ul class="Disc">
Expand Down Expand Up @@ -51,7 +52,7 @@ <h3>Audio Properties</h3>
<div style="float:right">Next: <a data-xref="{title}" href="../Audio_Buffers/Audio_Buffers.htm">Audio Buffers</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
Audio Groups
Expand Down
2 changes: 1 addition & 1 deletion Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Audio/audio_play_sound.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ <h4>Syntax:</h4>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span></p>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span> (or -1 if the sound could not be played)</p>
<p> </p>
<h4>Example 1: Basic Use</h4>
<p class="code">if (health &lt;= 0)<br />
Expand Down
2 changes: 1 addition & 1 deletion .../contents/GameMaker_Language/GML_Reference/Asset_Management/Audio/audio_play_sound_at.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ <h4>Syntax:</h4>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span></p>
<p class="code"><span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span> (or -1 if the sound could not be played)</p>
<p> </p>
<h4>Example 1:</h4>
<p class="code">if (global.SFX)<br />
Expand Down
Loading

0 comments on commit d8d6e04

Please sign in to comment.