// --------------------------------------------------------------------------

// ==========================================================================
// File:         TDx_Sound.CPP
// Authors:      BCB_Code_Generator v1.70,
//               Darren Dwyer (source code, documentation, demos, website),
//               Hugh Edwards (documentation, icons),
//               
// Description:  This file contains the code for 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.
// ==========================================================================

// --------------------------------------------------------------------------
// #includes ...
// --------------------------------------------------------------------------
#include <vcl\vcl.h>
#pragma hdrstop
// --------------------------------------------------------------------------
#include "TDx_Sound.H"
// --------------------------------------------------------------------------
// external classes used by TDx_Sound methods.
#include "TDSBufferDesc.H"
#include "TDx_SoundBuffer.H"
#include "TDSCaps.H"
// --------------------------------------------------------------------------
#pragma link "TDx_Library_Defns"
#pragma link "TDx_Library_Functions"
#pragma link "TDx_Sound_Library_Defns"
#pragma link "TDx_Sound_Library_Functions"

// --------------------------------------------------------------------------
// Object Registration...
// --------------------------------------------------------------------------
#if (__BORLANDC__ >= 0x0530) // BCB Version 3+
    #pragma package(smart_init)
#endif
// --------------------------------------------------------------------------
static inline void ValidCtrCheck(TDx_Sound*)
{
    new TDx_Sound(NULL);
}
// --------------------------------------------------------------------------
namespace Tdx_sound
{
    #if (__BORLANDC__ >= 0x0530) // BCB Version 3+
    void __fastcall PACKAGE Register()
    #else
    void __fastcall Register()
    #endif
    {
        TComponentClass classes[1] = {__classid(TDx_Sound)};
        RegisterComponents("TDx_Sound", classes, 0);
    }
}

// --------------------------------------------------------------------------
// Extra code for Callback Handling
// --------------------------------------------------------------------------
TDx_Sound* TDx_Sound_OnDSEnumerateOwner = NULL;

// --------------------------------------------------------------------------
// Constructor: TDx_Sound::TDx_Sound()
// Description: The default constructor for the TDx_Sound object.
// --------------------------------------------------------------------------
__fastcall TDx_Sound::TDx_Sound(TComponent* Owner)
    : TComponent(Owner)
{
fCreated = false;
fErrorValue = DS_OK;
}
// --------------------------------------------------------------------------
// Destructor:  TDx_Sound::~TDx_Sound()
// Description: The destructor for the TDx_Sound object.
// --------------------------------------------------------------------------
__fastcall TDx_Sound::~TDx_Sound()
{
// destroy internals
if (Created) Destroy();
}
// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::FGetCreated()
{
return fCreated;
}
// --------------------------------------------------------------------------
void __fastcall TDx_Sound::FSetCreated( bool pCreated )
{
fCreated = (pCreated && (fLPDIRECTSOUND==NULL));
}
// --------------------------------------------------------------------------
// 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 
// --------------------------------------------------------------------------
HRESULT __fastcall TDx_Sound::FGetErrorValue()
{
return fErrorValue;
}
// --------------------------------------------------------------------------
void __fastcall TDx_Sound::FSetErrorValue( HRESULT pErrorValue )
{
fErrorValue = pErrorValue;
}
// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
dword __fastcall TDx_Sound::FGetSpeakerConfig()
{
dword temp_SpeakerConfig;
GetSpeakerConfig(&temp_SpeakerConfig);
return temp_SpeakerConfig;
}
// --------------------------------------------------------------------------
void __fastcall TDx_Sound::FSetSpeakerConfig( dword pSpeakerConfig )
{
SetSpeakerConfig(pSpeakerConfig);
}
// --------------------------------------------------------------------------
// 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 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::Compact()
{
// Original Function Definition
// HRESULT Compact(); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Compact()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->Compact(  );

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::Compact()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::Create( GUID* pGUID )
{
// if the component internals have already been created, exit
if (fCreated)
    {
    fErrorValue = TDX_ALREADYCREATED;
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_ALREADYCREATED", "The "+Name+"::Create() method was called when the component has already been created successfully." );
    return false;
    }

// note: pGUID can be NULL

// create internal IDirectSound interface
fErrorValue = DirectSoundCreate( pGUID, &fLPDIRECTSOUND, NULL );

if (fErrorValue!=DS_OK)
    {
    if (FOnError) FOnError( this, Name+"::Create()", "TDX_ERROR", "The "+Name+"::Create() method failed because DirectSoundCreate() failed with error: "+TDx_Sound_Library_ErrorString(fErrorValue)+", "+TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// successfully created
fCreated = true;
if (FOnCreate) FOnCreate(this);
return true;
}

// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::CreateSoundBuffer( TDSBufferDesc* pBufferDesc, TDx_SoundBuffer* pSoundBuffer )
{
// Original Function Definition
// HRESULT CreateSoundBuffer( 
//   LPCDSBUFFERDESC lpcDSBufferDesc,               
//   LPLPDIRECTSOUNDBUFFER lplpDirectSoundBuffer,   
//   IUnknown FAR * pUnkOuter                       
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::CreateSoundBuffer()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pBufferDesc==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateSoundBuffer()", "TDX_BADPARAMS", "'pBufferDesc' cannot be 'NULL'");
    return false;
    }
if (pSoundBuffer==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::CreateSoundBuffer()", "TDX_BADPARAMS", "'pSoundBuffer' cannot be 'NULL'");
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->CreateSoundBuffer( pBufferDesc->Internal_DSBUFFERDESC_Ptr, pSoundBuffer->Internal_LPDIRECTSOUNDBUFFER_Ptr, NULL );

// Translate Data returned from Function
pBufferDesc->Internal_DSBUFFERDESC_Update();
pSoundBuffer->Internal_LPDIRECTSOUNDBUFFER_Update();

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::CreateSoundBuffer()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::DSEnumerate( LPVOID pContext )
{
// Original Function Definition
// HRESULT WINAPI DirectSoundEnumerate( 
//   LPDSENUMCALLBACK lpDSEnumCallback, 
//   LPVOID lpContext 
// 

// Check Parameters for Accuracy

// Call Original Function
TDx_Sound_OnDSEnumerateOwner = this;
fErrorValue = DirectSoundEnumerate( Internal_DSEnumerateCallback, (LPVOID) pContext );
TDx_Sound_OnDSEnumerateOwner = NULL;

// Handle any Known Results
if (fErrorValue!=DD_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::DSEnumerate()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );

    return false;
    }

// Finished!
return true;
}

// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::Destroy()
{
// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_NOTCREATED", "The "+Name+"::Destroy() method was called before being created successfully." );
    return false;
    }

// code that destroys the internal interface
if (FOnDestroy) FOnDestroy(this);

if (fLPDIRECTSOUND==NULL) 
    { 
    fErrorValue = TDX_ERROR;
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_ERROR", "The "+Name+" component's internal LPDIRECTSOUND is NULL but the TDx_Sound component is expecting it to be not NULL. Aborting the Destroy()." );
    return false;
    }

try { 
    fLPDIRECTSOUND->Release(); 
    } 
catch (...) 
    { 
    fErrorValue = TDX_ERROR; 
    if (FOnError) FOnError( this, Name+"::Destroy()", "TDX_ERROR", "An exception has occurred within LPDIRECTSOUND->Release(). Check that you are destroying all components in reverse order of creation." );
    }

// successful destruction
fLPDIRECTSOUND = NULL;
fCreated = false;
return true;
}

// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::DuplicateSoundBuffer( TDx_SoundBuffer* pOriginal, TDx_SoundBuffer* pDuplicate )
{
// Original Function Definition
// HRESULT DuplicateSoundBuffer( 
//   LPDIRECTSOUNDBUFFER lpDsbOriginal,   
//   LPLPDIRECTSOUNDBUFFER lplpDsbDuplicate   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::DuplicateSoundBuffer()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pOriginal==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::DuplicateSoundBuffer()", "TDX_BADPARAMS", "'pOriginal' cannot be 'NULL'");
    return false;
    }
if (pDuplicate==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::DuplicateSoundBuffer()", "TDX_BADPARAMS", "'pDuplicate' cannot be 'NULL'");
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->DuplicateSoundBuffer( pOriginal->Internal_LPDIRECTSOUNDBUFFER, pDuplicate->Internal_LPDIRECTSOUNDBUFFER_Ptr );

// Translate Data returned from Function
pDuplicate->Internal_LPDIRECTSOUNDBUFFER_Update();

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::DuplicateSoundBuffer()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::GetCaps( TDSCaps* pCaps )
{
// Original Function Definition
// HRESULT GetCaps( 
//   LPDSCAPS lpDSCaps   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetCaps()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pCaps==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetCaps()", "TDX_BADPARAMS", "'pCaps' cannot be 'NULL'");
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->GetCaps( pCaps->Internal_DSCAPS_Ptr );

// Translate Data returned from Function
pCaps->Internal_DSCAPS_Update();

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::GetCaps()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::GetSpeakerConfig( dword* pSpeakerConfig )
{
// Original Function Definition
// HRESULT GetSpeakerConfig( 
//   LPDWORD lpdwSpeakerConfig   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::GetSpeakerConfig()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Check Parameters for Accuracy
if (pSpeakerConfig==NULL)
    {
    fErrorValue = TDX_BADPARAMS;
    if (FOnError) FOnError( this, Name+"::GetSpeakerConfig()", "TDX_BADPARAMS", "'pSpeakerConfig' cannot be 'NULL'");
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->GetSpeakerConfig( (LPDWORD) pSpeakerConfig );

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::GetSpeakerConfig()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
BOOL __stdcall TDx_Sound::Internal_DSEnumerateCallback( LPGUID pGuid, LPCSTR pDescription, LPCSTR pModule, LPVOID pContext )
{
// Original Function Definition
// BOOL WINAPI DSEnumCallback(   
//   LPGUID lpGuid, 
//   LPCSTR lpcstrDescription, 
//   LPCSTR lpcstrModule, 
//   LPVOID lpContext 
// ); 

// Translate Parameters before calling Original Function
GUID* guid = pGuid;
AnsiString driver_description = pDescription;
AnsiString module = pModule;
void* context = pContext;

// transfer to the Callback Event (if it exists)
bool finished = false;
if (TDx_Sound_OnDSEnumerateOwner->OnDSEnumerate)
    TDx_Sound_OnDSEnumerateOwner->OnDSEnumerate(
        TDx_Sound_OnDSEnumerateOwner, guid, driver_description, module, context, finished );

// Finished, return FALSE to abort
if (finished) return FALSE;
return TRUE;
}

// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::SetCooperativeLevel( HWND pHWnd, dword pLevel )
{
// Original Function Definition
// HRESULT SetCooperativeLevel( 
//   HWND hwnd,     
//   DWORD dwLevel   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetCooperativeLevel()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->SetCooperativeLevel( pHWnd, (DWORD) pLevel );

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::SetCooperativeLevel()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// 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. 
// --------------------------------------------------------------------------
bool __fastcall TDx_Sound::SetSpeakerConfig( dword pSpeakerConfig )
{
// Original Function Definition
// HRESULT SetSpeakerConfig( 
//   DWORD dwSpeakerConfig   
// ); 

// if the component internals are not already created, exit
if (!fCreated)
    {
    fErrorValue = TDX_NOTCREATED;
    if (FOnError) FOnError( this, Name+"::SetSpeakerConfig()", "TDX_NOTCREATED", "The "+Name+" component has not been created successfully." );
    return false;
    }

// Call Original Function
fErrorValue = fLPDIRECTSOUND->SetSpeakerConfig( (DWORD) pSpeakerConfig );

// Handle any Known Results
if (fErrorValue!=DS_OK)
    {
    // Failure.
    if (FOnError) FOnError( this, Name+"::SetSpeakerConfig()", TDx_Sound_Library_ErrorString(fErrorValue), TDx_Sound_Library_ErrorMessage(fErrorValue) );
    return false;
    }

// Success!
return true;
}


// --------------------------------------------------------------------------
// Internal Interface Access
// --------------------------------------------------------------------------
LPDIRECTSOUND __fastcall TDx_Sound::FGetInternal_LPDIRECTSOUND()
{
return fLPDIRECTSOUND;
}
// --------------------------------------------------------------------------
LPDIRECTSOUND* __fastcall TDx_Sound::FGetInternal_LPDIRECTSOUND_Ptr()
{
return &fLPDIRECTSOUND;
}
// --------------------------------------------------------------------------
void __fastcall TDx_Sound::FSetInternal_LPDIRECTSOUND( LPDIRECTSOUND pLPDIRECTSOUND )
{
if (!fCreated)
    {
    fLPDIRECTSOUND = pLPDIRECTSOUND;
    fCreated = (fLPDIRECTSOUND!=NULL);
    }
}
// --------------------------------------------------------------------------
void __fastcall TDx_Sound::Internal_LPDIRECTSOUND_Update()
{
fCreated = (fLPDIRECTSOUND!=NULL);
}

// --------------------------------------------------------------------------