Purpose: It represents a segment, which is a
playable unit of data made up of multiple tracks
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:
ConnectToDLS
Declaration: HRESULT CSegment::ConnectToDLS(CCollection &Collection)
Purpose:
Connects all bands in the track to a
Parameters:
Collection [in]: Reference to a CCollection object
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_SET_UNSUPPORTED | Setting the parameter is not supported. |
| DM_FAILED | Error, see DirectMidi causes |
| DMUS_E_TRACK_NOT_FOUND | There is no track of the requested type |
Function:
Download
Declaration: HRESULT CSegment::Download(CPerformance &Performance)
Purpose: Downloads band data to a
performance
Parameters:
Performance [in]: Reference to a performance object
Remarks: This object keeps a list of all current performances where the
segment has been downloaded
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_NOT_FOUND | The requested item is not contained by the object |
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
| DMUS_E_TRACK_NOT_FOUND | There is no track of the requested type |
Function:
GetDefaultResolution
Declaration: HRESULT CSegment::GetDefaultResolution(DWORD *pdwResolution)
Purpose: Retrieves the default
resolution of the segment. This is the value used to determine how times such as
the segment start time are adjusted for synchronization with the rhythm
Parameters:
pdwResolution [out]: Address of a variable that receives the default resolution. This value can be 0 or one of the the following flags.
| Value | Description |
| DMUS_SEGF_MEASURE | Resolve times to next measure. |
| DMUS_SEGF_BEAT | Resolve times to next beat. |
| DMUS_SEGF_GRID | Resolve times to next grid. |
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetLength
Declaration: HRESULT CSegment::GetLength(MUSIC_TIME *pmtLength)
Purpose: Retrieves the length of
the segment
Parameters:
pmtLength [out]: Address of a variable that receives the segment's length in music time
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetLoopPoints
Declaration: HRESULT CSegment::GetLoopPoints(MUSIC_TIME *pmtStart,MUSIC_TIME *pmtEnd)
Purpose: Retrieves the start and
end loop points
Parameters:
pmtStart [out]: Address of a variable that receives the start point of the loop
pmtEnd [out]:Address of a variable that receives the end point of the loop. A value of 0 indicates that the entire segment loops
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetRepeats
Declaration: HRESULT CSegment::GetRepeats(DWORD *pdwRepeats)
Purpose: Retrieves the number of
times the looping portion of the segment is set to repeat
Parameters:
pdwRepeats [out]: Address of a variable that receives the number of times that the looping portion of the segment is set to repeat
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetSeek
Declaration: HRESULT CSegment::GetSeek(MUSIC_TIME *pmtSeek)
Purpose: This method retrieves the
seek pointer in the segment
Parameters:
pmtSeek [out]: Address of a variable that receives the seek pointer
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetSegment
Declaration: HRESULT CSegment::GetSegment(IDirectMusicSegment **ppSegment)
Purpose: Retrieves a pointer to the
segment interface that owns this segment
Parameters:
ppSegment [out]: Address of a variable that receives a pointer to the IDirectMusicSegment interface. Use QueryInterface to obtain IDirectMusicSegment8 interface
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_NOT_FOUND | The requested item is not contained by the object |
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetStartPoint
Declaration: HRESULT CSegment::GetStartPoint(MUSIC_TIME *pmtStart)
Purpose: Retrieves the time within
the segment at which it started playing
Parameters:
pmtStart [out]: Address of a variable that receives the music-time offset from the start of the segment at which play will begin or began
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
GetStartTime
Declaration: HRESULT CSegment::GetStartTime(MUSIC_TIME *pmtStart)
Purpose: Retrieves the performance
time at which the segment started playing
Parameters:
pmtStart [out]: Address of a variable that receives the music-time offset stored in this segment state
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
ReleaseSegment
Declaration: HRESULT CSegment::ReleaseSegment()
Purpose: Releases the segment.
Unloads the segment from all downloaded performances
Parameters: none
Returns:
| S_FALSE | Error |
| S_OK |
Succeeds |
Function:
SetDefaultResolution
Declaration: HRESULT CSegment::SetDefaultResolution(DWORD dwResolution)
Purpose: Sets the default resolution
of the segment
Parameters:
dwResolution [in]: Default resolution. This value can be 0 or one of the the following flags.
Remarks: This
method is used primarily by secondary segments to specify whether they are
synchronized to the measure, beat, or grid of the primary segment by default.
| Value | Description |
| DMUS_SEGF_MEASURE | Resolve times to next measure. |
| DMUS_SEGF_BEAT | Resolve times to next beat. |
| DMUS_SEGF_GRID | Resolve times to next grid. |
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetLength
Declaration: HRESULT CSegment::SetLength(MUSIC_TIME mtLength)
Purpose: Sets the default resolution
of the segment
Parameters:
mtLength [in]: Desired length. Must be greater than 0
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_OUT_OF_RANGE | The requested time is outside the range of the segment |
| 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 |
Function:
SetLoopPoints
Declaration: HRESULT CSegment::SetLoopPoints(MUSIC_TIME mtStart,MUSIC_TIME mtEnd)
Purpose: This method sets the start
and end points of the part of the segment that repeats the number of times set
by the CSegment::SetRepeats method
Parameters:
mtStart [in]: Point at which to begin the loop
mtEnd [in]: Point at which to end the loop. A value of 0 loops the entire segment
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_OUT_OF_RANGE | The requested time is outside the range of the segment |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetPChannelsUsed
Declaration: HRESULT CSegment::SetPChannelsUsed(DWORD dwNumPChannels,DWORD *paPChannels)
Purpose: This method sets the
Parameters:
dwNumPChannels [in]: Number of performance channels to set. This must be equal to the number of members in the array pointed to by paPChannels
paPChannels [in]: Address of an array of performance channel identifiers
Returns:
| S_OK |
Succeeds |
Throws:
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter. |
| E_OUTOFMEMORY | Insufficient memory to complete the task |
| 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 |
Function:
SetRepeats
Declaration: HRESULT CSegment::SetRepeats(DWORD dwRepeats)
Purpose: This method sets the number
of times the looping portion of the segment is to repeat
Parameters:
dwRepeats [in]: Number of times that the looping portion of the segment is to repeat, or DMUS_SEG_REPEAT_INFINITE to repeat until explicitly stopped. A value of 0 specifies a single play with no repeats
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetStartPoint
Declaration: HRESULT CSegment::SetStartPoint(MUSIC_TIME mtStart)
Purpose: This method sets the
point within the segment at which it starts playing
Parameters:
mtStart [in]: Point within the segment at which it is to start playing. Must be greater than or equal to 0 and less than the length of the segment
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_OUT_OF_RANGE | The requested time is outside the range of the segment |
| DM_FAILED | Error, see DirectMidi causes |
Function:
Unload
Declaration: HRESULT CSegment::Unload(CPerformance &Performance)
Purpose: Unloads a segment from a
performance
Parameters:
Performance [in]: Referecene to a performance object
Remarks: The performance is removed from the download list
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_TRACK_NOT_FOUND | There is no track of the requested type |
| E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
| DM_FAILED | Error, see DirectMidi causes |
Function:
UnloadAllPerformances
Declaration: HRESULT
CSegment::UnloadAllPerformances()
Purpose: Unloads the references to a
segment in all downloaded performances
Parameters: none
Returns:
| S_OK |
Succeeds |
Function:
operator = (CSegment &Segment)
Declaration: CSegment& CSegment::operator = (const CSegment &Segment)
Purpose: Clones a segment to another CSegment object
Parameters:
CSegment [in]: Reference to a CSegment object
Returns:
| CSegment | A cloned CSement |
Throws:
| 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 |