doc/alut.html

   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">
 162 LD_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
 189 int
 190 main (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">
 231 pkg-config --cflags freealut
 232 freealut-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">
 239 pkg-config --libs freealut
 240 freealut-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">
 272 ALenum 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">
 363 const 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">
 390 static void
 391 reportError (void)
 392 {
 393   fprintf (stderr, "ALUT error: %s\n",
 394            alutGetErrorString (alutGetError ()));
 395   exit (EXIT_FAILURE);
 396 }
 397
 398 int
 399 main (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">
 453 ALboolean 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">
 500 int
 501 main (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">
 527 ALboolean 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">
 563 ALboolean 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">
 672 ALuint 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">
 734 ALuint 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">
 792 ALuint 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">
 842 ALuint 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">
 917 ALvoid *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">
 980 ALvoid *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">
1042 ALvoid *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">
1095 ALvoid *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">
1170 const 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">
1240 void alutLoadWAVFile (ALbyte *filename,
1241                       ALenum *format,
1242                       void **data,
1243                       ALsizei *size,
1244                       ALsizei *frequency,
1245                       ALboolean *loop);
1246
1247 void alutLoadWAVMemory (ALbyte *buffer,
1248                         ALenum *format,
1249                         void **data,
1250                         ALsizei *size,
1251                         ALsizei *frequency,
1252                         ALboolean *loop);
1253
1254 void 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">
1275 ALint 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">
1303 ALint 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
1343 if (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">
1368 ALboolean 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  -->