BASS_Mixer_StreamCreate
Creates a mixer stream.
HSTREAM BASS_Mixer_StreamCreate(
DWORD freq,
DWORD chans,
DWORD flags
);
Parameters
| freq | The sample rate of the mixer output.
|
| chans | The number of channels... 1 = mono, 2 = stereo, 4 = quadraphonic, 6 = 5.1, 8 = 7.1.
|
| flags | Any combination of these flags.
| BASS_SAMPLE_8BITS | Produce 8-bit output. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the stream is 16-bit.
| | BASS_SAMPLE_FLOAT | Produce 32-bit floating-point output. See Floating-point channels for more info.
| | BASS_SAMPLE_SOFTWARE | Force the stream to not use hardware DirectSound mixing. Note this only applies to playback of the mixer's output; the mixing of the source channels is always performed by BASSmix.
| | BASS_SAMPLE_3D | Use 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono (chans=1). The SPEAKER flags can not be used together with this flag.
| | BASS_SAMPLE_FX | Enable 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_AUTOFREE | Automatically free the stream when playback ends.
| | BASS_STREAM_DECODE | Mix the sample data, without playing it. Use BASS_ChannelGetData to retrieve the mixed sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags can not be used together with this flag. The BASS_SAMPLE_SOFTWARE, BASS_SAMPLE_FX and BASS_MIXER_RESUME flags are also ignored.
| | BASS_MIXER_END | End the stream when there are no active (including stalled) source channels, else it is never-ending.
| | BASS_MIXER_NONSTOP | Do not stop producing output when there are no active source channels, else it will be stalled until there are active sources.
| | BASS_MIXER_POSEX | Keep a record of the source positions, making it possible to account for output latency when retrieving a source position. How far back the position record goes is determined by the BASS_CONFIG_MIXER_POSEX config option. If this flag is not used and neither is the BASS_STREAM_DECODE flag, then the mixer will automatically have a position record of equal length to the BASS_CONFIG_BUFFER setting.
| | BASS_MIXER_RESUME | When stalled, resume the mixer immediately upon a source being added or unpaused, else it will be resumed at the next update cycle.
| | BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
|
|
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_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
Source channels are "plugged" into a mixer using the BASS_Mixer_StreamAddChannel or BASS_Mixer_StreamAddChannelEx functions, and "unplugged" using the BASS_Mixer_ChannelRemove function. Sources can be added and removed at any time, so a mixer does not have a predetermined length and BASS_ChannelGetLength is not applicable. Likewise, seeking is not possible, except to position 0, as described below.
If the mixer output is being played, there will be some delay in the effect of adding/removing source channels or changing their attributes being heard, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute. The playback buffer can be flushed by calling BASS_ChannelPlay (restart = TRUE) or BASS_ChannelSetPosition (pos = 0). That can also be done to restart a mixer that has ended.
Unless the BASS_MIXER_END flag is specified, a mixer stream will never end. When there are no sources (or the sources have ended/stalled), it will produce no output until there is an active source. That is unless the BASS_MIXER_NONSTOP flag is used, in which case it will produce silent output while there are no active sources. The BASS_MIXER_END and BASS_MIXER_NONSTOP flags can be toggled at any time, using BASS_ChannelFlags.
Besides mixing channels, a mixer stream can be used for sample rate conversion. In that case the freq parameter would be set to the new sample rate, and the source channel's attributes would be left at their defaults. A mixer stream can also be used to downmix, upmix and generally rearrange channels, using the matrix mixing features.
See also
BASS_Mixer_StreamAddChannel, BASS_Mixer_StreamAddChannelEx
BASS_ChannelPlay, BASS_StreamFree