Step 9: Set 3-D Parameters

In this step you learn how to obtain the DirectSound3DBuffer8 object from the audiopath and use it to locate the sound in space. Although the sample application only pans the sound from right to left, the same technique can be used to move the sound in three dimensions.

In Step 3: Create the Audiopath, when the performance was initialized, the application requested a default audiopath of type DMUS_APATH_DYNAMIC_3D. This standard audiopath sends its data through a 3-D buffer. When the user moves the pan slider, the application responds first by obtaining an object for this buffer.

Private Sub scrlPan_Change()
  If dmSeg Is Nothing Then Exit Sub
 
  Dim dsBuf As DirectSound3DBuffer8
 
  Set dsBuf = dmPath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
    DMUS_PATH_BUFFER, 0, vbNullString, 0, _
    "IID_IDirectSound3DBuffer")

The parameters to DirectMusicAudioPath8.GetObjectInPath can be a little tricky to set up properly. For information on which parameters are relevant for objects at different stages in the path, see Retrieving Objects from an Audiopath.

In this case, you are retrieving a secondary buffer that is used by all performance channels on this audiopath. Set the lPChannel parameter to DMUS_PCHANNEL_ALL.

Because the buffer you want is the first of the two in the chain, you pass 0 as lBuffer. The DMUS_PATH_BUFFER stage contains only buffer objects, and not the DMOs attached to those buffers; therefore lIndex is ignored.

Now the application can use the buffer object to set the position of the sound source, as follows:

  dsBuf.SetPosition scrlPan.Value / 5, 0, 0, DS3D_IMMEDIATE
  Set dsBuf = Nothing
 
End Sub

The first three parameters specify the new position of the sound source in relation to the default listener. The default listener is at coordinates (0.0, 0.0, 0.0), facing toward the positive z-axis, with the top of the head toward the positive y-axis. Distance units are meters by default. For more information, see Coordinates of 3-D Space and Listener Orientation.

The last parameter of the DirectSound3DBuffer8.SetPosition method specifies whether the change is to be made immediately or deferred until all changes are committed. For more information, see Deferred Settings.