In Figure 6.1, “Basic Sonix Interface”, we see the API for Sonix (see Figure 6.2, “The Sonix Design” for the complete software architecture). The main parts that a sound programmer will use are the classes snx::SoundHandle and snx::sonix (a singleton). The snx::SoundHandle class is used to manipulate individual sounds. The snx::sonix singleton class is used to start, stop, and reconfigure the sound system. Both classes must be used for any sound to be heard.

Figure 6.1. Basic Sonix Interface

Starting the Sonix system is easy. Basically, the only call needed to start the system is snx::sonix::changeAPI(). The backend audio software is loaded into Sonix through a plug-in system. The plug-in to use is identified by a string name, one of “OpenAL”, “AudioWorks”, or “Audiere”, as shown in Example 6.12, “Initializing the Sonix Sound APi”. The choice of which to use depends on availability and compatibility. For example, AudioWorks is available on the IRIX operating system, but it can only be used with a build of VR Juggler that uses SPROC threads. On the other hand, OpenAL and Audiere on IRIX can only be used with a pthreads build of VR Juggler.

snx::sonix::instance()->changeAPI("OpenAL");

Setting up a sound is designed to be simple, and an example of doing so is shown in Example 6.13, “Setting Up a Sonix Sound Handle”. Here, we use an instance of snx::SoundInfo to configure the sound object, which is in turn accessed by an instance of snx::SoundHandle.

snx::SoundInfo info;
info.filename = "crack.wav";
info.datasource = snx::SoundInfo::FILESYTEM;

snx::SoundHandle crack_sound("crack");
crack_sound.configure(info);

Periodically, an update function must be called to keep Sonix running. The method is snx::sonix::step(), and it takes a single argument of type float representing the time since the last time it was called. In general, this should be invoked in the frame function of an application. In the context of VR Juggler, this would be either preFrame() or postFrame() in the application object interface. An example of using this function is shown in Example 6.14, “Sonix Frame Update”.

void MyApp::preFrame()
{
   // Update application state for the current frame
   // ...

   float time_delta = getTimeChangeInSeconds(); // use a system call or other API
                                                // to get the time delta
   snx::sonix::instance()->step(time_delta);
}

  1 #include <iostream>
    #include <string>
    #include <snx/sonix.h>
    
  5 int main(int argc, char* argv[])
    {
       std::string filename(:808kick.wav"), api("OpenAL");
    
       if ( ! snx::FileIO::fileExists(filename.c_str()) )
 10    {
          std::cout << "File not found: " << filename << "\n" << std::flush;
          return 1;
       }
    
 15    // start sonix using OpenAL
       snx::sonix::instance()->changeAPI(api);
    
       // fill out a description for the sound we want to play
       snx::SoundInfo sound_info;
 20    sound_info.filename = filename;
       sound_info.datasource = snx::SoundInfo::FILESYSTEM;
    
       // create the sound object
       snx::SoundHandle sound_handle;
 25    sound_handle.init("my simple sound");
       sound_handle.configure(sound_info);
    
       // trigger the sound
       sound_handle.trigger();
 30    sleep(1);
    
       // trigger the sound from a different position in 3D space
       sound_handle.setPosition(10.0f, 0.0f, 0.0f);
       sound_handle.trigger();
 35    sleep(1);
    
       // this simulates a running application
       while ( 1 )
       {
 40       snx::sonix::instance()->step(time_delta);
       }
    
       return 0;
    }

Sonix is reconfigurable, allowing audio APIs to be swapped out at run time safely without the dependent systems noticing. Applications using Sonix expect to be completely portable. Changing sound APIs at run time can be useful so that the user can experiment with quality and latency differences of different hardware and sound APIs. If no audio API is available on a given platform, calls to Sonix simply are ignored. This means that applications do not have to have special code to enable or disable sounds based on the availability of the backend sound software. These details are handled transparently by Sonix.

Everything in Sonix can be reconfigured behind the scenes during application execution. See Example 6.16, “Reconfiguring Sonix at Run Time” for a trivial example of how to reconfigure Sonix in C++. In a more complex context, this feature of Sonix has powerful implications. Sounds can be changed on the fly, as well as the API being used to render the sound. Such details are hidden behind sound handles and the snx::sonix singleton.

  1 // start sonix using OpenAL
    snx::sonix::instance()->changeAPI("OpenAL");
    
    // fill out a description for the sound we want to play
  5 snx::SoundInfo sound_info;
    sound_info.filename = "808kick.wav";
    sound_info.datasource = snx::SoundInfo::FILESYSTEM;
    
    // create the sound object
 10 snx::SoundHandle sound_handle;
    sound_handle.init("my sound for testing");
    sound_handle.configure(sound_info);
    
    // trigger the sound
 15 sound_handle.trigger();
    sleep(1);
    
    // trigger the sound using a different audio system
    snx::sonix::instance()->changeAPI("AudioWorks");
 20 sound_handle.trigger();
    sleep(1);
    
    // trigger our sound object using different source data
    sound_info.filename = "303riff.wav";
 25 sound_handle.configure(sound_info);
    sound_handle.trigger();
    sleep(1);
    

Before we conclude this section on using Sonix directly in applications, we examine the design details of Sonix. These details are beyond the scope of what needs to be understood in order for Sonix to be utilized by VR Juggler applications, so readers not interested in these details can skip ahead to the section called “Using the VR Juggler Sound Manager”.

Sonix was designed using modern software design principles including design patterns and object oriented design. The complete design of Sonix is depicted in UML in Figure 6.2, “The Sonix Design”. As evidenced by the diagram, the design of Sonix is quite simple, though the classes tend to have relatively large interfaces. Refer to the Sonix Programmer Reference, found on the Sonix documentaiton web page, for complete documentation of these interfaces.

Figure 6.2. The Sonix Design

Pluggable Audio Subsystems

Sonix supports the selection of several audio subsystems by the application through implementation plug-ins (see Figure 6.3, “Use of Plug-ins in Sonix”). Each plug-in implements an adapter to an underlying audio subsystem. The adapter supports a common interface that Sonix knows how talk to. Each adapter is then registered with a factory object, which may ask that adapter to clone itself for use by whomever called the factory.

Figure 6.3. Use of Plug-ins in Sonix