AudioPath Configurations

Now that we've seen all the wonder of what an AudioPath can do, we need some way to define them. There are two ways to do this:

• Create from a configuration file loaded from disk

• Create from a predefined set of useful AudioPath definitions

AudioPath File Configuration

You can create your own definition of an AudioPath and store it in a file called an AudioPath configuration file. DirectMusic Producer has a sophisticated AudioPath editor that lets you create, audition, and save AudioPath configuration files. With it, you can address all the features that we've discussed above, from pchannel assignments to tools, DMOs, and buffers.

The AudioPath configuration file does not load directly as an AudioPath. This would be unfortunate because it would mean that each file could only generate one instance of an AudioPath. Let's think of an example: Suppose you've designed an AudioPath for playing race car sounds in 3D. You create an AudioPath configuration with distortion and compression DMOs along with 3D positioning capability. You want to use the same AudioPath design interchangeably for each car that appears on the racetrack, and there could be a lot of them. You also don't want the overhead of loading another AudioPath from disk every time a new car pops into view. Clearly, that would be ridiculous given that all of the AudioPaths are defined the same, but, if you simply use the same AudioPath for all cars, it doesn't work because:

• They run in the same pchannel space, so pchannel-based commands like volume and pitch for one car are applied to all.

• Adjustments to the compression, distortion, and 3D position in the Buffer are all directed to the same object, so, for example, all cars are heard at the same point in space.

Therefore, you need both an AudioPath configuration that defines the AudioPath and then a way to create as many AudioPaths from that configuration as needed. The creation should be very quick and efficient, definitely not involving any file I/O.

In many ways, this is analogous to Segments. You load the Segment from disk. It represents the definition of a Segment but not the running instance. When you play the Segment, you get back a SegmentState. The SegmentState is the running instance of the Segment. Likewise, the AudioPath is the running instance of the AudioPath configuration.

So, like a Segment, you load the AudioPath configuration from disk. However, unlike a Segment, the AudioPath configuration doesn't have any methods. There's nothing you can do with it directly. So, it doesn't have a unique COM interface of its own. Instead, it is represented by the base level IUnknown interface.

With that understood, loading an AudioPath configuration is about the same as loading a Segment. Use the Loader's LoadObjectFromFile() method and pass it the file path and class ID for an AudioPath configuration, CLSID_DirectMusicAudioPath-Configuration.

    IUnknown *pIConfig;    pLoader->LoadObjectFromFile(        CLSID_DirectMusicAudioPathConfig,  // AudioPath config class ID.        IID_IUnknown,                      // No special interface.        pwzFileName,                       // File path.        (void **) &pIConfig);              // Config returned in pIConfig. 

Once you have the AudioPath configuration loaded, create as many AudioPaths from it as you like with the Performance's CreateAudio-Path() method.

    // Now, use this to create a live AudioPath.    IDirectMusicAudioPath *pIPath = NULL;    m_pPerformance->CreateAudioPath(pIConfig,true,&pIPath); 

Predefined Paths

Because there are some really useful standard AudioPath designs that people usually need, DirectMusic comes with a handful of predefined AudioPaths that you can just ask for without first loading a configuration file. These include:

• DMUS_APATH_DYNAMIC_3D: One bus that feeds into a mono 3D Buffer. Every instance has its own unique Buffer. Although you can play stereo waves and DLS instruments into this path, they will always be rendered in mono, since Direct-Sound 3D needs to place a mono sound in 3D space (so there is no way to play stereo sounds in 3D.).

• DMUS_APATH_DYNAMIC_MONO: One bus feeding into a mono Buffer without 3D. Again, each instance has a unique Buffer. Since there is only one bus out, MIDI pan control does nothing. But you can use the Buffer Pan command to pan the entire Buffer in the final mix.

• DMUS_APATH_DYNAMIC_STEREO: Two buses to a stereo Buffer. The Buffer is not shared, so each instance is unique. MIDI pan commands work here.

• DMUS_APATH_SHARED_STEREOPLUSREVERB: This is a standard music AudioPath. It has two Buffers, both of which are defined as shared, which means that no matter how many Audio-Paths you create, they all share the same audio processing buffers. The two Buffers are Dry Stereo, which receives the regular panned left and right signals, and Reverb, which holds a reverb DMO configured for music and receives the MIDI-controlled reverb send as a mono input, with stereo out to the mixer. (The reverb algorithm takes a mono signal and spreads it across the stereo spectrum, among other things.)

To create a predefined AudioPath, call the Performance's CreateStandardAudioPath() method and pass it the identifier for the predefined type that you'd like. Unlike AudioPath configurations, which have the number of pchannels built in, the standard types do not. One music AudioPath might need only 16 pchannels, while another might require 100. So, CreateStandardAudioPath() also requires a requested number of pchannels as a parameter.

    IDirectMusicAudioPath *pIPath = NULL;    pPerformance->CreateStandardAudioPath(        DMUS_APATH_DYNAMIC_3D,  // Make this a 3D path.        12,                     // Allocate 12 pchannels.        true,                   // Activate immediately.        &pIPath);               // Returned AudioPath.code)