IDirectSound8 Interface

' ***************************************************************************************
' IDirectSound8 Interface
' The IDirectSound8 interface is used to create buffer objects, manage devices, and set up
' the environment. This interface supersedes IDirectSound and adds new methods.
' Obtain this interface by using the DirectSoundCreate8 or DirectSoundFullDuplexCreate8
' function, or by using CoCreateInstance or CoCreateInstanceEx to create an object of
' class CLSID_DirectSound8.
' Remarks
' Only objects of class CLSID_DirectSound8 support this interface. All device objects
' created by DirectSoundCreate8 and DirectSoundFullDuplexCreate8 fall into this category.
' Objects of class CLSID_DirectSound, which include all those created by using the earlier
' DirectSoundCreate function, support only the earlier IDirectSound interface.
' The behavior of CLSID_DirectSound8 objects is somewhat different from that of
' CLSID_DirectSound objects. These differences are found in the IDirectSound interface as
' well as the IDirectSound8 interface. Specific differences in the behavior of the newer
' object include the following:
'    * In calls to IDirectSound::CreateSoundBuffer and IDirectSound8::CreateSoundBuffer,
'      DSBCAPS_CTRL3D cannot be set on a buffer with a non-mono format, and DSBCAPS_CTRL3D cannot
'      be combined with DSBCAPS_CTRLPAN.
'    * New buffer creation flags are supported.
'    * Buffers are not filled with silence on creation.
'    * The IDirectSoundBuffer interface returned by CreateSoundBuffer can be queried for
'      the IDirectSoundBuffer8 interface.
'    * WAV formats in the DSBUFFERDESC structure that have the WAVE_FORMAT_EXTENSIBLE
'      format tag are checked more strictly for validity.
' ***************************************************************************************

' ***************************************************************************************
'DECLARE_INTERFACE_(IDirectSound, IUnknown)
'{
'    // IUnknown methods
'  0.  STDMETHOD(QueryInterface)       (THIS_ REFIID, LPVOID *) PURE;
'  1.  STDMETHOD_(ULONG,AddRef)        (THIS) PURE;
'  2.  STDMETHOD_(ULONG,Release)       (THIS) PURE;

'    // IDirectSound methods
'  3.  STDMETHOD(CreateSoundBuffer)    (THIS_ LPCDSBUFFERDESC pcDSBufferDesc, LPDIRECTSOUNDBUFFER *ppDSBuffer, LPUNKNOWN pUnkOuter) PURE;
'  4.  STDMETHOD(GetCaps)              (THIS_ LPDSCAPS pDSCaps) PURE;
'  5.  STDMETHOD(DuplicateSoundBuffer) (THIS_ LPDIRECTSOUNDBUFFER pDSBufferOriginal, LPDIRECTSOUNDBUFFER *ppDSBufferDuplicate) PURE;
'  6.  STDMETHOD(SetCooperativeLevel)  (THIS_ HWND hwnd, DWORD dwLevel) PURE;
'  7.  STDMETHOD(Compact)              (THIS) PURE;
'  8.  STDMETHOD(GetSpeakerConfig)     (THIS_ LPDWORD pdwSpeakerConfig) PURE;
'  9.  STDMETHOD(SetSpeakerConfig)     (THIS_ DWORD dwSpeakerConfig) PURE;
' 10.  STDMETHOD(Initialize)           (THIS_ LPCGUID pcGuidDevice) PURE;
'};
' ***************************************************************************************

' ***************************************************************************************
'DECLARE_INTERFACE_(IDirectSound8, IDirectSound)
'{
'    // IUnknown methods
'  0.  STDMETHOD(QueryInterface)       (THIS_ REFIID, LPVOID *) PURE;
'  1.  STDMETHOD_(ULONG,AddRef)        (THIS) PURE;
'  2.  STDMETHOD_(ULONG,Release)       (THIS) PURE;

'    // IDirectSound methods
'  3.  STDMETHOD(CreateSoundBuffer)    (THIS_ LPCDSBUFFERDESC pcDSBufferDesc, LPDIRECTSOUNDBUFFER *ppDSBuffer, LPUNKNOWN pUnkOuter) PURE;
'  4.  STDMETHOD(GetCaps)              (THIS_ LPDSCAPS pDSCaps) PURE;
'  5.  STDMETHOD(DuplicateSoundBuffer) (THIS_ LPDIRECTSOUNDBUFFER pDSBufferOriginal, LPDIRECTSOUNDBUFFER *ppDSBufferDuplicate) PURE;
'  6.  STDMETHOD(SetCooperativeLevel)  (THIS_ HWND hwnd, DWORD dwLevel) PURE;
'  7.  STDMETHOD(Compact)              (THIS) PURE;
'  8.  STDMETHOD(GetSpeakerConfig)     (THIS_ LPDWORD pdwSpeakerConfig) PURE;
'  9.  STDMETHOD(SetSpeakerConfig)     (THIS_ DWORD dwSpeakerConfig) PURE;
' 10.  STDMETHOD(Initialize)           (THIS_ LPCGUID pcGuidDevice) PURE;

'    // IDirectSound8 methods
' 11.  STDMETHOD(VerifyCertification)  (THIS_ LPDWORD pdwCertified) PURE;
'};
' ***************************************************************************************

' ***************************************************************************************
' CreateSoundBuffer
' The CreateSoundBuffer method creates a sound buffer object to manage audio samples.
' Note: ppDSBuffer receives the IDirectSoundBuffer interface of the new buffer object.
' Use QueryInterface to obtain IDirectSoundBuffer8.
' IDirectSoundBuffer8 is not available for the primary buffer.
' HRESULT CreateSoundBuffer(
'   LPCDSBUFFERDESC pcDSBufferDesc,
'   LPDIRECTSOUNDBUFFER * ppDSBuffer,
'   LPUNKNOWN pUnkOuter
' );
' ***************************************************************************************
FUNCTION IDirectSound_CreateSoundBuffer ALIAS "IDirectSound_CreateSoundBuffer" ( _
    BYVAL pthis AS DWORD PTR, BYREF pcDSBufferDesc AS DSBUFFERDESC, _
    BYREF ppDSBuffer AS DWORD, BYVAL pUnkOuter AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS DWORD
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[3] USING IDirectSound_CreateSoundBuffer(pthis, pcDSBufferDesc, ppDSBuffer, pUnkOuter) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' GetCaps
' The GetCaps method retrieves the capabilities of the hardware device that is represented
' by the device object.
' HRESULT GetCaps(
'   LPDSCAPS pDSCaps
' );
' ***************************************************************************************
FUNCTION IDirectSound_GetCaps ALIAS "IDirectSound_GetCaps" ( _
    BYVAL pthis AS DWORD PTR, BYREF pDSCaps AS DSCAPS) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[4] USING IDirectSound_GetCaps(pthis, pDSCaps) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' DuplicateSoundBuffer
' The DuplicateSoundBuffer method creates a new secondary buffer that shares the original
' buffer's memory.
' HRESULT DuplicateSoundBuffer(
'   LPDIRECTSOUNDBUFFER pDSBufferOriginal,
'   LPDIRECTSOUNDBUFFER * ppDSBufferDuplicate
' );
' ***************************************************************************************
FUNCTION IDirectSound_DuplicateSoundBuffer ALIAS "IDirectSound_DuplicateSoundBuffer" ( _
    BYVAL pthis AS DWORD PTR, BYVAL pDSBufferOriginal AS DWORD, _
    BYREF ppDSBufferDuplicate AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[5] USING IDirectSound_DuplicateSoundBuffer(pthis, pDSBufferOriginal, ppDSBufferDuplicate) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' SetCooperativeLevel
' The SetCooperativeLevel method sets the cooperative level of the application for this
' sound device.
' HRESULT SetCooperativeLevel(
'   HWND hwnd,
'   DWORD dwLevel
' );
' ***************************************************************************************
FUNCTION IDirectSound_SetCooperativeLevel ALIAS "IDirectSound_SetCooperativeLevel" ( _
    BYVAL pthis AS DWORD PTR, BYVAL hWnd AS DWORD, BYVAL dwLevel AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[6] USING IDirectSound_SetCooperativeLevel(pthis, hWnd, dwLevel) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' Compact
' The Compact method moves the unused portions of on-board sound memory, if any, to a
' contiguous block so that the largest portion of free memory will be available.
' Note: The Compact method has no effect. This method was formerly used for compacting the
' on-board memory of ISA sound cards.
' HRESULT Compact();
' ***************************************************************************************
FUNCTION IDirectSound_Compact ALIAS "IDirectSound_Compact" (BYVAL pthis AS DWORD PTR) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[7] USING IDirectSound_Compact(pthis) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' GetSpeakerConfig
' The GetSpeakerConfig method retrieves the speaker configuration.
' HRESULT GetSpeakerConfig(
'   LPDWORD pdwSpeakerConfig
' );
' The value returned at pdwSpeakerConfig can be a packed DWORD containing both
' configuration and geometry information. Use the DSSPEAKER_CONFIG and DSSPEAKER_GEOMETRY
' macros to unpack the DWORD, as in the following example:
' if (DSSPEAKER_CONFIG(dwSpeakerConfig) == DSSPEAKER_STEREO)
'   {
'   if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) ==
'         DSSPEAKER_GEOMETRY_WIDE)
'     {
'       // Configuration is wide stereo.
'  ...}
'   }
' ***************************************************************************************
FUNCTION IDirectSound_GetSpeakerConfig ALIAS "IDirectSound_GetSpeakerConfig" ( _
    BYVAL pthis AS DWORD PTR, BYREF pdwSpeakerConfig AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[8] USING IDirectSound_GetSpeakerConfig(pthis, pdwSpeakerConfig) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' SetSpeakerConfig
' The SetSpeakerConfig method specifies the speaker configuration of the device.
' HRESULT SetSpeakerConfig(
'   DWORD dwSpeakerConfig
' );
' Note   This function controls a global Windows setting that affect all users and
' applications on the system. It is provided only for use by configuration utilities
' provided by audio device vendors.  No other applications should call it.
' If a geometry value is to be used, it must be packed in a DWORD along with the
' DSSPEAKER_STEREO flag. This can be done by using the DSSPEAKER_COMBINED macro, as in the
' following C++ example:
' lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(
'     DSSPEAKER_STEREO, DSSPEAKER_GEOMETRY_WIDE));
' ***************************************************************************************
FUNCTION IDirectSound_SetSpeakerConfig ALIAS "IDirectSound_SetSpeakerConfig" ( _
    BYVAL pthis AS DWORD PTR, BYVAL dwSpeakerConfig AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[9] USING IDirectSound_SetSpeakerConfig(pthis, dwSpeakerConfig) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' Initialize
' The Initialize method initializes a device object that was created by using the
' CoCreateInstance function.
' pcGuidDevice is the address of the globally unique identifier (GUID) specifying the
' sound driver to which this device object binds. Pass NULL to select the primary sound
' driver.
' HRESULT Initialize(
'   LPCGUID pcGuidDevice
' );
' ***************************************************************************************
FUNCTION IDirectSound_Initialize ALIAS "IDirectSound_Initialize" ( _
    BYVAL pthis AS DWORD PTR, BYREF pcGuidDevice AS GUID) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[10] USING IDirectSound_Initialize(pthis, pcGuidDevice) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************

' ***************************************************************************************
' VerifyCertification
' The VerifyCertification method ascertains whether the device driver is certified for
' DirectX.
' VerifyCertification(
'   LPDWORD pdwCertified
' );
' ***************************************************************************************
FUNCTION IDirectSound8_VerifyCertification ALIAS "IDirectSound8_VerifyCertification" ( _
    BYVAL pthis AS DWORD PTR, BYREF pdwCertified AS DWORD) EXPORT AS LONG

    LOCAL HRESULT AS LONG
    IF pthis = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION
    CALL DWORD @@pthis[11] USING IDirectSound8_VerifyCertification(pthis, pdwCertified) TO HRESULT
    FUNCTION = HRESULT

END FUNCTION
' ***************************************************************************************