Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/freealut-1.1.0/doc/alut.html @ 14

Last change on this file since 14 was 14, checked in by landauf, 17 years ago

added freealut
File size: 49.5 KB
RevLine 
[14]1<?xml version="1.0"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
4  <head>
5    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
6    <link rel="stylesheet" href="alut.css" type="text/css"/>
7    <title>The OpenAL Utility Toolkit</title>
8  </head>
9
10  <body>
11    <h1>The OpenAL Utility Toolkit (ALUT)</h1>
12
13    <h1>Contents</h1>
14
15    <ul>
16      <li>
17        <a href="#ReleaseHistory">Release History</a>
18      </li>
19      <li>
20        <a href="#Introduction">Introduction</a>
21        <ul>
22          <li><a href="#Licensing">Licensing</a></li>
23          <li><a href="#History">Some History</a></li>
24          <li><a href="#BackwardsCompatibility">Backwards Compatibility with Version 0.x.x</a></li>
25          <li><a href="#OpenGLGLUT">OpenGL, GLUT and using what you already know</a></li>
26        </ul>
27      </li>
28      <li>
29        <a href="#CompilingLinking">Compiling and Linking</a>
30      </li>
31      <li>
32        <a href="#API">The ALUT API</a>
33        <ul>
34          <li>
35            <a href="#ErrorHandling">Error Handling</a>
36            <ul>
37              <li><a href="#alutGetError">alutGetError</a></li>
38              <li><a href="#alutGetErrorString">alutGetErrorString</a></li>
39            </ul>
40          </li>
41          <li>
42            <a href="#InitializationExit">Initialization / Exit</a>
43            <ul>
44              <li><a href="#alutInit">alutInit</a></li>
45              <li><a href="#alutInitWithoutContext">alutInitWithoutContext</a></li>
46              <li><a href="#alutExit">alutExit</a></li>
47            </ul>
48          </li>
49          <li>
50            <a href="#Loading">Sound Sample File Loading</a>
51            <ul>
52              <li><a href="#alutCreateBufferFromFile">alutCreateBufferFromFile</a></li>
53              <li><a href="#alutCreateBufferFromFileImage"> alutCreateBufferFromFileImage</a></li>
54             <li><a href="#alutCreateBufferHelloWorld">alutCreateBufferHelloWorld</a></li>
55             <li><a href="#alutCreateBufferWaveform">alutCreateBufferWaveform</a></li>
56              <li><a href="#alutLoadMemoryFromFile">alutLoadMemoryFromFile</a></li>
57              <li><a href="#alutLoadMemoryFromFileImage">alutLoadMemoryFromFileImage</a></li>
58             <li><a href="#alutLoadMemoryHelloWorld">alutLoadMemoryHelloWorld</a></li>
59             <li><a href="#alutLoadMemoryWaveform">alutLoadMemoryWaveform</a></li>
60              <li><a href="#alutGetMIMETypes">alutGetMIMETypes</a></li>
61              <li><a href="#DeprecatedWAVLoaders">Deprecated WAV loaders</a></li>
62            </ul>
63          </li>
64          <li>
65            <a href="#VersionChecking">Version Checking</a>
66            <ul>
67              <li><a href="#alutGetMajorVersion">alutGetMajorVersion</a></li>
68              <li><a href="#alutGetMinorVersion">alutGetMinorVersion</a></li>
69              <li><a href="#VersioningMacros">Compile Time Version Checking</a></li>
70            </ul>
71          </li>
72          <li>
73            <a href="#Sleeping">Sleeping</a>
74            <ul>
75              <li><a href="#alutSleep">alutSleep</a></li>
76            </ul>
77          </li>
78        </ul>
79      </li>
80    </ul>
81
82    <h1><a name="ReleaseHistory"></a>Release History</h1>
83
84    <p>Discussion of the API is done via the <a
85    href="mailto:openal-devel@opensource.creative.com">openal-devel</a> mailing
86    list.</p>
87
88    <ul>
89      <li>2005-08-14: Version 1.0.0 by Steve Baker</li>
90      <li>2005-09-02: Version 1.0.1 by Sven Panne</li>
91      <li>2005-09-10: Version 1.0.2 by Sven Panne</li>
92      <li>2005-09-26: Version 1.0.3 by Sven Panne</li>
93      <li>2005-09-28: Version 1.0.4 by Sven Panne</li>
94      <li>2005-10-29: Version 1.0.5 by Sven Panne</li>
95      <li>2005-11-19: Version 1.0.6 by Sven Panne</li>
96      <li>2006-04-10: Version 1.0.7 by Sven Panne</li>
97      <li>2006-04-11: Version 1.1.0 by Sven Panne</li>
98    </ul>
99
100    <h1><a name="Introduction"></a>Introduction</h1>
101
102    <p>This is the <a href="http://www.openal.org/">OpenAL</a> Utility Toolkit
103    (ALUT) Reference Manual.</p>
104
105    <h2><a name="Licensing"></a>Licensing</h2>
106
107    <p>Some previous versions of ALUT were released under the BSD license -
108    others under LGPL. This version will be released exclusively under LGPL.</p>
109
110    <h2><a name="History"></a>Some History</h2>
111
112    <p>At the time of the first writing of this document (August 2005), ALUT was
113    a set of undocumented semi-portable functions that were mixed up in the
114    OpenAL library distribution. The intent had always been that ALUT would be a
115    cleanly separated library that would be portable between systems. It was
116    hoped that it would be well suited to producing succinct demo programs and
117    to help new developers to get started with OpenAL. It was to do this by
118    removing the annoying details of getting an audio application started -
119    allowing developers to learn OpenAL without distractions such as loading
120    sound samples from disk.</p>
121
122    <p>In order to move from this initial implementation to a clean API that
123    would meet the original goals of ALUT, it was necessary to break from the
124    past and make a clean start. The original version(s) were unnumbered - so we
125    will arbitarily label all previous versions as 0.x.x and start this cleaned
126    up version at release 1.0.0 to reflect changed API and implementations.</p>
127
128    <h2><a name="BackwardsCompatibility"></a>Backwards Compatibility with Version 0.x.x</h2>
129
130    <p>There are no formal guarantees of reverse compatibility with the various
131    versions of ALUT prior to 1.0.0. Having said that, some effort has been made
132    to at least allow these programs to continue to run if they are recompiled
133    against ALUT 1.0.0 or later.</p>
134
135    <p>The old Linux implementation of OpenAL poses a special compatibility
136    problem: ALUT 0.x.x was not a physically separate library on this platform,
137    it was actually part of libopenal itself. This is bad for at least two
138    reasons: It was handled differently on other platforms and much more
139    seriously it locked together OpenAL and ALUT releases. So a deliberate
140    decision was made to break binary compatibility in this respect and cleanly
141    split the libraries into an OpenAL (i.e. AL and ALC) part and an ALUT
142    one.</p>
143
144    <p>If you have a program which needs such an old, deprecated &quot;combined
145    OpenAL/ALUT&quot; and you are not able to recompile it for some reason
146    (e.g. it is available in binary format only), then temporarily setting the
147    environment variable <tt>LD_PRELOAD</tt> to the full path of your installed
148    ALUT dynamic library can help. If this really works depends on the platform,
149    but e.g. Linux, FreeBSD, NetBSD, Solaris etc. support this mechanism. On Mac
150    OS X there is a similar environment variable called
151    <tt>DYLD_INSERT_LIBRARIES</tt>, but this has not been tested yet.</p>
152
153    <div class="example">
154      <h4>Example: Using a legacy program with the new ALUT</h4>
155
156      <p>Let's assume that your ALUT dynamic library is at the usual location
157      <tt>/usr/lib/libalut.so</tt> and you have an old program called
158      <tt>myOldProg</tt>, then the following commandline in Bash syntax does the
159      trick:</p>
160
161<pre class="programlisting">
162LD_PRELOAD="/usr/lib/libalut.so" myOldProg
163</pre>
164
165    <p>Note that setting <tt>LD_PRELOAD</tt> globally might not be a good idea,
166    because in that case the new ALUT would be loaded before <em>every</em>
167    dynamically linked executable.</p>
168
169    </div>
170
171    <h2><a name="OpenGLGLUT"></a>OpenGL, GLUT and using what you already know</h2>
172
173    <p>If you are already familiar with OpenGL and its utility toolkit GLUT,
174    then you should feel very familiar with ALUT. Wherever GLUT has 'GL', ALUT
175    has 'AL' and wherever GLUT has 'glut', ALUT has 'alut'. 'Window' is replaced
176    with 'Context' throughout the API.</p>
177
178    <div class="example">
179      <h4>Example: 'Hello, world' in ALUT</h4>
180
181      <p>Here is the traditional first program for any language or library, but
182      this time it is actually <em>saying</em> 'Hello, world!' instead of
183      printing it:</p>
184
185<pre class="programlisting">
186#include &lt;stdlib.h&gt;
187#include &lt;AL/alut.h&gt;
188
189int
190main (int argc, char **argv)
191{
192  ALuint helloBuffer, helloSource;
193  alutInit (&amp;argc, argv);
194  helloBuffer = alutCreateBufferHelloWorld ();
195  alGenSources (1, &amp;helloSource);
196  alSourcei (helloSource, AL_BUFFER, helloBuffer);
197  alSourcePlay (helloSource);
198  alutSleep (1);
199  alutExit ();
200  return EXIT_SUCCESS;
201}
202</pre>
203
204      <p>Note that there error checks are missing in the program above to keep
205      it simple.</p>
206
207    </div>
208
209    <h3><a name="CompilingLinking"></a>Compiling and Linking</h3>
210
211    <p>All ALUT programs should contain:</p>
212
213<pre class="programlisting">
214#include &lt;AL/alut.h&gt;
215</pre>
216
217    <p>The ALUT header includes <tt>&lt;AL/al.h&gt;</tt> and
218    <tt>&lt;AL/alc.h&gt;</tt> for you so you don't need to include them again -
219    although it does not hurt to do so. ALUT reserves the
220    &quot;<tt>ALUT_</tt>&quot; prefix for preprocessor macros, so you should
221    never define such a macro in your own program. Furthermore, you should not
222    rely on any macro starting with &quot;<tt>ALUT_</tt>&quot; not mentioned in
223    this specification.</p>
224
225    <p>If you are using the freealut implementation of ALUT, which is available
226    via the <a href="http://www.openal.org/">OpenAL homepage</a>, you can find
227    out the necessary compilation flags by using one of the following
228    commands:</p>
229
230<pre class="screen">
231pkg-config --cflags freealut
232freealut-config --cflags
233</pre>
234
235    <p>To find out the necessary flags for linking, use one of the following
236    commands:</p>
237
238<pre class="screen">
239pkg-config --libs freealut
240freealut-config --libs
241</pre>
242
243    <p>On Windows, link with <tt>alut.dll</tt> and <tt>openal32.dll</tt>.</p>
244
245    <p>ALUT reserves the &quot;<tt>alut</tt>&quot; prefix for globally visible
246    functions and variables, so you should never define such a function or
247    variable in your own program. Furthermore, you should not rely on any such
248    function or variable not mentioned in this specification.</p>
249
250    <h1><a name="API"></a>The ALUT API</h1>
251
252    <h2><a name="ErrorHandling"></a>Error Handling</h2>
253
254    <p>ALUT's error handling and reporting is a little bit different from the
255    one used in OpenAL and OpenGL: All functions which can fail report
256    success/failure via a return value, where <tt>AL_FALSE</tt> /
257    <tt>AL_NONE</tt> / <tt>NULL</tt> mean failure. <tt>alutGetError</tt> can be
258    used to find out what exactly went wrong.</p>
259
260    <p>It is guaranteed that if a function fails, no data pointed to by pointer
261    arguments has been changed.</p>
262
263    <h3 class="manpage"><a name="alutGetError"></a>alutGetError</h3>
264
265    <h4>Name</h4>
266
267    <p><tt>alutGetError</tt> - return and clear the current error state</p>
268
269    <h4>Synopsis</h4>
270
271<pre class="programlisting">
272ALenum alutGetError (void);
273</pre>
274
275    <h4>Description</h4>
276
277    <p>Any ALUT routine that fails will return <tt>AL_FALSE</tt> /
278    <tt>AL_NONE</tt> / <tt>NULL</tt> and set the global error state. If a
279    subsequent error occurs while there is still an error recorded internally,
280    the second error will simply be ignored. Calling <tt>alutGetError</tt> will
281    reset the error code to <tt>ALUT_ERROR_NO_ERROR</tt>. Note that the error
282    state is <em>not</em> cleared by other successful ALUT calls.</p>
283
284    <h4>Return Value</h4>
285
286    <p><tt>alutGetError</tt> returns the contents of the global error state,
287    which can be one of the following values:</p>
288
289    <dl>
290      <dt><tt>ALUT_ERROR_NO_ERROR</tt></dt>
291      <dd>No ALUT error found.</dd>
292
293      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
294      <dd>ALUT ran out of memory.</dd>
295
296      <dt><tt>ALUT_ERROR_INVALID_ENUM</tt></dt>
297      <dd>ALUT was given an invalid enumeration token.</dd>
298
299      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
300      <dd>ALUT was given an invalid value.</dd>
301
302      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
303      <dd>The operation is invalid in the current ALUT state.</dd>
304
305      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
306      <dd>There is no current AL context.</dd>
307
308      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
309      <dd>There was already an AL error on entry to an ALUT function.</dd>
310
311      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
312      <dd>There was already an ALC error on entry to an ALUT function.</dd>
313
314      <dt><tt>ALUT_ERROR_OPEN_DEVICE</tt></dt>
315      <dd>There was an error opening the ALC device.</dd>
316
317      <dt><tt>ALUT_ERROR_CLOSE_DEVICE</tt></dt>
318      <dd>There was an error closing the ALC device.</dd>
319
320      <dt><tt>ALUT_ERROR_CREATE_CONTEXT</tt></dt>
321      <dd>There was an error creating an ALC context.</dd>
322
323      <dt><tt>ALUT_ERROR_MAKE_CONTEXT_CURRENT</tt></dt>
324      <dd>Could not change the current ALC context.</dd>
325
326      <dt><tt>ALUT_ERROR_DESTROY_CONTEXT</tt></dt>
327      <dd>There was an error destroying the ALC context.</dd>
328
329      <dt><tt>ALUT_ERROR_GEN_BUFFERS</tt></dt>
330      <dd>There was an error generating an AL buffer.</dd>
331
332      <dt><tt>ALUT_ERROR_BUFFER_DATA</tt></dt>
333      <dd>There was an error passing buffer data to AL.</dd>
334
335      <dt><tt>ALUT_ERROR_IO_ERROR</tt></dt>
336      <dd>I/O error, consult <tt>errno</tt> for more details.</dd>
337
338      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt></dt>
339      <dd>Unsupported file type.</dd>
340
341      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt></dt>
342      <dd>Unsupported mode within an otherwise usable file type.</dd>
343
344      <dt><tt>ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA</tt></dt>
345      <dd>The sound data was corrupt or truncated.</dd>
346    </dl>
347
348    <h4>Errors</h4>
349
350    <p><tt>alutGetError</tt> can be called in any ALUT state and will never
351    fail.</p>
352
353    <h3 class="manpage"><a name="alutGetErrorString"></a>alutGetErrorString</h3>
354
355    <h4>Name</h4>
356
357    <p><tt>alutGetErrorString</tt> - return an error message string
358    given an error code</p>
359
360    <h4>Synopsis</h4>
361
362<pre class="programlisting">
363const char *alutGetErrorString (ALenum error);
364</pre>
365
366    <h4>Description</h4>
367
368    <p><tt>alutGetErrorString</tt> can be used to convert an error code into a
369    human-readable description. The precise text of these descriptions may vary
370    from implementation to implementation and should not be relied upon by the
371    application.</p>
372
373    <h4>Return Value</h4>
374
375    <p><tt>alutGetErrorString</tt> returns a pointer to an immutable
376    zero-terminated string corresponding to the given error code.</p>
377
378    <h4>Errors</h4>
379
380    <p><tt>alutGetErrorString</tt> can be called in any ALUT state and
381    will never fail. An unknown error code is not considered an error
382    and a generic description will be returned in that case.</p>
383
384    <div class="example">
385      <h4>Example: Context Handling and Error Reporting</h4>
386
387      <p>A typical ALUT program might look like this:</p>
388
389<pre class="programlisting">
390static void
391reportError (void)
392{
393  fprintf (stderr, "ALUT error: %s\n",
394           alutGetErrorString (alutGetError ()));
395  exit (EXIT_FAILURE);
396}
397
398int
399main (int argc, char **argv)
400{
401  if (!alutInit (&amp;argc, argv))
402    {
403      reportError ();
404    }
405
406  /* ...play audio for a while... */
407
408  if (!alutExit ())
409    {
410      reportError ();
411    }
412
413  return EXIT_SUCCESS;
414}
415</pre>
416    </div>
417
418    <h2><a name="InitializationExit"></a>Initialization / Exit</h2>
419
420    <p>ALUT starts in an <em>uninitialized</em> state. <tt>alutInit</tt> and
421    <tt>alutInitWithoutContext</tt> put ALUT into the <em>initialized</em>
422    state. Those functions must only be called when the state is
423    <em>uninitialized</em>. <tt>alutExit</tt> puts ALUT back from an
424    <em>initialized</em> state to an <em>uninitialized</em> one.</p>
425
426    <p>The following functions must only be called in an <em>initialized</em>
427    state and with a current context: <tt>alutExit</tt>,
428    <tt>alutCreateBufferFromFile</tt>, <tt>alutCreateBufferFromFileImage</tt>,
429    <tt>alutLoadMemoryFromFile</tt>, <tt>alutLoadMemoryFromFileImage</tt>,
430    <tt>alutGetMIMETypes</tt>, <tt>alutCreateBufferHelloWorld</tt>,
431    <tt>alutCreateBufferWaveform</tt>. All these functions check for AL/ALC
432    errors on entry and immediately return <tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt>
433    or <tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt> if there was one. Note that as a
434    consequence of these checks the AL/ALC error states for the current
435    context/device are cleared after calling any of these functions.</p>
436
437    <p><tt>alutSleep</tt> can be called in every state.</p>
438
439    <p>The following functions never fail and can be called in any state:
440    <tt>alutGetError</tt>, <tt>alutGetErrorString</tt>,
441    <tt>alutGetMajorVersion</tt>, <tt>alutGetMinorVersion</tt>.</p>
442
443    <h3 class="manpage"><a name="alutInit"></a>alutInit</h3>
444
445    <h4>Name</h4>
446
447    <p><tt>alutInit</tt> - initialize the ALUT library and create a default
448    current context</p>
449
450    <h4>Synopsis</h4>
451
452<pre class="programlisting">
453ALboolean alutInit (int *argcp, char **argv);
454</pre>
455
456    <h4>Description</h4>
457
458    <p><tt>alutInit</tt> initializes the ALUT internals and creates an OpenAL
459    context on the default device and makes it the current OpenAL context. If
460    you want something more complex than that (e.g. running on a non-default
461    device or opening multiple contexts on multiple devices), you can use <a
462    href="#alutInitWithoutContext"><tt>alutInitWithoutContext</tt></a>
463    instead. <tt>alutInit</tt> examines the commandline arguments passed to it
464    and remove those it recognizes. It is acceptable to pass two <tt>NULL</tt>
465    pointers in settings where no useful information can be obtained from argc
466    and argv.</p>
467
468    <h4>Return Value</h4>
469
470    <p><tt>alutInit</tt> returns <tt>AL_TRUE</tt> on success or
471    <tt>AL_FALSE</tt> on failure.</p>
472
473    <h4>Errors</h4>
474
475    <dl>
476      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
477      <dd>One of the arguments was <tt>NULL</tt>, but not the other one.</dd>
478
479      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
480      <dd>ALUT has already been initialized.</dd>
481
482      <dt><tt>ALUT_ERROR_OPEN_DEVICE</tt></dt>
483      <dd>There was an error opening the default ALC device.</dd>
484
485      <dt><tt>ALUT_ERROR_CREATE_CONTEXT</tt></dt>
486      <dd>There was an error creating an ALC context.</dd>
487
488      <dt><tt>ALUT_ERROR_MAKE_CONTEXT_CURRENT</tt></dt>
489      <dd>Could not change the current ALC context.</dd>
490    </dl>
491
492    <div class="example">
493      <h4>Example: Handling command-line options</h4>
494
495      <p>If you pass <tt>alutInit</tt> the argc and argv from your main program,
496      it will examine your command-line options and use (and remove) those
497      options that it recognises:</p>
498
499<pre class="programlisting">
500int
501main (int argc, char **argv)
502{
503  alutInit (&amp;argc, argv);
504  ...
505}
506</pre>
507
508      <p>Precisely which (if any) command-line options are accepted and what
509      they control is implementation and operating system dependent. Note that
510      some implementations will use argv[0] in debug and error messages - but
511      this is not guaranteed by the API because it is operating-system
512      dependent. On some OS's, <tt>alutInit</tt> may use initial settings from
513      other sources such as 'registry' data, '<tt>.alutrc</tt>' files or shell
514      variables. Please consult the README.xxx file for your OS if you need
515      further details.</p>
516    </div>
517
518    <h3 class="manpage"><a name="alutInitWithoutContext"></a>alutInitWithoutContext</h3>
519
520    <h4>Name</h4>
521
522    <p><tt>alutInitWithoutContext</tt> - initialize the ALUT library</p>
523
524    <h4>Synopsis</h4>
525
526<pre class="programlisting">
527ALboolean alutInitWithoutContext (int *argcp, char **argv);
528</pre>
529
530    <h4>Description</h4>
531
532    <p><tt>alutInitWithoutContext</tt> initializes the ALUT internals. It does
533    not create any OpenAL context or device, so this has to be done via the
534    usual ALC calls. <tt>alutInitWithoutContext</tt> examines the commandline
535    arguments passed to it and remove those it recognizes. It is acceptable to
536    pass two <tt>NULL</tt> pointers in settings where no useful information can
537    be obtained from argc and argv.</p>
538
539    <h4>Return Value</h4>
540
541    <p><tt>alutInitWithoutContext</tt> returns <tt>AL_TRUE</tt> on success or
542    <tt>AL_FALSE</tt> on failure.</p>
543
544    <h4>Errors</h4>
545
546    <dl>
547      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
548      <dd>One of the arguments was <tt>NULL</tt>, but not the other one.</dd>
549
550      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
551      <dd>ALUT has already been initialized.</dd>
552    </dl>
553
554    <h3 class="manpage"><a name="alutExit"></a>alutExit</h3>
555
556    <h4>Name</h4>
557
558    <p><tt>alutExit</tt> - shutdown the ALUT library</p>
559
560    <h4>Synopsis</h4>
561
562<pre class="programlisting">
563ALboolean alutExit (void);
564</pre>
565
566    <h4>Description</h4>
567
568    <p>When the application has finished playing audio, it should shut down ALUT
569    using <tt>aluExit</tt>. This closes any OpenAL device/context that ALUT may
570    have created in <tt>alutInit</tt> (but not any that the application created
571    using ALC). After calling <tt>alutExit</tt>, you may subsequently call
572    <tt>alutInit</tt> or <tt>alutInitWithoutContext</tt> again. Note that under
573    well-behaved operating systems, it should be acceptable to simply exit from
574    your program without bothering to call <tt>alutExit</tt>, relying on the OS
575    to clean up after you. However, it is dangerous to rely on this behavior if
576    portable operation is expected.</p>
577
578    <h4>Return Value</h4>
579
580    <p><tt>alutExit</tt> returns <tt>AL_TRUE</tt> on success or
581    <tt>AL_FALSE</tt> on failure.</p>
582
583    <h4>Errors</h4>
584
585    <dl>
586      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
587      <dd>ALUT has not been initialised.</dd>
588
589      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
590      <dd>There is no current AL context.</dd>
591
592      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
593      <dd>There was already an AL error on entry to <tt>alutExit</tt>.</dd>
594
595      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
596      <dd>There was already an ALC error on entry to <tt>alutExit</tt>.</dd>
597
598      <dt><tt>ALUT_ERROR_CLOSE_DEVICE</tt></dt>
599      <dd>There was an error closing the ALC device created by
600      <tt>alutInit</tt>.</dd>
601
602      <dt><tt>ALUT_ERROR_MAKE_CONTEXT_CURRENT</tt></dt>
603      <dd>Could not release the current ALC context.</dd>
604
605      <dt><tt>ALUT_ERROR_DESTROY_CONTEXT</tt></dt>
606      <dd>There was an error destroying the ALC context created by
607      <tt>alutInit</tt>.</dd>
608    </dl>
609
610    <h2><a name="Loading"></a>Sound Sample File Loading</h2>
611
612    <p>ALUT attempts to simplify the business of getting a simple application
613    running by providing loaders for a range of file formats. Rather than
614    enumerate a list of formats that will likely grow with time, the loaders are
615    generic and try to do their best either by using OpenAL extensions if
616    possible or by converting the sound data into standard OpenAL formats.</p>
617
618    <p>In order to simplify initial startup and to keep test program
619    distributions clean, ALUT provides built-in sounds, too, that do not require
620    disk I/O because they are built into the ALUT library. These functions may
621    be used to write compact ALUT test/example applications with no external
622    file dependancies whatsoever. When sending short application programs to
623    either the ALUT or OpenAL developers as a part of bug reporting, one should
624    endeavor to use these functions instead of loading ones own sound files.</p>
625
626    <p>There are eight (= 4 * 2) different loaders, corresponding to the sources
627    and destinations of the sound data. The possible sources are:</p>
628
629    <ul>
630      <li>The loaders with a <tt>FromFile</tt> suffix get their sound data from
631      a named file.</li>
632
633      <li>The loaders with a <tt>FromFileImage</tt> suffix get their data from a
634      continuous memory region. This region can be re-used or destroyed
635      afterwards.</li>
636
637      <li>The loaders with a <tt>HelloWorld</tt> suffix get their fixed data
638      internally.</li>
639
640      <li>The loaders with a <tt>Waveform</tt> suffix get their data via
641      internal waveform calculation.</li>
642    </ul>
643
644    <p>The possible destinations are:</p>
645
646    <ul>
647      <li>The loaders with a <tt>alutCreateBuffer</tt> prefix create a new
648      OpenAL buffer and put the sound data into it. If possible, OpenAL
649      extensions are used to avoid conversions at the ALUT level and enable the
650      use of possible hardware/driveer features for some sound
651      formats. Therefore, these are the preferred loaders.</li>
652
653      <li>The loaders with a <tt>alutLoadMemory</tt> prefix allocate a new
654      memory region with <tt>malloc</tt> and put the sound data into it,
655      optionally passing back more information about the sound. The sound data
656      is guaranteed to be in one of the four standard OpenAL formats (8/16bit
657      monon/stereo) aftwerwards.  Because no OpenAL extensions can be used here,
658      these loaders might handle fewer sound formats than the
659      <tt>alutCreateBuffer</tt> ones.</li>
660    </ul>
661
662    <h3 class="manpage"><a name="alutCreateBufferFromFile"></a>alutCreateBufferFromFile</h3>
663
664    <h4>Name</h4>
665
666    <p><tt>alutCreateBufferFromFile</tt> - load a sound file into an OpenAL
667    buffer</p>
668
669    <h4>Synopsis</h4>
670
671<pre class="programlisting">
672ALuint alutCreateBufferFromFile (const char *filename);
673</pre>
674
675    <p><tt>alutCreateBufferFromFile</tt> tries to guess the sound data format by
676    looking at the filename and/or the file contents and loads the sound data
677    into an OpenAL buffer.</p>
678
679    <h4>Return Value</h4>
680
681    <p>On success, <tt>alutCreateBufferFromFile</tt> returns a handle to an
682    OpenAL buffer containing the loaded sound. It returns <tt>AL_NONE</tt> on
683    failure.</p>
684
685    <h4>Errors</h4>
686
687    <dl>
688      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
689      <dd>ALUT ran out of memory.</dd>
690
691      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
692      <dd>ALUT has not been initialised.</dd>
693
694      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
695      <dd>There is no current AL context.</dd>
696
697      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
698      <dd>There was already an AL error on entry to
699      <tt>alutCreateBufferFromFile</tt>.</dd>
700
701      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
702      <dd>There was already an ALC error on entry to
703      <tt>alutCreateBufferFromFile</tt>.</dd>
704
705      <dt><tt>ALUT_ERROR_GEN_BUFFERS</tt></dt>
706      <dd>There was an error generating an AL buffer.</dd>
707
708      <dt><tt>ALUT_ERROR_BUFFER_DATA</tt></dt>
709      <dd>There was an error passing buffer data to AL.</dd>
710
711      <dt><tt>ALUT_ERROR_IO_ERROR</tt></dt>
712      <dd>I/O error, consult <tt>errno</tt> for more details.</dd>
713
714      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt></dt>
715      <dd>Unsupported file type.</dd>
716
717      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt></dt>
718      <dd>Unsupported mode within an otherwise usable file type.</dd>
719
720      <dt><tt>ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA</tt></dt>
721      <dd>The sound data was corrupt or truncated.</dd>
722    </dl>
723
724    <h3 class="manpage"><a name="alutCreateBufferFromFileImage"></a>alutCreateBufferFromFileImage</h3>
725
726    <h4>Name</h4>
727
728    <p><tt>alutCreateBufferFromFileImage</tt> - load in-memory sound data into
729    an OpenAL buffer</p>
730
731    <h4>Synopsis</h4>
732
733<pre class="programlisting">
734ALuint alutCreateBufferFromFileImage (const ALvoid *data, ALsizei length);
735</pre>
736
737    <p><tt>alutCreateBufferFromFileImage</tt> tries to guess the sound data
738    format by looking at the contents of the memory region given as parameters
739    and loads the sound data into an OpenAL buffer.</p>
740
741    <h4>Return Value</h4>
742
743    <p>On success, <tt>alutCreateBufferFromFileImage</tt> returns a handle to an
744    OpenAL buffer containing the loaded sound. It returns <tt>AL_NONE</tt> on
745    failure.</p>
746
747    <h4>Errors</h4>
748
749    <dl>
750      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
751      <dd>ALUT ran out of memory.</dd>
752
753      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
754      <dd>ALUT has not been initialised.</dd>
755
756      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
757      <dd>There is no current AL context.</dd>
758
759      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
760      <dd>There was already an AL error on entry to
761      <tt>alutCreateBufferFromFileImage</tt>.</dd>
762
763      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
764      <dd>There was already an ALC error on entry to
765      <tt>alutCreateBufferFromFileImage</tt>.</dd>
766
767      <dt><tt>ALUT_ERROR_GEN_BUFFERS</tt></dt>
768      <dd>There was an error generating an AL buffer.</dd>
769
770      <dt><tt>ALUT_ERROR_BUFFER_DATA</tt></dt>
771      <dd>There was an error passing buffer data to AL.</dd>
772
773      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt></dt>
774      <dd>Unsupported file type.</dd>
775
776      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt></dt>
777      <dd>Unsupported mode within an otherwise usable file type.</dd>
778
779      <dt><tt>ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA</tt></dt>
780      <dd>The sound data was corrupt or truncated.</dd>
781    </dl>
782
783    <h3 class="manpage"><a name="alutCreateBufferHelloWorld"></a>alutCreateBufferHelloWorld</h3>
784
785    <h4>Name</h4>
786
787    <p><tt>alutCreateBufferHelloWorld</tt> - create a buffer with a 'Hello, world!' sound</p>
788
789    <h4>Synopsis</h4>
790
791<pre class="programlisting">
792ALuint alutCreateBufferHelloWorld (void);
793</pre>
794
795    <h4>Description</h4>
796
797    <p><tt>alutCreateBufferHelloWorld</tt> returns a handle to an OpenAL buffer
798    containing the sound of someone saying 'Hello, world!'.</p>
799
800    <h4>Return Value</h4>
801
802    <p>On success, <tt>alutCreateBufferHelloWorld</tt> returns a handle to an
803    OpenAL buffer containing a 'Hello, world!' sound. It returns
804    <tt>AL_NONE</tt> on failure.</p>
805
806    <h4>Errors</h4>
807
808    <dl>
809      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
810      <dd>ALUT ran out of memory.</dd>
811
812      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
813      <dd>ALUT has not been initialised.</dd>
814
815      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
816      <dd>There is no current AL context.</dd>
817
818      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
819      <dd>There was already an AL error on entry to
820      <tt>alutCreateBufferHelloWorld</tt>.</dd>
821
822      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
823      <dd>There was already an ALC error on entry to
824      <tt>alutCreateBufferHelloWorld</tt>.</dd>
825
826      <dt><tt>ALUT_ERROR_GEN_BUFFERS</tt></dt>
827      <dd>There was an error generating an AL buffer.</dd>
828
829      <dt><tt>ALUT_ERROR_BUFFER_DATA</tt></dt>
830      <dd>There was an error passing buffer data to AL.</dd>
831    </dl>
832
833    <h3 class="manpage"><a name="alutCreateBufferWaveform"></a>alutCreateBufferWaveform</h3>
834
835    <h4>Name</h4>
836
837    <p><tt>alutCreateBufferWaveform</tt> - create a buffer with a synthesized waveform sound</p>
838
839    <h4>Synopsis</h4>
840
841<pre class="programlisting">
842ALuint alutCreateBufferWaveform (ALenum waveshape,
843                                 ALfloat frequency,
844                                 ALfloat phase,
845                                 ALfloat duration);
846</pre>
847
848    <h4>Description</h4>
849
850    <p><tt>alutCreateBufferWaveform</tt> returns a handle to an OpenAL buffer
851    containing a snippet of audio with the specified waveshape at the specified
852    frequency (in Hertz), phase (in degrees: -180 to +180) and duration (in
853    seconds). Allowed waveforms are:</p>
854
855    <ul>
856      <li><tt>ALUT_WAVEFORM_SINE</tt></li>
857      <li><tt>ALUT_WAVEFORM_SQUARE</tt></li>
858      <li><tt>ALUT_WAVEFORM_SAWTOOTH</tt></li>
859      <li><tt>ALUT_WAVEFORM_WHITENOISE</tt></li>
860      <li><tt>ALUT_WAVEFORM_IMPULSE</tt></li>
861    </ul>
862
863    <p>The duration will always be rounded up to an exact number of cycles of
864    the sound to avoid a click if you loop the sample. The frequency and phase
865    arguments are ignored for <tt>ALUT_WHITENOISE</tt>.</p>
866
867    <h4>Return Value</h4>
868
869    <p>On success, <tt>alutCreateBufferWaveform</tt> returns a handle to an
870    OpenAL buffer containing the synthesized waveform. It returns
871    <tt>AL_NONE</tt> on failure.</p>
872
873    <h4>Errors</h4>
874
875    <dl>
876      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
877      <dd>ALUT ran out of memory.</dd>
878
879      <dt><tt>ALUT_ERROR_INVALID_ENUM</tt></dt>
880      <dd>An invalid waveform token was given to
881      <tt>alutCreateBufferWaveform</tt>.</dd>
882
883      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
884      <dd>The frequency was not positive or the duration was negative.</dd>
885
886      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
887      <dd>ALUT has not been initialised.</dd>
888
889      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
890      <dd>There is no current AL context.</dd>
891
892      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
893      <dd>There was already an AL error on entry to
894      <tt>alutCreateBufferWaveform</tt>.</dd>
895
896      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
897      <dd>There was already an ALC error on entry to
898      <tt>alutCreateBufferWaveform</tt>.</dd>
899
900      <dt><tt>ALUT_ERROR_GEN_BUFFERS</tt></dt>
901      <dd>There was an error generating an AL buffer.</dd>
902
903      <dt><tt>ALUT_ERROR_BUFFER_DATA</tt></dt>
904      <dd>There was an error passing buffer data to AL.</dd>
905    </dl>
906
907    <h3 class="manpage"><a name="alutLoadMemoryFromFile"></a>alutLoadMemoryFromFile</h3>
908
909    <h4>Name</h4>
910
911    <p><tt>alutLoadMemoryFromFile</tt> - load a sound file into OpenAL-like
912    data</p>
913
914    <h4>Synopsis</h4>
915
916<pre class="programlisting">
917ALvoid *alutLoadMemoryFromFile (const char *filename,
918                                ALenum *format,
919                                ALsizei *size,
920                                ALfloat *frequency);
921</pre>
922
923    <p><tt>alutLoadMemoryFromFile</tt> tries to guess the sound data format by
924    looking at the filename and/or the file contents and loads the sound data
925    into a newly <tt>malloc</tt>ed buffer, possibly converting it in the
926    process. The format is guaranteed to be a standard OpenAL format
927    afterwards.</p>
928
929    <h4>Return Value</h4>
930
931    <p>On success, <tt>alutLoadMemoryFromFile</tt> returns a pointer to a newly
932    allocated memory area containing the sound data, which can be <tt>free</tt>d
933    if not needed anymore. It returns <tt>NULL</tt> on failure. If any of the
934    format, size or frequency parameters are non-<tt>NULL</tt>, the respective
935    information about the sound will be passed back.</p>
936
937    <h4>Errors</h4>
938
939    <dl>
940      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
941      <dd>ALUT ran out of memory.</dd>
942
943      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
944      <dd>ALUT has not been initialised.</dd>
945
946      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
947      <dd>There is no current AL context.</dd>
948
949      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
950      <dd>There was already an AL error on entry to
951      <tt>alutLoadMemoryFromFile</tt>.</dd>
952
953      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
954      <dd>There was already an ALC error on entry to
955      <tt>alutLoadMemoryFromFile</tt>.</dd>
956
957      <dt><tt>ALUT_ERROR_IO_ERROR</tt></dt>
958      <dd>I/O error, consult <tt>errno</tt> for more details.</dd>
959
960      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt></dt>
961      <dd>Unsupported file type.</dd>
962
963      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt></dt>
964      <dd>Unsupported mode within an otherwise usable file type.</dd>
965
966      <dt><tt>ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA</tt></dt>
967      <dd>The sound data was corrupt or truncated.</dd>
968    </dl>
969
970    <h3 class="manpage"><a name="alutLoadMemoryFromFileImage"></a>alutLoadMemoryFromFileImage</h3>
971
972    <h4>Name</h4>
973
974    <p><tt>alutLoadMemoryFromFileImage</tt> - convert in-memory sound data into
975    OpenAL-like data</p>
976
977    <h4>Synopsis</h4>
978
979<pre class="programlisting">
980ALvoid *alutLoadMemoryFromFileImage (const ALvoid *data,
981                                     ALsizei length,
982                                     ALenum *format,
983                                     ALsizei *size,
984                                     ALfloat *frequency);
985</pre>
986
987    <p><tt>alutLoadMemoryFromFileImage</tt> tries to guess the sound data format
988    by looking at the contents of the memory region given as the first two
989    arguments and loads the sound data into a newly <tt>malloc</tt>ed buffer,
990    possibly converting it in the process. The format is guaranteed to be a
991    standard OpenAL format afterwards.</p>
992
993    <h4>Return Value</h4>
994
995    <p>On success, <tt>alutLoadMemoryFromFileImage</tt> returns a pointer to a
996    newly allocated memory area containing the sound data, which can be
997    <tt>free</tt>d if not needed anymore. It returns <tt>NULL</tt> on
998    failure. If any of the format, size or frequency parameters are
999    non-<tt>NULL</tt>, the respective information about the sound will be passed
1000    back.</p>
1001
1002    <h4>Errors</h4>
1003
1004    <dl>
1005      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
1006      <dd>ALUT ran out of memory.</dd>
1007
1008      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
1009      <dd>ALUT has not been initialised.</dd>
1010
1011      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
1012      <dd>There is no current AL context.</dd>
1013
1014      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
1015      <dd>There was already an AL error on entry to
1016      <tt>alutLoadMemoryFromFileImage</tt>.</dd>
1017
1018      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
1019      <dd>There was already an ALC error on entry to
1020      <tt>alutLoadMemoryFromFileImage</tt>.</dd>
1021
1022      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt></dt>
1023      <dd>Unsupported file type.</dd>
1024
1025      <dt><tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt></dt>
1026      <dd>Unsupported mode within an otherwise usable file type.</dd>
1027
1028      <dt><tt>ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA</tt></dt>
1029      <dd>The sound data was corrupt or truncated.</dd>
1030    </dl>
1031
1032    <h3 class="manpage"><a name="alutLoadMemoryHelloWorld"></a>alutLoadMemoryHelloWorld</h3>
1033
1034    <h4>Name</h4>
1035
1036    <p><tt>alutLoadMemoryHelloWorld</tt> - load a 'Hello, world!' sound into
1037    OpenAL-like data</p>
1038
1039    <h4>Synopsis</h4>
1040
1041<pre class="programlisting">
1042ALvoid *alutLoadMemoryHelloWorld (ALenum *format,
1043                                  ALsizei *size,
1044                                  ALfloat *frequency);
1045
1046</pre>
1047
1048    <h4>Description</h4>
1049
1050    <p><tt>alutLoadMemoryHelloWorld</tt> loads the sound of someone saying
1051    'Hello, world!' into a newly <tt>malloc</tt>ed buffer. The sound data is
1052    guaranteed to be in a standard OpenAL format, with a sample frequency chosen
1053    by the ALUT implementation.</p>
1054
1055    <h4>Return Value</h4>
1056
1057    <p>On success, <tt>alutLoadMemoryHelloWorld</tt> returns a pointer to a
1058    newly allocated memory area containing the sound data, which can be
1059    <tt>free</tt>d if not needed anymore. It returns <tt>NULL</tt> on
1060    failure. If any of the format, size or frequency parameters are
1061    non-<tt>NULL</tt>, the respective information about the sound will be passed
1062    back.</p>
1063
1064    <h4>Errors</h4>
1065
1066    <dl>
1067      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
1068      <dd>ALUT ran out of memory.</dd>
1069
1070      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
1071      <dd>ALUT has not been initialised.</dd>
1072
1073      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
1074      <dd>There is no current AL context.</dd>
1075
1076      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
1077      <dd>There was already an AL error on entry to
1078      <tt>alutLoadMemoryHelloWorld</tt>.</dd>
1079
1080      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
1081      <dd>There was already an ALC error on entry to
1082      <tt>alutLoadMemoryHelloWorld</tt>.</dd>
1083    </dl>
1084
1085    <h3 class="manpage"><a name="alutLoadMemoryWaveform"></a>alutLoadMemoryWaveform</h3>
1086
1087    <h4>Name</h4>
1088
1089    <p><tt>alutLoadMemoryWaveform</tt> - load a synthesized waveform sound into
1090    OpenAL-like data</p>
1091
1092    <h4>Synopsis</h4>
1093
1094<pre class="programlisting">
1095ALvoid *alutLoadMemoryWaveform (ALenum waveshape,
1096                                ALfloat frequency,
1097                                ALfloat phase,
1098                                ALfloat duration,
1099                                ALenum *format,
1100                                ALsizei *size,
1101                                ALfloat *sampleFrequency);
1102</pre>
1103
1104    <h4>Description</h4>
1105
1106    <p><tt>alutLoadMemoryWaveform</tt> loads a snippet of audio with the
1107    specified waveshape at the specified frequency (in Hertz), phase (in
1108    degrees: -180 to +180) and duration (in seconds) into a newly
1109    <tt>malloc</tt>ed buffer. The sound data is guaranteed to be in a standard
1110    OpenAL format, with a sample frequency chosen by the ALUT
1111    implementation. Allowed waveforms are:</p>
1112
1113    <ul>
1114      <li><tt>ALUT_WAVEFORM_SINE</tt></li>
1115      <li><tt>ALUT_WAVEFORM_SQUARE</tt></li>
1116      <li><tt>ALUT_WAVEFORM_SAWTOOTH</tt></li>
1117      <li><tt>ALUT_WAVEFORM_WHITENOISE</tt></li>
1118      <li><tt>ALUT_WAVEFORM_IMPULSE</tt></li>
1119    </ul>
1120
1121    <p>The duration will always be rounded up to an exact number of cycles of
1122    the sound to avoid a click if you loop the sample. The frequency and phase
1123    arguments are ignored for <tt>ALUT_WHITENOISE</tt>.</p>
1124
1125    <h4>Return Value</h4>
1126
1127    <p>On success, <tt>alutLoadMemoryWaveform</tt> returns a pointer to a newly
1128    allocated memory area containing the sound data, which can be <tt>free</tt>d
1129    if not needed anymore. It returns <tt>NULL</tt> on failure. If any of the
1130    format, size or sample frequency parameters are non-<tt>NULL</tt>, the
1131    respective information about the sound will be passed back.</p>
1132
1133    <h4>Errors</h4>
1134
1135    <dl>
1136      <dt><tt>ALUT_ERROR_OUT_OF_MEMORY</tt></dt>
1137      <dd>ALUT ran out of memory.</dd>
1138
1139      <dt><tt>ALUT_ERROR_INVALID_ENUM</tt></dt>
1140      <dd>An invalid waveform token was given to
1141      <tt>alutLoadMemoryWaveform</tt>.</dd>
1142
1143      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
1144      <dd>The frequency was not positive or the duration was negative.</dd>
1145
1146      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
1147      <dd>ALUT has not been initialised.</dd>
1148
1149      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
1150      <dd>There is no current AL context.</dd>
1151
1152      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
1153      <dd>There was already an AL error on entry to
1154      <tt>alutLoadMemoryWaveform</tt>.</dd>
1155
1156      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
1157      <dd>There was already an ALC error on entry to
1158      <tt>alutLoadMemoryWaveform</tt>.</dd>
1159    </dl>
1160
1161    <h3 class="manpage"><a name="alutGetMIMETypes"></a>alutGetMIMETypes</h3>
1162
1163    <h4>Name</h4>
1164
1165    <p><tt>alutGetMIMETypes</tt> - get list support supported audio MIME types</p>
1166
1167    <h4>Synopsis</h4>
1168
1169<pre class="programlisting">
1170const char *alutGetMIMETypes (ALenum loader);
1171</pre>
1172
1173    <h4>Description</h4>
1174
1175    <p><tt>alutGetMIMETypes</tt> returns a comma-separated list of
1176    supported MIME types for the given loader type, e.g. something like
1177    &quot;<tt>audio/basic,audio/mpeg,audio/x-wav</tt>&quot;. Allowed loader
1178    types are:</p>
1179
1180    <dl>
1181      <dt><tt>ALUT_LOADER_BUFFER</tt></dt>
1182
1183      <dd>For the loaders returning sound data in an OpenAL buffer,
1184      e.g. <tt>alutCreateBufferFromFile</tt> and
1185      <tt>alutCreateBufferFromFileImage</tt></dd>
1186
1187      <dt><tt>ALUT_LOADER_MEMORY</tt></dt>
1188
1189      <dd>For the loaders returning sound data in a newly allocated memory
1190      region, e.g. <tt>alutLoadMemoryFromFile</tt> and
1191      <tt>alutLoadMemoryFromFileImage</tt></dd>
1192    </dl>
1193
1194    <p>It is possible that <tt>ALUT_LOADER_MEMORY</tt> loaders will be unable to
1195    support some file types that <tt>ALUT_LOADER_BUFFER</tt> loaders can support
1196    (although the reverse is never the case). Furthermore, it is possible that
1197    for some file types (notably audio/x-wav) the support may be only for a few
1198    sub-formats. For example, an implementation may advertise that audio/x-wav
1199    is supported when in fact it only supports uncompressed (i.e. PCM) WAV files
1200    and not any of the compressed subformats. In this event, the various ALUT
1201    loaders may return an error and set
1202    <tt>ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE</tt> rather than
1203    <tt>ALUT_ERROR_UNSUPPORTED_FILE_TYPE</tt> which would indicate that no files
1204    of this type are allowed.</p>
1205
1206    <h4>Return Value</h4>
1207
1208    <p>On success, <tt>alutGetMIMETypes</tt> returns a zero-terminated string
1209    which contains a comma-separated list of supported MIME types. It returns
1210    <tt>NULL</tt> on failure.</p>
1211
1212    <h4>Errors</h4>
1213
1214    <dl>
1215      <dt><tt>ALUT_ERROR_INVALID_ENUM</tt></dt>
1216      <dd><tt>alutGetMIMETypes</tt> was given an invalid loader token.</dd>
1217
1218      <dt><tt>ALUT_ERROR_INVALID_OPERATION</tt></dt>
1219      <dd>ALUT has not been initialised.</dd>
1220
1221      <dt><tt>ALUT_ERROR_NO_CURRENT_CONTEXT</tt></dt>
1222      <dd>There is no current AL context.</dd>
1223
1224      <dt><tt>ALUT_ERROR_AL_ERROR_ON_ENTRY</tt></dt>
1225      <dd>There was already an AL error on entry to
1226      <tt>alutGetMIMETypes</tt>.</dd>
1227
1228      <dt><tt>ALUT_ERROR_ALC_ERROR_ON_ENTRY</tt></dt>
1229      <dd>There was already an ALC error on entry to
1230      <tt>alutGetMIMETypes</tt>.</dd>
1231    </dl>
1232
1233    <h3><a name="DeprecatedWAVLoaders"></a>Deprecated WAV loaders</h3>
1234
1235    <p>For backwards-compatibility with ALUT 0.x.x, ALUT still offers the three
1236    deprecated functions below. Note that on MacOS 0.x.x version, the
1237    '<tt>loop</tt>' parameter is omitted from both loader functions.</p>
1238
1239<pre class="programlisting">
1240void alutLoadWAVFile (ALbyte *filename,
1241                      ALenum *format,
1242                      void **data,
1243                      ALsizei *size,
1244                      ALsizei *frequency,
1245                      ALboolean *loop);
1246
1247void alutLoadWAVMemory (ALbyte *buffer,
1248                        ALenum *format,
1249                        void **data,
1250                        ALsizei *size,
1251                        ALsizei *frequency,
1252                        ALboolean *loop);
1253
1254void alutUnloadWAV (ALenum format ALvoid *data, ALsizei size, ALsizei frequency);
1255</pre>
1256
1257    <h2><a name="VersionChecking"></a>Version Checking</h2>
1258
1259    <p>ALUT version numbers consist of a major version number, a minor version
1260    number, and a patchlevel. The former two numbers will match the major/minor
1261    version number of the corresponding ALUT specification document and can be
1262    accessed at compile time as well as runtime. The patchlevel is not
1263    programmatically available and it is incremented only when fixing bugs
1264    without any API changes.</p>
1265
1266    <h3 class="manpage"><a name="alutGetMajorVersion"></a>alutGetMajorVersion</h3>
1267
1268    <h4>Name</h4>
1269
1270    <p><tt>alutGetMajorVersion</tt> - return the major ALUT version number</p>
1271
1272    <h4>Synopsis</h4>
1273
1274<pre class="programlisting">
1275ALint alutGetMajorVersion (void);
1276</pre>
1277
1278    <h4>Description</h4>
1279
1280    <p><tt>alutGetMajorVersion</tt> returns the major version number of the ALUT
1281    in use, which will match the major version number of the corresponding ALUT
1282    specification document.</p>
1283
1284    <h4>Return Value</h4>
1285
1286    <p><tt>alutGetMajorVersion</tt> returns the major version number of the ALUT
1287    in use.</p>
1288
1289    <h4>Errors</h4>
1290
1291    <p><tt>alutGetMajorVersion</tt> can be called in any ALUT state and will
1292    never fail.</p>
1293
1294    <h3 class="manpage"><a name="alutGetMinorVersion"></a>alutGetMinorVersion</h3>
1295
1296    <h4>Name</h4>
1297
1298    <p><tt>alutGetMinorVersion</tt> - return the minor ALUT version number</p>
1299
1300    <h4>Synopsis</h4>
1301
1302<pre class="programlisting">
1303ALint alutGetMinorVersion (void);
1304</pre>
1305
1306    <h4>Description</h4>
1307
1308    <p><tt>alutGetMinorVersion</tt> returns the minor version number of the ALUT
1309    in use, which will match the minor version number of the corresponding ALUT
1310    specification document.</p>
1311
1312    <h4>Return Value</h4>
1313
1314    <p><tt>alutGetMinorVersion</tt> returns the minor version number of the ALUT
1315    in use.</p>
1316
1317    <h4>Errors</h4>
1318
1319    <p><tt>alutGetMinorVersion</tt> can be called in any ALUT state and will
1320    never fail.</p>
1321
1322    <h3><a name="VersioningMacros"></a>Compile Time Version Checking</h3>
1323
1324<pre class="programlisting">
1325#define ALUT_API_MAJOR_VERSION 1
1326
1327#define ALUT_API_MINOR_VERSION 1
1328</pre>
1329
1330    <p>Version 1.0.0 introduced the above preprocessor symbols, whose values
1331    will be incremented appropriately in future revisions of ALUT. In version
1332    1.1.0, <tt>alutLoadMemoryHelloWorld</tt> and <tt>alutLoadMemoryWaveform</tt>
1333    have been added to the ALUT API.</p>
1334
1335    <div class="example">
1336      <h4>Example: Version consistency check</h4>
1337
1338      <p>Applications can verify at runtime that they have been compiled and
1339      linked with the matching header file and library file as follows:</p>
1340
1341<pre class="programlisting">
1342#ifdef ALUT_API_MAJOR_VERSION
1343if (alutGetMajorVersion () != ALUT_API_MAJOR_VERSION ||
1344    alutGetMinorVersion () != ALUT_API_MINOR_VERSION)
1345  /* Oh-oh!  The ALUT header and the ALUT library are different revisions... */
1346#else
1347  /* Oh-oh!  We're linking against an ALUT 0.x.x header file... */
1348#endif
1349</pre>
1350    </div>
1351
1352    <h2><a name="Sleeping"></a>Sleeping</h2>
1353
1354    <p>Having a general utility function like the following in an audio-related
1355    toolkit might seem strange at first, but sleeping is a common task in a lot
1356    of audio demos and it can't be done portably without cluttering the source
1357    code with <tt>#ifdefs</tt>.</p>
1358
1359    <h3 class="manpage"><a name="alutSleep"></a>alutSleep</h3>
1360
1361    <h4>Name</h4>
1362
1363    <p><tt>alutSleep</tt> - sleep for a given number of seconds</p>
1364
1365    <h4>Synopsis</h4>
1366
1367<pre class="programlisting">
1368ALboolean alutSleep (ALfloat duration);
1369</pre>
1370
1371    <h4>Description</h4>
1372
1373    <p><tt>alutSleep</tt> will delay the execution of the current thread for at
1374    least the given amount of seconds. It will only return earlier if a signal
1375    has been delivered to the thread, but this does not count as an error. Note
1376    that sleeping for zero seconds will give other runnable threads a chance to
1377    run.</p>
1378
1379    <h4>Return Value</h4>
1380
1381    <p><tt>alutSleep</tt> returns <tt>AL_TRUE</tt> on success or
1382    <tt>AL_FALSE</tt> on failure. Note that current implementations will always
1383    succeed if the duration is non-negative, but this might change in the
1384    future.</p>
1385
1386    <h4>Errors</h4>
1387
1388    <dl>
1389      <dt><tt>ALUT_ERROR_INVALID_VALUE</tt></dt>
1390      <dd><tt>alutSleep</tt> was given a negative duration.</dd>
1391    </dl>
1392
1393  </body>
1394</html>
1395<!-- Emacs stuff:
1396     ;;; Local Variables: ***
1397     ;;; mode: xml ***
1398     ;;; End: ***
1399 -->
Note: See TracBrowser for help on using the repository browser.