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

memTRUE = load the sample from memory.
fileFilename (mem = FALSE) or a memory location (mem = TRUE).
offsetFile offset to load the sample from (only used if mem = FALSE).
lengthData 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.
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_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 by streaming the file.
BASS_SAMPLE_MONOConvert 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_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.
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).
BASS_UNICODEfile 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_INITBASS_Init has not been successfully called.
BASS_ERROR_NOTAVAILSample functions are not available when using the "no sound" device.
BASS_ERROR_ILLPARAMmax and/or length is invalid. The length must be specified when loading from memory.
BASS_ERROR_FILEOPENThe file could not be opened.
BASS_ERROR_FILEFORMThe file's format is not recognised/supported.
BASS_ERROR_CODECThe 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_FORMATThe 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_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome 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.

See also

BASS_SampleCreate, BASS_SampleFree, BASS_SampleGetChannel, BASS_SampleGetInfo, BASS_StreamCreateFile