// -------------------------------------------------------------------------- // ========================================================================== // File: TDSBufferDesc.CPP // Authors: BCB_Code_Generator v1.62, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons), // // Description: This file contains the code for the TDSBufferDesc Component // // "TDx_Sound_Library v1.62" // (c) 2002 BCB-Tools.com Pty. Ltd., Sydney, Australia. // All Rights Reserved. // // Refer to the 'Licence.Txt' file for licencing & copyright information. // ========================================================================== // -------------------------------------------------------------------------- // #includes ... // -------------------------------------------------------------------------- #include #pragma hdrstop // -------------------------------------------------------------------------- #include "TDSBufferDesc.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(TDSBufferDesc*) { new TDSBufferDesc(NULL); } // -------------------------------------------------------------------------- namespace Tdsbufferdesc { #if (__BORLANDC__ >= 0x0530) // BCB Version 3+ void __fastcall PACKAGE Register() #else void __fastcall Register() #endif { TComponentClass classes[1] = {__classid(TDSBufferDesc)}; RegisterComponents("TDx_Sound", classes, 0); } } // -------------------------------------------------------------------------- // Constructor: TDSBufferDesc::TDSBufferDesc() // Description: The default constructor for the TDSBufferDesc object. // -------------------------------------------------------------------------- __fastcall TDSBufferDesc::TDSBufferDesc(TComponent* Owner) : TComponent(Owner) { Clear(); fFlags_Strings=NULL; } // -------------------------------------------------------------------------- // Destructor: TDSBufferDesc::~TDSBufferDesc() // Description: The destructor for the TDSBufferDesc object. // -------------------------------------------------------------------------- __fastcall TDSBufferDesc::~TDSBufferDesc() { if (fFlags_Strings!=NULL) delete fFlags_Strings; } // -------------------------------------------------------------------------- // Property: BufferBytes // Description: The BufferBytes property defines the size, in bytes, of the // new buffer. // // Set this value to 0 when creating a primary buffer, primary // buffers will be allocated resources optimal for the // particular sound device in use. // The size of a newly created primary buffer can be obtained // after creation from TDSBCaps::BufferBytes using // TDx_SoundBuffer::GetCaps(). // // When creating secondary buffers, the minimum and maximum // sizes allowed are currently defined in the dsound.h // DSBSIZE_MIN and DSBSIZE_MAX members as 4 bytes and 0x0FFFFFFF // bytes respectively. // -------------------------------------------------------------------------- dword __fastcall TDSBufferDesc::FGetBufferBytes() { return fDSBUFFERDESC.dwBufferBytes; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetBufferBytes( dword pBufferBytes ) { fDSBUFFERDESC.dwBufferBytes = pBufferBytes; } // -------------------------------------------------------------------------- // Property: ErrorValue // Description: The ErrorValue property contains the last error value // returned from a call to a TDSBufferDesc method or fget/fset. // eg. DS_OK or DDERR_SURFACELOST or TDX_ERROR // -------------------------------------------------------------------------- HRESULT __fastcall TDSBufferDesc::FGetErrorValue() { return fErrorValue; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetErrorValue( HRESULT pErrorValue ) { fErrorValue = pErrorValue; } // -------------------------------------------------------------------------- // Property: Flags // Description: The Flags property defines flags indicating the capabilities // to be included in the new sound buffer. // The described effect applies when the flag is set. // // One or more of the flags must be set. // For optimum performance only specify control options that // will be used. // Attempts to use a control that is not set on a buffer will // result in the method failing. // Flags: DSBCAPS_CTRL3D - // The buffer is to be a primary buffer or a 3D secondary // buffer. // For this to be a primary buffer, DSBCAPS_PRIMARYBUFFER must // be set. // DSBCAPS_CTRLFREQUENCY - // The buffer is to have frequency control capability. // Frequency control is the ability to modify the frequency, // in samples per second, at which the buffer is playing. // DSBCAPS_CTRLPAN - // The buffer is to have pan control capability. // Pan control is the ability to modify the relative values of // the left and right audio channels. // DSBCAPS_CTRLPOSITIONNOTIFY - // The buffer has position notification capability. // // Position notification is the ability to set triggers, which // activate specified events, on reaching certain positions or // conditions within a sound buffer. // // Setting DSBCAPS_CTRLPOSITIONNOTIFY when the hardware uses // VxD drivers forces the buffer to be located in software. // VxD drivers don't support the notifications. // // WDM drivers do support notifications so the buffer may be // located in hardware memory if available. // // Calling TDx_SoundBuffer::Play() with DSBPLAY_LOCHARDWARE // will fail if this flag is set. // DSBCAPS_CTRLVOLUME - // The buffer is to have volume control capability. // Volume control is the ability to modify the volume of a // sound buffer. // DSBCAPS_GETCURRENTPOSITION2 - // TDx_SoundBuffer::GetCurrentPosition() uses the new behavior // of the play cursor and thus return a much more accurate // position. // This flag should always be set unless compatability with // DirectX 1 is required. // This flag only affects emulated sound cards. // DSBCAPS_GLOBALFOCUS - // The buffer is to be a global sound buffer. // Global sound buffers will continue to play even when the // focus is switched to another application, unless that // application is utilizing the DSSCL_EXCLUSIVE or // DSSCL_WRITEPRIMARY cooperative levels. // DSBCAPS_LOCDEFER - // The location of the buffer in hardware or software memory // can be decided when the buffer is played. // // Buffers using the new Dx7 voice allocation and management // features need to set this flag. // DSBCAPS_LOCHARDWARE - // The buffer is to be located in hardware memory and use // hardware mixing. // This flag is optional and mutually exclusive with // DSBCAPS_LOCSOFTWARE. // If there are insufficient hardware resources when this // buffer is created, the creation request will fail. // It is up to the application to ensure that a mixing channel // will be available for this buffer, availability is not // guaranteed. // DSBCAPS_LOCSOFTWARE - // The buffer is to be located in software memory and use // software mixing. // This flag is optional and mutually exclusive with // DSBCAPS_LOCSOFTWARE. // DSBCAPS_MUTE3DATMAXDISTANCE - // The buffer is to cease playing when the maximum distance is // exceeded. // This option prevents the wasting wasting of processor time // by not calculating and mixing sounds that are effectively // inaudible. // DSBCAPS_PRIMARYBUFFER - // The buffer is to be a primary sound buffer. // Any buffer created will be a secondary buffer unless this // flag is set, // DSBCAPS_STATIC - // The buffer is to be used for static sound data. // If this flag is not set the buffer will be a streaming // sound buffer. // Unless otherwise specified, an attempt will be made to // locate this buffer in hardware memory. // DSBCAPS_STICKYFOCUS - // The buffer has a sticky focus. // Having a sticky focus means that an application will // continue to play any sticky focus buffers it has when the // user switches to another application, as long as the new // focus application doesnt utilize DirectSound.. // -------------------------------------------------------------------------- dword __fastcall TDSBufferDesc::FGetFlags() { return fDSBUFFERDESC.dwFlags; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetFlags( dword pFlags ) { fDSBUFFERDESC.dwFlags = pFlags; } // -------------------------------------------------------------------------- // Property: Format // Description: The Format property references a WAVEFORMATEX component // defining the waveform format that the new buffer will use. // When creating a primary buffer, this property must be NULL. // Once created, the format can be set using // TDx_SoundBuffer::SetFormat(). // -------------------------------------------------------------------------- WAVEFORMATEX* __fastcall TDSBufferDesc::FGetFormat() { return fDSBUFFERDESC.lpwfxFormat; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetFormat( WAVEFORMATEX* pFormat ) { fDSBUFFERDESC.lpwfxFormat = pFormat; } // -------------------------------------------------------------------------- // Property: Guid3DAlgorithm // Description: The Guid3DAlgorithm property defines which 2 speaker // virtualization algorithm should be used for software emulated // 3D sounds. // The described effect applies when the flag is set. // // DSCAPS_CTRL3D must be set or this property will be ignored, // in which case GUID_NULL should be set. Setting GUID_NULL is // identical to setting DS3DALG_DEFAULT. // // Speaker configuration is set using // TDx_Sound::SetSpeakerConfig(), but sound processing will // still behave as if a two-speaker sound configuration was // choosen (two speaker or headphone) regardless of the actual // setting. // Flags: DS3DALG _DEFAULT - // The DS3DALG_NO_VIRTUALIZATION algorithm is currently the // default setting. // DS3DALG _NO_VIRTUALIZATION - // 3D sounds are mapped onto a normal stereo panning function. // Thus, at 90 degrees left, sound will only come from the // left speaker and at 90 degrees right, sound will only come // from the right speaker. // There is no processing for vertical axis displacement, but // distance and doppler volume scaling are applied without 3D // filtering. // This algorithm is very efficient and can be accelerated // using a 2D hardware voice if no 3D voices are available, // since it only uses stereo panning, but no Head Related // Transfer Function (HRTF) processing will be done. // This algorithm will work for both WDM and Vxd drivers // DS3DALG_HRTF_FULL - // 3D sounds are processed using a high quality 3D audio // algorithm. // This setting utilizes the most CPU time, but gives the // highest quality 3D audio effect. // Buffers created with this flag that use a HRTF algorithm // that is not supported by the system will use the // DS3DALG_NO_VIRTUALIZATION setting instead. // This algorithm will work for Windows 98 2nd Ed and Windows // 2000 when using WDM drivers. // DS3DALG_HRTF_LIGHT - // 3D sounds are processed using a medium quality 3D audio // algorithm. // This setting utilizes less CPU time, but gives a slightly // lower quality 3D audio effect. // Buffers created with this flag that use a HRTF algorithm // that is not supported by the system will use the // DS3DALG_NO_VIRTUALIZATION setting instead. // This algorithm will work for Windows 98 2nd Ed and Windows // 2000 when using WDM drivers. // -------------------------------------------------------------------------- GUID __fastcall TDSBufferDesc::FGetGuid3DAlgorithm() { return fDSBUFFERDESC.guid3DAlgorithm; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetGuid3DAlgorithm( GUID pGuid3DAlgorithm ) { fDSBUFFERDESC.guid3DAlgorithm = pGuid3DAlgorithm; } // -------------------------------------------------------------------------- // Property: Size // Description: The Size property defines the size, in bytes, of the internal // structure used by this component. // -------------------------------------------------------------------------- dword __fastcall TDSBufferDesc::FGetSize() { return fDSBUFFERDESC.dwSize; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetSize( dword pSize ) { fDSBUFFERDESC.dwSize = pSize; } // -------------------------------------------------------------------------- // Method: Clear() // Description: The Clear() method can be used to clear the contents of the // TDSBufferDesc's internal DSBUFFERDESC structure. // Note: if you have manually linked a structure member to a // chunk of memory, make sure you release this memory before // calling Clear(). // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::Clear() { fDSBUFFERDESC.dwBufferBytes = 0; fErrorValue = DS_OK; fDSBUFFERDESC.dwFlags = 0; ZeroMemory(&fGuid3DAlgorithm,sizeof(_GUID)); fDSBUFFERDESC.dwSize = sizeof(DSBUFFERDESC); } // -------------------------------------------------------------------------- // Internal Structure Access // -------------------------------------------------------------------------- DSBUFFERDESC* __fastcall TDSBufferDesc::FGetInternal_DSBUFFERDESC_Ptr() { return &fDSBUFFERDESC; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetInternal_DSBUFFERDESC( DSBUFFERDESC* pDSBUFFERDESC ) { if (pDSBUFFERDESC==NULL) { fErrorValue = TDX_ERROR; if (FOnError) FOnError(this, "TDSBufferDesc::FSetInternal_DSBUFFERDESC()", "TDX_ERROR", "The supplied DSBUFFERDESC* was NULL" ); return; } CopyMemory( &fDSBUFFERDESC, pDSBUFFERDESC, sizeof(DSBUFFERDESC) ); Internal_DSBUFFERDESC_Update(); } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::Internal_DSBUFFERDESC_Update() { } // -------------------------------------------------------------------------- // Method: FGetFlags_ // Description: This method returns a TDSBufferDesc_Flags_Set<> of the flags // in the current fDSBUFFERDESC.dwFlags. // Note: Wrapper components use the following method to modify flags // via the BCB Object Inspector. // -------------------------------------------------------------------------- TDSBufferDesc_Flags_Set __fastcall TDSBufferDesc::FGetFlags_() { TDSBufferDesc_Flags_Set TempFlags_; TempFlags_.Clear(); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRL3D) TempFlags_ = TempFlags_ << dsbcaps_ctrl3d_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLFREQUENCY) TempFlags_ = TempFlags_ << dsbcaps_ctrlfrequency; if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLPAN) TempFlags_ = TempFlags_ << dsbcaps_ctrlpan_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLPOSITIONNOTIFY) TempFlags_ = TempFlags_ << dsbcaps_ctrlpositionnotify_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLVOLUME) TempFlags_ = TempFlags_ << dsbcaps_ctrlvolume; if (fDSBUFFERDESC.dwFlags & DSBCAPS_GETCURRENTPOSITION2) TempFlags_ = TempFlags_ << dsbcaps_getcurrentposition2_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_GLOBALFOCUS) TempFlags_ = TempFlags_ << dsbcaps_globalfocus; if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCDEFER) TempFlags_ = TempFlags_ << dsbcaps_locdefer; if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCHARDWARE) TempFlags_ = TempFlags_ << dsbcaps_lochardware; if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCSOFTWARE) TempFlags_ = TempFlags_ << dsbcaps_locsoftware_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_MUTE3DATMAXDISTANCE) TempFlags_ = TempFlags_ << dsbcaps_mute3datmaxdistance_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_PRIMARYBUFFER) TempFlags_ = TempFlags_ << dsbcaps_primarybuffer_; if (fDSBUFFERDESC.dwFlags & DSBCAPS_STATIC) TempFlags_ = TempFlags_ << dsbcaps_static; if (fDSBUFFERDESC.dwFlags & DSBCAPS_STICKYFOCUS) TempFlags_ = TempFlags_ << dsbcaps_stickyfocus; return TempFlags_; } // -------------------------------------------------------------------------- void __fastcall TDSBufferDesc::FSetFlags_( TDSBufferDesc_Flags_Set pFlags_ ) { fDSBUFFERDESC.dwFlags = 0; if (pFlags_.Contains(dsbcaps_ctrl3d_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_CTRL3D; if (pFlags_.Contains(dsbcaps_ctrlfrequency)) fDSBUFFERDESC.dwFlags |= DSBCAPS_CTRLFREQUENCY; if (pFlags_.Contains(dsbcaps_ctrlpan_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_CTRLPAN; if (pFlags_.Contains(dsbcaps_ctrlpositionnotify_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_CTRLPOSITIONNOTIFY; if (pFlags_.Contains(dsbcaps_ctrlvolume)) fDSBUFFERDESC.dwFlags |= DSBCAPS_CTRLVOLUME; if (pFlags_.Contains(dsbcaps_getcurrentposition2_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_GETCURRENTPOSITION2; if (pFlags_.Contains(dsbcaps_globalfocus)) fDSBUFFERDESC.dwFlags |= DSBCAPS_GLOBALFOCUS; if (pFlags_.Contains(dsbcaps_locdefer)) fDSBUFFERDESC.dwFlags |= DSBCAPS_LOCDEFER; if (pFlags_.Contains(dsbcaps_lochardware)) fDSBUFFERDESC.dwFlags |= DSBCAPS_LOCHARDWARE; if (pFlags_.Contains(dsbcaps_locsoftware_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_LOCSOFTWARE; if (pFlags_.Contains(dsbcaps_mute3datmaxdistance_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_MUTE3DATMAXDISTANCE; if (pFlags_.Contains(dsbcaps_primarybuffer_)) fDSBUFFERDESC.dwFlags |= DSBCAPS_PRIMARYBUFFER; if (pFlags_.Contains(dsbcaps_static)) fDSBUFFERDESC.dwFlags |= DSBCAPS_STATIC; if (pFlags_.Contains(dsbcaps_stickyfocus)) fDSBUFFERDESC.dwFlags |= DSBCAPS_STICKYFOCUS; } // -------------------------------------------------------------------------- // Method: FGetFlags_Strings() // This method creates and then returns a TStringList containing // the current set of 'Flags' flags. // Note: You must manually delete the retrieved TStringList after use // to avoid memory corruption. // -------------------------------------------------------------------------- TStringList* __fastcall TDSBufferDesc::FGetFlags_Strings() { // if the strings have not been allocated if (fFlags_Strings==NULL) { // attempt to allocate the strings fFlags_Strings = new TStringList(); // if the allocation failed if (fFlags_Strings==NULL) { fErrorValue = TDX_ERROR; if (FOnError) FOnError(this, "TDSBufferDesc::FGetFlags_Strings()", "TDX_ERROR", "Could not allocate memory used to retrieve various Flags_Strings" ); return NULL; } } fFlags_Strings->Clear(); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRL3D) fFlags_Strings->Add("DSBCAPS_CTRL3D"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLFREQUENCY) fFlags_Strings->Add("DSBCAPS_CTRLFREQUENCY"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLPAN) fFlags_Strings->Add("DSBCAPS_CTRLPAN"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLPOSITIONNOTIFY) fFlags_Strings->Add("DSBCAPS_CTRLPOSITIONNOTIFY"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_CTRLVOLUME) fFlags_Strings->Add("DSBCAPS_CTRLVOLUME"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_GETCURRENTPOSITION2) fFlags_Strings->Add("DSBCAPS_GETCURRENTPOSITION2"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_GLOBALFOCUS) fFlags_Strings->Add("DSBCAPS_GLOBALFOCUS"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCDEFER) fFlags_Strings->Add("DSBCAPS_LOCDEFER"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCHARDWARE) fFlags_Strings->Add("DSBCAPS_LOCHARDWARE"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_LOCSOFTWARE) fFlags_Strings->Add("DSBCAPS_LOCSOFTWARE"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_MUTE3DATMAXDISTANCE) fFlags_Strings->Add("DSBCAPS_MUTE3DATMAXDISTANCE"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_PRIMARYBUFFER) fFlags_Strings->Add("DSBCAPS_PRIMARYBUFFER"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_STATIC) fFlags_Strings->Add("DSBCAPS_STATIC"); if (fDSBUFFERDESC.dwFlags & DSBCAPS_STICKYFOCUS) fFlags_Strings->Add("DSBCAPS_STICKYFOCUS"); return fFlags_Strings; } // --------------------------------------------------------------------------