CAPathPerformance


Purpose:
Handles performance objects which use audipaths and 3D positioning. It is the overall manager of playback and is used for adding and removing ports, mapping performance channels to ports, playing segments, dispatching messages and routing them through tools, requesting and receiving event notification, and setting and retrieving various parameters. It also has several methods for getting information about timing and for converting time and music values from one system to another.

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: Initialize
Declaration: HRESULT CAPathPerformance::Initialize(CDirectMusic &DMusic,IDirectSound **ppDirectSound,HWND hWnd,DWORD dwDefaultPathType,DWORD dwPChannelCount,DWORD dwFlags,DMUS_AUDIOPARAMS *pAudioParams)
Purpose: Initializes a performance object with an audiopath
Parameters:   
 

Value

Description

DMUS_APATH_DYNAMIC_3D

One bus to a 3-D buffer. Does not send to environmental reverb.

DMUS_APATH_DYNAMIC_MONO

One bus to a mono buffer.

DMUS_APATH_DYNAMIC_STEREO

Two buses to a stereo buffer.

DMUS_APATH_SHARED_STEREOPLUSREVERB

Ordinary music setup with stereo outs and reverb.

Value Description
DMUS_AUDIOF_3D 3-D buffers.
DMUS_AUDIOF_ALL All features.
DMUS_AUDIOF_BUFFERS Multiple buffers.
DMUS_AUDIOF_DMOS Additional DMOs.
DMUS_AUDIOF_ENVIRON Environmental modeling.
DMUS_AUDIOF_EAX EAX effects.
DMUS_AUDIOF_STREAMING Support for streaming waveforms.

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_ALREADY_INITED The object has already been initialized
DSERR_BUFFERLOST The buffer memory has been lost and must be restored
DSERR_UNINITIALIZED The IDirectSound8::Initialize method has not been called or has not been called successfully before other methods were called
DSERR_PRIOLEVELNEEDED A cooperative level of DSSCL_PRIORITY or higher is required
DM_FAILED Error, see DirectMidi causes
E_NOINTERFACE No object interface is available
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
CLASS_E_NOAGGREGATION This class cannot be created as part of an aggregate
REGDB_E_CLASSNOTREG A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt
E_OUTOFMEMORY Insufficient memory to complete the task

Top    Index

Function: CreateAudioPath
Declaration: H
RESULT CAPathPerformance::CreateAudioPath(CAudioPath &Path,DWORD dwType,DWORD dwPChannelCount,BOOL bActivate)
Purpose:  Creates an audiopath with a standard configuration
Parameters:    

Value Description
DMUS_APATH_DYNAMIC_3D One bus to a 3-D buffer. Does not send to environmental reverb.
DMUS_APATH_DYNAMIC_MONO One bus to a mono buffer.
DMUS_APATH_DYNAMIC_STEREO Two buses to a stereo buffer.
DMUS_APATH_SHARED_STEREOPLUSREVERB Ordinary music setup with stereo outs and reverb.

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NOT_INIT A required object is not initialized or failed to initialize
DSERR_BUFFERLOST The buffer memory has been lost and must be restored
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task

Top    Index

Function: GetDefaultAudioPath
Declaration: HRESULT CAPathPerformance::GetDefaultAudioPath(CAudioPath &Path)
Purpose:  Gets a reference to the default audiopath in the performance
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NOT_INIT A required object is not initialized or failed to initialize
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

Function: SetDefaultAudioPath
Declaration: HRESULT CAPathPerformance::SetDefaultAudioPath(CAudioPath &Path)
Purpose:  Sets a default audiopath in the performance
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_AUDIOPATH_NOPORT The audiopath could not be used for playback because it lacked port assignments
DMUS_E_NOT_INIT A required object is not initialized or failed to initialize
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

Function: RemoveDefaultAudioPath
Declaration: HRESULT CAPathPerformance::RemoveDefaultAudioPath()
Purpose:  Removes a default audiopath in the performance
Parameters:   
none          

Returns:  

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_AUDIOPATH_NOPORT The audiopath could not be used for playback because it lacked port assignments
DMUS_E_NOT_INIT A required object is not initialized or failed to initialize
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

 

Function: ReleasePerformance
Declaration: HRESULT CAPathPerformance::ReleasePerformance()
Purpose:  Releases the performance object 
Parameters:   none           

Returns:  

S_FALSE Error
S_OK

Succeeds

Top    Index

Function: PlaySegment
Declaration: HRESULT CAPathPerformance::PlaySegment(CSegment &Segment,CAudioPath *Path,DWORD dwFlags,__int64 i64StartTime)
Purpose:  Plays a segment 
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_AUDIOPATH_NOPORT The audiopath could not be used for playback because it lacked port assignments
DMUS_E_AUDIOPATH_INACTIVE The audiopath is inactive, perhaps because the performance has been closed down
E_NOINTERFACE The interface is not supported
E_OUTOFMEMORY Insufficient memory to complete the task
DMUS_E_TIME_PAST The time requested is in the past
DMUS_E_SEGMENT_INIT_FAILED Segment initialization failed, probably because of a critical memory situation
DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

Function: PlaySegment (3D version)
Declaration: HRESULT CAPathPerformance::PlaySegment(C3DSegment &Segment,DWORD dwFlags,__int64 i64StartTime)
Purpose:  Plays a 3D segment 
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_AUDIOPATH_NOPORT The audiopath could not be used for playback because it lacked port assignments
DMUS_E_AUDIOPATH_INACTIVE The audiopath is inactive, perhaps because the performance has been closed down
E_NOINTERFACE The interface is not supported
E_OUTOFMEMORY Insufficient memory to complete the task
DMUS_E_TIME_PAST The time requested is in the past
DMUS_E_SEGMENT_INIT_FAILED Segment initialization failed, probably because of a critical memory situation
DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
DM_FAILED Error, see DirectMidi causes
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

Function: SendMidiMsg
Declaration: HRESULT CAPathPerformance::SendMidiMsg(BYTE bStatus,BYTE bByte1,BYTE bByte2,DWORD dwPChannel,CAudioPath &Path)
Purpose:  Sends a typical MIDI 1.0 message to the audiopath performance
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE No object interface is available
E_OUTOFMEMORY Insufficient memory to complete the task
DMUS_S_LAST_TOOL There are no more tools in the graph
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_CANNOT_FREE The message could not be freed, either because it was not allocated or because it has already been freed
DMUS_E_ALREADY_SENT The message has already been sent
DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
DMUS_E_NOT_FOUND The requested item is not contained by the object
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: AdjustTime
Declaration: HRESULT CAPathPerformance::AdjustTime(REFERENCE_TIME rtAmount)
Purpose:  The AdjustTime method adjusts the internal performance time forward or backward. This is mostly used to compensate for drift when synchronizing to another source
Parameters:   rtAmount [in]: Amount of time to add. This can be a value in the range from -10,000,000 to 10,000,000 (1 second to +1 second)       

Returns:  

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: DownloadInstrument
Declaration: HRESULT CAPathPerformance::DownloadInstrument(CInstrument &Instrument,DWORD dwPChannel,DWORD *pdwGroup,DWORD *pdwMChannel)
Purpose:  The DownloadInstrument method downloads DLS instrument data to a port
Parameters:   

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetBumperLength
Declaration: HRESULT CAPathPerformance::GetBumperLength(DWORD *pdwMilliSeconds)
Purpose:  The GetBumperLength method retrieves the interval between the time at which messages are placed in the port buffer and the time at which they begin to be processed by the port
Parameters:  

Remarks: The default value is 50 milliseconds

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetLatencyTime
Declaration: HRESULT CAPathPerformance::GetLatencyTime(REFERENCE_TIME *prtTime)
Purpose:  Retrieves the latency time, which is the performance time being heard from the speakers plus the time required to queue and render messages
Parameters:  

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetMasterTempo
Declaration: HRESULT CAPathPerformance::GetMasterTempo(float *fTempo)
Purpose:  Retrieves the current master tempo. This parameter must be set before retrieving it
Parameters:  


Returns:
 

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetMasterVolume
Declaration: HRESULT CAPathPerformance::GetMasterVolume(long *nVolume)
Purpose:  Retrieves the current master volume. This parameter must be set before retrieving it
Parameters:  


Returns:
 

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetPrepareTime
Declaration: HRESULT CAPathPerformance::GetPrepareTime(DWORD *pdwMilliSeconds)
Purpose:  Retrieves the interval between the time when messages are sent by tracks and the time when the sound is heard. This interval allows sufficient time for the message to be processed by tools
Parameters:  


Remarks: The default value is 1000 milliseconds

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetQueueTime
Declaration: HRESULT CAPathPerformance::GetQueueTime(REFERENCE_TIME *prtTime)
Purpose:
The GetQueueTime method retrieves the current flush time, which is the earliest time in the queue at which messages can be flushed. Messages that have time stamps earlier than this time have already been sent to the port and cannot be invalidated  
Parameters:  



Returns:
 

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetResolvedTime
Declaration: HRESULT CAPathPerformance::GetResolvedTime(REFERENCE_TIME rtTime,REFERENCE_TIME *prtResolved,DWORD dwTimeResolveFlags)
Purpose: Resolves a given time to a given boundary  
Parameters: 
 

DMUS_TIME_RESOLVE_AFTERPREPARETIME

Resolve to a time after the prepare time.

DMUS_TIME_RESOLVE_AFTERQUEUETIME

Resolve to a time after the queue time.

DMUS_TIME_RESOLVE_AFTERLATENCYTIME

Resolve to a time after the latency time.

DMUS_TIME_RESOLVE_GRID

Resolve to a time on a grid boundary.

DMUS_TIME_RESOLVE_BEAT

Resolve to a time on a beat boundary.

DMUS_TIME_RESOLVE_MEASURE

Resolve to a time on a measure boundary.

DMUS_TIME_RESOLVE_MARKER

Resolve to a marker.

DMUS_TIME_RESOLVE_SEGMENTEND

Resolve to the end of the segment.



Returns:
 

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetTime
Declaration: HRESULT CAPathPerformance::GetTime(REFERENCE_TIME *prtNow,MUSIC_TIME *pmtNow)
Purpose:
Retrieves the current time of the performance. Events cued at this time are now being performed  
Parameters: 

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: Invalidate
Declaration: HRESULT CAPathPerformance::Invalidate(MUSIC_TIME mtTime,DWORD dwFlags)
Purpose: The Invalidate method flushes all queued messages from the specified time forward and causes all tracks of all segments to resend their data
Parameters:  

Notes that have already been sent to the port are normally cut off by invalidation; that is, any pending note-off message is immediately sent. However, this behavior can be overridden by using one of the DMUS_NOTEF_FLAGS flags in the message structure

Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: IsPlaying
Declaration: HRESULT CAPathPerformance::IsPlaying(CSegment &Segment)
Purpose:
Ascertains whether a specified segment or segment state is currently being heard from the speakers
Parameters: 
 


Returns:
 

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: MusicToReferenceTime
Declaration: HRESULT CAPathPerformance::MusicToReferenceTime(MUSIC_TIME mtTime,REFERENCE_TIME *prtTime)
Purpose:
Converts a performance time in MUSIC_TIME format to performance time in REFERENCE_TIME format
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: ReferenceToMusicTime
Declaration: HRESULT CAPathPerformance::ReferenceToMusicTime(REFERENCE_TIME rtTime,MUSIC_TIME *pmtTime)
Purpose:
Converts a performance time in REFERENCE_TIME format to a performance time in MUSIC_TIME format
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

DMUS_E_NO_MASTER_CLOCK There is no master clock in the performance
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: PChannelInfo
Declaration: HRESULT CAPathPerformance::PChannelInfo(DWORD dwPChannel,IDirectMusicPort **ppPort,DWORD *pdwGroup,DWORD *pdwMChannel)
Purpose:
The PChannelInfo method retrieves the port, group, and MIDI channel for a given performance channel
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: RhythmToTime
Declaration: HRESULT CAPathPerformance::RhythmToTime(WORD wMeasure,BYTE bBeat,BYTE bGrid,short nOffset,DMUS_TIMESIGNATURE *pTimeSig,MUSIC_TIME *pmtTime)
Purpose:
The RhythmToTime method converts rhythm time to music time
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SetBumperLength
Declaration: HRESULT CAPathPerformance::SetBumperLength(DWORD dwMilliSeconds)
Purpose:
The SetBumperLength method sets the interval between the time at which messages are placed in the port buffer and the time at which they begin to be processed by the port
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SetMasterTempo
Declaration: HRESULT CAPathPerformance::SetMasterTempo(float fTempo)
Purpose: Sets the master tempo for the performance
Parameters: 
 


Remark: The master tempo is a scaling factor applied to the tempo by the final output tool. By default, it is 1. A value of 0.5 would halve the tempo, and a value of 2.0 would double it. This value can be set in the range from DMUS_MASTERTEMPO_MIN through DMUS_MASTERTEMPO_MAX

Returns:  

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_FAIL The method did not succeed
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SetMasterVolume
Declaration: HRESULT CAPathPerformance::SetMasterVolume(long nVolume)
Purpose:  Sets the master volume
Parameters:  


Remarks:  The master volume is an amplification or attenuation factor, in hundredths of a decibel, applied to the default volume of the entire performance and any other performances using the same synthesizer. The range of permitted values is determined by the port. For the default software synthesizer, the allowed range is +20db to -200dB, but the useful range is +10db to -100db. Hardware MIDI ports do not support changing master volume

Returns:
 

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_FAIL The method did not succeed
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SetPrepareTime
Declaration: HRESULT CAPathPerformance::SetPrepareTime(DWORD dwMilliSeconds)
Purpose:  Sets the interval between the time when messages are sent by tracks and the time when the sound is heard. This interval allows sufficient time for the message to be processed by tools
Parameters: 

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes

Top    Index

Function: Stop
Declaration: HRESULT CAPathPerformance::Stop(CSegment &Segment,__int64 i64StopTime,DWORD dwFlags)
Purpose:  Stops a current playing segment
Parameters: 

Value Description
DMUS_SEGF_AUTOTRANSITION Not implemented.
DMUS_SEGF_BEAT Stop on the next beat boundary at or after i64StopTime.
DMUS_SEGF_DEFAULT Stop on the default boundary, as set by the IDirectMusicSegment8::SetDefaultResolution method.
DMUS_SEGF_GRID Stop on the next grid boundary at or after i64StopTime.
DMUS_SEGF_MEASURE Stop on the next measure boundary at or after i64StopTime.
DMUS_SEGF_REFTIME The value in i64StopTime is in reference time.
DMUS_SEGF_SEGMENTEND Stop at the end of the primary segment.
DMUS_SEGF_MARKER Stop at the next marker.

 
Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: StopAll
Declaration: HRESULT CAPathPerformance::StopAll()
Purpose: Stops all current playing segments
Parameters: 
none                  

Returns:
 

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: TimeToRhythm
Declaration: HRESULT CAPathPerformance::TimeToRhythm(MUSIC_TIME mtTime,DMUS_TIMESIGNATURE *pTimeSig,WORD *pwMeasure,BYTE *pbBeat,BYTE *pbGrid,short *pnOffset)
Purpose:
Converts music time to rhythm time
Parameters: 
 


Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: UnloadInstrument
Declaration: HRESULT CAPathPerformance::UnloadInstrument(CInstrument &Instrument)
Purpose:  Unloads an instrument from the performance port
Parameters:   



Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
DMUS_E_NOT_DOWNLOADED_TO_PORT The object cannot be unloaded because it is not present on the port
DM_FAILED Error, see DirectMidi causes

Top    Index