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_SOFTWAREForce the stream to not use hardware mixing.
BASS_SAMPLE_3DUse 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono. The SPEAKER flags can not be used together with this flag.
BASS_SAMPLE_FXEnable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
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 can not be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
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_NOTAVAILOnly 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_FORMATThe 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_SPEAKERThe 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_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.

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

See also

BASS_Split_StreamGetSource, BASS_Split_StreamReset, BASS_Split_StreamResetEx, BASS_ATTRIB_SPLIT_ASYNCBUFFER, BASS_CONFIG_SPLIT_BUFFER

BASS_ChannelPlay, BASS_StreamFree