Purpose: Handles the instance of a single sampled instrument and stores its wave-form data and internal synthesis parameters 
Remark: The returns values are based on the DirectX9 constants except DM_FAILED.
The functions raise a CDMusicException exception type with the error data.
Member functions:

Function: ReleaseSample
Declaration: HRESULT CSampleInstrument::ReleaseSample()
Purpose: Releases the internal interfaces, unloads sample data from the synthesizer memory if it remains in memory,
deallocates wave-form memory and initilizes member variables to 0.
Parameters:   void

Returns:

Throws: none

Top    Index

Function: SetArticulationParams
Declaration: void CSampleInstrument::SetArticulationParams(ARTICPARAMS *pArticParams)
Purpose: Sets the DLS articulation parameters for the instrument
Parameters:    

• pArticParams [in]: A pointer to an ARTICPARAMS structure containing the parameters

Returns: none

Throws:

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: GetArticulationParams
Declaration: void CSampleInstrument::GetArticulationParams(ARTICPARAMS *pArticParams)
Purpose: Gets the ARTICPARAMS structure with the established parameters for the instrument
Parameters:    

• pArticParams [out]: A pointer to an ARTICPARAMS structure to fill

Returns: none

Throws:

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: SetWaveParams
Declaration: void CSampleInstrument::SetWaveParams(LONG lAttenuation,SHORT sFineTune,USHORT usUnityNote,ULONG fulOptions)
Purpose: Sets the wave data for a correct sound synthesis
Parameters:   

• lAttenuation [in]: Overall Attenuation to be applied to data

• sFineTune [in]: Fine Tune in log tuning 

• usUnityNote [in]: MIDI Unity Playback Note

• fulOptions [in]: Flag options. Can be one of the followings: 

F_WSMP_NO_TRUNCATION: No truncation for wave sample

F_WSMP_NO_COMPRESSION: No compressed wave data 

Remarks: For further information see the MMA DLS 1.0 specification document

Returns: none

Throws: none

Top    Index

Function: GetWaveParams
Declaration: void CSampleInstrument::GetWaveParams(LONG *plAttenuation,SHORT *psFineTune,USHORT *pusUnityNote,ULONG *pfulOptions)
Purpose: Gets the established wave synthesis data 
Parameters:   

• plAttenuation [out]: Overall Attenuation to be applied to data

• psFineTune [out]: Fine Tune in log tuning 

• pusUnityNote [out]: MIDI Unity Playback Note

• pfulOptions [out]: Flag options. Can be one of the followings:

F_WSMP_NO_TRUNCATION: No truncation for wave sample

F_WSMP_NO_COMPRESSION: No compressed wave data 

Remarks: For further information see the MMA DLS 1.0 specification document

Returns: none

Throws: none

Top    Index

Function: SetPatch
Declaration: void CSampleInstrument::SetPatch(DWORD dwPatch)
Purpose: Sets the destination MIDI program for a specific sample instrument
Parameters:    

• dwPatch [in]: Patch number

Returns: none

Throws: none

Top    Index

Function: SetRegion
Declaration: void CSampleInstrument::SetRegion(REGION *pRegion)
Purpose: Sets the region parameters for a DLS download
Parameters:    

• pRegion [in]: A pointer to a REGION structure

Returns: none

Throws: 

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: GetRegion
Declaration: void CSampleInstrument::GetRegion(REGION *pRegion)
Purpose: Gets the region parameters  
Parameters:    

• pRegion [out]: A pointer to a REGION structure

Returns: none

Throws: 

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: SetLoop
Declaration: void CSampleInstrument::SetLoop(BOOL bLoop)
Purpose: Sets the type of sample playback   
Parameters:    

• bLoop [in]: Can be one of the following values: 
  
  FALSE: The loop type is a normal forward playing loop which is continually played until the envelope reaches an off threshold in the release portion of the volume envelope
  
  TRUE: The loop type is a continually repeat playing loop until the user releases the playing note

Returns: none

Throws: none

Top    Index

Function: SetWaveForm
Declaration: void CSampleInstrument::SetWaveForm(BYTE *pRawData,WAVEFORMATEX *pwfex,DWORD dwSize)
Purpose: Sets the internal sample instrument wave-form
Parameters:    

• pRawData [in]: A pointer to a buffer containing the wave-form raw data

• pwfex [in]: WAVEFORMATEX windows structure containing the format of the wave-form

• dwSize [in]: Size of the input buffer in bytes

Remarks: This function fails if the user has already read a wave-form from a file. This function can be used to establish a new wave-form defined by the user. 

Returns: none

Throws: 

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: GetWaveForm
Declaration: void CSampleInstrument::GetWaveForm(BYTE **pRawData,WAVEFORMATEX *pwfex,DWORD *dwSize)
Purpose: Gets the internal sample instrument wave-form
Parameters:  

• pRawData [out]: A pointer to a buffer containing the wave-form raw data

• pwfex [out]: WAVEFORMATEX windows structure containing the format of the wave-form

• dwSize [out]: Size of the internal buffer in bytes

Returns: none

Throws: 

DM_FAILED

Error, see DirectMidi causes

Top    Index

Function: GetWaveFormSize
Declaration: DWORD CSampleInstrument::GetWaveFormSize()
Purpose: Gets the internal sample instrument wave-form size in bytes
Parameters:   none
Returns: The size of the wave-form in bytes

Throws: none

Top    Index