0. Index

0. Index
1. Introduction
2. Audio playback DirectMusic architecture
    2.1 Basic concepts
    2.2 Main COM interfaces in DirectMusic for audio playback
3. Developing audio applications using DirectMIDI
    3.1 Introduction - DirectMIDI audio processing layout
    3.2 Creating the application
        3.2.1 Setting up the development environment
        3.2.2 The main objects
        3.2.3 Starting up the performance
        3.2.4 Loading and playing segments
        3.2.5 3D Segment positioning
        3.2.6 MIDI functions with performances
       Sending a note-on in the 3D space
       Loading and playing a DLS instrument in 3D
       Wave sample instruments and thruing to the 3D performance
        3.2.7 Advanced audio features
        3.2.8 Exception handling

1. Introduction

This article focuses on the last part of the DirectMidi wrapper class library which allows performing advanced playback and mixing audio functions with the DirectMusic - DirectX API. In the first part, we saw how DirectMusic handles basic MIDI I/O operations such as input and output ports, thruing from one port to another and downloading DLS instruments. In this part I will give a basic understanding on the use of DirectMusic through the DirectMidi class library to get full performance when synchronizing several audio wave files at the same time, positioning the MIDI and wave sequences in the space, sending MIDI messages to the performances and using DLS instruments with them. 

2. Audio playback DirectMusic architecture

2.1 Basic concepts

The main problem of a basic system MIDI port like the MIDI Mapper is the limitation of the number of audio channels to 16. This limitation comes from the MIDI standard and extends to modern applications. This limitation is overcome in DirectMusic thanks to the appearance of Peformance channels. The performance channels are similar to MIDI channels except that they are virtually unlimited. Each performance channel contains a single instrument, an instrument coming from a MIDI sequence, a DLS instrument or a waveform. These parts have their own pan, volume and transposition settings. At this point we can state that one performance channel belongs to a single MIDI channel and to a channel group from the port. From now on, when working with performance objects we will always use zero-based performance channels. The chart below explains this relation:

Performance channels are handled by Performance objects which are the responsible of sending audio data from the source to the synthesizer. Performance objects also handle timing, the routing of messages, tool management and notifications. 

Another important object related to performance and performance channels are Audiopaths. An audiopath can be seen as a chain of objects through which data is streamed. An application can gain access to any of these objects. For example, you might retrieve a buffer object to set 3D properties of a sound source, or a DMO effect to change the parameters of the effect.

The last important objects involved in DirectMusic application are Segments. Segments are objects encapsulating sequenced sound data. The data might be a MIDI sequence, a waveform, a collection of information originating in a segment file from DirectMusic Producer, or a piece of music composed at run time from different components. 
A segment can be played as a primary or secondary segment. When playing as a primary segment only this segment can be played at a time. The secondary segments are typically short musical sound effects played at a time or synchornized over the primary segment.

2.2 Main COM interfaces in DirectMusic for audio playback

DirectMusic is part of DirectX technology which uses distributed object programming through COM. COM is the fundamental "object model" on which ActiveX Controls and OLE are built. COM allows an object to expose its functionality to other components and to host applications. It defines both how the object exposes itself and how this exposure works across processes and across networks. COM also defines the object's life cycle.
Although DirectMusic uses this technology, don't feel overwhelmed, since the class library automatically handles these situations. In the following lines the most important interfaces involved in a DirectMusic audio application are presented:

3. Developing audio applications using DirectMIDI

3.1 Introduction - DirectMIDI audio processing layout

As it happens with the MIDI part of the DirectMidi, the main kernel of the library for audio handling is based on its eleven related classes. They are commented hereafter: 

On the left side of the chart we can see the main objects of a DirectMusic application. The CDirectMusic class is the responsible of instancing the DirectMusic COM object for a Win32 application. It initializes DirectMusic and creates or specifies the DirectSound object required for the software synthesizer. 
The second elementary object is CMasterClock which performs the enumeration and selection of the desired hardware clock as reference clock. The CMasterClock is not used unless the user needs a specific timing configuration. 
After creating the CDirectMusic object we can proceed to initialize the most two important objects involved in a DirectMusic audio playback application. These objects are the CPortPerformance and CAPathPerformance which are the encapsulation and operational abstraction of the IDirectMusicPerformance8 interface. The CPortPerformance manages performances which use system ports like the MPU-401 or the software synthesizer which need to be added to this object. These CPortPerformance objects don't allow neither audiopaths nor 3D positioning. 
On the other hand we have the CAPathPerformance that allows managing a performance which uses the default software synthesizer port. These CAudioPathPerformances allow audiopaths and 3D positioning, besides the use of DMO's and effects like Reverb and Chorus. In order to attain 3D effects over the audio data stream and get DMO's we will need the CAudioPath object which can be retrived by using the CAPathPerformance methods. 
Two important objects required for 3D positioning are the C3DBuffer and C3DListener which are the abstraction of the IDirectSound3DBuffer8 and IDirectsound3DListener8 respectively and can be initialized from the CAudioPath object.
Finally, we have two objects required to keep a reference to an audio sequence represented by the IDirectMusicSegment8. These objects are the CSegment and C3DSegment. There is a subtle difference between these two objects. The CSegment object is a basic unit of an audio file. This CSegment is intended to be played in both types of performances. The C3DSegment object, on the other hand, is a higher abstraction or encapsulation of the objects required by a sequence intended to be used with 3D features. Therefore, this C3DObject contains a CAudioPath and inherits from a C3DBuffer and a C3DListener internally.       

3.2 Creating the application

3.2.1 Setting up the development environment

The DirectMidi wrapper can be used in any kind of Win32 applications provided by the Visual Studio wizard. In the source code explained in the example below I will use a "Simple application" of a Win32 console. Once we have created the basic files for this application we can proceed to include the headers (.h) and source files (.cpp) required by the DirectMusic application. Thus, for example, if we start an application which uses the Audio part of the DirectMidi library, we will need to include the followings headers: CDirectMidi.h, CDirectBase.h and CAudioPart.h.
So as for a MIDI application as for an Audio one, we will always need to include the first two headers. Then, depending on the classes we need, we will have to include the respective .cpp file for the implementation of that class. For example, if we use the COutputPort class, we will need to include the CMidiPort.cpp and COutputPort.cpp source files. For instance, if we use the CAPathPerformance, we will need the CPerformance.cpp and CAPathPerformance.cpp classes.
Besides the DirectMidi classes, we will also need to include the existing files inside the Dsutil directory of the DirectMidi folder, since they contain DirectX basic source code utilities for wave file handling.
After including all the required files, it's important to compile the whole project without precompiled headers (.pch) because the DirectMidi project doesn't support precompiled headers by default. Therefore, go to your Visual Studio 6 and select Project -> Settings and expand the left tree view to see your project files. Then, select the C/C++ tab option, click on the Precompiled headers in the combo and mark "Not using precompilder headers" for all the files included in the project. If you use Visual Studio 7, the procedure is similar: Click on the Solution explorer tab, select all the listed .cpp files and then right click. On properties, select C/C++, Precompiled headers and specify "Not Using Precompiled Headers".  Finally, remove all the references to the "stdafx.h" header in the project sources.
In order to avoid unresolved external symbols after linking the DirectX functions, we will need to include a path to the DirectX libraries and headers. To do this, go to Tools in the menu bar, select Options and then click on the Directories tab to add the path to the DirectX8/9 headers and library files. If you have the Visual Studio 7 (.NET), go to Tools in the menu bar, click on Options and then open the Projects folder. Expand the Show Directories for combo list and select the library and include files option. Finally, add the header and library files directories to their respective lists. 

3.2.2 The main objects

In this section it is explained how to declare and initialize the fundamental objects involved in a DirectMidi audio playback application. In the source code below you can see the list of instantiated DirectMidi objects:

// Main headers

// ANSI I/0 headers
#include <conio.h>
#include <iostream>
#include <math.h>
// The class wrapper
#include ".\\DirectMidi\\CDirectMidi.h"

// Inline library inclusion

#pragma comment (lib,"dxguid.lib") // guid definitions 
#pragma comment (lib,"winmm.lib")
#pragma comment (lib,"dsound.lib")
#pragma comment (lib,"dxerr9.lib")

using namespace std;
using namespace directmidi;

int main(int argc, char* argv[])
	CDirectMusic	CDMusic;
	CDLSLoader	CLoader;
	COutputPort	COutPort,COutPort2;
	CInputPort	CInPort;
	CPortPerformance	CPortPerformance;
	CAPathPerformance 	CAPathPerformance;
	CCollection       	CCollectionA;
	CInstrument       	CInstrument1;
	CAudioPath       	CAudioPath1;
	CSegment		CSegment1;
	C3DSegment       	C3DSegment1;
	C3DBuffer		C3DBuffer1;

In the first lines of the code we include the ANSI and DirectMidi headers required for the application. After this, we proceed to specify the libraries that will be linked within the application using the #pragma precompiler directive. It's very important to know that the DirectMidi library is wrapped into the directmidi namespace. Therefore, you must call using namespace directmidi in order to tell the compiler that we are referencing this logic grouping.
The first of these objects is the CDirectMusic which is the responsible to initialize the DirectMusic application and will be the last one to be released. The second main object is the CDLSLoader that manages the loading of audio sequences and DLS files. The next two important objects are COutPort which is the COutputPort object type that will be added to the CPortPerformanceObject and COutPort2 that will keep a reference to the internal output port of the CAPathPerformance object.
Together with these two output ports we have one of CInputPort type in order to handle thruing from the default MPU-401 port to the performance synthesizer and will be explained at the end of this article. Then we have the two performance objects used along the application whose differences were explained previously. 
This example code will make use of DLS instruments, so we will need a container for the instrument collection extracted from the DLS file and an instance to a CInstrument object in order to download them to the performance. In addition we will need a CAudioPath object to apply effects over the data stream and a CSegment and a C3DSegment to play stereo plus reverb and 3D positioning MIDI files respectively. Finally, we will attain 3D audio positioning by using a C3DBuffer object in conjunction with AudioPathPerformance.
Note that the instantiation order must be from parents to children objects, so that the later destruction of the objects follows a LIFO criterion, thus avoiding that a parent object is destructed before its children.

3.2.3 Starting up the performance 

As we have seen previously, all the required objects for a DirectMusic application were already instantiated. What is left now is calling their methods in a proper order to start music output. Take a look at the following lines: 

	/////////////////////////////// INITIALIZATION //////////////////////////

	// Initializes DirectMusic

	// Initializes an audiopath performance

	// Initializes a port performance object

	// Initializes loader object

	// Initializes output port

	// Selects the first software synthesizer port

	DWORD dwPortCount = 0;

	while (!(PortInfo.dwFlags & DMUS_PC_SOFTWARESYNTH));

	cout << "Selected output port: " << PortInfo.szPortDescription << endl; 
	COutPort.SetPortParams(0,0,0,SET_REVERB | SET_CHORUS,44100);
	////////////////////////////////// PLAYING A SEGMENT ////////////////////////////

	// Adds the selected port to the performance


After initializing DirectMusic, it proceeds to initialize the audiopath performance. To do this, it calls the CAPathPerformance::Initialize method with a reference to the created DirectMusic object, two NULL pointers representing the DirectSound object to be created and the HWND window handle for the creation of DirectSound. After these three first parameters are established, we can now specify what kind of default Audiopath we want in our application. In this case we choose a DMUS_APATH_DYNAMIC_3D type which is the one suitable for a 3D audio application.
In the previous line, the CPortPerformance object is initialized calling the CPortPerformance::Initialize method, passing a reference to the main DirectMusic object and two pointers representing the DirectSound and the HWND handler parameters. As it can be seen in the following code, we select and start a software synthesizer port, handled by the COutputPort object type named COutPort. After starting it, we call the CPortPerformance::AddPort method to add the port to the performance and assign it a block of 16 performance channels (first parameter) and map them to the port and the channel group (second parameter). 

3.2.4 Loading and playing segments

In the code below it is explained how to load a MIDI file sequence and play it with the two types of performances objects.

	// Loads a MIDI file into the segment

	// Repeats the segment ad infinitum

	// Downloads the segment to the performance

	// Plays the segment

	cout << "Playing a segment with the port performance. Press a key to continue...\n" << endl;


	// Stops the playing segment


	// Downloads the segment to the audio path performance


	// Plays the segment in the performance


	cout << "Playing a segment with the audio path performance. Press a key to continue...\n" << endl;


	// Stops the current playing segment


Using the CDLSLoader::LoadSegment method we can load either a MIDI or a WAVE (.WAV) file representing an audio sequence. We just need to specify the format of the file in the third parameter, where a TRUE boolean value indicates that we are trying to load a standard MIDI file (without attached DLS data) and a FALSE value indicates that we are going to load a wave, a segment or a MIDI file containing DLS. Optionally, we can specify how many times we want our sequence to be repeated. Therefore, if we call the CSegment::SetRepeats with the DMUS_SEG_REPEAT_INFINITE flag, the sequence will be repeated ad infinitum.
If we are using a software synthesizer, it is mandatory to call CSegment::Download in order to download the file data to the performance synthesizer. This is not necessary when non-software synthesiser ports are added. 
Once we have downloaded the sequence to the performance we can proceed to either play or stop it by using the CPortPerformance::PlaySegment and CPortPerformance::Stop methods respectively. Similarly, we can proceed to play a CSegment over the CAPathPerformance using the same methods, but this time, we need to call CSegment::Download.

 3.2.5 3D Segment positioning

The main pourpose of this section is to explain the use of a C3DSegment. It is a all-in-one piece for playing sounds in the 3D space.


	// Clones the normal segment to a 3D segment

	C3DSegment1 = CSegment1;

	// Plays the 3D segment in the audiopath performance


	// Positions the 3D buffer one unit in the negative X-axis


	cout << "Playing a 3D segment on your left. Press a key to continue...\n" << endl;


	// Positions the 3D buffer one unit in the positive X-axis


	cout << "Playing a 3D segment on your right. Press a key to continue...\n" << endl;



First of all, the C3DSegment object must be initialized with a reference to the AudiopathPerformance object where it is to be played. This will initialize its inherited C3DBuffer and C3DListener objects and its internal AudioPath.
The C3DSegment1 = CSegment1 expression is not necessary in the example since you can initialize a C3DSegment object by calling CDLSLoader::LoadSegment; it is there just for illustrative purpose. The reason is that DirectMidi supports "=" operator overloading for the CSegment base class and the C3DSegment inherited class. It just clones the audio data sequence and invokes a new IDirectMusicSegment interface for the new object.
After initializing the C3DSegment we can proceed to play the segment and position its DirectSound 3D buffer by calling C3DSegment::SetBufferPosition. It will apply space positioning to the playing sound.

3.2.6 MIDI functions with performances

One of the most important features in DirectMidi is the posibility to use MIDI commands and functions to apply different effects such as 3D positioning while having an unlimited number of notes playing at a time. In the next few lines we can see the base case. It shows how to send a NOTE_ON MIDI message to the port performance. 


	cout << "Sending a MIDI note-on to the port performance on PChannel 1. Press a key to continue...\n" << endl;



The fourth parameter in the CPortPerformance::SendMidiMsg method is the PChannel or Performance channel. It is here where the set of MIDI channel and channel group assigned to the downloaded segment are mapped. This PChannel contains a specific instrument and MIDI data. Therefore, we will never use MIDI channels when using performances in the future. Sending a note-on in the 3D space

The following simple code snippet, sends a NOTE_ON to the audiopath performance and positions the note on the left. When sending MIDI messages to the audiopath performances, we must provide an additional fifth parameter to the CAudioPathPerformance::SendMidiMsg that indicates the audiopath where we are working. In the example below we use the internal audiopath inside the C3DSegment object which controls 3D positioning. 


	// Sends a note-on with the 3D segment audiopath configuration


	cout << "Playing a MIDI note-on with the audio path performance on your left. 
	Press a key to continue...\n" << endl;


	CAPathPerformance.SendMidiMsg(NOTE_OFF,64,127,0,C3DSegment1.GetAudioPath()); Loading and playing a DLS instrument in 3D

The following code explains how to play a NOTE_ON MIDI command using DLS instruments and position it in the 3D space. It also presents some new DirectMidi methods to work with audiopaths. See below:

	///////////////////////////// PLAYING A DLS INSTRUMENT IN 3D /////////////////////

	// Gets the defult audiopath for the performance


	// Gets a 3D buffer


	// Positions the 3D buffer one unit in the negative X-axis


	// Unloads the segment from the audio path performance


	// Loads the default GM/GS collection


	// Gets the instrument 215


	// Assigns the patch 0


	// Set up the note range


	DWORD dwGroup,dwMChannel;

	// Downloads the instrument to the performance channel 1


	// Selects the patch and plays the note on PChannel 1


	cout << "Playing a GM/GS DLS instrument with the audio performance on your left. 
	Press a key to coninue...\n" << endl;



We start this example part introducing a new method to get the default audiopath in the call to the CAPathPerformance::Initialize method. The CAPathPerformance::GetDefaultAudioPath method retrieves the internally created audiopath. Once we have a reference to the object represeting the audiopath, we can proceed to obtain the C3DBuffer object that will perform 3D positioning in the application using the CAudioPath::Get3DBuffer method. If we wanted to set the position of the listener in the space we would have to call the CAudioPath::Get3DListener method.  
Before downloading a DLS instrument to the performance memory, we must unload the previously stored segment data from it. Therefore we call the CSegment::Unload method to achieve this. Now, we can load the DLS data, but we must first provide a container for the instrument list in the DLS file, the CCollectionA object. After calling CDLSLoader::LoadDLS and passing a referece to a CCollection object, we extract a specific instrument from it by calling CCollection::GetInstrument. Secondly, we set a patch number for the new instrument calling CInstrument::SetPatch and assigning it the 0 MIDI program. Finally, before proceeding to download the instrument, we should provide a playable note region for the instrument using the CInstrument::SetNoteRange method. Now, all is ready to download the instrument to the performance. The method which performs this is CAPathPerformance::DownloadInstrument which is not too different from the previously presented method to play audiopath performances. It just needs the PChannel where the instrument will be assigned and two DWORD's for retrieving the channel group and the MIDI channel where it will be stored. After downloading it, we must select the patch of the instrument by sending a PATCH_CHANGE message with the PChannel and the patch number to be set up in the performance. And finally, we can proceed to play the note in the 3D space by providing a referece to the defult audiopath (CAudioPath1) in the call to the CAPathPerformance::SendMidiMsg method. Wave sample instruments and thruing to the 3D performance

In this example we will be able to test one of the most amazing features of DirectMusic. We will load a sample from a wave file (.WAV) and download it to the audiopath performance in order to apply 3D effects. Afterwards, we will activate an input port to attain a thru connection between the port and the performance and play in the space with an external keyboard. The next code explains how to achieve it:

1	///////////////////////// PLAYING A SAMPLE INSTRUMENT IN 3D ///////////////
3	// Unloads the instrument from the audiopath performance

4	CAPathPerformance.UnloadInstrument(CInstrument1);
7	// Gets the port where the performance channel 2 resides
9	IDirectMusicPort8* pPort = NULL;
11	CAPathPerformance.PChannelInfo(2,&pPort,NULL,NULL);
13	// Initializes output port
15	COutPort2.Initialize(CDMusic);
17	// Activates ouput port from the interface
19	COutPort2.ActivatePortFromInterface(pPort);
21	CSampleInstrument CSample1;
23	// Loads the .wav file
25	CDLSLoader::LoadWaveFile(_T(".\\media\\starbreeze.wav"),CSample1,DM_USE_MEMORY);
27	// Assigns the patch
29	CSample1.SetPatch(2);
31	// Sets a continuous wave loop
33	CSample1.SetLoop(TRUE);
35	// Set additional wave parameters
37	CSample1.SetWaveParams(0,0,68,F_WSMP_NO_TRUNCATION); 
39	REGION region;
40	ARTICPARAMS articparams;
42	// Initializes structures
44	ZeroMemory(&region,sizeof(REGION));
45	ZeroMemory(&articparams,sizeof(ARTICPARAMS));
48	// Sets the region parameters
50	region.RangeKey.usHigh = 127;
51	region.RangeKey.usLow = 0;
52	region.RangeVelocity.usHigh = 127;
54	// Adjust LFO
56	articparams.LFO.tcDelay = TimeCents(10.0);
57	articparams.LFO.pcFrequency = PitchCents(5.0);
59	// Sets the pitch envelope
61	articparams.PitchEG.tcAttack = TimeCents(0.0);
62	articparams.PitchEG.tcDecay = TimeCents(0.0);
63	articparams.PitchEG.ptSustain = PercentUnits(0.0);
64	articparams.PitchEG.tcRelease = TimeCents(0.0);
67	// Sets the volume envelope
69	articparams.VolEG.tcAttack = TimeCents(1.275);
70	articparams.VolEG.tcDecay = TimeCents(0.0);
71	articparams.VolEG.ptSustain = PercentUnits(100.0);
72	articparams.VolEG.tcRelease = TimeCents(10.157);
75	// Sets the instrument parameters
77	CSample1.SetRegion(&region);
78	CSample1.SetArticulationParams(&articparams);
80	// Allocate interface memory
82	COutPort2.AllocateMemory(CSample1);
84	// Download the sample instrument to the port
86	COutPort2.DownloadInstrument(CSample1);
89	// Positions the buffer
91	C3DBuffer1.SetBufferPosition(1.0,0.0,0.0);
93	// Selects patch and plays the note
95	CAPathPerformance.SendMidiMsg(PATCH_CHANGE,2,0,2,CAudioPath1);
97	CAPathPerformance.SendMidiMsg(NOTE_ON,64,127,2,CAudioPath1);
100	cout << "Playing a downloaded WAV file with the audio path performance on the right.
	Press a key to continue... \n" << endl;
102	getch();
106	CAPathPerformance.SendMidiMsg(NOTE_OFF,64,127,2,CAudioPath1);
108	// Initializes and activates default input MIDI port
110	CInPort.Initialize(CDMusic);
111	CInPort.GetPortInfo(1,&PortInfo);
112	CInPort.ActivatePort(&PortInfo);
114	// Finds out which group and MIDI channel are assigned to PChannel 2 
116	CAPathPerformance.PChannelInfo(2,NULL,&dwGroup,&dwMChannel);
118	// Activates the thru over the retrieved MIDI channel and group
120	CInPort.SetThru(0,dwGroup,dwMChannel,COutPort2);
122	cout << "Activating MIDI thru from input MIDI channel 0 to PChannel 2.\n" \
123	"Play with an external keyboard. Press a key to continue... \n" << endl;
125	getch();

Firstly, before starting the sample loading, we proceed to unload the DLS instrument previously used, calling CAPathPerformance::UnloadInstrument.
In order to download the sample to the performance, we will need to know which default IDirectMusicPort8 the performance is using to access to the wave-table memory. Therefore, we inquire this port by calling the CAPathPerformance::PChannelInfo with a PChannel number as a parameter. This method provides a reference to an increased IDirectMusicPort8 interface pointer related to the specified PChannel. Once we have obtained the IDirectMusicPort8 interface pointer, we will be able to handle it in a higher level by activating a COutputPort object type through a call to the COutputPort::ActivatePortFromInterface method (line 19th).
After this important process, we can continue instancing a CSampleInstrument object type in order to load a wave file using the CDLSLoader::LoadWaveFile method. Afterwards, we proceed to apply instrument parameters such as patch number, unity key note, looping, regions and articulations as shown in lines 29-78th. 
Before downloading the data to the port wave-table, we need to allocate memory for the download interfaces, so we will call the COutputPort::AllocateMemory method. Finally, we can download the PCM data with the COutputPort::DownloadInstrument method and play the note in 3D space through the PChannel 2 as commented in the 91-97th lines. 

The second part of the example above explains how to activate the MIDI thru from the default input port to the performance. To do this, we will need to activate a CInputPort object (lines 110-112th) and obtain the channel group and the MIDI channel assigned to the PChannel 2. Once we have got this two parameters, we can proceed to activate the thru from the 0 MIDI channel in our external MIDI port to the PChannel that contains the MIDI channel and the channel group previously obtained in the call to CAPathPerformance::PChannelInfo. In this case it is the number 2.     

3.2.7 Advanced audio features

This last section explains how to apply advanced audio FX by using DMO's supplied by DirectX. 
DMO stands for DirectX Media Object and is a COM object that processes multimedia data streams from buffers allocated by the client. Basically the DMO is implemented as a COM object in a dll library and registered in the system. 
In the next lines it is explained how to apply Reverberation effects to the downloaded sample instrument. See below:

	//////////////////////// RETRIEVING A STANDARD DMO OBJECT ///////////////////

	// Releases the old audiopath handler


	// Removes the default audiopath

	// Creates a new audiopath


	// Declares a DMO interface pointer

	CComPtr<IDirectSoundFXWavesReverb8> pEffectDMO;

	// Gets the DMO


	// Maximum reverberation 

	DSFXWavesReverb FX; 



	cout << "Playing a sample on PChannel 2 with maximum reverberation.\n" \
	"Play with an external keyboard. Press a key to end the application...\n" << endl;

catch (CDMusicException& DMExcp)
	cout << "\n" << DMExcp.GetErrorDescription() << "\n" << endl;

return 0;

Before applying the effect to the performance, it's important to release the old audiopath which was configured for 3D positioning and doesn't allow retrieving FX interfaces. Therefore, we call the CAudioPath::ReleaseAudioPath method to remove the references to the last audiopath. After releasing it, we can proceed to create a new audiopath which shares its FX buffers.
So we call the CAPathPerformance::CreateAudioPath method with DMUS_APATH_SHARED_STEREOPLUSREVERB as a parameter to create it. Previously apply the effect, since it's necessary to instance a pointer to a IDirectSoundFXWavesReverb8 handled by the CComPtr ATL template. This template will automatically release the COM interface references. Then, we can get the reference to the DMO object by calling the CAudioPath::GetObjectInPath method with the DMUS_PCHANNEL_ALL parameter to search in all PChannels, the DMUS_PATH_BUFFER_DMO parameter to get a DMO object in a buffer, the 1 index representing the buffer in which the DMO resides, the class identifier of the object, the 0 index to find the first matching object and the FX interface pointer. If success is returned by the pevious method call, we are ready to apply the effect by filling the suitable parameters in the DSFXWavesReverb members and calling the IDirectSoundFXWavesReverb8::SetAllParameters interface method to execute it.
The next table shows the different FX interfaces that can be retrieved from the stereo plus reverb audiopath:




IID_IDirectSoundFXGargle8 IDirectSoundFXGargle8 Gargle
IID_IDirectSoundFXChorus8 IDirectSoundFXChorus8 Chorus
IID_IDirectSoundFXFlanger8 IDirectSoundFXFlanger8 Flanger
IID_IDirectSoundFXEcho8 IDirectSoundFXEcho8 Echo
IID_IDirectSoundFXDistortion8 IDirectSoundFXDistortion8 Distortion
IID_IDirectSoundFXCompressor8 IDirectSoundFXCompressor8 Compressor
IID_IDirectSoundFXParamEq8 IDirectSoundFXParamEq8 ParamEq
IID_IDirectSoundFXWavesReverb8 IDirectSoundFXWavesReverb8 Reverb
IID_IDirectSoundFXI3DL2Reverb8 IDirectSoundFXI3DL2Reverb8 I3DL2Reverb

3.2.8 Exception handling

The implementation of the DirectMidi class library provides assertion and failure detection in each line of the source code where a call to a DirectMusic COM method is made. This prevents error situations when a bad call is made, either by invoking the function in the wrong order or by supplying incorrect parameters such as non-initialized variables. 
Looking at the scheme of a DirectMidi wrapper function we can see that the method provides exhaustive information about the class member function, the line and the HRESULT description where the exception was thrown:

HRESULT CMasterClock::ActivateMasterClock(LPCLOCKINFO ClockInfo)
	TCHAR strMembrFunc[] = _T("CMasterClock::ActivateMasterClock()");

	if (!m_pMusic8 || !ClockInfo) throw CDMusicException(strMembrFunc,hr,__LINE__);

	if (FAILED(hr = m_pMusic8->SetMasterClock(ClockInfo->guidClock)))
		throw CDMusicException(strMembrFunc,hr,__LINE__);

	if (FAILED(hr = m_pMusic8->GetMasterClock(&ClockInfo->guidClock,&m_pReferenceClock)))
		throw CDMusicException(strMembrFunc,hr,__LINE__);

	return S_OK;

Therefore, when we catch a DirectMidi exception through a reference to a CDMusicException object and we can obtain information about the error with the following class members:

 * HRESULT m_hrCode: HRESULT code where the DirectMusic API call failed.

 * TCHAR m_strMethod: UNICODE/MBCS string containing a method description where the error was generated.

 * INT m_nLine: Number of the line in the module where the error was produced.

 * LPCTSTR GetErrorDescription(): Retrieves a complete error description with the previous commented members.

 * LPCTSTR ErrorToString(): Returns a string with a definition of the generated error.