BASS_SampleGetChannel

Creates/initializes a playback channel for a sample.

DWORD BASS_SampleGetChannel(
    HSAMPLE handle,
    DWORD flags
);

Parameters

handleHandle of the sample.
flagsA combination of these flags.
BASS_SAMCHAN_NEWDo not recycle/override one of the sample's existing channels.
BASS_SAMCHAN_STREAMCreate a stream (HSTREAM) rather than a sample channel (HCHANNEL).
BASS_SAMPLE_LOOPLoop the sample. This is applied automatically if it has been set in the sample's default flags.
BASS_SAMPLE_OVER_VOLOverride: the channel with the lowest volume is overridden. If no override flags are specified then the sample's default override flags will be used.
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_STREAM_AUTOFREEAutomatically free the stream when playback ends. This flag is ignored without BASS_SAMCHAN_STREAM.
BASS_STREAM_DECODEDecode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. This flag is ignored without BASS_SAMCHAN_STREAM.
BASS_SPEAKER_xxxSpeaker assignment flags. These flags have no effect when the sample is more than stereo.

Return value

If successful, the handle of the new channel is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not a valid sample handle.
BASS_ERROR_NOCHANThe sample has no free channels, and the BASS_SAMCHAN_NEW flag was specified or no BASS_SAMPLE_OVER flag was.
BASS_ERROR_TIMEOUTThe sample's minimum time gap (see BASS_SAMPLE) has not yet passed since the last channel was created.
BASS_ERROR_NOTAVAILThe BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.

Remarks

A sample can be played in two ways: with a sample channel (HCHANNEL) or a stream (HSTREAM). A sample channel is a bit more CPU and memory efficient, while a stream has more features available, eg. DSP/FX and synchronization. In either case, they all share the same sample data, and just have their own individual state information (volume/position/etc).

Use BASS_SampleGetInfo and BASS_SampleSetInfo to set a sample's default attributes, which are used when creating a channel. After creation, a channel's attributes can be changed via BASS_ChannelSetAttribute, BASS_ChannelSet3DAttributes and BASS_ChannelSet3DPosition. BASS_Apply3D should be called before starting playback of a 3D sample, even if you just want to use the default settings.

The number of sample streams (HSTREAM) is unlimited. The number of sample channels (HCHANNEL) is limited to the sample's max value (set during creation or via BASS_SampleSetInfo), and existing channels can be overridden when needed for new ones. When channel overriding has been enabled (via a BASS_SAMPLE_OVER flag) and there are multiple candidates for overriding (eg. with identical volume), the oldest of them will be chosen to make way for the new channel.

If a sample has a max setting of 1 then a HCHANNEL handle (not HSTREAM) returned will be identical to the HSAMPLE handle (unless disabled via the BASS_CONFIG_SAMPLE_ONEHANDLE config option). This means you can use the HSAMPLE handle with functions that usually require a HCHANNEL handle, but you must still call this function first to initialize the channel.

A sample channel (HCHANNEL) is automatically freed when it is overridden by a new channel, or when stopped by BASS_ChannelStop, BASS_SampleStop or BASS_Stop. If you wish to stop a channel and re-use it, BASS_ChannelPause should be used to pause it instead. Determining whether a channel still exists can be done by trying to use the handle in a function call. A list of all the sample's existing channels can also be retrieved via BASS_SampleGetChannels.

A new sample channel (HCHANNEL) will have an initial state of being paused (BASS_ACTIVE_PAUSED). This prevents the channel being claimed by another call of this function before it has been played, unless it gets overridden due to a lack of free channels.

Example

Play a sample with its default settings.
HCHANNEL channel = BASS_SampleGetChannel(sample, 0); // get a sample channel
BASS_ChannelStart(channel); // play it

See also

BASS_ChannelPlay, BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttribute, BASS_SampleCreate, BASS_SampleGetChannels, BASS_SampleLoad, BASS_SampleStop, BASS_CONFIG_SRC_SAMPLE