BASS_SampleCreate


Creates a new sample.

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

Parameters

lengthThe sample's length, in bytes.
freqThe default sample rate.
chansThe number of channels... 1 = mono, 2 = stereo, etc.
maxMaximum 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).
flagsA combination of these flags.
BASS_SAMPLE_8BITSUse 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the sample is 16-bit.
BASS_SAMPLE_FLOATUse 32-bit floating-point sample data. Not really recommended for samples as it (at least) doubles the memory usage.
BASS_SAMPLE_LOOPLooped? 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_SOFTWAREForce the sample to not use hardware mixing.
BASS_SAMPLE_VAMEnables 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_3DEnable 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_MUTEMAXMute the sample when it is at (or beyond) its max distance (software-mixed 3D samples only).
BASS_SAMPLE_OVER_VOLOverride: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POSOverride: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DISTOverride: 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_INITBASS_Init has not been successfully called.
BASS_ERROR_NOTAVAILSample functions are not available when using the "no sound" device.
BASS_ERROR_ILLPARAMmax is invalid.
BASS_ERROR_FORMATThe sample format is not supported by the device/drivers.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome 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

See also

BASS_SampleLoad, BASS_SampleSetData, BASS_StreamCreate