From b7d6ae781c4075a5481b2ddf592d1632df3c4d77 Mon Sep 17 00:00:00 2001 From: athomas Date: Tue, 8 Jul 2003 20:16:34 +0000 Subject: fill justified the paragraphs in the tutorials git-svn-id: file:///home/mbien/NetBeansProjects/JOGAMP/joal-sync/svn-server-sync-demos/joal-demos/trunk@33 235fdd13-0e8c-4fed-b5ee-0a390d04b286 --- www/devmaster/lesson6.html | 141 +++++++++++++++++++++++---------------------- 1 file changed, 72 insertions(+), 69 deletions(-) (limited to 'www/devmaster/lesson6.html') diff --git a/www/devmaster/lesson6.html b/www/devmaster/lesson6.html index 3a0c5ee..36e3660 100644 --- a/www/devmaster/lesson6.html +++ b/www/devmaster/lesson6.html @@ -32,16 +32,17 @@ OpenAL Tutorials from DevMaster.net. Reprinted with Permission.

Author: Jesse Maurais
Adapted For Java By: Athomas Goldberg

-

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.

-

We will first consider a few functions that will help us out a lot by the time - we have finished.

+

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.

+

We will first consider a few functions that will help us out + a lot by the time we have finished.

/**
  * 1) Identify the error code.
  * 2) Return the error as a string.
@@ -99,13 +100,13 @@ public static int loadALBuffer(String path) throws<
 private static Vector buffers = new Vector(); // Holds all loaded buffers.
 private static Vector sources = new Vector(); // Holds all validated sources.
-

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.

+

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.

public String getALErrorString(int err) {
     switch(err) {
         case AL.AL_NO_ERROR: return "AL_NO_ERROR";
@@ -119,11 +120,11 @@ public static int loadALBuffer(String path) throws<
 }
-

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.

+

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.

public String getALCErrorString(int err) {
     switch(err) {
         case ALC_NO_ERROR: return "ALC_NO_ERROR";
@@ -137,14 +138,15 @@ public static int loadALBuffer(String path) throws<
 }
-

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.

-

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.

+

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.

+

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.

public int loadALBuffer(String path) throws IOException {
     // Variables to store data which defines the buffer.
     int[] format = new int[1];
@@ -187,11 +189,12 @@ public static int loadALBuffer(String path) throws<
     return buffer[0];
 }
-

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.

+

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.

public int getLoadedALBuffer(String path) throws IOException {
     int count = 0; // 'count' will be an index to the buffer list.
 
@@ -220,16 +223,16 @@ public static int loadALBuffer(String path) throws<
 }
-

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.

+

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.

public static int loadALSample(String path, boolean loop) throws IOException {
     int[] source = new int[1];
     int buffer;
@@ -260,11 +263,11 @@ public static int loadALBuffer(String path) throws<
     return source[0];
 }
-

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.

+

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.

public static void killALLoadedData() {
     loadedFiles.clear();
 }
@@ -287,13 +290,13 @@ public static int loadALBuffer(String path) throws<
 }
-

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.

+

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.

public static void killALData()
 {
     // Release all buffer data.
@@ -311,10 +314,10 @@ public static int loadALBuffer(String path) throws<
     sources.clear();
 }
-

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.

+

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.

    try {
         initOpenAL();
         loadALData();
@@ -323,14 +326,14 @@ public static int loadALBuffer(String path) throws<
     }
-

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.

-

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.

+

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.

+

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.

© 2003 DevMaster.net. -- cgit v1.2.3