IDirectMusicInstrument::SetPatch

The IDirectMusicInstrument::SetPatch method sets the patch number for the instrument. Although each instrument in a DLS collection has a predefined patch number, the patch number can be reassigned once the IDirectMusicCollection::GetInstrument method has been used to retrieve the instrument from the collection. For more information on DirectMusic patch numbers, see IDirectMusicInstrument::GetPatch.

HRESULT SetPatch(
  DWORD dwPatch
);

Parameters

dwPatch

New patch number to assign to instrument.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return DMUS_E_INVALIDPATCH.

Remarks

The following code example gets an instrument from a collection, remaps its MSB bank select to a different bank, then downloads the instrument.

HRESULT myRemappedDownload(
    IDirectMusicCollection *pCollection,
    IDirectMusicPort *pPort,
    IDirectMusicDownloadedInstrument **ppDLInstrument,
    BYTE bMSB,       // Requested MIDI MSB for patch bank select
    DWORD dwPatch)   // Requested patch
 
{
    HRESULT hr;
    IDirectMusicInstrument* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        dwPatch &= 0xFF00FFFF;  // Clear MSB.
        dwPatch |= bMSB << 16;  // Insert new MSB value.
        pInstrument->SetPatch(dwPatch);
        hr = pPort->DownloadInstrument(pInstrument, 
                ppDLInstrument, 
                NULL, 0);       // Download all regions.
        pInstrument->Release();
    }
    return hr;
}

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusicc.h.