Added lesson 6

git-svn-id: file:///home/mbien/NetBeansProjects/JOGAMP/joal-sync/svn-server-sync-demos/joal-demos/trunk@31 235fdd13-0e8c-4fed-b5ee-0a390d04b286
author: athomas <[email protected]> 2003-07-08 20:03:06 +0000
committer: athomas <[email protected]> 2003-07-08 20:03:06 +0000
commit: 4bf057572535db6a4b29b0fa4702ecab82a34885 (patch)
tree: c94727b87efe10dff9b9a6c9ebf73d792aca7810 /www
parent: 58f406079040312c9efd3d737881367550b8520a (diff)
2 files changed, 347 insertions, 0 deletions
diff --git a/www/devmaster/lesson6.html b/www/devmaster/lesson6.html
new file mode 100644
index 0000000..3a0c5ee
--- /dev/null
+++ b/www/devmaster/lesson6.html
@@ -0,0 +1,344 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>Untitled Document</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="stylesheet" type="text/css" href="general.css">
+</head>
+<body>
+
+<div align="center">
+
+<IMG SRC="http://games.dev.java.net/images/navbar.gif" WIDTH=454 HEIGHT=43 BORDER=0 ALT="" USEMAP="#navbar_Map"></div>
+  <MAP NAME="navbar_Map">
+    <AREA SHAPE="rect" ALT="Wiki" COORDS="340,0,386,43" HREF="http://wiki.java.net/bin/view/Games">
+    <AREA SHAPE="rect" ALT="Weblogs" COORDS="286,0,339,43" HREF="http://weblogs.java.net/weblogs/project/games">
+    <AREA SHAPE="rect" ALT="Forums" COORDS="216,0,285,43" HREF="http://games.dev.java.net/forums">
+    <AREA SHAPE="rect" ALT="JavaGames Home" COORDS="91,0,215,43" HREF="http://community.java.net/games">
+    <AREA SHAPE="rect" ALT="www.java.net" COORDS="1,1,91,44" HREF="http://www.java.net" TARGET="_self">
+  </MAP><br>
+<br>
+OpenAL Tutorials from DevMaster.net. Reprinted with Permission.<br>
+<br>
+<table border="0" cellspacing="0" style="border-collapse: collapse" width="100%" cellpadding="0" id="AutoNumber1" height="12" bgcolor="#666699">
+  <tr> 
+    <td width="47%" height="12" valign="middle"><p><b><font color="#FFFFFF">OpenAL 
+        Tutorials</font></b></p></td>
+    <td width="53%" height="12" align="right" valign="middle"><p align="right"><a href="http://devmaster.net/"><font color="#66FF99">DevMaster.net</font></a></p></td>
+  </tr>
+</table>
+<p class="ArticleTitle"><font size="5">Advanced Loading and Error Handles<br>
+  </font><font color="#000000" size="4"><strong>Lesson 6</strong></font></p>
+<p align="right" class="ArticleAuthor">Author: <a href="mailto:[email protected]">Jesse 
+  Maurais</a><br>
+  Adapted For Java By: <a href="mailto:[email protected]">Athomas Goldberg</a></p>
+<p>We've been doing some pretty simple stuff up until now that didn't require 
+  us to be very precise in the way we've handled things. The reason for this is 
+  that we have been writing code for simplicity in order to learn easier, rather 
+  that for robustness. Since we are going to move into some advanced stuff soon 
+  we will take some time to learn the proper ways. Most importantly we will learn 
+  a more advanced way of handling errors. We will also reorganize the way we have 
+  been loading audio data. There wasn't anything wrong with our methods in particular, 
+  but we will need a more organized and flexible approach to the process.</p>
+<p>We will first consider a few functions that will help us out a lot by the time 
+  we have finished.</p>
+<pre class=code><font color="#0000FF"><span class=codeComment><font color="#006600">/**
+ * 1) Identify the error code.
+ * 2) Return the error as a string.
+ */</font></span>
+public</font> <font color="#0000FF">static</font> String getALErrorString(<font color="#0000FF">int</font> err);
+
+<span class=codeComment><font color="#006600">/**
+ * 1) Identify the error code.
+ * 2) Return the error as a string.
+ */</font></span>
+<font color="#0000FF">public</font> <font color="#0000FF">static</font> String getALCErrorString(<font color="#0000FF">int</font> err);
+
+<font color="#0000FF"><span class=codeComment><font color="#006600">/**
+ * 1) Creates a buffer.
+ * 2) Loads a wav file into the buffer.
+ * 3) Returns the buffer id.
+ */</font></span>
+public static int </font>loadALBuffer(String path) <font color="#0000FF">throws</font> IOException;
+
+<span class=codeComment><font color="#006600">/**
+ * 1) Checks if file has already been loaded.
+ * 2) If it has been loaded already, return the buffer id.
+ * 3) If it has not been loaded, load it and return buffer id.
+ */</font></span>
+<font color="#0000FF">public static int </font>getLoadedALBuffer(String path) <font color="#0000FF">throws</font> IOException;
+
+
+<font color="#0000FF"><span class=codeComment><font color="#006600">/**
+ * 1) Creates a source.
+ * 2) Calls 'GetLoadedALBuffer' with 'path' and uses the
+ *    returned buffer id as it's sources buffer.
+ * 3) Returns the source id.
+ */
+</font></span>public static int </font>loadALSample(String path, <span class=codeKeyword><font color="#0000FF">boolean</font></span> loop) <font color="#0000FF">throws</font> IOException;
+<span class=codeKeyword>
+</span><span class=codeComment><font color="#006600">/**
+ * 1) Releases temporary loading phase data.
+ */</font></span>
+<span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALLoadedData();
+<span class=codeKeyword>
+</span><span class=codeComment><font color="#006600">/**
+ * 1) Loads all buffers and sources for the application.
+ */</font></span>
+<span class=codeKeyword><font color="#0000FF">public static boolean</font></span><font color="#0000FF"> </font>loadALData();
+<span class=codeKeyword>
+</span><span class=codeComment><font color="#006600">/**
+ * 1) Releases all buffers.
+ * 2) Releases all sources.
+ */</font></span>
+<font color="#0000FF"><span class=codeKeyword>public </span>static <span class=codeKeyword>void</span> </font>killALData();
+
+
+<font color="#0000FF">private static</font> Vector loadedFiles = <font color="#0000FF">new</font> Vector(); <span class=codeComment><font color="#006600">// Holds loaded file paths temporarily.</font></span>
+
+<font color="#0000FF">private static</font> Vector buffers = <font color="#0000FF">new</font> Vector(); <span class=codeComment><font color="#006600">// Holds all loaded buffers.</font></span><font color="#006600">
+</font><font color="#0000FF">private static</font> Vector sources<font color="#006600"> = <font color="#0000FF">new</font> </font>Vector();<font color="#006600"> <span class=codeComment>// Holds all validated sources.</span></font>
+</pre>
+<p>Take a close look at the functions and try to understand what we are going 
+  to be doing. Basically what we are trying to create is a system in which we 
+  no longer have to worry about the relationship between buffers and sources. 
+  We can call for the creation of a source from a file and this system will handle 
+  the buffer's creation on it's own so we don't duplicate a buffer (have two buffers 
+  with the same data). This system will handle the buffers as a limited resource, 
+  and will handle that resource efficiently.</p>
+<pre class=code><font color="#0000FF">public</font> String getALErrorString(<font color="#0000FF">int</font> err) {
+    <span class=codeKeyword><font color="#0000FF">switch</font></span>(err) {
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_NO_ERROR: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_NO_ERROR";
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_INVALID_NAME: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_INVALID_NAME";
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_INVALID_ENUM: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_INVALID_ENUM";
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_INVALID_VALUE: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_INVALID_VALUE";
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_INVALID_OPERATION: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_INVALID_OPERATION";
+        <span class=codeKeyword><font color="#0000FF">case</font></span> AL.AL_OUT_OF_MEMORY: <span class=codeKeyword><font color="#0000FF">return</font></span> "AL_OUT_OF_MEMORY";
+        <font color="#0000FF">default</font>: <font color="#0000FF">return</font> <font color="#0000FF">null</font>;
+    }
+}
+
+</pre>
+<p>This function will convert an OpenAL error code to a string so it can be read 
+  on the console (or some other device). The OpenAL sdk says that the only exception 
+  that needs be looked for in the current version is the 'AL_OUT_OF_MEMORY' error. 
+  However, we will account for all the errors so that our code will be up to date 
+  with later versions.</p>
+<pre class=code><font color="#0000FF">public</font> String getALCErrorString(<font color="#0000FF">int</font> err) {
+    <span class=codeKeyword><font color="#0000FF">switch</font></span>(err) {
+        <span class=codeKeyword><font color="#0000FF">case</font></span> ALC_NO_ERROR: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_NO_ERROR";
+<span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_DEVICE: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_DEVICE";
+<span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_CONTEXT: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_CONTEXT";
+<span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_ENUM: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_ENUM";
+<span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_VALUE: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_VALUE";
+<span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_OUT_OF_MEMORY: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_OUT_OF_MEMORY";
+        <font color="#0000FF">default</font>: <font color="#0000FF">return</font> <font color="#0000FF">null</font>;
+    }
+}
+
+</pre>
+<p>This function will perform a similar task as the previous one accept this one 
+  will interpret Alc errors. OpenAL and Alc share common id's, but not common 
+  enough and not dissimilar enough to use the same function for both.</p>
+<p>One more note about the function 'alGetError': The OpenAL sdk defines that 
+  it only holds a single error at a time (i.e. there is no stacking). When the 
+  function is invoked it will return the first error that it has received, and 
+  then clear the error bit to 'AL_NO_ERROR'. In other words an error will only 
+  be stored in the error bit if no previous error is already stored there.</p>
+<pre class=code><font color="#0000FF">public int</font> loadALBuffer(String path) <font color="#0000FF">throws</font> IOException {
+    <span class=codeComment><font color="#006600">// Variables to store data which defines the buffer.</font></span>
+    <font color="#0000FF">int</font>[] format = <font color="#0000FF">new int</font>[1];
+    <font color="#0000FF">int</font>[] size = <font color="#0000FF">new int</font>[1];
+    ByteBuffer[] data = <font color="#0000FF">new</font> ByteBuffer[1];
+    <font color="#0000FF">int</font>[] freq = <font color="#0000FF">new int</font>[1];
+    <font color="#0000FF">int</font>[] loop = <font color="#0000FF">new int</font>[1];
+
+    <font color="#006600"><span class=codeComment>// Buffer id and error checking variable.</span></font>
+    <font color="#0000FF">int</font>[] buffer = <font color="#0000FF">new int</font>[1];
+    int result;
+
+    <span class=codeComment><font color="#006600">// Generate a buffer. Check that it was created successfully.</font></span>
+    al.alGenBuffers(1, buffer);
+
+    <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
+        <span class=codeKeyword><font color="#0000FF">throw</font></span><font color="#0000FF"> new</font> IOException(getALErrorString(result));
+
+    <span class=codeComment><font color="#006600">// Read in the wav data from file. Check that it loaded correctly.</font></span><font color="#006600">
+</font>
+    ALut.alutLoadWAVFile(path, format, data, size, freq, loop);
+
+    <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
+        <span class=codeKeyword><font color="#0000FF">throw</font></span><font color="#0000FF"> new </font>IOException(getALErrorString(result));
+
+    <span class=codeComment><font color="#006600">// Send the wav data into the buffer. Check that it was received properly.</font></span>
+    al.alBufferData(buffer[1], format[0], data[0], size[0], freq[0]);
+
+    <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
+        <span class=codeKeyword><font color="#0000FF">throw</font></span> new IOException(getALErrorString(result));
+
+<font color="#006600">    <span class=codeComment>// Get rid of the temporary data.</span>
+</font>
+    ALut.alutUnloadWAV(format[0], data[0], size[0], freq[0]);
+
+    <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
+        <span class=codeKeyword><font color="#0000FF">throw</font></span> new IOException(getALErrorString(result));
+
+<font color="#006600">    <span class=codeComment>// Return the buffer id.</span>
+</font>    <span class=codeKeyword><font color="#0000FF">return</font></span> buffer[0];
+}
+</pre>
+<p>As you can see we do an error check at every possible phase of the load. Any 
+  number of things can happen at this point which will cause an error to be thrown. 
+  There could be no more system memory either for the buffer creation or the data 
+  to be loaded, the wav file itself may not even exist, or an invalid value can 
+  be passed to any one of the OpenAL functions which will generate an error.</p>
+<pre class=code><font color="#0000FF">public int </font>getLoadedALBuffer(String path) <font color="0000ff">throws</font> IOException {
+    <span class=codeKeyword><font color="#0000FF">int</font></span> count = 0; <span class=codeComment><font color="#006600">// 'count' will be an index to the buffer list.</font></span>
+
+    <font color="#0000FF">int</font> buffer; <span class=codeComment><font color="#006600">// Buffer id for the loaded buffer.</font></span>
+
+
+    <span class=codeComment>// Iterate through each file path in the list.</span>
+    Iterator iter = loadedFiles.iterator();
+    <font color="#0000FF">int i = 0;
+    while</font>(iter.hasNext()) {
+		String str = (String)iter.next();
+       if(str.equals(path)) {
+           <font color="#0000FF">return</font> ((Integer)buffers.get(i)).intValue();
+       }
+		i++;
+	 }
+    <span class=codeComment><font color="#006600">// If we have made it this far then this file is new and we will create a buffer for it.</font></span>
+    buffer = loadALBuffer(path);
+
+    <span class=codeComment><font color="#006600">// Add this new buffer to the list, and register that this file has been loaded already.</font></span>
+    buffers.add(new Integer(buffer));
+
+    loadedFiles.add(path);
+
+    <span class=codeKeyword><font color="#0000FF">return</font></span> buffer;
+}
+
+</pre>
+<p>This will probably be the piece of code most people have trouble with, but 
+  it's really not that complex. We are doing a search through a list which contains 
+  the file paths of all the wav's we have loaded so far. If one of the paths matches 
+  the one we want to load, we will simply return the id to the buffer we loaded 
+  it into the first time. This way as long as we consistently load our files through 
+  this function, we will never have buffers wasted due to duplication. Every file 
+  loaded this way must also be kept track of with it's own list. The 'buffers' 
+  list is parallel to the 'loadedFiles' list. What I mean by this is that every 
+  buffer in the index of 'buffers', is the same path of the index in 'loadedFiles' 
+  from which that buffer was created.</p>
+<pre class=code><font color="#0000FF">public static int </font>loadALSample(String path, <span class=codeKeyword><font color="#0000FF">boolean</font></span> loop) <font color="0000ff">throws</font> IOException {
+    <font color="#0000FF">int</font>[] source = <font color="0000ff">new int</font>[1];
+    <font color="0000ff">int</font> buffer;
+    <font color="0000ff">int</font> result;
+
+    <span class=codeComment><font color="006600">// Get the files buffer id (load it if necessary).</font></span>
+    buffer = getLoadedALBuffer(path);
+
+    <span class=codeComment><font color="006600">// Generate a source.</font></span>
+    al.alGenSources(1, source);
+
+    <span class=codeKeyword><font color="000066">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
+        <span class=codeKeyword><font color="0000ff">throw</font></span> new IOException(getALErrorString(result));
+
+    <font color="#006600"><span class=codeComment>// Setup the source properties.</span></font>
+
+    al.alSourcei (source[0], AL.AL_BUFFER,   buffer   );
+    al.alSourcef (source[0], AL.AL_PITCH,    1.0f      );
+    al.alSourcef (source[0], AL.AL_GAIN,     1.0f      );
+    al.alSourcefv(source[0], AL.AL_POSITION, sourcePos);
+    al.alSourcefv(source[0], AL.AL_VELOCITY, sourceVel);
+    al.alSourcei (source[0], AL.AL_LOOPING,  loop ? AL.AL_TRUE : AL.AL_FALSE );
+
+    <span class=codeComment>// Save the source id.</span>
+    sources.add(new Integer(source[0]));
+
+    <span class=codeComment>// Return the source id.</span>
+    <span class=codeKeyword><font color="0000ff">return</font></span> source[0];
+}
+</pre>
+<p>Now that we have created a system which will handle the buffers for us, we 
+  just need an extension to it that will get the sources. In this code we obtain 
+  the result of a search for the file, which is the buffer id that the file was 
+  loaded into. This buffer is bound to the new source. We save the source id internally 
+  and also return it.</p>
+<pre class=code><span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALLoadedData() {
+    loadedFiles.clear();
+}
+
+</pre>
+<p>The global vector loadedFiles' stored the file path of every wav file that 
+  was loaded into a buffer. It doesn't make sense to keep this data lying around 
+  after we have loaded all of our data, so we will dispose of it.</p>
+<pre class=code><span class=codeComment><font color="#006600">// Source id's.</font></span>
+
+<font color="#0000FF">int</font> phaser1;
+<font color="#0000FF">int</font> phaser2;
+
+<span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>loadALData() <font color="#0000FF">throws</font> IOException {
+    <font color="#006600"><span class=codeComment>// Anything for your application here. No worrying about buffers.</span></font>
+    phaser1 = loadALSample("wavdata/phaser.wav", <span class=codeKeyword><font color="#0000FF">false</font></span>);
+    phaser2 = loadALSample("wavdata/phaser.wav", <span class=codeKeyword><font color="#0000FF">true</font></span>);
+
+    killLoadedALData();
+}
+
+</pre>
+<p>We have seen the function in previous tutorials. It will represent the part 
+  of a program which loads all wav's used by the program. In it we can see why 
+  our system is useful. Even though we have made a call to load the same wav file 
+  into two distinct sources, the buffer for the file 'phaser.wav' will only be 
+  created once, and the sources 'gPhaser1' and 'gPhaser2' will both use that buffer 
+  for playback. There is no more concern for handling buffers because the system 
+  will handle them automatically.</p>
+<pre class=code><span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALData()
+{
+<font color="006600">    <span class=codeComment>// Release all buffer data.</span>
+</font>    Iterator iter = buffers.iterator();
+    <span class=codeKeyword><font color="#0000FF">while</font>(iter.hasNext()) {</span>
+        al.alDeleteBuffers(1, new int[] { ((Integer)iter.next()).intValue());
+    }
+<font color="006600">    <span class=codeComment>// Release all source data.</span>
+</font>    iter = sources.iterator();<font color="006600">
+</font>    <span class=codeKeyword><font color="#0000FF">while</font>(iter.hasNext()) {</span>
+        al.alDeleteSources(1, new int[] { ((Integer)iter.next()).intValue());
+    }<font color="006600">
+    <span class=codeComment>// Destroy the lists.</span></font>
+    buffers.clear();
+    sources.clear();
+}
+</pre>
+<p>All along we have been storing the buffer and source id's into stl vectors. 
+  We free all the buffers and sources by going through them and releasing them 
+  individually. After which we destroy the lists themselves. All we need to do 
+  now is catch the OpenAL errors that we have thrown.</p>
+<pre class=code>    <span class=codeKeyword><font color="#0000FF">try</font></span> {
+        initOpenAL();
+        loadALData();
+    } <span class=codeKeyword><font color="#0000FF">catch</font></span>(IOException err){
+        err.printStackTrace();
+    }
+
+</pre>
+<p>If something has gone wrong during the course of the load we will be notified 
+  of it right away. When we catch the error it will be reported on the console. 
+  We can use this for debugging or general error reporting. </p>
+<p>That's it. A more advanced way of reporting errors, and a more robust way of 
+  loading your wav files. We may find we need to do some modifications in the 
+  future to allow for more flexibility, but for now we will be using this source 
+  for basic file loading in future tutorials. Expect future tutorials to expand 
+  on this code.</p>
+<table border="0" cellspacing="1" style="border-collapse: collapse" width="100%" id="AutoNumber2" bgcolor="#666699">
+  <tr> 
+    <td width="40%"> <p dir="ltr"><font color="#FFFFFF" size="2">� 2003 DevMaster.net. 
+        All rights reserved.</font></td>
+    <td width="60%"> <p align="right" dir="ltr"><font size="2"><a href="mailto:[email protected]"> 
+        <font color="#FFFFFF">Contact us</font></a><font color="#FFFFFF"> if you 
+        want to write for us or for any comments, suggestions, or feedback.</font></font></td>
+  </tr>
+</table>
+</body>
+</html>
diff --git a/www/index.html b/www/index.html
index 8e09685..a34e552 100644
--- a/www/index.html
+++ b/www/index.html
@@ -104,6 +104,9 @@
                           Look at the ALC</li>
                         <li><a href="devmaster/lesson5.html">lesson 5:</a> Sources 
                           Sharing Buffers</li>
+                        <li><a href="devmaster/lesson6.html">lesson 6:</a> Advanced 
+                          Loading and Error Handles.</li>
+                        <li>lesson 7: The Doppler Effect</li>
                       </ul>
                     </li>
                   </ul></td>
author	athomas <[email protected]>	2003-07-08 20:03:06 +0000
committer	athomas <[email protected]>	2003-07-08 20:03:06 +0000
commit	4bf057572535db6a4b29b0fa4702ecab82a34885 (patch)
tree	c94727b87efe10dff9b9a6c9ebf73d792aca7810 /www
parent	58f406079040312c9efd3d737881367550b8520a (diff)