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.

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

IDirectMusicThru8