Jogamp
www/devmaster/lesson*.html: Fix header, title, navigation and links.
[joal-demos.git] / www / devmaster / lesson6.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>JOAL OpenAL Tutorials from DevMaster.net Lesson 6: Advanced Loading and Error Handles</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6 <link rel="stylesheet" type="text/css" href="general.css">
7 </head>
8 <body>
9 <a href="../index.html"><img src="../../../images/jogamp_symbols/website_final_blue_joal_346x70pel.png" alt="JOAL Symbol"></a><a href="http://www.openal.org"><img src="../openal_c.gif"></a>
10 <br>
11 OpenAL Tutorials from DevMaster.net. Reprinted with Permission.<br>
12 <br>
13 <table border="0" cellspacing="0" style="border-collapse: collapse" width="100%" cellpadding="0" id="AutoNumber1" height="12" bgcolor="#666699">
14   <tr> 
15     <td width="47%" height="12" valign="middle"><p><b><font color="#FFFFFF">OpenAL 
16         Tutorials</font></b></p></td>
17     <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>
18   </tr>
19 </table>
20 <p class="ArticleTitle"><font size="5">Advanced Loading and Error Handles<br>
21   </font><font color="#000000" size="4"><strong>Lesson 6</strong></font></p>
22 <p align="right" class="ArticleAuthor">Author: <a href="mailto:lightonthewater@hotmail.com">Jesse 
23   Maurais</a><br>
24   Adapted For Java By: <a href="mailto:athomas@dev.java.net">Athomas Goldberg</a></p>
25 <p align="justify">We've been doing some pretty simple stuff up until now that 
26   didn't require us to be very precise in the way we've handled things. The reason 
27   for this is that we have been writing code for simplicity in order to learn 
28   easier, rather that for robustness. Since we are going to move into some advanced 
29   stuff soon we will take some time to learn the proper ways. Most importantly 
30   we will learn a more advanced way of handling errors. We will also reorganize 
31   the way we have been loading audio data. There wasn't anything wrong with our 
32   methods in particular, but we will need a more organized and flexible approach 
33   to the process.</p>
34 <p align="justify">We will first consider a few functions that will help us out 
35   a lot by the time we have finished.</p>
36 <pre class=code><font color="#0000FF"><span class=codeComment><font color="#006600">/**
37  * 1) Identify the error code.
38  * 2) Return the error as a string.
39  */</font></span>
40 public</font> <font color="#0000FF">static</font> String getALErrorString(<font color="#0000FF">int</font> err);
41
42 <span class=codeComment><font color="#006600">/**
43  * 1) Identify the error code.
44  * 2) Return the error as a string.
45  */</font></span>
46 <font color="#0000FF">public</font> <font color="#0000FF">static</font> String getALCErrorString(<font color="#0000FF">int</font> err);
47
48 <font color="#0000FF"><span class=codeComment><font color="#006600">/**
49  * 1) Creates a buffer.
50  * 2) Loads a wav file into the buffer.
51  * 3) Returns the buffer id.
52  */</font></span>
53 public static int </font>loadALBuffer(String path) <font color="#0000FF">throws</font> IOException;
54
55 <span class=codeComment><font color="#006600">/**
56  * 1) Checks if file has already been loaded.
57  * 2) If it has been loaded already, return the buffer id.
58  * 3) If it has not been loaded, load it and return buffer id.
59  */</font></span>
60 <font color="#0000FF">public static int </font>getLoadedALBuffer(String path) <font color="#0000FF">throws</font> IOException;
61
62
63 <font color="#0000FF"><span class=codeComment><font color="#006600">/**
64  * 1) Creates a source.
65  * 2) Calls 'GetLoadedALBuffer' with 'path' and uses the
66  *    returned buffer id as it's sources buffer.
67  * 3) Returns the source id.
68  */
69 </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;
70 <span class=codeKeyword>
71 </span><span class=codeComment><font color="#006600">/**
72  * 1) Releases temporary loading phase data.
73  */</font></span>
74 <span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALLoadedData();
75 <span class=codeKeyword>
76 </span><span class=codeComment><font color="#006600">/**
77  * 1) Loads all buffers and sources for the application.
78  */</font></span>
79 <span class=codeKeyword><font color="#0000FF">public static boolean</font></span><font color="#0000FF"> </font>loadALData();
80 <span class=codeKeyword>
81 </span><span class=codeComment><font color="#006600">/**
82  * 1) Releases all buffers.
83  * 2) Releases all sources.
84  */</font></span>
85 <font color="#0000FF"><span class=codeKeyword>public </span>static <span class=codeKeyword>void</span> </font>killALData();
86
87
88 <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>
89
90 <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">
91 </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>
92 </pre>
93 <p align="justify">Take a close look at the functions and try to understand what 
94   we are going to be doing. Basically what we are trying to create is a system 
95   in which we no longer have to worry about the relationship between buffers and 
96   sources. We can call for the creation of a source from a file and this system 
97   will handle the buffer's creation on it's own so we don't duplicate a buffer 
98   (have two buffers with the same data). This system will handle the buffers as 
99   a limited resource, and will handle that resource efficiently.</p>
100 <pre class=code><font color="#0000FF">public</font> String getALErrorString(<font color="#0000FF">int</font> err) {
101     <span class=codeKeyword><font color="#0000FF">switch</font></span>(err) {
102         <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";
103         <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";
104         <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";
105         <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";
106         <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";
107         <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";
108         <font color="#0000FF">default</font>: <font color="#0000FF">return</font> <font color="#0000FF">null</font>;
109     }
110 }
111
112 </pre>
113 <p align="justify">This function will convert an OpenAL error code to a string 
114   so it can be read on the console (or some other device). The OpenAL sdk says 
115   that the only exception that needs be looked for in the current version is the 
116   'AL_OUT_OF_MEMORY' error. However, we will account for all the errors so that 
117   our code will be up to date with later versions.</p>
118 <pre class=code><font color="#0000FF">public</font> String getALCErrorString(<font color="#0000FF">int</font> err) {
119     <span class=codeKeyword><font color="#0000FF">switch</font></span>(err) {
120         <span class=codeKeyword><font color="#0000FF">case</font></span> ALC_NO_ERROR: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_NO_ERROR";
121 <span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_DEVICE: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_DEVICE";
122 <span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_CONTEXT: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_CONTEXT";
123 <span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_ENUM: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_ENUM";
124 <span class=codeKeyword>        <font color="#0000FF">case</font></span> ALC_INVALID_VALUE: <span class=codeKeyword><font color="#0000FF">return</font></span> "ALC_INVALID_VALUE";
125 <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";
126         <font color="#0000FF">default</font>: <font color="#0000FF">return</font> <font color="#0000FF">null</font>;
127     }
128 }
129
130 </pre>
131 <p align="justify">This function will perform a similar task as the previous one 
132   accept this one will interpret Alc errors. OpenAL and Alc share common id's, 
133   but not common enough and not dissimilar enough to use the same function for 
134   both.</p>
135 <p align="justify">One more note about the function 'alGetError': The OpenAL sdk 
136   defines that it only holds a single error at a time (i.e. there is no stacking). 
137   When the function is invoked it will return the first error that it has received, 
138   and then clear the error bit to 'AL_NO_ERROR'. In other words an error will 
139   only be stored in the error bit if no previous error is already stored there.</p>
140 <pre class=code><font color="#0000FF">public int</font> loadALBuffer(String path) <font color="#0000FF">throws</font> IOException {
141     <span class=codeComment><font color="#006600">// Variables to store data which defines the buffer.</font></span>
142     <font color="#0000FF">int</font>[] format = <font color="#0000FF">new int</font>[1];
143     <font color="#0000FF">int</font>[] size = <font color="#0000FF">new int</font>[1];
144     ByteBuffer[] data = <font color="#0000FF">new</font> ByteBuffer[1];
145     <font color="#0000FF">int</font>[] freq = <font color="#0000FF">new int</font>[1];
146     <font color="#0000FF">int</font>[] loop = <font color="#0000FF">new int</font>[1];
147
148     <font color="#006600"><span class=codeComment>// Buffer id and error checking variable.</span></font>
149     <font color="#0000FF">int</font>[] buffer = <font color="#0000FF">new int</font>[1];
150     int result;
151
152     <span class=codeComment><font color="#006600">// Generate a buffer. Check that it was created successfully.</font></span>
153     al.alGenBuffers(1, buffer);
154
155     <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
156         <span class=codeKeyword><font color="#0000FF">throw</font></span><font color="#0000FF"> new</font> IOException(getALErrorString(result));
157
158     <span class=codeComment><font color="#006600">// Read in the wav data from file. Check that it loaded correctly.</font></span><font color="#006600">
159 </font>
160     ALut.alutLoadWAVFile(path, format, data, size, freq, loop);
161
162     <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
163         <span class=codeKeyword><font color="#0000FF">throw</font></span><font color="#0000FF"> new </font>IOException(getALErrorString(result));
164
165     <span class=codeComment><font color="#006600">// Send the wav data into the buffer. Check that it was received properly.</font></span>
166     al.alBufferData(buffer[1], format[0], data[0], size[0], freq[0]);
167
168     <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
169         <span class=codeKeyword><font color="#0000FF">throw</font></span> new IOException(getALErrorString(result));
170
171 <font color="#006600">    <span class=codeComment>// Get rid of the temporary data.</span>
172 </font>
173     ALut.alutUnloadWAV(format[0], data[0], size[0], freq[0]);
174
175     <span class=codeKeyword><font color="#0000FF">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
176         <span class=codeKeyword><font color="#0000FF">throw</font></span> new IOException(getALErrorString(result));
177
178 <font color="#006600">    <span class=codeComment>// Return the buffer id.</span>
179 </font>    <span class=codeKeyword><font color="#0000FF">return</font></span> buffer[0];
180 }
181 </pre>
182 <p align="justify">As you can see we do an error check at every possible phase 
183   of the load. Any number of things can happen at this point which will cause 
184   an error to be thrown. There could be no more system memory either for the buffer 
185   creation or the data to be loaded, the wav file itself may not even exist, or 
186   an invalid value can be passed to any one of the OpenAL functions which will 
187   generate an error.</p>
188 <pre class=code><font color="#0000FF">public int </font>getLoadedALBuffer(String path) <font color="0000ff">throws</font> IOException {
189     <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>
190
191     <font color="#0000FF">int</font> buffer; <span class=codeComment><font color="#006600">// Buffer id for the loaded buffer.</font></span>
192
193
194     <span class=codeComment>// Iterate through each file path in the list.</span>
195     Iterator iter = loadedFiles.iterator();
196     <font color="#0000FF">int i = 0;
197     while</font>(iter.hasNext()) {
198                 String str = (String)iter.next();
199        if(str.equals(path)) {
200            <font color="#0000FF">return</font> ((Integer)buffers.get(i)).intValue();
201        }
202                 i++;
203          }
204     <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>
205     buffer = loadALBuffer(path);
206
207     <span class=codeComment><font color="#006600">// Add this new buffer to the list, and register that this file has been loaded already.</font></span>
208     buffers.add(new Integer(buffer));
209
210     loadedFiles.add(path);
211
212     <span class=codeKeyword><font color="#0000FF">return</font></span> buffer;
213 }
214
215 </pre>
216 <p align="justify">This will probably be the piece of code most people have trouble 
217   with, but it's really not that complex. We are doing a search through a list 
218   which contains the file paths of all the wav's we have loaded so far. If one 
219   of the paths matches the one we want to load, we will simply return the id to 
220   the buffer we loaded it into the first time. This way as long as we consistently 
221   load our files through this function, we will never have buffers wasted due 
222   to duplication. Every file loaded this way must also be kept track of with it's 
223   own list. The 'buffers' list is parallel to the 'loadedFiles' list. What I mean 
224   by this is that every buffer in the index of 'buffers', is the same path of 
225   the index in 'loadedFiles' from which that buffer was created.</p>
226 <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 {
227     <font color="#0000FF">int</font>[] source = <font color="0000ff">new int</font>[1];
228     <font color="0000ff">int</font> buffer;
229     <font color="0000ff">int</font> result;
230
231     <span class=codeComment><font color="006600">// Get the files buffer id (load it if necessary).</font></span>
232     buffer = getLoadedALBuffer(path);
233
234     <span class=codeComment><font color="006600">// Generate a source.</font></span>
235     al.alGenSources(1, source);
236
237     <span class=codeKeyword><font color="000066">if</font> </span>((result = al.alGetError()) != AL.AL_NO_ERROR)
238         <span class=codeKeyword><font color="0000ff">throw</font></span> new IOException(getALErrorString(result));
239
240     <font color="#006600"><span class=codeComment>// Setup the source properties.</span></font>
241
242     al.alSourcei (source[0], AL.AL_BUFFER,   buffer   );
243     al.alSourcef (source[0], AL.AL_PITCH,    1.0f      );
244     al.alSourcef (source[0], AL.AL_GAIN,     1.0f      );
245     al.alSourcefv(source[0], AL.AL_POSITION, sourcePos);
246     al.alSourcefv(source[0], AL.AL_VELOCITY, sourceVel);
247     al.alSourcei (source[0], AL.AL_LOOPING,  loop ? AL.AL_TRUE : AL.AL_FALSE );
248
249     <span class=codeComment>// Save the source id.</span>
250     sources.add(new Integer(source[0]));
251
252     <span class=codeComment>// Return the source id.</span>
253     <span class=codeKeyword><font color="0000ff">return</font></span> source[0];
254 }
255 </pre>
256 <p align="justify">Now that we have created a system which will handle the buffers 
257   for us, we just need an extension to it that will get the sources. In this code 
258   we obtain the result of a search for the file, which is the buffer id that the 
259   file was loaded into. This buffer is bound to the new source. We save the source 
260   id internally and also return it.</p>
261 <pre class=code><span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALLoadedData() {
262     loadedFiles.clear();
263 }
264
265 </pre>
266 <p>The global vector loadedFiles' stored the file path of every wav file that 
267   was loaded into a buffer. It doesn't make sense to keep this data lying around 
268   after we have loaded all of our data, so we will dispose of it.</p>
269 <pre class=code><span class=codeComment><font color="#006600">// Source id's.</font></span>
270
271 <font color="#0000FF">int</font> phaser1;
272 <font color="#0000FF">int</font> phaser2;
273
274 <span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>loadALData() <font color="#0000FF">throws</font> IOException {
275     <font color="#006600"><span class=codeComment>// Anything for your application here. No worrying about buffers.</span></font>
276     phaser1 = loadALSample("wavdata/phaser.wav", <span class=codeKeyword><font color="#0000FF">false</font></span>);
277     phaser2 = loadALSample("wavdata/phaser.wav", <span class=codeKeyword><font color="#0000FF">true</font></span>);
278
279     killLoadedALData();
280 }
281
282 </pre>
283 <p align="justify">We have seen the function in previous tutorials. It will represent 
284   the part of a program which loads all wav's used by the program. In it we can 
285   see why our system is useful. Even though we have made a call to load the same 
286   wav file into two distinct sources, the buffer for the file 'phaser.wav' will 
287   only be created once, and the sources 'gPhaser1' and 'gPhaser2' will both use 
288   that buffer for playback. There is no more concern for handling buffers because 
289   the system will handle them automatically.</p>
290 <pre class=code><span class=codeKeyword><font color="#0000FF">public static void</font></span><font color="#0000FF"> </font>killALData()
291 {
292 <font color="006600">    <span class=codeComment>// Release all buffer data.</span>
293 </font>    Iterator iter = buffers.iterator();
294     <span class=codeKeyword><font color="#0000FF">while</font>(iter.hasNext()) {</span>
295         al.alDeleteBuffers(1, new int[] { ((Integer)iter.next()).intValue());
296     }
297 <font color="006600">    <span class=codeComment>// Release all source data.</span>
298 </font>    iter = sources.iterator();<font color="006600">
299 </font>    <span class=codeKeyword><font color="#0000FF">while</font>(iter.hasNext()) {</span>
300         al.alDeleteSources(1, new int[] { ((Integer)iter.next()).intValue());
301     }<font color="006600">
302     <span class=codeComment>// Destroy the lists.</span></font>
303     buffers.clear();
304     sources.clear();
305 }
306 </pre>
307 <p align="justify">All along we have been storing the buffer and source id's into 
308   stl vectors. We free all the buffers and sources by going through them and releasing 
309   them individually. After which we destroy the lists themselves. All we need 
310   to do now is catch the OpenAL errors that we have thrown.</p>
311 <pre class=code>    <span class=codeKeyword><font color="#0000FF">try</font></span> {
312         initOpenAL();
313         loadALData();
314     } <span class=codeKeyword><font color="#0000FF">catch</font></span>(IOException err){
315         err.printStackTrace();
316     }
317
318 </pre>
319 <p align="justify">If something has gone wrong during the course of the load we 
320   will be notified of it right away. When we catch the error it will be reported 
321   on the console. We can use this for debugging or general error reporting. </p>
322 <p align="justify">That's it. A more advanced way of reporting errors, and a more 
323   robust way of loading your wav files. We may find we need to do some modifications 
324   in the future to allow for more flexibility, but for now we will be using this 
325   source for basic file loading in future tutorials. Expect future tutorials to 
326   expand on this code.</p>
327 <table border="0" cellspacing="1" style="border-collapse: collapse" width="100%" id="AutoNumber2" bgcolor="#666699">
328   <tr> 
329     <td width="40%"> <p dir="ltr"><font color="#FFFFFF" size="2">© 2003 DevMaster.net. 
330         All rights reserved.</font></td>
331     <td width="60%"> <p align="right" dir="ltr"><font size="2"><a href="mailto:webmaster@devmaster.net"> 
332         <font color="#FFFFFF">Contact us</font></a><font color="#FFFFFF"> if you 
333         want to write for us or for any comments, suggestions, or feedback.</font></font></td>
334   </tr>
335 </table>
336 </body>
337 </html>
http://JogAmp.org git info: FAQ, tutorial and man pages.