BASS_SampleCreate

Creates a new sample.

HSAMPLE BASS_SampleCreate(
    DWORD length,
    DWORD freq,
    DWORD chans,
    DWORD max,
    DWORD flags
);

Parameters

length

The sample's length, in bytes.

freq

The default sample rate.

chans

The number of channels... 1 = mono, 2 = stereo, etc.

max

Maximum number of simultaneous playbacks... 1 (min) - 65535 (max)... use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).

flags

A combination of these flags.

BASS_SAMPLE_8BITS	Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the sample is 16-bit.
BASS_SAMPLE_FLOAT	Use 32-bit floating-point sample data. Not really recommended for samples as it (at least) doubles the memory usage.
BASS_SAMPLE_LOOP	Looped? Note that only complete sample loops are allowed; you cannot loop just a part of the sample. More fancy looping can be achieved via streaming.
BASS_SAMPLE_SOFTWARE	Force the sample to not use hardware mixing.
BASS_SAMPLE_VAM	Enables the DX7 voice allocation and management features on the sample, which allows the sample to be played in software or hardware. This flag is ignored if the BASS_SAMPLE_SOFTWARE flag is also specified.
BASS_SAMPLE_3D	Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the sample must be mono (chans=1).
BASS_SAMPLE_MUTEMAX	Mute the sample when it is at (or beyond) its max distance (software-mixed 3D samples only).
BASS_SAMPLE_OVER_VOL	Override: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POS	Override: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DIST	Override: the channel furthest away (from the listener) is overridden (3D samples only).

Return value

If successful, the new sample's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT	BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL	Sample functions are not available when using the "no sound" device.
BASS_ERROR_ILLPARAM	max is invalid.
BASS_ERROR_FORMAT	The sample format is not supported by the device/drivers.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_NO3D	Could not initialize 3D support.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

The sample's initial content is undefined. BASS_SampleSetData should be used to set the sample's data.

Unless the BASS_SAMPLE_SOFTWARE flag is used, the sample will use hardware mixing if hardware resources are available. Use BASS_GetInfo to see if there are hardware mixing resources available, and which sample formats are supported by the hardware. The BASS_SAMPLE_VAM flag allows a sample to be played by both hardware and software, with the decision made when the sample is played rather than when it is loaded. A sample's VAM options are set via BASS_SampleSetInfo.

To play a sample, first a channel must be obtained using BASS_SampleGetChannel, which can then be played using BASS_ChannelPlay.

If you want to play a large or one-off sample, then it would probably be better to stream it instead with BASS_StreamCreate.

Platform-specific

The BASS_SAMPLE_VAM flag requires DirectX 7 (or above). Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary.

Example

Create a 440 Hz sine wave sample.

HSAMPLE sample=BASS_SampleCreate(256, 28160, 1, 1, BASS_SAMPLE_LOOP|BASS_SAMPLE_OVER_POS); // create sample
short data[128]; // data buffer
int a;
for (a=0; a<128; a++)
    data[a]=(short)(32767.0*sin((double)a*6.283185/64)); // sine wave
BASS_SampleSetData(sample, data); // set the sample's data

BASS