Creates/initializes a playback channel for a sample.
HCHANNEL BASS_SampleGetChannel( HSAMPLE handle, BOOL onlynew );
|handle||Handle of the sample to play.|
|onlynew||Do not recycle/override one of the sample's existing channels?|
|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.|
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).
HCHANNEL channel = BASS_SampleGetChannel(sample, FALSE); // get a sample channel BASS_ChannelPlay(channel, FALSE); // play it