| Microsoft DirectX 9.0 SDK Update (Summer 2004) |
IDirectMusicThru8::ThruChannel
The ThruChannel method establishes or breaks a thruing connection between a channel on a capture port and a channel on another port.
Syntax
HRESULT ThruChannel(
DWORD dwSourceChannelGroup,
DWORD dwSourceChannel,
DWORD dwDestinationChannelGroup,
DWORD dwDestinationChannel,
LPDIRECTMUSICPORT pDestinationPort
);
Parameters
dwSourceChannelGroup
Channel group on the capture port. This value is always 1.
dwSourceChannel
Source channel.
dwDestinationChannelGroup
Channel group on the destination port.
dwDestinationChannel
Destination channel.
pDestinationPort
Address of the IDirectMusicPort8 interface for the destination channel. Set this value to NULL to break an existing thruing connection.
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 |
| E_NOTIMPL |
| E_INVALIDARG |
| DMUS_E_PORT_NOT_RENDER |
Remarks
System-exclusive messages are not transmitted to the destination port.
Thruing to the Microsoft software synthesizer or other synthesizers that do not have a constant latency is not recommended. Thruing is done as soon as possible upon reception of the incoming MIDI events. Because of the comparatively high latency of the software synthesizer (compared with a hardware port) and the fact that it renders blocks of audio data at the same time, each event is delayed by a small, essentially random amount of time before it plays. This random offset shows up as jitter in the playback of the data. Latency of other devices (such as an MPU-401 port) is small enough that jitter does not occur.
If an application needs to thru to the software synthesizer, it should add a small offset to the incoming note event time stamps to compensate for the rendering latency of the synthesizer.
The following code example obtains the IDirectMusicThru8 interface and establishes a thru connection between all channels on group 1 of the capture port and the equivalent channels on a destination port.
HRESULT SetupOneToOneThru(
IDirectMusicPort8 *pCapturePort,
IDirectMusicPort8 *pRenderPort)
{
HRESULT hr;
IDirectMusicThru8 *pThru;
hr = pCapturePort->QueryInterface(IID_IDirectMusicThru8,
(void**)&pThru);
if (FAILED(hr)) return hr;
for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
{
hr = pThru->ThruChannel(1, dwChannel,
1, dwChannel, (IDirectMusicPort*)pRenderPort);
if (FAILED(hr)) break;
}
pThru->Release();
return hr;
}
Requirements
Header: Declared in dmusici.h.
See Also
© 2004 Microsoft Corporation. All rights reserved.