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?|
Return valueIf successful, the handle of the new channel is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.
|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.|
RemarksUse 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).
ExamplePlay a sample with its default settings.
HCHANNEL channel=BASS_SampleGetChannel(sample, FALSE); // get a sample channel BASS_ChannelPlay(channel, FALSE); // play it