www/devmaster/lesson*.html:* -> com.jogamp.openal.*
[joal-demos.git] / www / devmaster / lesson6.html
Content-type: text/html Git - joal-demos.git/blame - www/devmaster/lesson6.html

500 - Internal Server Error

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