1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<title>Castle Game Engine: CastleSoundAllocator: Class TSoundAllocator</title>
<meta name="generator" content="PasDoc 0.13.0">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="StyleSheet" type="text/css" href="pasdoc.css">
</head>
<body>
<table class="container"><tr><td class="navigation">
<h2>Castle Game Engine</h2><p><a href="introduction.html" class="navigation">Introduction</a></p><p><a href="AllUnits.html" class="navigation">Units</a></p><p><a href="ClassHierarchy.html" class="navigation">Class Hierarchy</a></p><p><a href="AllClasses.html" class="navigation">Classes, Interfaces, Objects and Records</a></p><p><a href="AllTypes.html" class="navigation">Types</a></p><p><a href="AllVariables.html" class="navigation">Variables</a></p><p><a href="AllConstants.html" class="navigation">Constants</a></p><p><a href="AllFunctions.html" class="navigation">Functions and Procedures</a></p><p><a href="AllIdentifiers.html" class="navigation">Identifiers</a></p></td><td class="content">
<a name="TSoundAllocator"></a><h1 class="cio">Class TSoundAllocator</h1>
<table class="sections wide_list">
<tr>
<td><a class="section" href="#PasDoc-Description">Description</a></td><td><a class="section" href="#PasDoc-Hierarchy">Hierarchy</a></td><td><a class="section" href="#PasDoc-Fields">Fields</a></td><td><a class="section" href="#PasDoc-Methods">Methods</a></td><td><a class="section" href="#PasDoc-Properties">Properties</a></td></tr></table>
<a name="PasDoc-Description"></a><h2 class="unit">Unit</h2>
<p class="unitlink">
<a href="CastleSoundAllocator.html">CastleSoundAllocator</a></p>
<h2 class="declaration">Declaration</h2>
<p class="declaration">
<code>type TSoundAllocator = class(TObject)</code></p>
<h2 class="description">Description</h2>
<p>
Manage allocated OpenAL sounds. You leave to this class creating and deleting of OpenAL sounds. When you need OpenAL sound to do something, just call <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#AllocateSound">AllocateSound</a> method.
<p>This class will manage OpenAL sources in an intelligent manner, which means when you need new sound, we may </p>
<ol class="paragraph_spacing">
<li value="1"><p>Reuse already allocated sound that is not used to play anything.</p></li>
<li value="2"><p>Allocate new sound (but we will keep allocated sounds count within <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a> sound limit, to not overload OpenAL implementation with work).</p></li>
<li value="3"><p>We may simply interrupt already allocated sound, if new sound is more important.</p></li>
</ol>
<p>
<p>Our OpenAL resources are created in <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#ALContextOpen">ALContextOpen</a>, and released in <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#ALContextClose">ALContextClose</a>.
<p>The very reason behind this class is to hide from you the fact that the number of OpenAL sources are limited. In particular, this means that when OpenAL will run out of sources, no OpenAL error (alGetError) will be left, and no exception will be raised. In the worst case <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#AllocateSound">TSoundAllocator.AllocateSound</a> will return nil, but in more probable cases some other sources (unused, or with less priority) will be reused.
<p>Note that this means that the code in this unit must read in some situations alGetError. That's because reading alGetError is the only way to know when OpenAL implementation has run out of sources. So the code in this unit may in various places raise <a class="normal" href="CastleALUtils.EALError.html">EALError</a> if you made some error in your OpenAL code, and you didn't check alGetError yourself often enough.</p>
<a name="PasDoc-Hierarchy"></a><h2 class="hierarchy">Hierarchy</h2>
<ul class="hierarchy"><li class="ancestor">TObject</li>
<li class="thisitem">TSoundAllocator</li></ul><h2 class="overview">Overview</h2>
<a name="PasDoc-Fields"></a><h3 class="summary">Fields</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>internal const <b><a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMinAllocatedSources">DefaultMinAllocatedSources</a></b> = 4;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>internal const <b><a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMaxAllocatedSources">DefaultMaxAllocatedSources</a></b> = 16;</code></td>
</tr>
</table>
<a name="PasDoc-Methods"></a><h3 class="summary">Methods</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="protected.gif" alt="Protected" title="Protected"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#LoadFromConfig">LoadFromConfig</a></b>(const Config: <a href="CastleXMLConfig.TCastleConfig.html">TCastleConfig</a>); virtual;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="protected.gif" alt="Protected" title="Protected"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#SaveToConfig">SaveToConfig</a></b>(const Config: <a href="CastleXMLConfig.TCastleConfig.html">TCastleConfig</a>); virtual;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>constructor <b><a href="CastleSoundAllocator.TSoundAllocator.html#Create">Create</a></b>;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#ALContextOpen">ALContextOpen</a></b>; virtual;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#ALContextClose">ALContextClose</a></b>; virtual;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>function <b><a href="CastleSoundAllocator.TSoundAllocator.html#AllocateSound">AllocateSound</a></b>(const Importance: Integer): <a href="CastleSoundAllocator.TSound.html">TSound</a>;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#Refresh">Refresh</a></b>;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleSoundAllocator.TSoundAllocator.html#StopAllSources">StopAllSources</a></b>;</code></td>
</tr>
</table>
<a name="PasDoc-Properties"></a><h3 class="summary">Properties</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>property <b><a href="CastleSoundAllocator.TSoundAllocator.html#AllocatedSources">AllocatedSources</a></b>: <a href="CastleSoundAllocator.TSoundList.html">TSoundList</a> read FAllocatedSources;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="published.gif" alt="Published" title="Published"></a></td>
<td class="itemcode"><code>property <b><a href="CastleSoundAllocator.TSoundAllocator.html#MinAllocatedSources">MinAllocatedSources</a></b>: Cardinal
read FMinAllocatedSources write SetMinAllocatedSources
default <a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMinAllocatedSources">DefaultMinAllocatedSources</a>;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="published.gif" alt="Published" title="Published"></a></td>
<td class="itemcode"><code>property <b><a href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a></b>: Cardinal
read FMaxAllocatedSources write SetMaxAllocatedSources
default <a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMaxAllocatedSources">DefaultMaxAllocatedSources</a>;</code></td>
</tr>
</table>
<h2 class="description">Description</h2>
<h3 class="detail">Fields</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="DefaultMinAllocatedSources"></a><code>internal const <b>DefaultMinAllocatedSources</b> = 4;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="DefaultMaxAllocatedSources"></a><code>internal const <b>DefaultMaxAllocatedSources</b> = 16;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<h3 class="detail">Methods</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="protected.gif" alt="Protected" title="Protected"></a></td>
<td class="itemcode"><a name="LoadFromConfig"></a><code>procedure <b>LoadFromConfig</b>(const Config: <a href="CastleXMLConfig.TCastleConfig.html">TCastleConfig</a>); virtual;</code></td>
</tr>
<tr><td colspan="2">
<p>
Load and save into XML config file some sound engine properties. Everything is loaded / saved under the path "sound/" inside Config.
<p><a class="normal" href="CastleSoundAllocator.TSoundAllocator.html">TSoundAllocator</a> saves <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MinAllocatedSources">MinAllocatedSources</a>, <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a>. Descendant <a class="normal" href="CastleSoundEngine.TSoundEngine.html">TSoundEngine</a> additionally saves current Device, Enable (unless Enable was set by --no-sound command-line option). Descendant <a class="normal" href="CastleSoundEngine.TRepoSoundEngine.html">TRepoSoundEngine</a> additionally saves sound and music volume.
<p></p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="protected.gif" alt="Protected" title="Protected"></a></td>
<td class="itemcode"><a name="SaveToConfig"></a><code>procedure <b>SaveToConfig</b>(const Config: <a href="CastleXMLConfig.TCastleConfig.html">TCastleConfig</a>); virtual;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Create"></a><code>constructor <b>Create</b>;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="ALContextOpen"></a><code>procedure <b>ALContextOpen</b>; virtual;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="ALContextClose"></a><code>procedure <b>ALContextClose</b>; virtual;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="AllocateSound"></a><code>function <b>AllocateSound</b>(const Importance: Integer): <a href="CastleSoundAllocator.TSound.html">TSound</a>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Allocate sound for playing. You should initialize the OpenAL sound properties and start playing the sound (you have OpenAL sound identifier in <a class="normal" href="CastleSoundAllocator.TSound.html#ALSource">TSound.ALSource</a>).
<p>Note that if you don't call alSourcePlay, the source may be detected as unused (and recycled for another sound) at the next <code>AllocateSound</code>, PlaySound, <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#Refresh">Refresh</a> and such calls.
<p>If we can't allocate new OpenAL sound, we return nil. This may happen your OpenAL context is not initialized. It may also happen if we cannot create more sources (because we hit <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a> limit, or OpenAL just refuses to create more sources) and all existing sounds are used and their Importance is > given here Importance.
<p>Note for looping sounds: just like any other sound, looping sound may be stopped because the sounds are needed for other sounds. If you want to try to restart the looping sound, you will have to implement it yourself. Or you can just set Importance of looping sounds high enough, and don't use too many looping sounds, to never let them be eliminated by other sounds.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Refresh"></a><code>procedure <b>Refresh</b>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Detect unused sound sources. If you rely on your sources receiving <a class="normal" href="CastleSoundAllocator.TSound.html#OnRelease">TSound.OnRelease</a> in a timely manner, be sure to call this method often. Otherwise, it's not needed to call this at all (unused sounds will be detected automatically on-demand anyway).
<p>This is automatically called by <a class="normal" href="CastleSceneManager.TCastleSceneManager.html">TCastleSceneManager</a>.
<p>For every source that is marked as Used, this checks whether this source is actually in playing/paused state right now. If not, it calls <a class="normal" href="CastleSoundAllocator.TSound.html#Release">TSound.Release</a> (thus setting Used to <code>False</code> and triggering OnRelease) for this source.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="StopAllSources"></a><code>procedure <b>StopAllSources</b>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Stop all the sources currently playing. Especially useful since you have to stop a source before releasing it's associated buffer.</p>
</td></tr>
</table>
<h3 class="detail">Properties</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="AllocatedSources"></a><code>property <b>AllocatedSources</b>: <a href="CastleSoundAllocator.TSoundList.html">TSoundList</a> read FAllocatedSources;</code></td>
</tr>
<tr><td colspan="2">
<p>
All allocated (not necessarily used) OpenAL sources. Useful only for advanced or debuging tasks, in normal circumstances we mange this completely ourselves. This is <code>Nil</code> when <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#ALContextOpen">ALContextOpen</a> was not yet called.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="published.gif" alt="Published" title="Published"></a></td>
<td class="itemcode"><a name="MinAllocatedSources"></a><code>property <b>MinAllocatedSources</b>: Cardinal
read FMinAllocatedSources write SetMinAllocatedSources
default <a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMinAllocatedSources">DefaultMinAllocatedSources</a>;</code></td>
</tr>
<tr><td colspan="2">
<p>
Minimum / maximum number of allocated OpenAL sources. Always keep <code>MinAllocatedSources</code> <= <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a>.
<p>For the sake of speed, we always keep allocated at least <code>MinAllocatedSources</code> OpenAL sources. This must be >= 1. Setting <code>MinAllocatedSources</code> too large value will raise <a class="normal" href="CastleSoundAllocator.ENoMoreOpenALSources.html">ENoMoreOpenALSources</a>.
<p>At most <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a> sources may be simultaneously used (played). This prevents us from allocating too many sounds, which would be bad for OpenAL speed (not to mention that it may be impossible under some OpenAL implementations, like Windows one). When all <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#MaxAllocatedSources">MaxAllocatedSources</a> sources are playing, the only way to play another sound is to use appropriately high <code>Importance</code> to <a class="normal" href="CastleSoundAllocator.TSoundAllocator.html#AllocateSound">AllocateSound</a>.
<p></p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="published.gif" alt="Published" title="Published"></a></td>
<td class="itemcode"><a name="MaxAllocatedSources"></a><code>property <b>MaxAllocatedSources</b>: Cardinal
read FMaxAllocatedSources write SetMaxAllocatedSources
default <a href="CastleSoundAllocator.TSoundAllocator.html#DefaultMaxAllocatedSources">DefaultMaxAllocatedSources</a>;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<!-- Piwik -->
<script type="text/javascript">
var _paq = _paq || [];
_paq.push(["trackPageView"]);
_paq.push(["enableLinkTracking"]);
(function() {
var u=(("https:" == document.location.protocol) ? "https" : "http") + "://michalis.ii.uni.wroc.pl/piwik-castle-engine/";
_paq.push(["setTrackerUrl", u+"piwik.php"]);
_paq.push(["setSiteId", "1"]);
var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Piwik Code -->
<noscript>
<!-- Piwik Image Tracker -->
<img src="http://michalis.ii.uni.wroc.pl/piwik-castle-engine/piwik.php?idsite=1&rec=1" style="border:0" alt="" />
<!-- End Piwik -->
</noscript>
<hr noshade size="1"><span class="appinfo"><em>Generated by <a href="http://pasdoc.sourceforge.net/">PasDoc 0.13.0</a> on 2015-06-15 04:43:12</em>
</span>
</td></tr></table></body></html>
|
