天行健 君子當自強而不息

DirectMusic在DirectX8中得到了巨大的增強，但是DirectSound基本保持原有的狀態。DirectSound是主要的數字聲音回放組件。DirectMusic處理所有的樂曲格式，包括MIDI、DirectMusic本地格式文件和波表文件。DirectMusic處理完之后將它們送入DirectSound中做其他處理，這意味著回放MIDI的時候可以使用數字化的樂器。

使用DirectSound

使用時需要創建一個和聲卡通訊的COM對象，用這個COM對象再創造一些獨立的聲音數據緩沖區（被稱之為輔助音頻緩沖區 secondary sound buffers）來存儲音頻數據。緩沖區中的這些數據在主混音緩存（稱之為主音頻緩存 primary sound buffer）中被混合，然后可以用指定的任何格式播放出來。回放格式通過采樣頻率、聲道數、采樣精度排列，可能的采樣頻率有8000HZ， 11025HZ，22050HZ和44100HZ（CD音質）。

對于聲道數可以有兩個選擇：單通道的單聲道聲音和雙通道的立體聲聲音。采樣精度被限制在兩種選擇上：8位的低質量聲音和16位的高保真聲音。在沒有修改的情況下，DirectSound主緩沖區的默認設置是22025HZ采樣率、8位精度、立體聲。在DirectSound中可以調整聲音的播放速度（這同樣會改變聲音的音調），調整音量 、循環播放等。甚至還可以在一個虛擬的 3D環境中播放，以模擬一個實際環繞在周圍的聲音。

需要做的是將聲音數據充滿緩沖區，如果聲音數據太大的話，必須創建流播放方法，加載聲音數據中的一小塊，當這一小塊播放完畢以后，再加載另外的小塊數據進緩沖區，一直持續這個過程，直到聲音被處理完畢。在緩沖區中調整播放位置可以實現流式音頻，當播放完成通知應用程序更新音頻數據。這個通知更新的過程我們稱之為“通告”。在同一時間被播放的緩存數目雖然沒有限制，但是仍然需要保證緩沖區數目不要太多，因為每增加一個緩沖區，就要消耗很多內存和CPU資源。

在項目中使用DirectSound和DirectMusic，需要添加頭文件dsound.h和dmsuic.h，并且需要鏈接DSound.lib到包含庫中，添加DXGuid.lib庫可以讓DirectSound更容易使用。

以下是DirectSound COM接口：

IDirectSound8：DirectSound接口。
IDirectSoundBuffer8：主緩沖區和輔助緩沖區接口，保存數據并控制回放。
IDirectSoundNotify8：通知對象，通知應用程序指定播放位置已經達到。

各個對象間的關系如下圖所示：

IDirectSound8是主接口，用它來創建緩沖區（IDirectSoundBuffer8），然后用緩沖區接口創建通告接口（IDirectSoundNotify8），通告接口告訴應用程序指定的位置已經到達，通告接口在流化音頻文件時非常有用。

初始化DirectSound

使用 DirectSound的第一步是創建IDirectSound8對象，IDirectSound8起到控制音頻硬件設備的作用，可以通過 DirectSoundCreate8函數來創建。

The DirectSoundCreate8 function creates and initializes an object that supports the IDirectSound8 interface.

HRESULT DirectSoundCreate8(
 LPCGUID lpcGuidDevice,
 LPDIRECTSOUND8 * ppDS8,
 LPUNKNOWN pUnkOuter
);

The CreateSoundBuffer method creates a sound buffer object to manage audio samples.

HRESULT CreateSoundBuffer(
 LPCDSBUFFERDESC pcDSBufferDesc,
 LPDIRECTSOUNDBUFFER * ppDSBuffer,
 LPUNKNOWN pUnkOuter
);

Parameters

pcDSBufferDesc

Address of a DSBUFFERDESC structure that describes the sound buffer to create.

ppDSBuffer

Address of a variable that receives the IDirectSoundBuffer interface of the new buffer object. Use QueryInterface to obtain IDirectSoundBuffer8. IDirectSoundBuffer8 is not available for the primary buffer.

pUnkOuter

Address of the controlling object's IUnknown interface for COM aggregation. Must be NULL.

Return Values

If the method succeeds, the return value is DS_OK, or DS_NO_VIRTUALIZATION if a requested 3D algorithm was not available and stereo panning was substituted. See the description of the guid3DAlgorithm member of DSBUFFERDESC. If the method fails, the return value may be one of the error values shown in the following table.
 

Remarks

DirectSound does not initialize the contents of the buffer, and the application cannot assume that it contains silence.

If an attempt is made to create a buffer with the DSBCAPS_LOCHARDWARE flag on a system where hardware acceleration is not available, the method fails with either DSERR_CONTROLUNAVAIL or DSERR_INVALIDCALL, depending on the operating system.

The DSBUFFERDESC structure describes the characteristics of a new buffer object. It is used by the IDirectSound8::CreateSoundBuffer method and by the DirectSoundFullDuplexCreate8 function.

An earlier version of this structure, DSBUFFERDESC1, is maintained in Dsound.h for compatibility with DirectX 7 and earlier.

typedef struct DSBUFFERDESC {
 DWORD dwSize;
 DWORD dwFlags;
 DWORD dwBufferBytes;
 DWORD dwReserved;
 LPWAVEFORMATEX lpwfxFormat;
 GUID guid3DAlgorithm;
} DSBUFFERDESC;

Members

dwSize

Size of the structure, in bytes. This member must be initialized before the structure is used.

dwFlags

Flags specifying the capabilities of the buffer. See the dwFlags member of the DSBCAPS structure for a detailed listing of valid flags.

dwBufferBytes

Size of the new buffer, in bytes. This value must be 0 when creating a buffer with the DSBCAPS_PRIMARYBUFFER flag. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX, defined in Dsound.h.

dwReserved

Reserved. Must be 0.

lpwfxFormat

Address of a WAVEFORMATEX or WAVEFORMATEXTENSIBLE structure specifying the waveform format for the buffer. This value must be NULL for primary buffers.

guid3DAlgorithm

Unique identifier of the two-speaker virtualization algorithm to be used by DirectSound3D hardware emulation. If DSBCAPS_CTRL3D is not set in dwFlags, this member must be GUID_NULL (DS3DALG_DEFAULT). The following algorithm identifiers are defined.

 

Value	Description	Availability
DS3DALG_DEFAULT	DirectSound uses the default algorithm. In most cases this is DS3DALG_NO_VIRTUALIZATION. On WDM drivers, if the user has selected a surround sound speaker configuration in Control Panel, the sound is panned among the available directional speakers.	Applies to software mixing only. Available on WDM or Vxd Drivers.
DS3DALG_NO_VIRTUALIZATION	3D output is mapped onto normal left and right stereo panning. At 90 degrees to the left, the sound is coming out of only the left speaker; at 90 degrees to the right, sound is coming out of only the right speaker. The vertical axis is ignored except for scaling of volume due to distance. Doppler shift and volume scaling are still applied, but the 3D filtering is not performed on this buffer. This is the most efficient software implementation, but provides no virtual 3D audio effect. When the DS3DALG_NO_VIRTUALIZATION algorithm is specified, HRTF processing will not be done. Because DS3DALG_NO_VIRTUALIZATION uses only normal stereo panning, a buffer created with this algorithm may be accelerated by a 2D hardware voice if no free 3D hardware voices are available.	Applies to software mixing only. Available on WDM or Vxd Drivers.
DS3DALG_HRTF_FULL	The 3D API is processed with the high quality 3D audio algorithm. This algorithm gives the highest quality 3D audio effect, but uses more CPU cycles. See Remarks.	Applies to software mixing only. Available on Microsoft Windows 98 Second Edition and later operating systems when using WDM drivers.
DS3DALG_HRTF_LIGHT	The 3D API is processed with the efficient 3D audio algorithm. This algorithm gives a good 3D audio effect, but uses fewer CPU cycles than DS3DALG_HRTF_FULL.	Applies to software mixing only. Available on Windows 98 Second Edition and later operating systems when using WDM drivers.

dwFlags

Flags that specify buffer-object capabilities. Use one or more of the values shown in the following table.

 

Value	Description
DSBCAPS_CTRL3D	The buffer has 3D control capability.
DSBCAPS_CTRLFREQUENCY	The buffer has frequency control capability.
DSBCAPS_CTRLFX	The buffer supports effects processing.
DSBCAPS_CTRLPAN	The buffer has pan control capability.
DSBCAPS_CTRLVOLUME	The buffer has volume control capability.
DSBCAPS_CTRLPOSITIONNOTIFY	The buffer has position notification capability. See the Remarks for DSCBUFFERDESC.
DSBCAPS_GETCURRENTPOSITION2	The buffer uses the new behavior of the play cursor when IDirectSoundBuffer8::GetCurrentPosition is called. In the first version of DirectSound, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was directly behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play cursor. If this flag is not specified, the old behavior is preserved for compatibility. This flag affects only emulated devices; if a DirectSound driver is present, the play cursor is accurate for DirectSound in all versions of DirectX.
DSBCAPS_GLOBALFOCUS	The buffer is a global sound buffer. With this flag set, an application using DirectSound can continue to play its buffers if the user switches focus to another application, even if the new application uses DirectSound. The one exception is if you switch focus to a DirectSound application that uses the DSSCL_WRITEPRIMARY flag for its cooperative level. In this case, the global sounds from other applications will not be audible.
DSBCAPS_LOCDEFER	The buffer can be assigned to a hardware or software resource at play time, or when IDirectSoundBuffer8::AcquireResources is called.
DSBCAPS_LOCHARDWARE	The buffer uses hardware mixing.
DSBCAPS_LOCSOFTWARE	The buffer is in software memory and uses software mixing.
DSBCAPS_MUTE3DATMAXDISTANCE	The sound is reduced to silence at the maximum distance. The buffer will stop playing when the maximum distance is exceeded, so that processor time is not wasted. Applies only to software buffers.
DSBCAPS_PRIMARYBUFFER	The buffer is a primary buffer.
DSBCAPS_STATIC	The buffer is in on-board hardware memory.
DSBCAPS_STICKYFOCUS	The buffer has sticky focus. If the user switches to another application not using DirectSound, the buffer is still audible. However, if the user switches to another DirectSound application, the buffer is muted.
DSBCAPS_TRUEPLAYPOSITION	Force IDirectSoundBuffer8::GetCurrentPosition to return the buffer's true play position. This flag is only valid in Windows Vista.

The SetFormat method sets the format of the primary buffer. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

HRESULT SetFormat(
 LPCWAVEFORMATEX pcfxFormat
);

Parameters

pcfxFormat

Address of a WAVEFORMATEX structure that describes the new format for the primary sound buffer.

Return Values

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
 

Remarks

The format of the primary buffer should be set before secondary buffers are created.

The method fails if the application has the DSSCL_NORMAL cooperative level.

If the application is using DirectSound at the DSSCL_WRITEPRIMARY cooperative level, and the format is not supported, the method fails.

If the cooperative level is DSSCL_PRIORITY, DirectSound stops the primary buffer, changes the format, and restarts the buffer. The method succeeds even if the hardware does not support the requested format; DirectSound sets the buffer to the closest supported format. To determine whether this has happened, an application can call the GetFormat method for the primary buffer and compare the result with the format that was requested with the SetFormat method.

This method is not available for secondary sound buffers. If a new format is required, the application must create a new DirectSoundBuffer object.

The WAVEFORMATEX structure defines the format of waveform-audio data. Only format information common to all waveform-audio data formats is included in this structure. For formats that require additional information, this structure is included as the first member in another structure, along with the additional information.

This structure is part of the Platform SDK and is not declared in Dsound.h. It is documented here for convenience.

typedef struct WAVEFORMATEX {
 WORD wFormatTag;
 WORD nChannels;
 DWORD nSamplesPerSec;
 DWORD nAvgBytesPerSec;
 WORD nBlockAlign;
 WORD wBitsPerSample;
 WORD cbSize;
} WAVEFORMATEX;

Members

wFormatTag

Waveform-audio format type. Format tags are registered with Microsoft Corporation for many compression algorithms. A complete list of format tags can be found in the Mmreg.h header file. For one- or two-channel PCM data, this value should be WAVE_FORMAT_PCM.

nChannels

Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.

nSamplesPerSec

Sample rate, in samples per second (hertz). If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplesPerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, this member must be computed according to the manufacturer's specification of the format tag.

nAvgBytesPerSec

Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, nAvgBytesPerSec should be equal to the product of nSamplesPerSec and nBlockAlign. For non-PCM formats, this member must be computed according to the manufacturer's specification of the format tag.

nBlockAlign

Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM or WAVE_FORMAT_EXTENSIBLE, nBlockAlign must be equal to the product of nChannels and wBitsPerSample divided by 8 (bits per byte). For non-PCM formats, this member must be computed according to the manufacturer's specification of the format tag.

Software must process a multiple of nBlockAlign bytes of data at a time. Data written to and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

wBitsPerSample

Bits per sample for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, then wBitsPerSample should be equal to 8 or 16. For non-PCM formats, this member must be set according to the manufacturer's specification of the format tag. If wFormatTag is WAVE_FORMAT_EXTENSIBLE, this value can be any integer multiple of 8. Some compression schemes cannot define a value for wBitsPerSample, so this member can be zero.

cbSize

Size, in bytes, of extra format information appended to the end of the WAVEFORMATEX structure. This information can be used by non-PCM formats to store extra attributes for the wFormatTag. If no extra information is required by the wFormatTag, this member must be set to zero. For WAVE_FORMAT_PCM formats (and only WAVE_FORMAT_PCM formats), this member is ignored.