BASS_SampleLoad

Loads a WAV, AIFF, MP3, MP2, MP1, OGG or plugin supported sample.

HSAMPLE BASS_SampleLoad(
    BOOL mem,
    void *file,
    QWORD offset,
    DWORD length,
    DWORD max,
    DWORD flags
);

Parameters

mem

TRUE = load the sample from memory.

file

Filename (mem = FALSE) or a memory location (mem = TRUE).

offset

File offset to load the sample from (only used if mem = FALSE).

length

Data length... 0 = use all data up to the end of file (if mem = FALSE). If length over-runs the end of the file, it will automatically be lowered to the end of the file.

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_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 by streaming the file.
BASS_SAMPLE_MONO	Convert the sample (MP3/MP2/MP1 only) to mono, if it is not already. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
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.
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).
BASS_UNICODE	file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.

Return value

If successful, the loaded 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 and/or length is invalid. The length must be specified when loading from memory.
BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file's format is not recognised/supported.
BASS_ERROR_CODEC	The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMAT	The sample format is not supported by the device/drivers. If the sample is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_NO3D	Could not initialize 3D support.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

This function supports the same file formats as BASS_StreamCreateFile does, including those supported via the plugin system.

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.

After loading a sample from memory (mem = TRUE), the memory can safely be discarded, as a copy is made.

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

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.

BASS