TSdlAudioBuffer
A buffer that holds audio data in a specific format
Definition
Unit: Neslib.Sdl3.Audio
Properties
| Name | Description |
|---|---|
| Buffer | The audio data, in the format specified in Spec. |
| Size | The size of the audio data, in bytes. |
| Spec | Specifies the format of the audio in the buffer. |
Constructors
| Name | Description |
|---|---|
| Create(TSdlAudioFormat, Integer, Integer, TSdlAudioBuffer) | Creates a buffer from another buffer and converts it to the given format if needed. |
| Create(TSdlAudioFormat, Integer, Integer, Integer) | Creates a new audio buffer. |
| CreateFromWav(String) | Loads a WAV from a file path. |
| CreateFromWav(TSdlIOStream, Boolean) | Load the audio data of a WAVE file into this buffer. |
Methods
| Name | Description |
|---|---|
| Free | Frees the audio buffer |
| Mix | Mix audio data. |
Property Descriptions
Buffer
The audio data, in the format specified in Spec.
property Buffer: Pointer read FBuffer
Type: Pointer
Size
The size of the audio data, in bytes.
property Size: Integer read FSize
Type: Integer
Spec
Specifies the format of the audio in the buffer.
property Spec: TSdlAudioSpec read FSpec
Type: TSdlAudioSpec
Constructor Descriptions
Create
Creates a buffer from another buffer and converts it to the given format if needed.
Please note that this constructor is for convenience, but should not be used to resample audio in blocks, as it will introduce audio artifacts on the boundaries. You should only use this constructor if you are converting audio data in its entirety in one call. If you want to convert audio in smaller chunks, use an TSDlAudioStream, which is designed for this situation.
Internally, this function creates and destroys an TSdlAudioStream on each use, so it's also less efficient than using one directly, if you need to convert multiple times.
When the application is done with this buffer, it should call Free to dispose of it.
constructor Create(const AFormat: TSdlAudioFormat; const ANumChannels, AFreq: Integer; const ASrc: TSdlAudioBuffer); overload
Parameters
AFormat: TSdlAudioFormat
: The format of the audio in this buffer.
ANumChannels: Integer
: The number of audio channels for this buffer.
AFreq: Integer
: The sample frequency in Hz for this buffer.
ASrc: TSdlAudioBuffer
: The input audio buffer that will be converted.
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to call this constructor from any thread
Create
Creates a new audio buffer.
When the application is done with this buffer, it should call Free to dispose of it.
constructor Create(const AFormat: TSdlAudioFormat; const ASize, ANumChannels, AFreq: Integer); overload
Parameters
AFormat: TSdlAudioFormat
: The format of the audio in the buffer.
ASize: Integer
: The size in bytes of the buffer to create.
ANumChannels: Integer
: The number of audio channels.
AFreq: Integer
: The sample frequency in Hz.
See Also
CreateFromWav
Loads a WAV from a file path.
This constructor raises an error if the .WAV file cannot be opened, uses an unknown data format, or is corrupt.
When the application is done with this buffer, it should call Free to dispose of it.
constructor CreateFromWav(const APath: String); overload
Parameters
APath: String
: The file path of the WAV file to open.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to call this constructor from any thread
CreateFromWav
Load the audio data of a WAVE file into this buffer.
Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and mu-law (8 bits). Other formats are currently unsupported and cause an error.
It's necessary to use Free to free this buffer when it is no longer used.
Because of the underspecification of the .WAV format, there are many problematic files in the wild that cause issues with strict decoders. To provide compatibility with these files, this decoder is lenient in regards to the truncation of the file, the fact chunk, and the size of the RIFF chunk. The hints TSdlHints.WaveRiffChunkSize, TSdlHints.WaveTruncation, and TSdlHints.WaveFactChunk can be used to tune the behavior of the loading process.
Any file that is invalid (due to truncation, corruption, or wrong values in the headers), too big, or unsupported causes an error. Additionally, any critical I/O error from the data source will terminate the loading process with an error.
It is required that the data source supports seeking.
This constructor raises an error if the .WAV file cannot be opened, uses an unknown data format, or is corrupt.
When the application is done with this buffer, it should call Free to dispose of it.
constructor CreateFromWav(const ASrc: TSdlIOStream; const ACloseIO: Boolean); overload
Parameters
ASrc: TSdlIOStream
: The data source for the WAVE data.
ACloseIO: Boolean
: If True, calls TSdlIOStream.Close on ASrc before returning, even in the case of an error.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to call this constructor from any thread
Method Descriptions
Free
Frees the audio buffer
procedure Free; inline
Mix(TSdlAudioBuffer, Integer, Single)
Mix audio data.
This mixes ASrc into this buffer, performing addition, volume adjustment, and overflow clipping.
The ASrc buffer must be in the same format as this buffer.
This is provided for convenience -- you can mix your own audio data.
Do not use this method for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input (not to mention this being an inefficient way of doing it).
It is a common misconception that this method is required to write audio data to an output stream in an audio callback. While you can do that, this method is really only needed when you're mixing a single audio stream with a volume adjustment.
procedure Mix(const ASrc: TSdlAudioBuffer; const ASize: Integer = 0; const AVolume: Single = 1)
Exceptions
ESdlError: Raised on failure.
Parameters
ASrc: TSdlAudioBuffer
: The source audio buffer to be mixed.
ASize: Integer = 0
: (Optional) size in bytes of the audio buffers. If 0 (the default), it will use the minimum size of the 2 buffers.
AVolume: Single = 1
: (Optional) volume, ranging from 0.0 - 1.0, and should be set to 1.0 (default) for full audio volume.
Remarks
It is safe to call this method from any thread