BASS_SampleGetChannel

Creates/initializes a playback channel for a sample.

HCHANNEL BASS_SampleGetChannel(
    HSAMPLE handle,
    BOOL onlynew
);

Parameters

handle	Handle of the sample to play.
onlynew	Do not recycle/override one of the sample's existing channels?

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_HANDLE	handle is not a valid sample handle.
BASS_ERROR_NOCHAN	The sample has no free channels... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specified for the sample or onlynew = TRUE.
BASS_ERROR_TIMEOUT	The sample's minimum time gap (BASS_SAMPLE) has not yet passed since the last channel was created.

Remarks

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.

If a sample has a maximum number of simultaneous playbacks of 1 (the max parameter was 1 when calling BASS_SampleLoad or BASS_SampleCreate), then the HCHANNEL handle returned will be identical to the HSAMPLE handle. That 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.

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.

A sample channel is automatically freed when it's 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.

The new channel 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.

All of a sample's channels share the same sample data, and just have their own individual playback state information (volume/position/etc).

Example

Play a sample with its default settings.

HCHANNEL channel=BASS_SampleGetChannel(sample, FALSE); // get a sample channel
BASS_ChannelPlay(channel, FALSE); // play it

BASS