DelphiSound Documentation

Copyright © 1999 by Alixoft, LLC. All rights reserved worldwide.

The DelphiSound package consists of two (2) primary objects: DXSPlay and DXSRec. DXSPlay controls DirectX DirectSound Playback Buffers while DXSRec controls a single DirectX DirectSound Capture Buffer. Generally, DirectX supports only one capture buffer at this time. (DirectX 6.0).

DXSPlay

Types

TafDXSPlayStaticBuffer The static playback buffer class

TafDXSPlayStreamingBuffer The streaming buffer playback class

Properties and Methods:

Create and free the DXSPlay object. There can be only one DXSPlay object in your application.

procedure DXSPlay_Init(AOwner : TComponent; Handle : HWND; CooperativeLevel : Integer);

procedure DXSPlay_Free;

StaticBuffers : TList; A list of the static buffers in use.

StreamingBuffers : TList; A list of the streaming buffers in use.

Never manipulate these lists directly (never add to or remove from them).

function SetPrimaryFormat(Channels, Bits : Integer; SamplesPerSecond : Longint) : Boolean;

procedure SetCooperativeLevel(CooperativeLevel : Integer);

Used to set the primary sound buffer and DirectSound Cooperative level.

property Ready : Boolean; Is DirectSound Playback object ready?

property OnError : TafDXSOnError; Event handler for errors

property ErrorDescription : String; A text description of the last error

Functions to manage Static Buffers

function NewStaticBuffer(Flags : Longint) : TafDXSPlayStaticBuffer;

function NewStaticBuffer(Name : String; Flags : Longint) : TafDXSPlayStaticBuffer;

function StaticBuffer(Name : String) : TafDXSPlayStaticBuffer;

function StaticBuffer(Index : Longint) : TafDXSPlayStaticBuffer;

Functions to manage Streaming Buffers

function NewStreamingBuffer(Channels, Bits : Integer; SamplesPerSecond, Flags, BufferSize : Longint) : TafDXSPlayStreamingBuffer;

function NewStreamingBuffer(Name : String; Channels, Bits : Integer; SamplesPerSecond, Flags, BufferSize : Longint) : TafDXSPlayStreamingBuffer;

function StreamingBuffer(Name : String) : TafDXSPlayStreamingBuffer;

function StreamingBuffer(Index : Longint) : TafDXSPlayStreamingBuffer;

Return the Playback capabilities in the DirectSound structure

property Capabilities : TDSCaps;

Return the Playback capabilities independently

property Flags : Cardinal;

property MinSecondarySampleRate : Cardinal;

property MaxSecondarySampleRate : Cardinal;

property PrimaryBuffers : Cardinal;

property MaxHwMixingAllBuffers : Cardinal;

property MaxHwMixingStaticBuffers : Cardinal;

property MaxHwMixingStreamingBuffers : Cardinal;

property FreeHwMixingAllBuffers : Cardinal;

property FreeHwMixingStaticBuffers : Cardinal;

property FreeHwMixingStreamingBuffers : Cardinal;

property MaxHw3DAllBuffers : Cardinal;

property MaxHw3DStaticBuffers : Cardinal;

property MaxHw3DStreamingBuffers : Cardinal;

property FreeHw3DAllBuffers : Cardinal;

property FreeHw3DStaticBuffers : Cardinal;

property FreeHw3DStreamingBuffers : Cardinal;

property TotalHwMemBytes : Cardinal;

property FreeHwMemBytes : Cardinal;;

property MaxContigFreeHwMemBytes : Cardinal;

property UnlockTransferRateHwBuffers : Cardinal;

property PlayCpuOverheadSwBuffers : Cardinal;

Description

The DXSPlay object must be instantiated through a call to DXSPlay_Init. This creates the single DXSPlay object and sets the owner, handle and cooperative level. If you need to set the Primary Buffer you should do this next with a call to DXSPlay.SetCooperativeLevel.

From then on, you can make use of the Capabilities properties to determine the sound system ability, and create sound buffers for further manipulation. Static sound buffers are buffers whose entire sound data is stored in computer memory. Streaming sound buffers contain only a part of the sound data they will play, and additional data must be "streamed" in to the buffer from time to time to continue the playback uninterrupted. Both can be created with calls to DXSPlay.NewStaticBuffer and DXSPlay.NewStreamingBuffer respectively.

These calls will return the buffer object. You may manage these objects yourself, but the DXSPlay object will keep a list of them and free them on its release if they are not already freed. You must never manipulate the DXSPlay buffer lists. Doing so will allow buffers to remain un-terminated which will result in system problems. You may cycle through the buffer list, but always create a buffer with a call to NewXXXBuffer and free the buffer by calling the Buffer’s Free method (Buffer.Free).

Static Buffers

(TafDXSPlayStaticBuffer)

Properties and Methods

property Name : String; A name you may give the buffer

property Channels : Integer; The number of channels the buffer has (1 or 2)

property Bits : Integer; The number of bits the buffer uses (8 or 16)

property SamplesPerSecond : Longint; The Frequency of the buffer

property BufferFlags : DWORD; Flags used to create the buffer (DirectSound)

property Volume : Longint; Volume the buffer will play at

property Pan : DWORD; Pan (Left-Right) location of the buffer in space

property Frequency : DWORD; Frequency the buffer will play at

property Position : DWORD; Position in the buffer (to start playing)

property BufferSize : Longint; Size of the buffer in bytes

property UserString : String; A string the user may store information in

procedure Play; Play the buffer

procedure PlayLoop; Loop the buffer (play and repeat until stopped)

procedure Stop; Stop the buffer playback

property Status : TafDXSState; Status of the buffer

property StatusDescription : String; Text description of the buffer status

property OnError : TafDXSOnError; Buffer Error event handler

property ErrorDescription : String; Text description of the buffer’s last error

function ReadBuffer(var Ptr : Pointer; var Size : longint) : Boolean;

Stop the buffer and copy its contents to Pointer. If Pointer is nil, allocate the necessary buffersize and copy to Pointer. The developer must free this memory later (Freemem(Pointer, Size);)

function WriteBuffer(Ptr : Pointer; Size : longint) : Boolean;

Stop the buffer and copy the data referenced by Pointer into the buffer. (Buffer Channels, Bits and SamplesPerSecond remain as they were).

function WriteBuffer(Channels, Bits : Integer; SamplesPerSecond : Longint; Ptr : Pointer; Size : longint) : Boolean;

Stop the buffer and copy the data referenced by Pointer into the buffer. (Buffer Channels, Bits and SamplesPerSecond are set to new values).

procedure ClearBuffer; Stop and clear the buffer.

procedure LoadFromWaveFile(Filename : String);

Open the wave file and read its entire contents into the stopped buffer (Buffer Channels, Bits and SamplesPerSecond are set to the file’s values).

procedure SaveToWaveFile(Filename : String);

Stop the buffer and write its entire contents to the wave file (Buffer Channels, Bits and SamplesPerSecond are set in the file to the buffer’s values).

The Static Buffer should be created with a call to DXSPlay.NewStaticBuffer(Flags). Flags are any valid DirectSound Flags. This call returns the Buffer object. Once assigned, you can perform any operation on the buffer. Note many operations stop the buffer if it is in play (mostly data manipulation calls). Further, you must specify certain Flags in the NewStaticBuffer if you intend to manipulate the buffer’s Volume, Pan or Frequency.

The static buffer automatically sets its Static flag.

Static buffers are good for short repetative sounds, like foot steps or gun shots. The are also easily manipulated. You can copy the entire buffer to a new location in memory and play with the data byte by byte, then copy it back to the buffer and play it to achieve some sound effect (echo for instance).

If the sound is longer than 200,000 bytes a static buffer may not be ideal.

Streaming Buffers

(TafDXSPlayStreamingBuffer)

Properties and Methods

Streaming buffers include all methods and properties of the Static buffer (reproduced here for clarity)

property Name : String; A name you may give the buffer

property Channels : Integer; The number of channels the buffer has (1 or 2)

property Bits : Integer; The number of bits the buffer uses (8 or 16)

property SamplesPerSecond : Longint; The Frequency of the buffer

property BufferFlags : DWORD; Flags used to create the buffer (DirectSound)

property Volume : Longint; Volume the buffer will play at

property Pan : DWORD; Pan (Left-Right) location of the buffer in space

property Frequency : DWORD; Frequency the buffer will play at

property Position : DWORD; Position in the buffer (to start playing)

property BufferSize : Longint; Size of the buffer in bytes

property UserString : String; A string the user may store information in

procedure Play; Play the buffer

procedure PlayLoop; Loop the buffer (play and repeat until stopped)

procedure Stop; Stop the buffer playback

property Status : TafDXSState; Status of the buffer

property StatusDescription : String; Text description of the buffer status

property OnError : TafDXSOnError; Buffer Error event handler

property ErrorDescription : String; Text description of the buffer’s last error

function ReadBuffer(var Ptr : Pointer; var Size : longint) : Boolean;

Stop the buffer and copy its contents to Pointer. If Pointer is nil, allocate the necessary buffersize and copy to Pointer. The developer must free this memory later (Freemem(Pointer, Size);)

function WriteBuffer(Ptr : Pointer; Size : longint) : Boolean;

Stop the buffer and copy the data referenced by Pointer into the buffer. (Buffer Channels, Bits and SamplesPerSecond remain as they were).

function WriteBuffer(Channels, Bits : Integer; SamplesPerSecond : Longint; Ptr : Pointer; Size : longint) : Boolean;

Stop the buffer and copy the data referenced by Pointer into the buffer. (Buffer Channels, Bits and SamplesPerSecond are set to new values).

procedure ClearBuffer; Stop and clear the buffer.

procedure LoadFromWaveFile(Filename : String);

Open the wave file and read its entire contents into the stopped buffer (Buffer Channels, Bits and SamplesPerSecond are set to the file’s values).

procedure SaveToWaveFile(Filename : String);

Stop the buffer and write its entire contents to the wave file (Buffer Channels, Bits and SamplesPerSecond are set in the file to the buffer’s values).

Plus the following additional methods and properties:

property OnDataRequired: TNotifyEvent; Event fired when the buffer needs audio data

property CleanBuffer : Boolean; When set to true, the buffer whipes itself clean as it plays (very useful). Defaults to True.

procedure InsertData(Buffer : Pointer; BufferSize : longint);

Add audio data to the buffer’s internal Queue. This data is played as required in a first in first out (FIFO) manor. BufferSize is the size of the data to insert. For smooth playback, it should be half of the Buffer’s actual BufferSize.

procedure PrimeBuffer; Put the first two audio Queue entries into the buffer. This is used before the buffer is played, but after some data has been given to the buffer to allow the buffer to start playing immediately.

procedure ClearQueue; Clear the buffer’s internal queue of audio data

function QueueCount : Longint; How many audio data chunks are waiting to be played by the buffer. Note the fact that there are 0 queue elements remaining does not mean the buffer has finished playing all data. It just means that it has no more to add to the output stream at that time.

The Streaming Buffer should be created with a call to DXSPlay.NewStreamingBuffer(Channels, Bits, SamplesPerSecond, Flags, BufferSize). Flags are any valid DirectSound Flags. BufferSize is the true size of the buffer in memory. Generally, the buffer is divided in to two (2) halves for playback streaming purposes. When data is inserted, it should be in (BufferSize div 2) sized chunks (for example).

This call returns the Buffer object. Once assigned, you can perform any operation on the buffer. Note many operations stop the buffer if it is in play (mostly data manipulation calls). Further, you must specify certain Flags in the NewStreamingBuffer if you intend to manipulate the buffer’s Volume, Pan or Frequency.

The streaming buffer automatically sets removes its Static flag and sets its control position notification flags.

Streaming buffers are good for long wave files or large streams of audio data. The are more difficult to manipulate, but they allow data to be added as they play.

If the sound is shorter than 50,000 bytes a static buffer is a better choice.

 

DXSRec

Types

TafDXSRecStreamingBuffer The streaming buffer playback class

Properties and Methods:

Create and free the DXSRec object. There can be only one DXSRec object in your application.

procedure DXSRec_Init(AOwner : TComponent);

procedure DXSRec_Free;

StreamingBuffer : TafDXSRecStreamingBuffer; The current streaming buffer

property Ready : Boolean; Is DirectSound Capture object ready?

property OnError : TafDXSOnError; Event handler for errors

property ErrorDescription : String; A text description of the last error

 

Functions to manage Streaming Buffers

function NewStreamingBuffer(Channels, Bits : Integer; SamplesPerSecond, Flags, BufferSize : Longint) : TafDXSRecStreamingBuffer;

function NewStreamingBuffer(Name : String; Channels, Bits : Integer; SamplesPerSecond, Flags, BufferSize : Longint) : TafDXSRecStreamingBuffer;

Return the Capture capabilities in the DirectSound structure

property Capabilities : TDSCCaps;

Description

The DXSRec object must be instantiated through a call to DXSRec_Init. This creates the single DXSRec object and sets the owner. If you need to use DirectSound Playback, this should be done first.

Once initialized, you can make use of the Capabilities property to determine the sound system ability, and create a single streaming buffer for further manipulation. The streaming capture buffer should be created with a call to DXSRec.NewStreamingBuffer.

This call will return the buffer object as well as place its pointer in the StreamingBuffer property. You may manage this object yourself, but the DXSRec object will keep note of it and free it on its release if it is not already freed. Do not alter the value of the StreamingBuffer property. It will automatically be reset to nil when the buffer is freed properly (Buffer.Free).

The Streaming Capture Buffer

(TafDXSRecStreamingBuffer)

Properties and Methods

property Name : String; A name you may give the buffer

property Channels : Integer; The number of channels the buffer has (1 or 2)

property Bits : Integer; The number of bits the buffer uses (8 or 16)

property SamplesPerSecond : Longint; The Frequency of the buffer

property BufferFlags : DWORD; Flags used to create the buffer (currently 0)

property Position : DWORD; Position in the buffer (to start playing)

property BufferSize : Longint; Size of the buffer in bytes

property UserString : String; A string the user may store information in

procedure Rec; Start the buffer capturing

procedure RecLoop; Loop the buffer (capture and repeat until stopped)

procedure Stop; Stop the buffer capture

property Status : TafDXSState; Status of the buffer

property StatusDescription : String; Text description of the buffer status

property OnError : TafDXSOnError; Buffer Error event handler

property ErrorDescription : String; Text description of the buffer’s last error

 

function ReadBuffer(var Ptr : Pointer; var Size : longint) : Boolean;

Stop the buffer and copy its contents to Pointer. If Pointer is nil, allocate the necessary buffersize and copy to Pointer. The developer must free this memory later (Freemem(Pointer, Size);)

procedure ClearBuffer; Stop and clear the buffer.

 

property OnDataAvailable:TNotifyEvent; Event fired when the buffer has audio data

procedure RetrieveData(var Buffer : Pointer; var BufferSize : longint);

Get audio data from the buffer’s internal Queue. This data is captured in a first in first out (FIFO) manor. BufferSize is the size of the data to retrieve. For smooth capture, it should be half of the Buffer’s actual BufferSize. If the pointer is nil, the Pointer and BufferSize are determined in the function and the Pointer allocated there. It then must be freed by the developer.

procedure ClearQueue; Clear the buffer’s internal queue of audio data

function QueueCount : Longint; How many audio data chunks are waiting to be retrieved by the developer.

The Capture Buffer should be created with a call to DXSRec.NewStreamingBuffer(Channels, Bits, SamplesPerSecond, Flags, BufferSize). Flags are any valid DirectSound Flags (0). BufferSize is the true size of the buffer in memory. Generally, the buffer is divided in to two (2) halves for capture streaming purposes. When data is retrieved, it should be in (BufferSize div 2) sized chunks (for example).

This call returns the Buffer object. Once assigned, you can perform any operation on the buffer. Note many operations stop the buffer if it is capturing (mostly data manipulation calls).

 

General Notes

Streaming Buffers should be sized to an even number. This is so that each half of the buffer is equally sized for capture or playback.

 

DXSUtil

(Wave file utilities)

Types

TafWAVEStream The wave stream class

Properties and Methods:

constructor Create(const FileName: string; Mode: Word);

property Bits : Integer; Bits in the file (8 or 16)

property Channels : Integer; Channels in the file (1 or 2)

property SamplesPerSecond : Longint; Frequency of the file

property Position : longint; Position to read/write in the file

property Size : Longint; Size of the file (bytes)

property Valid : Boolean; Is the file valid?

function Read(var Buffer; Count: Longint): Longint;

function Read(Position : Longint; var Buffer; Count: Longint): Longint;

function Write(const Buffer; Count: Longint): Longint;

function Write(Position : Longint; const Buffer; Count: Longint): Longint;

function Seek(Offset: Longint; Origin: Word): Longint;

Independent Functions:

function Load_WaveFileData_to_Buffer(Filename : String;

var BufferPtr : Pointer;

var BufferSize : Longint;

var Channels : Integer;

var Bits : Integer;

var SamplesPerSecond : Longint) : Boolean;

Load data into BufferPtr of Size BufferSize. If BufferPtr is nil, then it allocates the pointer and fills it with the entire file’s size. It also sets the Channels, Bits and SamplesPerSecond from the file.

function Save_Buffer_to_WaveFileData(Filename : String;

BufferPtr : Pointer;

BufferSize : Longint;

Channels : Integer;

Bits : Integer;

SamplesPerSecond : Longint) : Boolean;

Save data from BufferPtr of Size BufferSize to a file.

 

Types

The event handler definition for all buffer error events buffer

TafDXSOnError = procedure(Sender : TObject; Description : String) of Object;

Exceptions created by buffers

EDXSPlay_Exception = class(Exception); Playback buffer exceptions

EDXSRec_Exception = class(Exception); Capture buffer exceptions

 

Buffer State constants

TafDXSState = (DXSS_LOOPING, DXSS_PLAYING, DXSS_RECORDING, DXSS_STOPPED, DXSS_LOST, DXSS_UNKNOWN);

DirectSound Priority Levels (Defined in Dsound.Pas)

DSSCL_NORMAL = $00000001;

DSSCL_PRIORITY = $00000002;

DSSCL_EXCLUSIVE = $00000003;

DSSCL_WRITEPRIMARY = $00000004;

DirectSound Flags (Defined in Dsound.Pas)

DSBCAPS_STATIC = $00000002;

DSBCAPS_LOCHARDWARE = $00000004;

DSBCAPS_LOCSOFTWARE = $00000008;

DSBCAPS_CTRLFREQUENCY = $00000020;

DSBCAPS_CTRLPAN = $00000040;

DSBCAPS_CTRLVOLUME = $00000080;

DSBCAPS_CTRLDEFAULT = $000000E0;

DSBCAPS_CTRLALL = $000001F0;

DSBCAPS_STICKYFOCUS = $00004000;

DSBCAPS_GLOBALFOCUS = $00008000;

DSCBCAPS_WAVEMAPPED = $80000000;