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.

BASS_SAMPLE_3D	Enable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_STREAM_AUTOFREE	Automatically free the stream when playback ends.
BASS_STREAM_DECODE	Render 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_POS	The splitter's length and position is based on the splitter's (rather than the source's) channel count.
BASS_SPLIT_SLAVE	Only get data from the splitter buffer, not directly from the source.
BASS_SPEAKER_xxx	Speaker assignment flags. These flags have no effect when the stream is more than stereo.

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	The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_FORMAT	The sample format is not supported.
BASS_ERROR_SPEAKER	The specified SPEAKER flags are invalid.
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.

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.