IDirectMusicInstrument8::SetPatch

The 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 after the IDirectMusicCollection8::GetInstrument method has been used to retrieve the instrument from the collection. For more information on DirectMusic patch numbers, see IDirectMusicInstrument8::GetPatch.

Syntax

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 one of the error values shown in the following table.

Remarks

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

Example Code

HRESULT myRemappedDownload(
  IDirectMusicCollection8 *pCollection,
  IDirectMusicPort8 *pPort,
  IDirectMusicDownloadedInstrument8 **ppDLInstrument,
  BYTE bMSB,   // Requested MIDI MSB for patch bank select
  DWORD dwPatch) // Requested patch
 
{
  HRESULT hr;
  IDirectMusicInstrument8* 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

  Header: Declared in dmusicc.h.

See Also

• IDirectMusicInstrument8