IDirectMusicInstrument8::SetPatch

Microsoft DirectX 9.0

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

Patch number to assign.

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.

Return code

DMUS_E_NOT_INIT

DMUS_E_INVALIDPATCH

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:

HRESULT RemappedDownload(
    IDirectMusicCollection8 *pCollection,
    IDirectMusicPort8 *pPort,
    IDirectMusicDownloadedInstrument8 **ppDLInstrument,
    BYTE bMSB,
    DWORD dwPatch)
 
{
  HRESULT hr;
  IDirectMusicInstrument8* pInstrument;
  hr = pCollection->GetInstrument(dwPatch, &pInstrument);
  if (SUCCEEDED(hr))
  {
    dwPatch &= 0xFF00FFFF;
    dwPatch |= bMSB << 16;
    pInstrument->SetPatch(dwPatch);
    hr = pPort->DownloadInstrument(pInstrument, 
                                   ppDLInstrument, NULL, 0);
    pInstrument->Release();
  }
  return hr;
}

Requirements

Header: Declared in dmusicc.h.

See Also