BASS_Split_StreamCreate

Creates a splitter stream.

HSTREAM BASS_Split_StreamCreate(
    DWORD channel,
    DWORD flags,
    int *chanmap
);

Parameters

channelThe handle of the channel to split... a HMUSIC, HSTREAM or HRECORD.
flagsAny combination of these flags.
BASS_SAMPLE_3DEnable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_STREAM_AUTOFREEAutomatically free the stream when playback ends.
BASS_STREAM_DECODERender the sample data, without playing it. Use BASS_ChannelGetData to retrieve the sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag.
BASS_SPLIT_POSThe splitter's length and position is based on the splitter's (rather than the source's) channel count.
BASS_SPLIT_SLAVEOnly get data from the splitter buffer, not directly from the source.
BASS_SPEAKER_xxxSpeaker assignment flags. These flags have no effect when the stream is more than stereo.
chanmapChannel 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_INITBASS_Init has not been successfully called.
BASS_ERROR_HANDLEchannel is not valid.
BASS_ERROR_DECODEchannel is not a decoding channel.
BASS_ERROR_ILLPARAMchanmap contains an invalid channel index.
BASS_ERROR_NOTAVAILThe BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_FORMATThe sample format is not supported.
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome 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.

The source can be a "dummy" stream (STREAMPROC_DUMMY). In that case, the BASS_SPLIT_SLAVE flag is set automatically because the splitters can only receive data as it is processed rather than request it.

When a source is freed, all of its splitter streams are automatically freed.

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

See also

BASS_Split_StreamGetSource, BASS_Split_StreamReset, BASS_Split_StreamResetEx, BASS_ATTRIB_SPLIT_ASYNCBUFFER, BASS_CONFIG_SPLIT_BUFFER

BASS_ChannelPlay, BASS_StreamFree