Step 6: Adding the Tool to the Performance

Once it has defined the CEchoTool class, the application can create a tool object, insert it into a graph, and add it to the performance so that it will intercept appropriate messages in the pipeline.

The following code creates an instance of the CEchoTool class, initializes the number of echoes to be produced by the tool, creates a graph to contain the tool, and adds the graph to the performance. (In the Echotool sample application, some of this work is done in a helper function, AddTool. The code has been modified here to make it easier to follow.)

/* It is assumed that pPerf is a valid pointer to the
   IDirectMusicPerformance interface of a performance object. */
 
CEchoTool         *pEchoTool;
IDirectMusicGraph* pGraph;
 
pEchoTool = new CEchoTool;
if (pEchoTool)
{
    pEchoTool->SetEchoNum(0);
 
    // Create an IDirectMusicGraph object to hold the tool.
    if (SUCCEEDED(CoCreateInstance(
            CLSID_DirectMusicGraph,
            NULL,
            CLSCTX_INPROC, 
            IID_IDirectMusicGraph,
            (void**)&pGraph)))
    {
        // Add the tool to the graph.
        if (SUCCEEDED(pGraph->InsertTool(
                (IDirectMusicTool*)pCEchoTool, 
                NULL,   // Apply to all PChannels
                0,      // How many PChannels otherwise
                0)))    // Index of tool in graph
        {
        // Add the graph to the performance. This increments the
        // reference count, so the original graph can then be
        // released.
        pPerf->SetGraph(pGraph);
        }
        pGraph->Release();
    } 
}
 

Note that setting the graph on the performance ensures that messages from all segments will have the opportunity to be processed by its tools. Alternatively, you could use the IDirectMusicSegment::SetGraph method to apply tools only to a particular segment.