#ifndef TDx_SoundBufferH #define TDx_SoundBufferH // ========================================================================== // File: TDx_SoundBuffer.H // Authors: BCB_Code_Generator v1.62, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons), // // Description: This file defines the TDx_SoundBuffer 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 #include #include #include // -------------------------------------------------------------------------- #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 the TDx_SoundBuffer component. class TDx_Sound; // -------------------------------------------------------------------------- // external classes used by TDx_SoundBuffer methods. class TDSBufferDesc; class TDSBCaps; // -------------------------------------------------------------------------- // ========================================================================== // Class: TDx_SoundBuffer // Description: The TDx_SoundBuffer component wraps the DirectX // IDirectSoundBuffer interface which is used to define the // sound environment. // // It is used to start and stop the playback of a sound buffer // and restore the memory of buffers that have been lost, the // current positions of the play and write cursors can be // retrieved or modified and the buffer may be partially or // completely locked and unlocked so new sound data may be // written. // // This component can also be used to set or retrieve the // capabilities, format, status, frequency, pan or volume of a // sound buffer. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDx_SoundBuffer : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDx_SoundBuffer : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // Property: Playing // Description: The Playing property can be used to determine whether or // not a buffer is currently playing. If true, the sound // buffer is currently playing. If false, the sound buffer // is not currently playing. // // This is equivalent to calling // TDx_SoundBuffer::GetStatus() and checking for // DSBSTATUS_PLAYING. // ---------------------------------------------------------------------- __property bool Playing = { read=FGetPlaying, nodefault }; // ---------------------------------------------------------------------- // Event: OnBufferLost() // Description: The OnBufferLost event is triggered when the various // TDx_SoundBuffer methods determine that the buffer has // been lost. // This event is ideal for restoring a lost buffer to its // previous state. // ---------------------------------------------------------------------- __property TDx_Event OnBufferLost = {read=FOnBufferLost, write=FOnBufferLost, nodefault}; // ---------------------------------------------------------------------- // Event: OnCreate() // Description: The OnCreate() event is triggered by the // TDx_SoundBuffer::Create() method after it has // successfully created the internal LPDIRECTSOUNDBUFFER // used within the TDx_SoundBuffer 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 LPDIRECTSOUNDBUFFER interface. // // For example, you could retrieve the TDx_SoundBuffer // component's capabilities, Create() dependant components, // allocate memory, etc. // // When used in conjunction with the // TDx_SoundBuffer::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_SoundBuffer::Destroy() method, just before the // TDx_SoundBuffer internal LPDIRECTSOUNDBUFFER interface is // destroyed. // // Note: This event is an ideal place to place code that // reverses the results of the TDx_SoundBuffer::OnCreate() // event. For example, assume you have already setup the // TDx_SoundBuffer::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_SoundBuffer::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_SoundBuffer component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // Property: Created // Description: The Created property is true if the internal // LPDIRECTSOUNDBUFFER used in this component has been // successfully created, otherwise Created is false. // // To create the internal LPDIRECTSOUNDBUFFER, call the // TDx_SoundBuffer::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_SoundBuffer method or // fget/fset. eg. DS_OK or DDERR_SURFACELOST or TDX_ERROR // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DS_OK }; // ---------------------------------------------------------------------- // Property: Frequency // Description: The Frequency property can be used as an alternative to // calling the TDx_SoundBuffer::GetFrequency() and // TDx_SoundBuffer::SetFrequency() methods. // Retrieving this property calls the GetFrequency() method // and returns the result. // Setting this property calls the SetFrequency() method and // passes the supplied property value as the method // parameter. // ---------------------------------------------------------------------- __property dword Frequency = { read=FGetFrequency, write=FSetFrequency, nodefault }; // ---------------------------------------------------------------------- // Property: Pan // Description: The Pan property can be used as an alternative to calling // the TDx_SoundBuffer::GetPan() and // TDx_SoundBuffer::SetPan() methods. // Retrieving this property calls the GetPan() method and // returns the result. // Setting this property calls the SetPan() method and // passes the supplied property value as the method // parameter. // ---------------------------------------------------------------------- __property long Pan = { read=FGetPan, write=FSetPan, nodefault }; // ---------------------------------------------------------------------- // Property: StreamFormat // Description: The StreamFormat property references an internal // WAVEFORMATEX structure defining the format of the current // stream. // This internal structure is setup when you call the // TDx_SoundBuffer::OpenStream(), // TDx_SoundBuffer::CreateFromFile(), // TDx_SoundBuffer::CreateStream() or // TDx_SoundBuffer::SaveToFile() methods. // ---------------------------------------------------------------------- __property WAVEFORMATEX* StreamFormat = { read=FGetStreamFormat, default=NULL }; // ---------------------------------------------------------------------- // Property: StreamIsOpen // Description: The StreamIsOpen property will be true if a stream is // currently open and false otherwise. // ---------------------------------------------------------------------- __property bool StreamIsOpen = { read=FGetStreamIsOpen, default=false }; // ---------------------------------------------------------------------- // Property: StreamSize // Description: The StreamSize property holds the total number of bytes // in the current stream. // Set this property to the total size of the stream to be // saved, in bytes, before calling // TDx_SoundBuffer::SaveToFile(). // // After calling TDx_SoundBuffer::CreateFromStream(), this // property will contain the total number of bytes of data // read from the stream. // After calling TDx_SoundBuffer::CreateStream() or // TDx_SoundBuffer::OpenStream() this property will be 0. // After calling TDx_SoundBuffer::CloseStream() this // property will contain the total number of bytes read from // or written to the stream using // TDx_SoundBuffer::ReadFromStream() or // TDx_SoundBuffer::WriteToStream() since the last call to // TDx_SoundBuffer::CreateStream() // After calling TDx_SoundBuffer::CreateStream() this // property will contain the total number of bytes read from // or written to the stream. // // ---------------------------------------------------------------------- __property dword StreamSize = { read=FGetStreamSize, write=FSetStreamSize, default=0 }; // ---------------------------------------------------------------------- // Property: Volume // Description: The Volume property can be used as an alternative to // calling the TDx_SoundBuffer::GetVolume() and // TDx_SoundBuffer::SetVolume() methods. // Retrieving this property calls the GetVolume() method and // returns the result. // Setting this property calls the SetVolume() method and // passes the supplied property value as the method // parameter. // ---------------------------------------------------------------------- __property long Volume = { read=FGetVolume, write=FSetVolume, nodefault }; // ---------------------------------------------------------------------- // Property: WaveFileFormat // Description: The WaveFileFormat property is used internally to setup // the .WAV file header for streaming. // ---------------------------------------------------------------------- __property TDX_WAVE_FILE_FORMAT WaveFileFormat = { read=FGetWaveFileFormat, write=FSetWaveFileFormat, nodefault }; // ---------------------------------------------------------------------- // Method: CloseStream() // Description: The CloseStream method will close the current .wav file. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_ERROR // ---------------------------------------------------------------------- virtual bool __fastcall CloseStream(); // ---------------------------------------------------------------------- // Method: Create() // Description: The Create() method is used to automatically create the // internal LPDIRECTSOUNDBUFFER interface used in the // TDx_SoundBuffer component and must be called before any // methods of the TDx_SoundBuffer component will function. // Params: pBufferDesc - // The BufferDesc parameter references a TDSBufferDesc // defining the properties of the sound buffer being // created. // pSound - // The Sound parameter references the existing TDx_Sound // component for which the sound buffer is to be created. // ---------------------------------------------------------------------- virtual bool __fastcall Create( TDSBufferDesc* pBufferDesc, TDx_Sound* pSound ); // ---------------------------------------------------------------------- // Method: CreateFromFile() // Description: The CreateFromFile method will create a sound buffer of // the same format as a specified .wav file. // If there is an existing buffer for this component, it // will be destroyed before the new one is created. // The size of the new buffer will equal that of the file's // sound data, which is automatically loaded into the // buffer. // // The internal WAVEFORMATEX structure referenced by the // TDx_SoundBuffer::StreamFormat property will automatically // be filled with the format data of the specified .wav // file. // // Note: // This method does not support the loading of .wav files // where the format of the .wav file being loaded is not the // raw, uncompressed, WAVE_FORMAT_PCM .wav file standard // that DirectSound supports. It currently supports only // WAVE_FORMAT_PCM files, and may have undetermined results // if used with non-WAVE_FORMAT_PCM files. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // TDX_ERROR // Params: pFileName - // The FileName parameter defines the path and filename of // the .wav file which will be used to create the sound // buffer. // pBufferDesc - // The BufferDesc parameter references a TDSBufferDesc // component for holding the properties of the new buffer. // // The TDSBufferDesc component will mostly be filled // automatically from data contained in the .wav file. // // If control options in addition to the // DSBCAPS_GETCURRENTPOSITION2 are required, it is // neccessary to set the desired flags in the TDSBufferDesc // component manually before calling this method. // pSound - // The Sound parameter references the existing TDx_Sound // component for which the sound buffer is to be created. // ---------------------------------------------------------------------- virtual bool __fastcall CreateFromFile( AnsiString pFileName, TDSBufferDesc* pBufferDesc, TDx_Sound* pSound ); // ---------------------------------------------------------------------- // Method: CreateStream() // Description: The CreateStream method will create and open a new .wav // file. // Once created, sound data may be written to the file with // TDx_SoundBuffer::WriteToStream(). // Once all data has been written to the stream, close the // stream using TDx_SoundBuffer::CloseStream() // When the stream is open, the // TDx_SoundBuffer::StreamIsOpen property will be true. // // If the method call fails, the OnError event will be // triggered with one of the following values: // // TDX_BADPARAMS // TDX_ERROR // Params: pFileName - // The FileName parameter defines the path and filename of // the .wav file to be created. // pFormat - // The Format method parameter describes the format of the // sound file to be created. This parameter must point to a // user-supplied WAVEFORMATEX structure that has been filled // with appropriate values. // // You can retrieve the WAVEFORMATEX of the current buffer // using the TDx_SoundBuffer::GetFormat() method. // // You can also pass in a non-WAVE_FORMAT_PCM structure // typecast as a WAVEFORMATEX, and supply the byte-size of // the non-WAVE_FORMAT_PCM using the FormatSize parameter. // pFormatSize - // The FormatSize parameter must contain the size of the // WAVEFORMATEX structure passed into this method via the // Format parameter. // Generally this will be sizeof(WAVEFORMATEX) but it may // differ depending on the definition of the WAVEFORMATEX.. // ---------------------------------------------------------------------- virtual bool __fastcall CreateStream( AnsiString pFileName, WAVEFORMATEX* pFormat, int pFormatSize ); // ---------------------------------------------------------------------- // Method: Destroy() // Description: The Destroy() method is used to automatically destroy the // internal LPDIRECTSOUNDBUFFER interface used in the // TDx_SoundBuffer 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: GetCaps() // Description: The TDx_SoundBuffer::GetCaps method will return the // current capabilities of the buffer. // // If the method call fails, the OnError event may be // triggered with the following value: // TDX_BADPARAMS // DSERR_INVALIDPARAM // Params: pBufferCaps - // The BufferCaps parameter references a TDSBCaps component // for holding the capabilities of the sound buffer if this // method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetCaps( TDSBCaps* pBufferCaps ); // ---------------------------------------------------------------------- // Method: GetCurrentPosition() // Description: The TDx_SoundBuffer::GetCurrentPosition method will // return the current postion of the play and write cursors // within the sound buffer. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pCurrentPlayCursor - // The CurrentPlayCursor parameter will reference the // current offset, in bytes, of the play cursor within the // buffer if this method returns successfully. // Set this parameter to NULL if only the write position is // desired. // pCurrentWriteCursor - // The CurrentWriteCursor parameter will reference the // current offset, in bytes, of the write cursor within the // buffer if this method returns successfully. // Set this parameter to NULL if only the play position is // desired. // ---------------------------------------------------------------------- virtual bool __fastcall GetCurrentPosition( dword* pCurrentPlayCursor, dword* pCurrentWriteCursor ); // ---------------------------------------------------------------------- // Method: GetFormat() // Description: The TDx_SoundBuffer::GetFormat method will return either // the sound data format of the buffer or amount of space // needed to retrieve that information. // // If the method call fails, the OnError event may be // triggered with the following value: // DSERR_INVALIDPARAM // Params: pFormat - // The Format parameter references a WAVEFORMATEX structure // for holding the sound data format of the buffer. // // Setting this parameter to NULL will cause the required // buffer size to be placed in the SizeWritten parameter of // this method. // pSizeAllocated - // The SizeAllocated parameter defines the size, in bytes, // of the WAVEFORMATEX structure referenced by the Format // parameter of this method. // pSizeWritten - // The SizeWritten parameter will reference the amount, in // bytes, written into the WAVEFORMATEX structure referenced // by the Format parameter of this method. // This parameter may be set to NULL. // ---------------------------------------------------------------------- virtual bool __fastcall GetFormat( WAVEFORMATEX* pFormat, dword pSizeAllocated, dword* pSizeWritten ); // ---------------------------------------------------------------------- // Method: GetFrequency() // Description: The TDx_SoundBuffer::GetFrequency method will return the // frequency, in samples per second, at which the sound // buffer is playing. // // The minimum and maximum frequencies are defined in the // dsound.h DSBFREQUENCY_MIN and DSBFREQUENCY_MAX members as // 100 and 100,000 respectively. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_CONTROLUNAVAIL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pFrequency - // The Frequency parameter will reference the playing // frequency of the buffer if this method returns // successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetFrequency( dword* pFrequency ); // ---------------------------------------------------------------------- // Method: GetPan() // Description: The TDx_SoundBuffer::GetPan method will return the // relative volume of the left and right audio channels. // // The left, right and center pan values are defined in the // dsound.h DSBPAN_LEFT, DSBPAN_RIGHT and DSBPAN_CENTER // members as -10,000, 10,000 and 0 respectively. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_CONTROLUNAVAIL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pPan - // The Pan parameter will reference the relative volume of // the left and right audio channels if this method returns // successfully. // // Displacement to the negative represents attenuation, in // 100ths of a decibel, of the right channel and // displacement to the positive represents attentuation of // the left channel in a similar manner. // ---------------------------------------------------------------------- virtual bool __fastcall GetPan( long* pPan ); // ---------------------------------------------------------------------- // Method: GetStatus() // Description: The TDx_SoundBuffer::GetStatus method will return the // current status of the sound buffer. // // If the method call fails, the OnError event may be // triggered with the following value: // TDX_BADPARAMS // DSERR_INVALIDPARAM // Params: pStatus - // The Status parameter will reference flags indicating the // current status of the sound buffer if this method returns // successfully. // The described effect applies when the flag is set. // Flags: // DSBSTATUS_BUFFERLOST - // The buffer has been lost. // Restoration is required before playing or locking // of the buffer can be performed. // DSBSTATUS_LOCHARDWARE - // The buffer is playing and is located in hardware // memory. // This flag only applies for buffers created with // DSBCAPS_LOCDEFER set. // DSBSTATUS_LOCSOFTWARE - // The buffer is playing and is located in system // memory. // This flag only applies for buffers created with // DSBCAPS_LOCDEFER set. // DSBSTATUS_LOOPING - // The buffer is looping. // The buffer returns to the beginning and continues // playing when it reaches the end of the buffer. // When this flag is set, the buffer will also be // playing. // DSBSTATUS_PLAYING - // The buffer is playing. // DSBSTATUS_TERMINATED - // The buffer is not playing. // This flag is set when the voice management logic // halts the play of a sound buffer and only applies // for buffers created with DSBCAPS_LOCDEFER set. // ---------------------------------------------------------------------- virtual bool __fastcall GetStatus( dword* pStatus ); // ---------------------------------------------------------------------- // Method: GetVolume() // Description: The TDx_SoundBuffer::GetVolume method will return the // volume, in 100ths of a decibel, currently set for the // sound buffer. // // The minimum and maximum volumes are defined in the // dsound.h DSBVOLUME_MIN and DSBVOLUME_MAX members as // -10,000 and 0 respectively. // // Minimum volume indicates the sound is attenuated by 100 // decibels while the maximum volume represents the original // unadjusted volume of the sound. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_CONTROLUNAVAIL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pVolume - // The Volume parameter will reference the volume, in 100ths // of a decibel, of the buffer if this method returns // successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetVolume( long* pVolume ); // ---------------------------------------------------------------------- // Method: Lock() // Description: The TDx_SoundBuffer::Lock method will return a valid // write pointer to the buffer's audio data. // // This method returns write pointers only, do not attempt // to use them for the purpose of reading. // // The buffer should not be locked for long periods of time // as the play cursor may reach the locked portion of the // buffer and cause configuration dependent audio problems. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_BUFFERLOST // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pWriteCursor - // The WriteCursor parameter defines the offset, in bytes, // of where the lock is to begin in the buffer. // // Setting either of the flags in the flags parameter of // this method causes this parameter to be ignored. // pWriteBytes - // The WriteBytes parameter defines the amount, in bytes, of // buffer to be locked. // // The space that is locked may wrap around to the start of // the buffer, which is conceptually circular, in which case // the AudioPtr2 parameter of this method will reference the // start of the buffer. // pAudioPtr1 - // The AudioPtr1 parameter will reference the first block of // locked sound buffer if this method returns successfully. // pAudioBytes1 - // The AudioBytes1 parameter references the number of bytes // referenced by the AudioPtr1 parameter of this method. // // When this value is less than the value in the WriteBytes // parameter of this method, it means AudioPtr2 will // reference a second block of sound data. // pAudioPtr2 - // The AudioPtr2 parameter will reference the second block // of locked sound buffer if this method returns // successfully. // // When this parameter is NULL it means AudioPtr1 references // the entire locked region of the sound buffer and any // portion of the area that wraps around will not be locked. // pAudioBytes2 - // The AudioBytes2 parameter references the number of bytes // referenced by the AudioPtr2 parameter of this method. // // When the AudioPtr2 parameter of this method is set to // NULL, this parameter will be 0. // pFlags - // The Flags parameter defines flags indicating // modifications to the lock event. // The described effect applies when the flag is set. // Flags: // DSBLOCK_ENTIREBUFFER - // Lock the whole sound buffer. // Setting this flag causes the WriteCursor parameter // of this method to be ignored. // DSBLOCK_FROMWRITECURSOR - // Use the current write position as the start of the // sound buffer lock area. // Setting this flag causes the WriteCursor parameter // of this method to be ignored. // ---------------------------------------------------------------------- virtual bool __fastcall Lock( dword pWriteCursor, dword pWriteBytes, void** pAudioPtr1, dword* pAudioBytes1, void** pAudioPtr2, dword* pAudioBytes2, dword pFlags ); // ---------------------------------------------------------------------- // Method: OpenStream() // Description: The OpenStream method will open an existing .wav file for // reading or writing. // This method will automatically fill the internal // WAVEFORMATEX structure referenced by the StreamFormat // property of this component with the format data of the // .wav file being opened. // // Once opened the file can be read with // TDx_SoundBuffer::ReadFromStream() or written using // TDx_SoundBuffer::WriteToStream(). // Once all data has been read from or written to the // stream, close the stream using // TDx_SoundBuffer::CloseStream() // When the stream is open, the // TDx_SoundBuffer::StreamIsOpen property will be true. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // TDX_ERROR // Params: pFileName - // The FileName parameter defines the path and filename of // the exisitng .wav file which is to be opened. // ---------------------------------------------------------------------- virtual bool __fastcall OpenStream( AnsiString pFileName ); // ---------------------------------------------------------------------- // Method: Play() // Description: The TDx_SoundBuffer::Play method will cause the sound // buffer to play from the current position of the play // cursor. // // Calling this method will succeed, but no sound will be // produced unless a cooperative level has been set using // TDx_Sound::SetCooperativeLevel(). // // A secondary buffer being played when there is no primary // buffer will cause the primary buffer to be automatically // created and played. // // Calling this method when the buffer is already playing // will succeed, playing will continue using the flag // settings defined in the latest call to this method. // // Calling this method on a primary buffer will cause it to // continue playing between sounds, thus reducing the // overhead of starting and stopping play and potential // sound artifacts such as popping. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_BUFFERLOST // DSERR_HWUNAVAIL // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pPriority - // The Priority parameter defines the priority given to the // sound being played. // // This value may be used to decide which sound buffer is // played using hardware resources when // DSBPLAY_TERMINATEBY_PRIORITY is set in the Flags // parameter of this method. // // When DSBCAPS_ LOCDEFER is not set, this parameter must be // 0. // Priorities range from 0 to ffffffff, with 0 having the // lowest priory. // pFlags - // The Flags parameter defines a flag indicating how the // buffer is to be played. // The described effect applies when the flag is set. // Flags: // DSBPLAY_LOCHARDWARE - // Play the sound using hardware only. // // The buffer must have DSBCAPS_LOCDEFER set. // DSBPLAY_LOCSOFTWARE cannot be set in conjunction // with this flag. // If no hardware voices are available and no // DSBPLAY_TERMINATEBY_xxx flags set, the method call // will fail. // When neither this flag or DBSPLAY_LOCSOFTWARE are // set, the sound will be played using hardware or // software, depending on resource availablility. // DSBPLAY_LOCSOFTWARE - // Play the sound using software only. // // The buffer must have DSBCAPS_LOCDEFER set. // The DSBPLAY_LOCHARDWARE and DSBPLAY_TERMINATEBY_xxx // flags cannot be set in conjunction with this flag. // When neither this flag or DBSPLAY_LOCHARDWARE are // set, the sound will be played using hardware or // software, depending on resource availablility. // DSBPLAY_LOOPING - // Play restarts from the beginning of the buffer // whenever the end is reached. // Primary sound buffers must have this flag set. // DSBPLAY_TERMINATEBY_DISTANCE - // If there are no hardware resources available, stop // playing a 3D buffer that has // DSBCAPS_MUTE3DATMAXDISTANCE set and is beyond its // max distance and play this buffer instead. // If there are no 3D buffers meeting the // requirements, the play will fail. // Only 3D buffers with DSBCAPS_LOCDEFER set may be // terminated in this way. // DSBPLAY_TERMINATEBY_PRIORITY - // If there are no hardware resources available, stop // playing the buffer with the lowest priority and // play this buffer instead. // A buffers priority is defined by the Priority // parameter of this method and the play will fail if // there are no hardware buffers with a lower priority // than this one. // DSBPLAY_TERMINATEBY_DISTANCE cannot be set in // conjunction with this flag. // Only buffers with DSBCAPS_LOCDEFER set may be // terminated in this way. // DSBPLAY_TERMINATEBY_TIME - // If there are no hardware resources available, stop // playing the buffer with the least play time left // and play this buffer instead. // Only buffers with DSBCAPS_LOCDEFER set may be // terminated in this way. // ---------------------------------------------------------------------- virtual bool __fastcall Play( dword pPriority, dword pFlags ); // ---------------------------------------------------------------------- // Method: ReadFromStream() // Description: The ReadFromStream method will read a specified amount of // sound data from the .wav file opened with // TDx_SoundBuffer::OpenStream(). // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // TDX_ERROR // Params: pBytesToRead - // The BytesToRead parameter defines the amount, in bytes, // of sound data to read from the current .wav file. // pSoundData - // The SoundData parameter references the array of bytes // that will be used for holding the sound data read from // the current .wav file. // // The provided byte array must be large enough to contain // the amount of data specified by the BytesToRead // parameter. // // This parameter may be set to one of the pointers returned // by TDx_SoundBuffer::Lock() to read sound data directly // into the sound buffer. // pBytesActuallyRead - // The BytesActuallyRead parameter will reference the // amount, in bytes, that was actually written to the // SoundData parameter if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall ReadFromStream( dword pBytesToRead, byte* pSoundData, dword* pBytesActuallyRead ); // ---------------------------------------------------------------------- // Method: Restore() // Description: The TDx_SoundBuffer::Restore method will restore memory // allocated to the sound buffer when it has been lost. // // This method restores the memory, not the contents, of the // sound buffer. // Attempts to restore buffers when the application does not // have the input focus may not succeed. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_BUFFERLOST // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // ---------------------------------------------------------------------- virtual bool __fastcall Restore(); // ---------------------------------------------------------------------- // Method: SaveToFile() // Description: The SaveToFile method will save the entire sound buffer // to a specified file. // // This method will not append data. If you wish to save // sound data a segment at a time, // TDx_SoundBuffer::WriteToStream() should be used. // // The application should ensure the desired WAVEFORMATEX // values are set in the StreamFormat property of this // component prior to calling this method. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // TDX_ERROR // Params: pFileName - // The FileName parameter defines the path and filename of // the new .wav file which is to be created. // pFormat - // The Format method parameter describes the format of the // sound file to be created. This parameter must point to a // user-supplied WAVEFORMATEX structure that has been filled // with appropriate values. // pFormatSize - // The FormatSize parameter must contain the size of the // WAVEFORMATEX structure passed into this method via the // Format parameter. Generally this will be // sizeof(WAVEFORMATEX) but it may differ depending on the // definition of the WAVEFORMATEX. // ---------------------------------------------------------------------- virtual bool __fastcall SaveToFile( AnsiString pFileName, WAVEFORMATEX* pFormat, int pFormatSize ); // ---------------------------------------------------------------------- // Method: SetCurrentPosition() // Description: The TDx_SoundBuffer::SetCurrentPosition method will set // the play position for a secondary sound buffer. // // This method cannot be used on primary sound buffers. // When playing, the buffer will jump to the designated // position and continue to play. // When stopped, the buffer will begin playing from the // designated position the next time TDx_SoundBuffer::Play() // is called. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pNewPosition - // The NewPosition parameter defines the new offset, in // bytes, of the play cursor within the buffer. // ---------------------------------------------------------------------- virtual bool __fastcall SetCurrentPosition( dword pNewPosition ); // ---------------------------------------------------------------------- // Method: SetFormat() // Description: The TDx_SoundBuffer::SetFormat method will set the // primary sound buffer format for the application. // // The application must hold at least the DSSCL_PRIORITY // cooperative level for this method to succeed. // // Whenever the application has the input focus, the primary // buffer will be set to the specified format. // // When the DSSCL_WRITEPRIMARY cooperative level is being // used, the buffer must be explicitly stopped and started // for the SetFormat call. The buffer will be automatically // stopped and started for the other cooperative levels. // // Setting an unsupported format will still succeed. The // closest supported format will be used and conversion from // the requested format will be performed during mixing. // This may cause some performance loss. Compare the // specified format with that retrieved using // TDx_SoundBuffer::GetFormat() to determine if this is // being done. // // To change the data format for a secondary sound buffer, // recreate the buffer with the new format. // // Compressed audio formats are not currently supported and // must be converted to pulse-code modulation (PCM) before // writing to a sound buffer. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_BADFORMAT // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_OUTOFMEMORY // DSERR_PRIOLEVELNEEDED // DSERR_UNSUPPORTED // Params: pFormat - // The Format parameter references a WAVEFORMATEX structure // which describes the new primary sound buffer format. // ---------------------------------------------------------------------- virtual bool __fastcall SetFormat( const WAVEFORMATEX* pFormat ); // ---------------------------------------------------------------------- // Method: SetFrequency() // Description: The TDx_SoundBuffer::SetFrequency method will define the // playing frequency, in Hertz, of audio samples for a // secondary sound buffer. // // The minimum and maximum frequencies are defined in the // dsound.h DSBFREQUENCY_MIN and DSBFREQUENCY_MAX members as // 100 and 100,000 respectively. // // Changing frequency modifies the pitch of audio data, not // the format. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_CONTROLUNAVAIL // DSERR_GENERIC // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pFrequency - // The Frequency parameter defines the frequency, in hertz, // at which audio samples are to be played by the buffer. // // DSBFREQUENCY_ORIGINAL may be used to restore the original // frequency defined in the format used when creating the // buffer. // ---------------------------------------------------------------------- virtual bool __fastcall SetFrequency( dword pFrequency ); // ---------------------------------------------------------------------- // Method: SetPan() // Description: The TDx_SoundBuffer::SetPan method will set the relative // volume for the left and right audio channels. // // The left, right and center pan values are defined in the // dsound.h DSBPAN_LEFT, DSBPAN_RIGHT and DSBPAN_CENTER // members as -10,000, 10,000 and 0 respectively. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_CONTROLUNAVAIL // DSERR_GENERIC // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pPan - // The Pan parameter defines the relative volume of the left // and right channels. // Displacement to the negative represents attenuation, in // 100ths of a decibel, of the right channel and // displacement to the positive represents attentuation to // the left channel in a similar manner. // ---------------------------------------------------------------------- virtual bool __fastcall SetPan( long pPan ); // ---------------------------------------------------------------------- // Method: SetVolume() // Description: The TDx_SoundBuffer::SetVolume method will set the // volume, in 100ths of a decibel, for the sound buffer. // // The minimum and maximum volumes are defined in the // dsound.h DSBVOLUME_MIN and DSBVOLUME_MAX members as // -10,000 and 0 respectively. // // Minimum volume indicates the sound is attenuated by 100 // decibels while the maximum volume represents the original // unadjusted volume of the sound. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_CONTROLUNAVAIL // DSERR_GENERIC // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pVolume - // The Volume parameter defines the volume, in 100ths of a // decibel, to be set for the buffer. // ---------------------------------------------------------------------- virtual bool __fastcall SetVolume( long pVolume ); // ---------------------------------------------------------------------- // Method: Stop() // Description: The TDx_SoundBuffer::Stop method will halt the playing of // the sound buffer. // // The play position of a secondary buffer will be set to // the next sample to be played. Play will resume from where // the buffer was stopped. // // When called on a primary buffer utilizing the // DSSCL_WRITEPRIMARY cooperative level, the buffer will be // stopped and the play position reset to 0. This is done // because most sound devices can only play from the // beginning of the primary buffer. // // For other cooperative levels, this method will reverse // the effects of TDx_SoundBuffer::Play() being called on a // primary buffer. // That is, the buffer will stop whenever there are no // secondary buffers playing. The buffer will not actually // stop playing until all the secondary buffers of this or // any other application have stopped. // // If the method call fails, the OnError event will be // triggered with one of the following values: // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // ---------------------------------------------------------------------- virtual bool __fastcall Stop(); // ---------------------------------------------------------------------- // Method: Unlock() // Description: The TDx_SoundBuffer::Unlock method will release the sound // buffer area previously locked by TDx_SoundBuffer::Lock(). // // Both pointers and both byte values returned by // TDx_SoundBuffer::Lock() must be supplied, even if 0 bytes // were written to the second pointer. // // Do not lock the sound buffer for long periods of time as // the play cursor could reach the locked bytes and // configuration dependent audio problems may result. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // DSERR_INVALIDCALL // DSERR_INVALIDPARAM // DSERR_PRIOLEVELNEEDED // Params: pAudioPtr1 - // The AudioPtr1parameter should reference the value // returned in the AudioPtr1 parameter of // TDx_SoundBuffer::Lock(). // pAudioBytes1 - // The AudioBytes1 parameter defines the number of bytes // written to the area referenced by the AudioPtr1 // parameter. // pAudioPtr2 - // The AudioPtr2 parameter should reference the value // returned in the AudioPtr2 parameter of // TDx_SoundBuffer::Lock(). // pAudioBytes2 - // The AudioBytes2 parameter defines the number of bytes // written to the area referenced by the AudioPtr2 // parameter. // ---------------------------------------------------------------------- virtual bool __fastcall Unlock( void* pAudioPtr1, dword pAudioBytes1, void* pAudioPtr2, dword pAudioBytes2 ); // ---------------------------------------------------------------------- // Method: WriteToStream() // Description: The WriteToStream method will write a specified amount of // sound data to the current .wav file. // // If the method call fails, the OnError event will be // triggered with one of the following values: // TDX_BADPARAMS // TDX_ERROR // Params: pBytesToWrite - // The BytesToWrite parameter defines the amount, in bytes, // of sound data to write to the current .wav file. // pSoundData - // The SoundData parameter references the array of bytes // that will be written to the current .wav file. // // This parameter may be set to one of the pointers returned // by TDx_SoundBuffer::Lock() to write sound data directly // from the sound buffer. // pBytesActuallyWritten - // The BytesActuallyWritten parameter will reference the // amount, in bytes, that was actually written to the file // if this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall WriteToStream( dword pBytesToWrite, byte* pSoundData, dword* pBytesActuallyWritten ); // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDx_SoundBuffer(TComponent* Owner); virtual __fastcall ~TDx_SoundBuffer(); // ---------------------------------------------------------------------- // The following properties and methods are used internally by // TDx_Sound_Library and should not be used. // ---------------------------------------------------------------------- __property LPDIRECTSOUNDBUFFER Internal_LPDIRECTSOUNDBUFFER = { read=FGetInternal_LPDIRECTSOUNDBUFFER, write=FSetInternal_LPDIRECTSOUNDBUFFER, nodefault }; __property LPDIRECTSOUNDBUFFER* Internal_LPDIRECTSOUNDBUFFER_Ptr = { read=FGetInternal_LPDIRECTSOUNDBUFFER_Ptr, nodefault }; void __fastcall Internal_LPDIRECTSOUNDBUFFER_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Property: StreamHandle // Description: The StreamHandle property is used internally by the // TDx_SoundBuffer component to implement sound streaming. // ---------------------------------------------------------------------- __property int StreamHandle = { read=FGetStreamHandle, default=-1 }; // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- bool __fastcall FGetCreated(); void __fastcall FSetCreated( bool pCreated ); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); dword __fastcall FGetFrequency(); void __fastcall FSetFrequency( dword pFrequency ); long __fastcall FGetPan(); void __fastcall FSetPan( long pPan ); bool __fastcall FGetPlaying(); WAVEFORMATEX* __fastcall FGetStreamFormat(); int __fastcall FGetStreamHandle(); bool __fastcall FGetStreamIsOpen(); dword __fastcall FGetStreamSize(); void __fastcall FSetStreamSize( dword pStreamSize ); long __fastcall FGetVolume(); void __fastcall FSetVolume( long pVolume ); TDX_WAVE_FILE_FORMAT __fastcall FGetWaveFileFormat(); void __fastcall FSetWaveFileFormat( TDX_WAVE_FILE_FORMAT pWaveFileFormat ); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Internal Interface Access // ---------------------------------------------------------------------- LPDIRECTSOUNDBUFFER __fastcall FGetInternal_LPDIRECTSOUNDBUFFER(); void __fastcall FSetInternal_LPDIRECTSOUNDBUFFER( LPDIRECTSOUNDBUFFER pLPDIRECTSOUNDBUFFER ); LPDIRECTSOUNDBUFFER* __fastcall FGetInternal_LPDIRECTSOUNDBUFFER_Ptr(); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- bool fCreated; HRESULT fErrorValue; dword fFrequency; long fPan; bool fPlaying; WAVEFORMATEX* fStreamFormat; int fStreamHandle; bool fStreamIsOpen; dword fStreamSize; long fVolume; TDX_WAVE_FILE_FORMAT fWaveFileFormat; // ---------------------------------------------------------------------- // Interface Variables // ---------------------------------------------------------------------- LPDIRECTSOUNDBUFFER fLPDIRECTSOUNDBUFFER; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_Event FOnBufferLost; TDx_Event FOnCreate; TDx_Event FOnDestroy; TDx_Error FOnError; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------