#ifndef TDx_SoundH
#define TDx_SoundH

// ==========================================================================
// File:         TDx_Sound.H
// Authors:      BCB_Code_Generator v1.70,
//               Darren Dwyer (source code, documentation, demos, website),
//               Hugh Edwards (documentation, icons),
//               
// Description:  This file defines the TDx_Sound Component 
//
// "TDx_Sound_Library v1.70"
// (c) 2003 BCB-Tools.com Pty. Ltd., Sydney, Australia.
// All Rights Reserved.
//
// Refer to the 'Licence.Txt' file for licencing & copyright information.
// ==========================================================================

// --------------------------------------------------------------------------
#include "TDx_Library_Defns.H"
#include "TDx_Library_Functions.H"
// --------------------------------------------------------------------------
#include "TDx_Sound_Library_Defns.H"
#include "TDx_Sound_Library_Functions.H"
// --------------------------------------------------------------------------
// external classes used by TDx_Sound methods.
class TDSBufferDesc;
class TDx_SoundBuffer;
class TDSCaps;

// --------------------------------------------------------------------------
// --------------------------------------------------------------------------
// Definition for the OnDSEnumerate callback event.
typedef	__fastcall void	(__closure*     TDx_DSEnumerateCallback) 
                        ( TObject*      Sender, 
                          GUID*         Guid, 
                          AnsiString    DriverDescription, 
                          AnsiString    DriverModule, 
                          void*         Context, 
                          bool&         Finished ); 

// ==========================================================================
// Class:       TDx_Sound
// Description: The TDx_Sound Component wraps the DirectX IDirectSound 
//              interface which is used to set environmental controls and 
//              create TDx_SoundBuffer components. 
//              
//              It is used to determine the capablilities of the sound 
//              hardware, create and duplicate sound buffers, set the 
//              cooperative level, optimize hardware memory and retrieve or 
//              define the type and positioning of the speakers associated 
//              with the sound hardware. 
// ==========================================================================
#if (__BORLANDC__ >= 0x0530) // BCB Version 3 +
class PACKAGE TDx_Sound : public TComponent
{
// --------------------------------------------------------------------------
#else // BCB Version 1
class TDx_Sound : public TComponent
{
#endif
// ==========================================================================
__published:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Event:       OnCreate()
    // Description: The OnCreate() event is triggered by the 
    //              TDx_Sound::Create() method after it has successfully 
    //              created the internal LPDIRECTSOUND used within the 
    //              TDx_Sound component. 
    //              
    //              Note that since this event is only called upon successful 
    //              creation, this event is an ideal place for code that is 
    //              to be activated only once, immediately upon the 
    //              successful creation of the LPDIRECTSOUND interface. 
    //              
    //              For example, you could retrieve the TDx_Sound component's 
    //              capabilities, Create() dependant components, allocate 
    //              memory, etc. 
    //              
    //              When used in conjunction with the TDx_Sound::OnDestroy() 
    //              event, you can fully automate and insulate your code on a 
    //              per-component basis. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnCreate = {read=FOnCreate, write=FOnCreate, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnDestroy()
    // Description: The OnDestroy() event is triggered by the 
    //              TDx_Sound::Destroy() method, just before the TDx_Sound 
    //              internal LPDIRECTSOUND interface is destroyed. 
    //              
    //              Note: This event is an ideal place to place code that 
    //              reverses the results of the TDx_Sound::OnCreate() event. 
    //              For example, assume you have already setup the 
    //              TDx_Sound::OnCreate() event to retrieve the component's 
    //              capabilities, Create() a dependant component and allocate 
    //              some memory; 
    //              You can then fully automate and insulate your code on a 
    //              per-component basis by placing code in the 
    //              TDx_Sound::OnDestroy() event to deallocate memory, 
    //              Destroy() the dependant components and, when required, 
    //              destroy the capabilities component. 
    // ----------------------------------------------------------------------
    __property TDx_Event OnDestroy = {read=FOnDestroy, write=FOnDestroy, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Event:       OnError()
    // Description: The OnError event is called when an error occurs in the 
    //              TDx_Sound component. 
    // ----------------------------------------------------------------------
    __property TDx_Error OnError = {read=FOnError, write=FOnError, 
    nodefault}; 

    // ----------------------------------------------------------------------
    // Callback:    OnDSEnumerate()
    // Description: The OnDSEnumerate event is used to process information 
    //              returned by the TDx_Sound::DSEnumerate method. 
    //              Set the Finished parameter to true to halt the 
    //              enumeration process. 
    // ----------------------------------------------------------------------
    __property TDx_DSEnumerateCallback OnDSEnumerate = {read=FOnDSEnumerate, 
    write=FOnDSEnumerate, nodefault}; 

// ==========================================================================
public:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Property:    Created
    // Description: The Created property is true if the internal 
    //              LPDIRECTSOUND used in this component has been 
    //              successfully created, otherwise Created is false. 
    //              
    //              To create the internal LPDIRECTSOUND, call the 
    //              TDx_Sound::Create() method. 
    // ----------------------------------------------------------------------
    __property bool Created = {read=FGetCreated,write=FSetCreated, 
    default=false }; 

    // ----------------------------------------------------------------------
    // Property:    ErrorValue
    // Description: The ErrorValue property contains the last error value 
    //              returned from a call to a TDx_Sound method or fget/fset. 
    //              eg. DS_OK or DDERR_SURFACELOST or TDX_ERROR 
    // ----------------------------------------------------------------------
    __property HRESULT ErrorValue = { read=FGetErrorValue, 
    write=FSetErrorValue, default=DS_OK }; 

    // ----------------------------------------------------------------------
    // Property:    SpeakerConfig
    // Description: The SpeakerConfig property can be used as an alternative 
    //              to calling the TDx_Sound::GetSpeakerConfig() and 
    //              TDx_Sound::SetSpeakerConfig() methods. 
    //              Retrieving this property calls the GetSpeakerConfig() 
    //              method and returns the result. 
    //              Setting this property calls the SetSpeakerConfig() method 
    //              and passes the supplied property value as the method 
    //              parameter. 
    // ----------------------------------------------------------------------
    __property dword SpeakerConfig = { read=FGetSpeakerConfig, 
    write=FSetSpeakerConfig, nodefault }; 

    // ----------------------------------------------------------------------
    // Method:      Compact()
    // Description: The TDx_Sound::Compact method will shuffle the allocated 
    //              sound card memory so as to make the largest amount of 
    //              free memory available. 
    //              
    //              This method will fail unless the DSSCL_PRIORITY 
    //              cooperative level or better is held and no operations are 
    //              currently in progress. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              DSERR_INVALIDPARAM 
    //              DSERR_PRIOLEVELNEEDED 
    //              DSERR_UNINITIALIZED 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Compact(); 

    // ----------------------------------------------------------------------
    // Method:      Create()
    // Description: The Create() method is used to automatically create the 
    //              internal LPDIRECTSOUND interface used in the TDx_Sound 
    //              component and must be called before any methods of the 
    //              TDx_Sound component will function. 
    // Params:      pGUID - 
    //                The GUID parameter identifies the sound device to use 
    //                when creating the sound interface. Set this parameter to 
    //                NULL to use the Windows primary sound device. 
    //                
    //                The TDx_Sound::DSEnumerate method can be used to obtain 
    //                the GUID's of the available sound devices. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Create( GUID* pGUID ); 

    // ----------------------------------------------------------------------
    // Method:      CreateSoundBuffer()
    // Description: The TDx_Sound::CreateSoundBuffer method will create a 
    //              TDx_SoundBuffer for holding audio sample sequences. 
    //              
    //              All required capabilities must be requested by setting 
    //              the appropriate flag in TDSBufferDesc::Flags or they will 
    //              not be available. 
    //              
    //              The TDx_Sound component must set a cooperative level 
    //              before buffers can be played. 
    //              You can use TDx_SoundBuffer::Create() to achieve the same 
    //              result as this method with the added advantage of being 
    //              able to use the TDx_SoundBuffer::OnCreate() event. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              TDX_BADPARAMS 
    //              DSERR_ALLOCATED 
    //              DSERR_BADFORMAT 
    //              DSERR_CONTROLUNAVAIL 
    //              DSERR_INVALIDPARAM 
    //              DSERR_NOAGGREGATION 
    //              DSERR_OUTOFMEMORY 
    //              DSERR_UNINITIALIZED 
    //              DSERR_UNSUPPORTED 
    // Params:      pBufferDesc - 
    //                The BufferDesc parameter references a TDSBufferDesc 
    //                component defining the capabilities of the buffer being 
    //                created. 
    //              pSoundBuffer - 
    //                The SoundBuffer parameter will reference the newly 
    //                created buffer if this method returns successfully. 
    //                If this method fails this parameter will be set to NULL. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall CreateSoundBuffer( TDSBufferDesc* pBufferDesc, 
    TDx_SoundBuffer* pSoundBuffer ); 

    // ----------------------------------------------------------------------
    // Method:      DSEnumerate()
    // Description: The TDx_Sound::DSEnumerate method will scan all the sound 
    //              devices installed on the system and call the 
    //              TDx_Sound::OnDSEnumCallback() event for each device. 
    //              
    //              There is no need to write a manual callback function, 
    //              just place your code in the TDx_Sound::OnDSEnumCallback() 
    //              event. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              DSERR_INVALIDPARAM 
    // Params:      pContext - 
    //                The Context parameter references an application defined 
    //                object that is passed to the callback event for each 
    //                device enumerated. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall DSEnumerate( LPVOID pContext ); 

    // ----------------------------------------------------------------------
    // Method:      Destroy()
    // Description: The Destroy() method is used to automatically destroy the 
    //              internal LPDIRECTSOUND interface used in the TDx_Sound 
    //              component and should be called when the internal 
    //              interface is no longer required. 
    //              
    //              Note: This method is called by the component's 
    //              destructor. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall Destroy(); 

    // ----------------------------------------------------------------------
    // Method:      DuplicateSoundBuffer()
    // Description: The TDx_Sound::DuplicateSoundBuffer method will create a 
    //              new buffer which references the same memory as the 
    //              original. 
    //              
    //              The duplicate will initially have the same properties as 
    //              the original but they can be changed independently. 
    //              
    //              Each buffer can be played or stopped without affecting 
    //              the other but if the data in the buffer is changed by 
    //              either component it will affect both buffers. 
    //              
    //              Buffer memory will be released when the last component 
    //              referencing it is released. 
    //              This method cannot duplicate a hardware buffer in system 
    //              memory. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              TDX_BADPARAMS 
    //              DSERR_ALLOCATED 
    //              DSERR_INVALIDCALL 
    //              DSERR_INVALIDPARAM 
    //              DSERR_OUTOFMEMORY 
    //              DSERR_UNINITIALIZED 
    // Params:      pOriginal - 
    //                The Original parameter references the buffer to be 
    //                duplicated. 
    //              pDuplicate - 
    //                The Duplicate parameter will reference the newly created 
    //                duplicate buffer if this method returns successfully. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall DuplicateSoundBuffer( TDx_SoundBuffer* pOriginal, 
    TDx_SoundBuffer* pDuplicate ); 

    // ----------------------------------------------------------------------
    // Method:      GetCaps()
    // Description: The TDx_Sound::GetCaps method will retrieve the hardware 
    //              capabilities of the sound device. 
    //              
    //              This method retrieves the maximum and current capacity in 
    //              each field. 
    //              The use of resources within some fields may influence the 
    //              capacity of others due to resource trade offs. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              TDX_BADPARAMS 
    //              DSERR_GENERIC 
    //              DSERR_INVALIDPARAM 
    //              DSERR_UNINITIALIZED 
    // Params:      pCaps - 
    //                The Caps parameter references a TDSCaps component for 
    //                holding the retrieved hardware capabilities if this 
    //                method returns successfully. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetCaps( TDSCaps* pCaps ); 

    // ----------------------------------------------------------------------
    // Method:      GetSpeakerConfig()
    // Description: The TDx_Sound::GetSpeakerConfig method will return the 
    //              current speaker configuration settings.   
    //              
    //              As the result may be a  packed DWORD when 
    //              DSSPEAKER_STEREO is returned, use the following 
    //              predefined macros to extract the correct configuration 
    //              and geometry. 
    //              
    //              DSSPEAKER_CONFIG(SpeakerConfig) 
    //              DSSPEAKER_GEOMETRY(SpeakerConfig) 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              TDX_BADPARAMS 
    //              DSERR_INVALIDPARAM 
    //              DSERR_UNINITIALIZED 
    // Params:      pSpeakerConfig - 
    //                The SpeakerConfig parameter will reference flags defining 
    //                the current speaker configuration settings if this method 
    //                returns successfully. 
    //                The described effect applies when the flag is set. 
    //                Flags:
    //                  DSSPEAKER_5POINT1 -
    //                    Surround sound speakers are being used with a 
    //                    subwoofer. 
    //                  DSSPEAKER_GEOMETRY_MAX -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 180 degrees. 
    //                  DSSPEAKER_GEOMETRY_MIN -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 5 degrees. 
    //                  DSSPEAKER_GEOMETRY_NARROW -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 10 degrees. 
    //                  DSSPEAKER_GEOMETRY_WIDE -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 20 degrees. 
    //                  DSSPEAKER_HEADPHONE -
    //                    Headphones are being used. 
    //                  DSSPEAKER_MONO -
    //                    A single speaker is being used. 
    //                  DSSPEAKER_QUAD -
    //                    Quadraphonic speakers are being used. 
    //                  DSSPEAKER_STEREO -
    //                    Stereo speakers are being used. 
    //                    This is the default value. 
    //                  DSSPEAKER_SURROUND -
    //                    Surround sound speakers are being used. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall GetSpeakerConfig( dword* pSpeakerConfig ); 

    // ----------------------------------------------------------------------
    // Method:      SetCooperativeLevel()
    // Description: The TDx_Sound::SetCooperativeLevel method will set the 
    //              applications cooperative level for the sound device.   
    //              
    //              DSSCL_PRIORITY is the recommended cooperative level. 
    //              The cooperative level must be set by an application 
    //              before its buffers can be played. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              DSERR_ALLOCATED 
    //              DSERR_INVALIDPARAM 
    //              DSERR_UNINITIALIZED 
    //              DSERR_UNSUPPORTED 
    // Params:      pHWnd - 
    //                The HWnd parameter defines the applications window 
    //                handle. 
    //                When also using TDx_Draw, this window handle must be the 
    //                same as that used in TDx_Draw::SetCooperativeLevel(). 
    //              pLevel - 
    //                The Level parameter defines flags indicating the priority 
    //                level being requested. 
    //                The described effect applies when the flag is set. 
    //                Flags:
    //                  DSSCL_EXCLUSIVE -
    //                    The application has exclusive level access to the 
    //                    sound device. 
    //                    All DSSCL_PRIORITY level privileges apply plus when 
    //                    the application has the input focus it will be the 
    //                    only one audible. 
    //                  DSSCL_NORMAL -
    //                    The application has normal level access to the 
    //                    sound device. 
    //                    The format of the primary buffer may not be 
    //                    changed, sound output is restricted to the default 
    //                    8-bit sound format. 
    //                  DSSCL_PRIORITY -
    //                    The application has priority level access to the 
    //                    sound device. 
    //                    Priority level access allows the use of 
    //                    TDx_SoundBuffer::SetFormat() and 
    //                    TDx_SoundBuffer::Compact() methods. 
    //                  DSSCL_WRITEPRIMARY -
    //                    The application has write access to the primary 
    //                    sound buffers. 
    //                    No secondary sound buffers can be played. 
    //                    This cooperative level cannot be set if 
    //                    DSCAPS_EMULDRIVER is set in TDSCaps::Flags. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetCooperativeLevel( HWND pHWnd, dword pLevel ); 

    // ----------------------------------------------------------------------
    // Method:      SetSpeakerConfig()
    // Description: The TDx_Sound::SetSpeakerConfig method will define the 
    //              speaker configuration settings. 
    //              
    //              If the method call fails, the OnError event will be 
    //              triggered with one of the following values: 
    //              DSERR_INVALIDPARAM 
    //              DSERR_UNINITIALIZED 
    // Params:      pSpeakerConfig - 
    //                The SpeakerConfig parameter defines flags indicating the 
    //                speaker configuration to be set. 
    //                The described effect applies when the flag is set. 
    //                
    //                When defining a geometry value, the following macro must 
    //                be used to pack this parameter correctly. 
    //                DSSPEAKER_COMBINED(DSSPEAKER_STEREO, 
    //                DSSPEAKER_GEOMETRY_value) 
    //                Flags:
    //                  DSSPEAKER_5POINT1 -
    //                    Surround sound speakers are being used with a 
    //                    subwoofer. 
    //                  DSSPEAKER_GEOMETRY_MAX -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 180 degrees. 
    //                  DSSPEAKER_GEOMETRY_MIN -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 5 degrees. 
    //                  DSSPEAKER_GEOMETRY_NARROW -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 10 degrees. 
    //                  DSSPEAKER_GEOMETRY_WIDE -
    //                    The stereo speakers are placed such as to have an 
    //                    arc of 20 degrees. 
    //                  DSSPEAKER_HEADPHONE -
    //                    Headphones are being used. 
    //                  DSSPEAKER_MONO -
    //                    A single speaker is being used. 
    //                  DSSPEAKER_QUAD -
    //                    Quadraphonic speakers are being used. 
    //                  DSSPEAKER_STEREO -
    //                    Stereo speakers are being used. 
    //                    This is the default value. 
    //                  DSSPEAKER_SURROUND -
    //                    Surround sound speakers are being used. 
    // ----------------------------------------------------------------------
    virtual bool __fastcall SetSpeakerConfig( dword pSpeakerConfig ); 

    // ----------------------------------------------------------------------
    // Constructor() and Destructor()
    // ----------------------------------------------------------------------
    __fastcall TDx_Sound(TComponent* Owner); 
    virtual __fastcall ~TDx_Sound(); 

    // ----------------------------------------------------------------------
    // The following properties and methods are used internally by 
    // TDx_Sound_Library and should not be used. 
    // ----------------------------------------------------------------------
    __property LPDIRECTSOUND Internal_LPDIRECTSOUND = { 
    read=FGetInternal_LPDIRECTSOUND, write=FSetInternal_LPDIRECTSOUND, 
    nodefault }; 
    __property LPDIRECTSOUND* Internal_LPDIRECTSOUND_Ptr = { 
    read=FGetInternal_LPDIRECTSOUND_Ptr, nodefault }; 
    void __fastcall Internal_LPDIRECTSOUND_Update(); 

// ==========================================================================
protected:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Method:   Internal_DSEnumerateCallback()
    // Description: The Internal_DSEnumerateCallback method is used 
    //              internally by the TDx_Sound component as a callback 
    //              function. 
    //              
    //              It translates DirectX-style parameters to BCB-style 
    //              parameters before calling the 
    //              TDx_Sound::OnDSEnumCallback() event. 
    // Params:      pDescription - 
    //                This parameter is used internally. 
    //              pModule - 
    //                This parameter is used internally. 
    //              pContext - 
    //                This parameter is used internally. 
    // ----------------------------------------------------------------------
    static BOOL __stdcall Internal_DSEnumerateCallback( LPGUID pGuid, LPCSTR 
    pDescription, LPCSTR pModule, LPVOID pContext ); 

    // ----------------------------------------------------------------------
    // Property Access Methods
    // ----------------------------------------------------------------------
    bool __fastcall FGetCreated(); 
    void __fastcall FSetCreated( bool pCreated ); 
    HRESULT __fastcall FGetErrorValue(); 
    void __fastcall FSetErrorValue( HRESULT pErrorValue ); 
    dword __fastcall FGetSpeakerConfig(); 
    void __fastcall FSetSpeakerConfig( dword pSpeakerConfig ); 

// ==========================================================================
private:
// ==========================================================================

    // ----------------------------------------------------------------------
    // Internal Interface Access
    // ----------------------------------------------------------------------
    LPDIRECTSOUND __fastcall FGetInternal_LPDIRECTSOUND(); 
    void __fastcall FSetInternal_LPDIRECTSOUND( LPDIRECTSOUND pLPDIRECTSOUND 
    ); 
    LPDIRECTSOUND* __fastcall FGetInternal_LPDIRECTSOUND_Ptr(); 

    // ----------------------------------------------------------------------
    // Property Variables 
    // ----------------------------------------------------------------------
    bool fCreated; 
    HRESULT fErrorValue; 

    // ----------------------------------------------------------------------
    // Interface Variables 
    // ----------------------------------------------------------------------
    LPDIRECTSOUND fLPDIRECTSOUND; 

    // ----------------------------------------------------------------------
    // Event Variables
    // ----------------------------------------------------------------------
    TDx_Event FOnCreate;
    TDx_Event FOnDestroy;
    TDx_Error FOnError;

    // ----------------------------------------------------------------------
    // Callback Variables
    // ----------------------------------------------------------------------
    TDx_DSEnumerateCallback FOnDSEnumerate;

};
// --------------------------------------------------------------------------
#endif
// --------------------------------------------------------------------------