#ifndef TDSBufferDescH #define TDSBufferDescH // ========================================================================== // File: TDSBufferDesc.H // Authors: BCB_Code_Generator v1.62, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons), // // Description: This file defines 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. // ========================================================================== // -------------------------------------------------------------------------- #include "TDx_Library_Defns.H" #include "TDx_Library_Functions.H" // -------------------------------------------------------------------------- #include "TDx_Sound_Library_Defns.H" #include "TDx_Sound_Library_Functions.H" // ========================================================================== // Set: TDSBufferDescFlags_Set // Description: A set of mangled DirectX flag names that are used to set the // TDSBufferDesc::Flags property using the BCB Object Inspector. // For detailed descriptions of each flag, see the Flags // property description below. // ========================================================================== enum TDSBufferDesc_Flags_Flags { dsbcaps_ctrl3d_, dsbcaps_ctrlfrequency, dsbcaps_ctrlpan_, dsbcaps_ctrlpositionnotify_, dsbcaps_ctrlvolume, dsbcaps_getcurrentposition2_, dsbcaps_globalfocus, dsbcaps_locdefer, dsbcaps_lochardware, dsbcaps_locsoftware_, dsbcaps_mute3datmaxdistance_, dsbcaps_primarybuffer_, dsbcaps_static, dsbcaps_stickyfocus }; typedef Set< TDSBufferDesc_Flags_Flags, dsbcaps_ctrl3d_, dsbcaps_stickyfocus > TDSBufferDesc_Flags_Set; // -------------------------------------------------------------------------- // ========================================================================== // Class: TDSBufferDesc // Description: The TDSBufferDesc component wraps the DirectX DSBUFFERDESC // structure which describes the characteristics of a sound // buffer. // // This component is used when a sound buffer is created with // TDx_SoundBuffer::Create() or TDx_Sound::CreateSoundBuffer(). // // The TDSBufferDesc component differs from the TDSBCaps // component in that some information, such as the buffer being // located in hardware or software memory, is optional and may // be set, and some properties relating to performance (download // to hardware time and CPU mixing overhead) are absent. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDSBufferDesc : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDSBufferDesc : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // 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. // Note: This property is used to set the various DirectX Flags // for the 'Flags' property via the BCB Object Inspector. // For detailed descriptions of each flag, see the Flags // property description below. // ---------------------------------------------------------------------- __property TDSBufferDesc_Flags_Set Flags_ = { read=FGetFlags_, write=FSetFlags_, nodefault }; // ---------------------------------------------------------------------- // 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. // ---------------------------------------------------------------------- __property dword BufferBytes = { read=FGetBufferBytes, write=FSetBufferBytes, default=0 }; // ---------------------------------------------------------------------- // Property: Size // Description: The Size property defines the size, in bytes, of the // internal structure used by this component. // ---------------------------------------------------------------------- __property dword Size = { read=FGetSize, write=FSetSize, default=sizeof(DSBUFFERDESC) }; // ---------------------------------------------------------------------- // Event: OnError() // Description: The OnError event is called when an error occurs in the // TDSBufferDesc component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // 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 // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DS_OK }; // ---------------------------------------------------------------------- // 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.. // ---------------------------------------------------------------------- __property dword Flags = { read=FGetFlags, write=FSetFlags, default=0 }; // ---------------------------------------------------------------------- // 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(). // ---------------------------------------------------------------------- __property WAVEFORMATEX* Format = { read=FGetFormat, write=FSetFormat, nodefault }; // ---------------------------------------------------------------------- // 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. // ---------------------------------------------------------------------- __property GUID Guid3DAlgorithm = { read=FGetGuid3DAlgorithm, write=FSetGuid3DAlgorithm, nodefault }; // ---------------------------------------------------------------------- // 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(). // ---------------------------------------------------------------------- virtual void __fastcall Clear(); // ---------------------------------------------------------------------- // Property: Flags_Strings() // Description: This property returns a TStringList containing current // flag values for the Flags property. Note: Any memory // associated with these strings is released on destruction. // ---------------------------------------------------------------------- __property TStringList* Flags_Strings = { read=FGetFlags_Strings }; // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDSBufferDesc(TComponent* Owner); virtual __fastcall ~TDSBufferDesc(); // ---------------------------------------------------------------------- // Internal Structure Access // ---------------------------------------------------------------------- __property DSBUFFERDESC* Internal_DSBUFFERDESC_Ptr = { read=FGetInternal_DSBUFFERDESC_Ptr, nodefault }; void __fastcall Internal_DSBUFFERDESC_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Object Inspector 'Flag' Access Methods // ---------------------------------------------------------------------- TDSBufferDesc_Flags_Set __fastcall FGetFlags_(); void __fastcall FSetFlags_( TDSBufferDesc_Flags_Set pFlags_ ); // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- dword __fastcall FGetBufferBytes(); void __fastcall FSetBufferBytes( dword pBufferBytes ); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); dword __fastcall FGetFlags(); void __fastcall FSetFlags( dword pFlags ); WAVEFORMATEX* __fastcall FGetFormat(); void __fastcall FSetFormat( WAVEFORMATEX* pFormat ); GUID __fastcall FGetGuid3DAlgorithm(); void __fastcall FSetGuid3DAlgorithm( GUID pGuid3DAlgorithm ); dword __fastcall FGetSize(); void __fastcall FSetSize( dword pSize ); // ---------------------------------------------------------------------- // Flag_Strings Access Methods // ---------------------------------------------------------------------- TStringList* __fastcall FGetFlags_Strings(); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Internal Structure Access // ---------------------------------------------------------------------- DSBUFFERDESC* __fastcall FGetInternal_DSBUFFERDESC_Ptr(); void __fastcall FSetInternal_DSBUFFERDESC( DSBUFFERDESC* pDSBUFFERDESC ); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- HRESULT fErrorValue; GUID fGuid3DAlgorithm; // ---------------------------------------------------------------------- // Flags_Strings Variables // ---------------------------------------------------------------------- TStringList* fFlags_Strings; // ---------------------------------------------------------------------- // Structure Variables // ---------------------------------------------------------------------- DSBUFFERDESC fDSBUFFERDESC; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_Error FOnError; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------