Purpose: Handles all output midi ports and
performs DLS load and unload.
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: void
COutputPort::Initialize(CDirectMusic &pDMusic)
Purpose:
Initializes the output port object
Parameters:
pDMusic [in]:
Reference to the main DirectMusic object
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
Function: GetNumPorts
Declaration: DWORD
COutputPort::GetNumPorts()
Purpose: Returns the number of
output midi ports in the system
Parameters: none
Returns:
Number of ports |
Number of ouput midi ports, if 0 is returned, no ouput ports present |
Throws:
E_INVALIDARG | Invalid argument |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_NOINTERFACE | No object interface is available |
DM_FAILED | Error, see DirectMidi causes |
Function:
GetPortInfo
Declaration: HRESULT COutputPort::GetPortInfo(DWORD dwNumPort,LPINFOPORT
lpInfoPort)
Purpose: Gets the port info structure of a given
number of midi port
Parameters:
Returns:
S_FALSE | There is no port with that index value |
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
E_INVALIDARG | Invalid argument |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_NOINTERFACE | No object interface is available |
Function:
GetActivatedPortInfo
Declaration: HRESULT COuputPort::GetActivatedPortInfo(LPINFOPORT
lpInfoPort)
Purpose: Gets the port info structure of the
current activated midi port
Parameters:
lpInfoPort [out]: Address of an INFOPORT structure
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
E_INVALIDARG | Invalid argument |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
Function:
ActivatePort
Declaration: HRESULT COutputPort::ActivatePort(LPINFOPORT InfoPort,DWORD
dwSysExSize)
Purpose: Activate the output midi port providing a
pointer to an INFOPORT structure with the port identification.
Allocate the
buffer memory for outgoing system exclusive data
Parameters:
Returns:
S_OK |
Succeeds |
Throws:
S_FALSE | Error |
DSERR_NODRIVER | No sound driver is available for use, or the given GUID is not a valid DirectSound device ID |
E_NOINTERFACE | No object interface is available |
DM_FAILED | Error, see DirectMidi causes |
E_INVALIDARG | Invalid argument |
DMUS_E_DSOUND_NOT_SET | The port could not be created because no DirectSound object has been specified |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_OUTOFMEMORY | Insufficient memory to complete the task |
Function:
ActivatePortFromInterface
Declaration: HRESULT COuputtPort::ActivatePortFromInterface(IDirectMusicPort8* pPort,DWORD dwSysExSize)
Purpose: Activate the
output midi port providing a
pointer to an IDirectMusicPort8 interface pointer.
Allocate the
buffer memory for outgoing system exclusive events.
Parameters:
Remarks:
The external IDirectMusicPort8 interface pointer doesn't have to be explicitly released
Returns:
S_OK |
Succeeds |
Throws:
S_FALSE | Error |
DSERR_NODRIVER | No sound driver is available for use, or the given GUID is not a valid DirectSound device ID |
E_NOINTERFACE | No object interface is available |
DM_FAILED | Error, see DirectMidi causes |
E_INVALIDARG | Invalid argument |
DMUS_E_DSOUND_NOT_SET | The port could not be created because no DirectSound object has been specified |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_OUTOFMEMORY | Insufficient memory to complete the task |
Function: ReleasePort
Declaration: HRESULT
COutputPort::ReleasePort()
Purpose: Releases the DirectMidi
internal COM interfaces for a new port selection, this method is also called by
the destructor
Parameters:
none
Remarks: Call this member function to deactivate the selected
output midi port in run-time
Returns:
S_OK |
Succeeds |
DM_FAILED | Error, see DirectMidi causes |
Throws:
DSERR_NODRIVER | No sound driver is available for use, or the given GUID is not a valid DirectSound device ID |
Function:
KsProperty
Declaration: HRESULT COutputPort::KsProperty(GUID
Set,ULONG Id,ULONG Flags,LPVOID pvPropertyData,ULONG ulDataLength,PULONG
pulBytesReturned)
Purpose: The KsProperty method retrieves or sets the value of a property for
the midi port
Parameters:
Set [in]:Identifier of the property set. The following property-set GUIDs are predefined by DirectMusic: See table |
Id [in]: Item within the property set |
Flags [in]: One of the following flags to specify the operation: See table |
pvPropertyData [in/out]: For a set operation, the address of a memory buffer containing data that represents the new value of the property. For a get operation, the address of a memory buffer big enough to hold the value of the property. For a basic support query, the address of a buffer at least a DWORD in size |
ulDataLength [in]: Length of the buffer pointed to by pvPropertyData |
pulBytesReturned [out]: On a KSPROPERTY_TYPE_GET or KSPROPERTY_TYPE_BASICSUPPORT call, address of a variable that receives the number of bytes returned in pvPropertyData by the port |
Example: The following example code demonstrates the use of this property by
setting a new latency for the synthesizer
in milliseconds.
COutputPort.KsProperty(GUID_DMUS_PROP_WriteLatency,0,KSPROPERTY_TYPE_SET,(LPVOID)&dwLatency,sizeof(dwLatency),&ulDummy); |
Returns:
S_OK |
Succeeds |
DMUS_E_UNKNOWN_PROPERTY | The property set or item is not implemented by this port |
Throws:
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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_FAIL | The method did not succeed |
DM_FAILED | Error, see DirectMidi causes |
Function:
SetBuffer
Declaration: HRESULT COutputPort::SetBuffer(DWORD dwBufferSize)
Purpose:
Sets internal buffer for storing outgoing MIDI messages
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 |
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOINTERFACE | No object interface is available |
DM_FAILED |
Error, see DirectMidi causes |
Function:
RemoveBuffer
Declaration: HRESULT COutputPort::RemoveBuffer()
Purpose:
Removes the internal buffer
Returns:
S_FALSE | Error |
S_OK |
Succeeds |
Function:
SetPortParams
Declaration: HRESULT COutputPort::SetPortParams(DWORD dwVoices,DWORD dwAudioChannels,DWORD dwChannelGroups,DWORD dwEffectFlags,DWORD dwSampleRate)
Purpose:
Sets the port synthesis parameters
Parameters:
dwVoices [in]: | Number of voices required on this port. This is not an absolute maximum; the port can create additional temporary voices to enable smooth transitions when lower-priority voices have to be dropped | ||||||||||
dwAudioChannels [in]: | Desired number of output channels | ||||||||||
dwChannelGroups [in]: | Number of channel groups to be allocated on this port | ||||||||||
dwEffectFlags [in]: | Flags indicating which special effects are wanted. The following values are defined:
Or one of the followings defined in CDirectMidi.h: Synthesizer Effects |
||||||||||
dwSampleRate [in]: | Desired sample rate, in hertz |
Returns: None
Throws: None
Function:
SetNumChannelGroups
Declaration: HRESULT COutputPort::SetNumChannelGroups(DWORD dwChannelGroups)
Purpose:
This method changes the number of channel groups that the application
needs on the port
Parameters:
dwChannelGroups [in]:Number of channel groups on this port that the application wants to allocate
Returns:
S_OK |
Succeeds |
Throws:
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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_FAIL | The method did not succeed |
DM_FAILED | Error, see DirectMidi causes |
Function:
GetNumChannelGroups
Declaration: HRESULT COutputPort::GetNumChannelGroups(LPDWORD pdwChannelGroups)
Purpose:
This method retrieves the number of channel groups on the port
Parameters:
pdwChannelGroups [out]:Address of a variable that receives the number of channel groups
Returns:
S_OK |
Succeeds |
Throws:
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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_FAIL | The method did not succeed |
DM_FAILED | Error, see DirectMidi causes |
Function:
SetChannelPriority
Declaration: HRESULT COutputPort::SetChannelPriority(DWORD dwChannelGroup,DWORD dwChannel,DWORD dwPriority)
Purpose: This method sets the priority of a MIDI channel
Parameters:
dwChannelGroup [in]: Group that the channel is in. This value must be 1 or greater
dwChannel [in]: Index of the channel on the group
dwPriority [in]: The priority ranking
Returns:
S_OK |
Succeeds |
Throws:
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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_FAIL | The method did not succeed |
DM_FAILED | Error, see DirectMidi causes |
Function:
GetChannelPriority
Declaration: HRESULT COutputPort::GetChannelPriority(DWORD dwChannelGroup,DWORD dwChannel,LPDWORD pdwPriority)
Purpose: This method retrieves the priority of a MIDI channel
Parameters:
dwChannelGroup [in]: Group that the channel is in. This value must be 1 or greater
dwChannel [in]: Index of the channel on the group
pdwPriority [out]: Address of a variable that receives the priority ranking
Remarks:
The following values, defined in Dmusicc.h, each represent a range of priorities. They are listed here in descending order of priority.
Value |
DAUD_CRITICAL_VOICE_PRIORITY |
DAUD_HIGH_VOICE_PRIORITY |
DAUD_STANDARD_VOICE_PRIORITY |
DAUD_LOW_VOICE_PRIORITY |
DAUD_PERSIST_VOICE_PRIORITY |
Value |
DAUD_CHAN10_VOICE_PRIORITY_OFFSET |
DAUD_CHAN1_VOICE_PRIORITY_OFFSET |
DAUD_CHAN2_VOICE_PRIORITY_OFFSET |
DAUD_CHAN3_VOICE_PRIORITY_OFFSET |
DAUD_CHAN4_VOICE_PRIORITY_OFFSET |
DAUD_CHAN5_VOICE_PRIORITY_OFFSET |
DAUD_CHAN6_VOICE_PRIORITY_OFFSET |
DAUD_CHAN7_VOICE_PRIORITY_OFFSET |
DAUD_CHAN8_VOICE_PRIORITY_OFFSET |
DAUD_CHAN9_VOICE_PRIORITY_OFFSET |
DAUD_CHAN11_VOICE_PRIORITY_OFFSET |
DAUD_CHAN12_VOICE_PRIORITY_OFFSET |
DAUD_CHAN13_VOICE_PRIORITY_OFFSET |
DAUD_CHAN14_VOICE_PRIORITY_OFFSET |
DAUD_CHAN15_VOICE_PRIORITY_OFFSET |
DAUD_CHAN16_VOICE_PRIORITY_OFFSET |
Channels that have the same priority value have equal priority, regardless of which channel group they belong to
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
Function:
GetSynthStats
Declaration: HRESULT COutputPort::GetSynthStats(LPSYNTHSTATS SynthStats)
Purpose: This method retrieves information about the state of the
synthesizer
Parameters: SynthStats [out]: A pointer to a
SYNTHSTATS structure
Returns:
S_OK |
Succeeds |
Throws:
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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 |
Function:
GetReferenceClock
Declaration: IReferenceClock*
COutputPort::GetReferenceClock()
Purpose: Returns a pointer to the internal IReferenceClock interface
Parameters: none
Returns:
IReferenceClock | Pointer to the IReferenceClock interface |
Function:
GetFormat
Declaration: HRESULT COutputPort::GetFormat(LPWAVEFORMATEX pWaveFormatEx,LPDWORD pdwWaveFormatExSize,LPDWORD pdwBufferSize)
Purpose: Retrieves information about the WAV format specified in
the COutputPort::SetPortParams structure, and the recommended size of the buffer
to use for waveform output. The information can be used to create a compatible
DirectSound buffer for the port
Parameters:
pWaveFormatEx [out]: Address of the WAVEFORMATEX structure that receives information about the format. This value can be NULL. See Remarks
pdwWaveFormatExSize [out]: Address of a variable that specifies or receives the size of the structure
pdwBufferSize [out]: Address of a variable that receives the recommended size of the DirectSound buffer
Remarks:
Remarks
The WAVEFORMATEX structure can have a variable length that depends on the details of the format. Before retrieving the format description, the application should query the synthesizer object for the size of the format by calling this method and specifying NULL for the pWaveFormatEx parameter. The size of the structure is returned in the variable pointed to by pdwWaveFormatExSize. The application can then allocate sufficient memory and call GetFormat again to retrieve the format description.
If pWaveFormatEx is not NULL, DirectMusic writes, at most, pdwWaveFormatExSize bytes to the structure.
Returns:
S_OK |
Succeeds |
Throws:
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
DM_FAILED | Error, see DirectMidi causes |
Function:
AllocateMemory
Declaration:
HRESULT COutputPort::AllocateMemory(CSampleInstrument &pSampleInstrument)
Purpose: Prepares the port for a wave-table memory access,
obtains the download interfaces and allocates the wave and instrument data
Parameters:
pSampleInstrument [in]: A reference to a CSampleInstrument object
Returns:
S_OK |
Succeeds |
Throws:
E_FAIL | The method did not succeed |
DMUS_E_NOT_DOWNLOADED_TO_PORT | The object cannot be unloaded because it is not present on the port |
DMUS_E_INVALID_DOWNLOADID | An invalid download identifier was used in the process of creating a download buffer |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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 |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
DM_FAILED | Error, see DirectMidi causes |
Function:
DownloadInstrument (CInstrument)
Declaration: HRESULT COutputPort::DownloadInstrument(CInstrument
&pInstrument)
Purpose: Downloads a given instrument
to the port wave-table memory
Parameters:
Returns:
S_OK |
Succeeds |
DM_FAILED | Error, see DirectMidi causes |
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 |
E_OUTOFMEMORY | Insufficient memory to complete the task |
Function:
DownloadInstrument (CSampleInstrument)
Declaration: HRESULT COutputPort::DownloadInstrument(CSampleInstrument &pSampleInstrument)
Purpose: Downloads a given
sample instrument
to the port wave-table memory
Parameters:
Returns:
S_OK |
Succeeds |
Throws:
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
DM_FAILED | Error, see DirectMidi causes |
E_FAIL | The method did not succeed |
DMUS_E_ALREADY_DOWNLOADED | The buffer has already been downloaded |
DMUS_E_BADARTICULATION | Invalid
articulation chunk in |
DMUS_E_BADINSTRUMENT | Invalid
instrument chunk in |
DMUS_E_BADOFFSETTABLE | The offset table has errors |
DMUS_E_BADWAVE | Corrupt wave header |
DMUS_E_BADWAVELINK | The
wave-link chunk in |
DMUS_E_BUFFERNOTSET | No buffer was prepared for the data |
DMUS_E_NOARTICULATION | Articulation
missing from an instrument in the |
DMUS_E_NOTMONO | The
wave chunk has more than one interleaved channel. |
DMUS_E_NOTPCM | Waveform data is not in PCM format |
DMUS_E_UNKNOWNDOWNLOAD | The synthesizer does not support this type of download |
Function:
UnloadInstrument (CInstrument)
Declaration: HRESULT COutputPort::UnloadInstrument(CInstrument
&pInstrument)
Purpose: Unloads an instrument to the
port wave-table memory and frees its space from the
synthesizer
Parameters:
pInstrument [in]: Reference to a CInstrument object
Returns:
S_OK |
Succeeds |
DM_FAILED | Error, see DirectMidi causes |
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 |
Function:
UnloadInstrument (CSampleInstrument)
Declaration: HRESULT COutputPort::UnloadInstrument(CSampleInstrument &pSampleInstrument)
Purpose: Unloads
a sample instrument to the
port wave-table memory and frees its space from the
synthesizer
Parameters:
pSampleInstrument [in]: Reference to a CSampleInstrument object
Returns:
S_OK |
Succeeds |
Throws:
E_NOINTERFACE | No object interface is available |
DMUS_E_SYNTHNOTCONFIGURED | The synthesizer is not properly configured or opened |
DM_FAILED | Error, see DirectMidi causes |
Function:
DeallocateMemory
Declaration: HRESULT COutputPort::DeallocateMemory(CSampleInstrument &pSampleInstrument)
Purpose:
Deallocates the wave-table memory space and releases the download
interfaces
Parameters:
pSampleInstrument [in]: Reference to a CSampleInstrument object
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
Function:
CompactMemory
Declaration: HRESULT COutputPort::CompactMemory()
Purpose:
This method instructs the port to compact
Parameters: void
Returns:
S_OK |
Succeeds |
Throws:
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
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_FAIL | The method did not succeed |
DM_FAILED | Error, see DirectMidi causes |
Function: SendMidiMsg (Long
version)
Declaration: HRESULT
COutputPort::SendMidiMsg(LPBYTE lpMsg,DWORD dwLength,DWORD dwChannel,DWORD
dwChannelGroup)
Purpose: Sends any kind of data to
the port (typically a MIDI system exclusive message)
Parameters:
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
S_FALSE | Error |
E_POINTER | NULL pointer argument |
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_FAIL | The call to IReferenceClock::GetTime method did not succeed |
Function:
SendMidiMsg (Short version)
Declaration: HRESULT
COutputPort::SendMidiMsg(DWORD dwMsg,DWORD
dwChannelGroup)
Purpose: Sends a typical MIDI 1.0
message to the port
Parameters:
dwMsg [in]: Variable containing the message
dwChannellGroup [in]: Channel group. Each channel group is a set of 16 MIDI channels
Returns:
S_OK |
Succeeds |
Throws:
DM_FAILED | Error, see DirectMidi causes |
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
S_FALSE | Error |
E_POINTER | NULL pointer argument |
DMUS_E_INVALID_EVENT | The event either is not a valid MIDI message or makes use of running status and cannot be packed into the buffer |
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_FAIL | The call to IReferenceClock::GetTime method did not succeed |
Function:
SetEffect
Declaration: HRESULT
COutputPort::SetEffect(BYTE
Effect)
Purpose: Activates an audio effect in the
port
Parameters:
Returns:
DMUS_E_UNKNOWN_PROPERTY | The property set or item is not implemented by this port |
S_OK |
Succeeds |
Throws:
E_FAIL | The method did not succeed |
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_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
E_POINTER | An invalid pointer, usually NULL, was passed as a parameter |
E_OUTOFMEMORY | Insufficient memory to complete the task |
E_NOINTERFACE | No object interface is available |
DM_FAILED | Error, see DirectMidi causes |
Function:
EncodeMidiMsg
Declaration: DWORD
COutputPort::EncodeMidiMsg(BYTE Status,BYTE DataByte1,BYTE
DataByte2)
Purpose: Packs a separate midi message
in a DWORD midi 1.0 message
Parameters:
See DirectMidi Midi 1.0 messages
Returns: The encoded midi
1.0 message
Top
Index
Function:
EncodeMidiMsg
Declaration: DWORD
COutputPort::EncodeMidiMsg(BYTE Command,BYTE Channel,BYTE DataByte1,BYTE
DataByte2)
Purpose: Packs a separate midi message
in a DWORD midi 1.0 message
Parameters:
Command [in]: Command byte
Status [in]: Byte of status
DataByte1 [in]: First byte of data
DataByte2 [in]: Second byte of
data
See
DirectMidi Midi 1.0 messages