Skip to content

Commit

Permalink
Merge pull request #174 from YoYoGames/develop.gurpreet
Browse files Browse the repository at this point in the history 
Develop.gurpreet
  • Loading branch information
@gurpreetsinghmatharoo
gurpreetsinghmatharoo authored Sep 17, 2024
2 parents 8f5fcf4 + b02efe6 commit 4dc5728
Show file tree
Hide file tree
Showing 12 changed files with 138 additions and 42 deletions.
11 changes: 10 additions & 1 deletion Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,16 @@ <h2>Web Audio</h2>
</ul>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> This event will be triggered on <i>all</i> platforms, but on everything except HTML5 it will only be triggered once on Game Start when the audio engine is first initialised.</p>
<p>To check if audio can be played using Web Audio, you can use <span class="inline2"><a data-xref="{title}" href="audio_sound_is_playable.htm">audio_sound_is_playable</a></span>.</p>
<h2 id="h1">Audio Error Handling</h2>
<p>There may be cases where a function has to either throw a fatal error (crashing the game) or print an error message to the Output Log. These general cases are described below:</p>
<ul class="colour">
<li>Any function taking a <span data-keyref="Type_Asset_Sound"><a href="../../../../The_Asset_Editors/Sounds.htm" target="_blank">Sound Asset</a></span> will throw a fatal error when passed an invalid sound (i.e. the given sound asset does not exist).</li>
<li>Functions taking a <span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span> will print an error message to the Output Log when an invalid sound is passed (i.e. the sound instance is not playing), however it will not cause a crash. The same applies to functions taking an <span data-keyref="Type_ID_Audio_Sync_Group"><a href="Audio_Synchronisation/audio_create_sync_group.htm" target="_blank">Audio Sync Group ID</a></span>.</li>
<li>Functions taking specific values such as <span class="inline3_func"><a data-xref="{title}" href="audio_falloff_set_model.htm">audio_falloff_set_model</a></span> will throw a fatal error when an invalid value is passed.</li>
<li>Invalid operations will throw a fatal error (e.g. attempting to <a href="Audio_Buffers/audio_start_recording.htm">record</a> using an already active input device).</li>
</ul>
<p>For cases that throw a fatal error, you can instead choose to have an output message logged by calling <span class="inline3_func"><a data-xref="{title}" href="audio_throw_on_error.htm">audio_throw_on_error</a></span> with <span class="inline2">true</span>. This will make the game continue in a situation where it would have otherwise crashed, however the effect of the error may still cause bugs in your game. See the function page for information on which functions are affected.</p>
<h2>Function Reference</h2>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> Any function taking a <span data-keyref="Type_Asset_Sound"><a href="../../../../The_Asset_Editors/Sounds.htm" target="_blank">Sound Asset</a></span> will throw a fatal error when passed an invalid sound (i.e. the given sound asset does not exist). Functions taking a <span data-keyref="Type_ID_Sound_Instance"><a href="audio_play_sound.htm" target="_blank">Sound Instance ID</a></span> will print an error message to the output log when an invalid sound is passed (i.e. the sound instance is not playing) however it will not cause a crash.</p>
<h3>Asset Info</h3>
<ul class="colour">
<li><a data-xref="{title}" href="audio_exists.htm">audio_exists</a></li>
Expand Down Expand Up @@ -144,6 +152,7 @@ <h3>Configuration</h3>
<li><a data-xref="{title}" href="audio_falloff_set_model.htm">audio_falloff_set_model</a></li>
<li><a data-xref="{title}" href="audio_system_is_available.htm">audio_system_is_available</a></li>
<li><a data-xref="{title}" href="audio_system_is_initialised.htm">audio_system_is_initialised</a></li>
<li><a data-xref="{title}" href="audio_throw_on_error.htm">audio_throw_on_error</a></li>
</ul>
<h3>Debugging</h3>
<ul class="colour">
Expand Down
9 changes: 5 additions & 4 deletions ...uage/GML_Reference/Asset_Management/Audio/Audio_Synchronisation/Audio_Synchronisation.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 Synchronisation</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 @@ -15,7 +15,8 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">Audio Synchronisation</span></h1>
<p>The audio sync group functions let you play multiple sounds that start at exactly the same time and stay in sync (on a per sample level). This enables you to (for example) add various tracks for a single song and then fade in and out sections without having to worry about whether there will be any delay between them. Note that these functions currently only work with <i>compressed</i> audio, ie. <span class="inline">*.ogg</span> and <span class="inline">*.mp3</span> format files.</p>
<p>The audio sync group functions let you play multiple sounds that start at exactly the same time and stay in sync (on a per sample level). This enables you to (for example) add various tracks for a single song and then fade in and out sections without having to worry about whether there will be any delay between them.</p>
<p>All sounds in sync groups are played at the highest <a href="../audio_play_sound.htm">priority</a>.</p>
<div data-conref="../../../../../assets/snippets/HTML5_Not_Available.hts"> </div>
<p>The following functions exist to deal with synchronising audio tracks:</p>
<ul class="colour">
Expand All @@ -27,7 +28,7 @@ <h1><span data-field="title" data-format="default">Audio Synchronisation</span><
<li><a href="audio_resume_sync_group.htm">audio_resume_sync_group</a></li>
<li><a href="audio_sync_group_get_track_pos.htm">audio_sync_group_get_track_pos</a></li>
<li><a href="audio_destroy_sync_group.htm">audio_destroy_sync_group</a></li>
<li><a href="audio_sync_group_debug.htm">audio_sync_group_debug</a></li>
<li><a href="audio_sync_group_debug.htm">audio_sync_group_debug</a> <span data-conref="../../../../../assets/snippets/Tag_obsolete.hts"> </span></li>
<li><a href="audio_sync_group_is_playing.htm">audio_sync_group_is_playing</a></li>
<li><a data-xref="{title}" href="audio_sync_group_is_paused.htm">audio_sync_group_is_paused</a></li>
</ul>
Expand All @@ -40,7 +41,7 @@ <h1><span data-field="title" data-format="default">Audio Synchronisation</span><
<div style="float:right">Next: <a data-xref="{title}" href="../Audio_Loop_Points/Audio_Loop_Points.htm">Audio Loop Points</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 Synchronisation
Expand Down
12 changes: 6 additions & 6 deletions ...e/GML_Reference/Asset_Management/Audio/Audio_Synchronisation/audio_play_in_sync_group.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_play_in_sync_group</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 @@ -15,7 +15,7 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>audio_play_in_sync_group</h1>
<p>With this function you can assign a sound to a previously created sync group. The group index is the value returned when you created the group using the function <a href="audio_create_sync_group.htm"><span class="inline">audio_create_sync_group()</span></a>, and the sound index is the index of any <i>compressed</i> sound (<span class="inline">*.ogg</span> or <span class="inline">*.mp3</span>) from the Asset Browser. This function only adds the sound to the group, but it does not play the sound. The return value will be <span class="inline2">&gt;= 0</span> if it succeeds and <span class="inline2">-1</span> if it fails, where a successful value indicates the sound&#39;s order in the sync group (so 0 would be the first sound added, 1 would be the second, etc...). </p>
<p>With this function you can assign a sound to a previously created sync group. The group index is the value returned when you created the group using the function <a href="audio_create_sync_group.htm"><span class="inline">audio_create_sync_group()</span></a>, and the sound index is the handle of any sound from the Asset Browser. This function only adds the sound to the group, but it does not play the sound. The return value will be <span class="inline2">&gt;= 0</span> if it succeeds and <span class="inline2">-1</span> if it fails, where a successful value indicates the sound&#39;s order in the sync group (so 0 would be the first sound added, 1 would be the second, etc.). </p>
<div data-conref="../../../../../assets/snippets/HTML5_Not_Available.hts"> </div>
<p> </p>
<h4>Syntax:</h4>
Expand All @@ -29,19 +29,19 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>group_index</td>
<td><span data-keyref="Type_ID_Audio_Sync_Group"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio_Synchronisation/audio_create_sync_group.htm" target="_blank">Audio Sync Group ID</a></span></td>
<td><span data-keyref="Type_ID_Audio_Sync_Group"><a href="audio_create_sync_group.htm" target="_blank">Audio Sync Group ID</a></span></td>
<td>The group index to assign the sound to.</td>
</tr>
<tr>
<td>sound_index</td>
<td><span data-keyref="Type_Asset_Sound"><a href="../../../../../../The_Asset_Editors/Sounds.htm" target="_blank">Sound Asset</a></span></td>
<td><span data-keyref="Type_Asset_Sound"><a href="../../../../../The_Asset_Editors/Sounds.htm" target="_blank">Sound Asset</a></span></td>
<td>The sound index to be assigned to the group.</td>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Real"><a href="../../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></p>
<p class="code"><span data-keyref="Type_Real"><a href="../../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">sg = audio_create_sync_group(true);<br />
Expand All @@ -61,7 +61,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="audio_start_sync_group.htm">audio_start_sync_group</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
audio_play_in_sync_group
Expand Down
9 changes: 5 additions & 4 deletions ...age/GML_Reference/Asset_Management/Audio/Audio_Synchronisation/audio_sync_group_debug.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_sync_group_debug</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,7 +14,8 @@
</head>
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">audio_sync_group_debug</span></h1>
<h1><span data-field="title" data-format="default">audio_sync_group_debug</span> <span data-conref="../../../../../assets/snippets/Tag_obsolete.hts"> </span></h1>
<p class="note"><span data-conref="../../../../../assets/snippets/Tag_important.hts"> </span> This function is obsolete, please use <span class="inline3_func"><a data-xref="{title}" href="../audio_debug.htm">audio_debug</a></span> instead.</p>
<p>This function displays debug information about any given sync group (the group index is the value returned when the group was created using the function <span class="inline3_func"><a data-xref="{title}" href="audio_create_sync_group.htm">audio_create_sync_group</a></span>). You can call the function with a value of -1 to switch off the overlay.</p>
<p>When you are debugging the audio sync groups, the overlay will show:</p>
<ul class="colour">
Expand Down Expand Up @@ -52,7 +53,7 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>group_index</td>
<td><span data-keyref="Type_ID_Audio_Sync_Group"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Audio/Audio_Synchronisation/audio_create_sync_group.htm" target="_blank">Audio Sync Group ID</a></span></td>
<td><span data-keyref="Type_ID_Audio_Sync_Group"><a href="audio_create_sync_group.htm" target="_blank">Audio Sync Group ID</a></span></td>
<td>The group index to debug, or -1 to switch off the debugging.</td>
</tr>
</tbody>
Expand Down Expand Up @@ -80,7 +81,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="audio_sync_group_is_playing.htm">audio_sync_group_is_playing</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_sync_group_debug
Expand Down
10 changes: 5 additions & 5 deletions ...al/contents/GameMaker_Language/GML_Reference/Asset_Management/Audio/audio_channel_num.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_channel_num</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 @@ -17,8 +17,8 @@
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">audio_channel_num</span></h1>
<p>With this function you can set how many audio channels are available for playing audio in <span data-keyref="GameMaker Name">GameMaker</span>.</p>
<p>This basically means the number of sounds (or <em>sound instances</em> or <em>voices</em>) that can be played <em>simultaneously</em>. Or, put differently, the number of calls to any of the <span class="inline2">audio_play_sound_</span> functions that you can make before sounds may be lost.</p>
<p>If the number exceeds this value, those sounds with a lower <i>priority</i> are stopped to free up a channel for the sounds with a higher <i>priority</i>.</p>
<p>This basically means the number of sounds (or <em>sound instances</em> or <em>voices</em>) that can be played <em>simultaneously</em>. Or, put differently, the number of calls to any of the <span class="inline2">audio_play_sound*</span> (and <span class="inline3_func"><a data-xref="{title}" href="Audio_Synchronisation/audio_play_in_sync_group.htm">audio_play_in_sync_group</a></span>) functions that you can make before sounds may be lost. If the number exceeds this value, those sounds with a lower <i>priority</i> are stopped to free up a channel for the sounds with a higher <i>priority</i>.</p>
<p>You can pass <span class="inline2">0</span> to disable audio playback.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_tip.hts"> </span> You can use this function to optimise your game for devices as the lower the number of channels for audio the better the performance, but bear in mind that this may also cause noticeable cutoff of certain sounds if many are played at once.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_warning.hts"> </span> This function is a configuration function of the audio engine and stops all playing sounds when called (i.e. <span class="inline3_func"><a data-xref="{title}" href="audio_stop_all.htm">audio_stop_all</a></span>). Ideally it should not be called when sounds are already playing, unless you are e.g. using this as an adjustable setting in your game.</p>
<p> </p>
Expand All @@ -33,7 +33,7 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>num</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>Number of available audio channels (default is <span data-keyref="Max_Audio_Channels_Default">128</span>)</td>
</tr>
</tbody>
Expand Down Expand Up @@ -74,7 +74,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a data-xref="{title}" href="audio_falloff_set_model.htm">audio_falloff_set_model</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_channel_num
Expand Down
10 changes: 5 additions & 5 deletions ...s/GameMaker_Language/GML_Reference/Asset_Management/Audio/audio_system_is_initialised.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_system_is_initialised</title>
<meta name="generator" content="Adobe RoboHelp 2020" />
<meta name="generator" content="Adobe RoboHelp 2022" />
<link rel="stylesheet" type="text/css" href="../../../../assets/css/default.css" />
<script src="../../../../assets/scripts/main_script.js" type="module"></script>
<meta name="rh-authors" content="" />
Expand All @@ -27,7 +27,7 @@ <h4>Syntax:</h4>
<p class="code"><span data-field="title" data-format="default">audio_system_is_initialised</span>();</p>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Bool"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Boolean</a></span></p>
<p class="code"><span data-keyref="Type_Bool"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Boolean</a></span></p>
<p> </p>
<h4>Example:</h4>
<p> </p>
Expand All @@ -51,7 +51,7 @@ <h4>Example:</h4>
    audio_emitter_bus(em_emitter, bus_special_effects);<br />
}<br />
<br />
if (audio_initialised) <br />
if (audio_initialised)<br />
{<br />
    // The audio system can be used here<br />
    // ...<br />
Expand All @@ -64,10 +64,10 @@ <h4>Example:</h4>
<div class="buttons">
<div class="clear">
<div>Back: <a data-xref="{title}" href="Audio.htm">Audio</a></div>
<div>Next: <a data-xref="{title}" href="audio_debug.htm">audio_debug</a></div>
<div>Next: <a data-xref="{title}" href="audio_throw_on_error.htm">audio_throw_on_error</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_system_is_initialised
Expand Down
Loading

0 comments on commit 4dc5728

Please sign in to comment.