IDirectMusicThru::ThruChannel

The IDirectMusicThru::ThruChannel method establishes or breaks a thruing connection between a channel on a capture port and a channel on another port.

HRESULT ThruChannel(
  DWORD dwSourceChannelGroup, 
  DWORD dwSourceChannel, 
  DWORD dwDestinationChannelGroup,
  DWORD dwDestinationChannel,
  LPDIRECTMUSICPORT pDestinationPort
);
 

Parameters

dwSourceChannelGroup

Channel group on the capture port. In the current version of DirectMusic, this value will always be 1.

dwSourceChannel

Source channel.

dwDestinationChannelGroup

Channel group on the destination port.

dwDestinationChannel

Destination channel.

pDestinationPort

IDirectMusicPort for the destination channel. Set this value to NULL in order to break an existing thruing connection.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method may return one of the following error values:

Remarks

Thruing to the Microsoft Software Synthesizer 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 a time, each event is delayed by a small, essentially random amount of time before it actually 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 the 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 example function obtains the IDirectMusicThru 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(
    IDirectMusicPort *pCapturePort,
    IDirectMusicPort *pRenderPort)
{
    HRESULT hr;
    IDirectMusicThru *pThru;
 
    hr = pCapturePort->QueryInterface(IID_IDirectMusicThru,
            (void**)&pThru);
    if (FAILED(hr)) 
        return hr;
 
    for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
    {
        hr = pThru->ThruChannel(1, dwChannel,
            1, dwChannel, pRenderPort);
        if (FAILED(hr))
            break;    
    }
 
    pThru->Release();
    return hr;
}
 

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusicc.h.