BASS_Split_StreamCreate
Creates a splitter stream.
HSTREAM BASS_Split_StreamCreate( DWORD channel, DWORD flags, int *chanmap );
Parameters
channel | The handle of the channel to split... a HMUSIC, HSTREAM or HRECORD. | ||||||||||||||||
flags | Any combination of these flags.
| ||||||||||||||||
chanmap | Channel mapping... pointer to an array of channel indexes (0=first, -1=end of array), NULL = a 1:1 mapping of the source. |
Return value
If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.Error codes
BASS_ERROR_INIT | BASS_Init has not been successfully called. |
BASS_ERROR_HANDLE | channel is not valid. |
BASS_ERROR_DECODE | channel is not a decoding channel. |
BASS_ERROR_ILLPARAM | chanmap contains an invalid channel index. |
BASS_ERROR_NOTAVAIL | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels. |
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported. |
BASS_ERROR_SPEAKER | The 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. |
BASS_ERROR_MEM | There is insufficient memory. |
BASS_ERROR_NO3D | Could not initialize 3D support. |
BASS_ERROR_UNKNOWN | Some other mystery problem! |
Remarks
A "splitter" basically does the opposite of a mixer: it splits a single source into multiple streams rather then mixing multiple sources into a single stream. Like mixer sources, splitter sources must be decoding channels.The splitter stream will have the same sample rate and resolution as its source, but it can have a different number of channels, as dictated by the chanmap parameter. Even when the number of channels is different (and so the amount of data produced is different), BASS_ChannelGetLength will give the source length, and BASS_ChannelGetPosition will give the source position that is currently being output by the splitter stream, unless the BASS_SPLIT_POS flag is used. The BASS_SPLIT_POS flag can be toggled at any time via BASS_ChannelFlags.
All splitter streams with the same source share a buffer to access its sample data. The length of the buffer is determined by the BASS_CONFIG_SPLIT_BUFFER config option; the splitter streams should not be allowed to drift apart beyond that, otherwise those left behind will suffer buffer overflows. Data will usually be requested from the source only when it is needed, but it can also be gotten ahead of time asynchronously instead via the BASS_ATTRIB_SPLIT_ASYNCBUFFER attribute, so that it is ready for the splitter(s) to access immediately when needed.
If the BASS_SPLIT_SLAVE flag is used, the splitter stream will only receive data from the buffer and will not request more data from the source, so it can only receive data that has already been received by another splitter stream with the same source. The BASS_SPLIT_SLAVE flag can be toggled at any time via BASS_ChannelFlags.
When BASS_ChannelSetPosition is used on a splitter stream, its source will be set to the requested position and the splitter stream's buffer state will be reset so that it immediately receives data from the new position. The position change will affect all of the source's splitter streams, but the others will not have their buffer state reset; they will continue to receive any buffered data before reaching the data from the new position. BASS_Split_StreamReset can be used to reset the buffer state; that can also be used to reset a splitter stream that has ended so that it can be played again.
When a source is freed, all of its splitter streams are automatically freed.
Platform-specific
Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored.Example
Create a splitter stream from a stereo source with the channels reversed.int chanmap[]={1, 0, -1}; // channel mapping: left = source right, right = source left split=BASS_Split_StreamCreate(source, 0, chanmap); // create the splitter stream