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 is always 1.

dwSourceChannel

Source channel.

dwDestinationChannelGroup

Channel group on the destination port.

dwDestinationChannel

Destination channel.

pDestinationPort

Address of the IDirectMusicPort 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 following error values:

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 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;
}

Requirements

  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.