BASS 0.8a - Copyright (c) 1999-2000 Ian Luck. All rights reserved
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Files that you should have found in the BASS "package"
======================================================
BASS.TXT      This file
BASS.DLL      The BASS module
BASS.CHM      BASS documentation
MO3.EXE       MO3 encoder
FILE_ID.DIZ   BBS description file
C\            C/C++ API and samples...
  BASS.H        BASS C/C++ header file
  BASS.LIB      BASS import library
  BASSTEST.EXE  BASS example program
  BASSTEST.C    Example program source-code
  BASSTEST.RC   Example program resource file
  BASSTEST.H    Example program resource header file
  CONTEST.EXE   BASS console example program
  CONTEST.C     Console example program source-code
  3DTEST.EXE    BASS 3D/A3D/EAX example program
  3DTEST.C      3D example program source-code
  3DTEST.RC     3D example program resource file
  3DTEST.H      3D example program resource header file
  ENGINE.WAV    3D example program test WAVE sample
  LOADNGET.C    LoadLibrary/GetProcAddress example source-code
  LOADNGET.RC   LoadLibrary/GetProcAddress example resource file
  DSPTEST.C     DSP example program source-code
  DSPTEST.RC    DSP example program resource file
  DSPTEST.H     DSP example program resource header file
VB\           Visual Basic API and samples...
  README.TXT    VB notes
  BASS.BAS      BASS Visual Basic Module file
  BASSTEST.VBP  Example program project file
  FRMMAIN.FRM   Main Form for BASSTEST Project
  3DTEST.VBP    3D example program Project File
  FRM3D.FRM     Main Form for 3D example program
  FRM3D.FRX     VB Data file to accompany FRM3D.FRM
DELPHI\       Delphi API and samples...
  README.TXT    Delphi API notes
  BASS.PAS      BASS Delphi unit
  3DTEST\       BASS 3D/A3D/EAX example project
    D3TEST.DPR    Project file
    D3TEST.DOF    Project options file
    DTMAIN.PAS    Main unit
    DTMAIN.DFM    Main form
    DTSELECT.PAS  Device selector unit
    DTSELECT.DFM  Device selector form
  BASSTEST\     BASS example project
    BASSTEST.DPR  Project file
    BASSTEST.DOF  Project options file
    BTMAIN.PAS    Main unit
    BTMAIN.DFM    Main form
  CONTEST\      BASS console example project
    CONTEST.DPR   Project file
    CONTEST.DOF   Project options file
  DSPTEST\      DSP example project
    DSPTEST.DPR   Project file
    DSPTEST.DOF   Project options file
    DTMAIN.PAS    Main unit
    DTMAIN.DFM    Main form
  STREAMTEST\   BASS stream example project
    STREAMTEST.DPR Project file
    STREAMTEST.DOF Project options file
    STMAIN.PAS    Main unit
    STMAIN.DFM    Main form

NOTE: The BASS ZIP should be decompressed with the directory stucture
      maintained. This should be automatic with any Windows unZIPper,
      but you'll have to use the '-d' option with PKUNZIP.

NOTE: To run the sample EXEs, first you'll have to copy BASS.DLL into
      the same directory as the EXEs. Or, you could put it somewhere
      in the path (eg. the WINDOWS directory).

What's the point?
=================
BASS is a sound system for use in Windows 95/98/2000/NT software. It's
purpose is to provide powerful (yet easy to use) sample, stream, MOD
music, and audio CD playback functions.

See the documentation for descriptions of all the BASS functions. You
will need to have Internet Explorer installed to view the documentation.
The BASS.H file also contains brief descriptions of the BASS functions.
You should also see the included example program source-codes for some
examples of how to use BASS in your own programs.

Requirements
============
BASS requires DirectX 3 or above, so it not only works with Windows
95/98/2000, but also Windows NT 4.0 (with service pack 4). BASS does
not require that a soundcard with DirectSound/DirectSound3D hardware
accelerated drivers is installed, but it does improve performance if
there is one. BASS also takes advantage of MMX acceleration, which
improves the performance of the MOD music playback.

Main Features
=============
* WAV samples
- supports mono/stereo 8/16 bit samples (including compressed)

* Custom samples
- generate or load custom samples

* Sample streams
- stream any sample data in mono/stereo 8/16 bit

* File streams
- MP3 and WAV (including compressed) file streaming

* MOD music
- uses the XMPlay engine = balls-on accurate reproduction

* MO3 music
- MP3 compressed MOD music

* CD audio
- play any track with a single function call

* Synchronization
- synchronize events in your program to the music

* User defined DSP functions
- custom effects may be applied to musics and streams

* 3D sound
- play samples/streams/musics in any 3D position

* Environmental Audio eXtensions (EAX)
- enhanced 3D sound with 3D reverberations

* New DirectX 7 features
- support for new 3D algorithm and voice management features

* Free!
- you may freely use BASS in your freeware games/demos/etc...

Samples
=======
BASS supports compressed and non-compressed mono/stereo 8/16 bit WAV
samples. Samples may be loaded from a file or a memory location. When
possible, samples are loaded into the hardware, so that they benefit
from "hardware acceleration". Use BASS_GetInfo to see which (if any)
sample formats are supported by the hardware.

You can set the max number of simultaneous playbacks for each sample,
and the override method to use when the max number has been reached.
The sample rate, volume, panning and looping are adjustable for each
playing sample.

BASS also allows you to use other sample formats (ie. not only WAVs),
by letting you generate the sample data.

NOTE: DirectSound only allows complete sample looping, you can't loop
      just a part of the sample.

Streams
=======
You can play a large amount of sample data without requiring a large
amount of memory, by using a sample stream. BASS allows streaming in
mono/stereo and 8/16 bit. The sample rate, volume and panning are
adjustable for each stream. Multiple sample streams can be played
simultaneously.

There are two options for streaming, either BASS streams it for you
(MP3 and WAV formats), or you create a function to write the stream
data. By creating your own stream writer functions, you can play any
sample format that is not supported by BASS, by decoding the data
into a stream.

BASS can automatically stream MP3 and WAV files, from either file or
memory. Only MPEG 1.0/2.0 layer 3 files are supported. Layers 1 and 2
are not supported. WAV files can be compressed with any CODEC, but the
CODEC is required to be installed on the user's computer for the WAV
to be decoded.

MOD Music
=========
BASS's MOD playback is based on the XMPlay engine. The XM/IT/MOD/S3M/MTM
formats are supported, with FastTracker2 and ProTracker1 options also
available for the MOD files. MODs can be loaded from a file or a memory
location. The MOD's samples are interpolated during mixing for superior
sound quality.

The looping, ramping (click removal), volume, amplification, and panning
seperation settings are all configurable, as is the balance and playback
rate. Multiple MOD musics can be played simultaneously.

You can synchronize events in your program to when a MOD reaches chosen
positions, and/or to when chosen instruments are played. The number of
synchronizers used is unlimited.

MO3 Music
=========
MO3s are treated and used in exactly the same way as normal MOD musics.
The advantage of MO3s is that they can be a lot smaller with virtually
identical quality. Playing a MO3 does not use any more CPU power than
playing the original MOD version does. The only difference is a longer
load time as the samples are being decoded.

MO3s are created using the provided MO3 encoder. The MO3 encoder uses
an external MP3 encoder to compress the samples. Settings for MP3ENC,
BLADEENC and LAME are provided.

MP3ENC has a good sound quality and maintains the sound shape well, but
it is shareware (ie. not free). BLADEENC is freeware and has a fairly
good sound quality, but it tends to slightly shortens the samples which
can be especially troublesome with looped samples. LAME's sound quality
is very good, and it usually also maintains the sample shape very well
(BEST AT SAMPLE RATES OF 32000HZ AND ABOVE). It also supports Variable
Bit Rate (VBR) encoding, and is freeware.

MP3ENC, BLADEENC and LAME are available from these websites:
    http://www.iis.fhg.de/amm/download/mp3enc/index.html
    http://www.bladeenc.cjb.net/
    http://www.chat.ru/~dkutsanov/~index.htm

Any other command-line MP3 encoder can also be used.

Some sounds do not like MP3 compression, so MO3 also provides a lossless
compression that will on average reduce samples to around 50% of their
size. The rest of the MOD structure is also compressed. This all means
that you can greatly reduce the size of MOD musics without even using
any MP3 compression.

A few tips when creating MO3s:
* Use 16-bit samples... MP3 only works with 16-bit samples, 8-bit
  samples are converted to 16-bit first, doubling their size. So you
  may as well take advantage of the extra quality of 16-bit samples
  when creating the original MOD versions.
* Finetune the encoder settings for each sample... to get the best
  quality to size ratio don't just use the compression level slider.
  All samples vary in the amount that they can be compressed before
  losing too much quality.
* Pay particular attention to looped samples... MP3 does not maintain
  the sample shape exactly (some encoders more than others), so a loop
  that normally sounds correct may produce a "click" or have a gap in
  the MP3 version. If you're using LAME, then set the sample rate to
  32000hz or above for best results.

CD Audio
========
The CD system is seperate from the other functions in BASS, it doesn't
require DirectSound or any other special libraries to be installed.
BASS makes playing CD audio very simple... there's nothing more to say!

3D Sound
========
If you are at all familiar with DirectSound3D, then you should have no
problem using the 3D functions of BASS. But, even if you have not used
DS3D it shouldn't be too hard to do 3D sound, see the example source
file 3DTEST.C for a simple example of using 3D sound in BASS.

To enable 3D sound, simply use the BASS_DEVICE_3D flag with BASS_Init.
Then use the BASS_SAMPLE_3D/BASS_MUSIC_3D flag when loading/creating a
sample/stream/MOD music to enable 3D functionality on it.

3D sound sources are mono, the left/right components are calculated by
the 3D engine. When using a stereo sound in 3D, it is converted to mono
during playback, which is a bit of needless processing (as well as a
waste of memory). So your 3D sounds should be mono in the first place.
MOD musics are automatically mixed in mono when used in 3D, but it is up
to you to use mono samples and streams in 3D. Because 3D channels are
mono, playing MOD musics and streams in 3D can actually require less CPU
than in plain stereo, because less software mixing is required, assuming
the 3D mixing is being done by the hardware.

3D sounds and non-3D sounds can be played together, it's not a matter of
all 3D or else none 3D.

EAX greatly enhances the 3D sound by reverberating the sounds to mimic
the behaviour of a real environment. There are plenty of different types
of environment to choose from, see the EAX_ENVIRONMENT_xxx flags for a
complete list. Presets (EAX_PRESET_xxx) are provided, but the EAX reverb
parameters can also be fine tuned to taste. The amount of reverb applied
to each channel can be adjusted, or as is the default, EAX can calculate
the reverb automatically, based on the distance of the sound from the
listener.

EAX affects 3D channels only, "normal" channels are unaffected by it.
For the EAX effects to be heard, it requires that the user's soundcard
supports EAX, and that DirectX 5 or above is installed.

To enable the A3D functions you must use the BASS_DEVICE_A3D flag with
BASS_Init. The usage of the A3D functions require the user to have A3D
drivers installed, otherwise BASS_Init will fail.

Using BASS
==========
C/C++, Visual Basic and Delphi BASS APIs are provided, to use BASS with
another language you'll first have to convert the header file. Or, as a
last resort, you could use LoadLibrary and GetProcAddress.

One benefit of the LoadLibrary method is that it allows you to "look"
for the correct BASS version, because you can load and unload BASS.DLL
at any time. This also allows those who'ld prefer not to have a seperate
DLL to store it with the program (eg. in a resource), write it to disk,
load it, use it, free it and delete it.

The major downside, is that you have to manually import each function
that you use, using the GetProcAddress function. But it has been made
a lot simpler to import BASS this way by the use of the BASSDEF #define.
Here's a small example:

#define BASSDEF(f) (WINAPI *f) // define the functions as pointers
#include "bass.h"
...
HINSTANCE bass=LoadLibrary("BASS.DLL"); // load BASS
BASS_Init=GetProcAddress(bass,"BASS_Init"); // get BASS_Init
BASS_Init(-1,44100,0,hWnd); // call BASS_Init

See the LOADNGET.C file for a more complete example.

There is no guarantee that all future BASS versions will be compatible
with all previous versions, so your program should use BASS_GetVersion
to check the version that is loaded. This also means that you should
put BASS.DLL in the same directory as your program (not just somewhere
in the path), to avoid the possibility of a wrong version being loaded.

If you are updating your software from a previous BASS version, then
you should check the "History" section (below), to see which (if any)
of the functions that you are using have been affected by a change.

To use BASS with Borland C++ Builder, you'll first have to create a
Borland C++ Builder import library for it. This is done by using the
IMPLIB tool that comes with Borland C++ Builder. Simply execute this:

    IMPLIB BASSBCB.LIB BASS.DLL

... and then use BASSBCB.LIB in your projects to import BASS.

Latest Version
==============
The latest version of BASS can always be found at the BASS homepage:

        http://www.un4seen.com/music/

Copyright, Disclaimer, and all that other jazz
==============================================
The BASS library is free for non-money making use... if you are
not charging for the software, then you can use BASS in it for
free (a mention in the credits would be nice though!). If you
wish to use BASS in shareware or commercial products, then see
the next section.

This software is provided "as is", without warranty of ANY KIND,
either expressed or implied, including but not limited to the
implied warranties of merchantability and/or fitness for a
particular purpose. The author shall NOT be held liable for
ANY damage to you, your computer, or to anyone or anything else,
that may result from its use, or misuse. Basically, you use it
at YOUR OWN RISK.

Usage of BASS indicates that you agree to the above conditions.

You may freely distribute the BASS package as long as NO FEE is
charged and all the files remain INTACT AND UNMODIFIED.

All trademarks and other registered names contained in the BASS
package are the property of their respective owners.

BASS in shareware and commercial software?
==========================================
BASS is available for use in your shareware and commercial software.
The license types available are as follows:

SHAREWARE: Allows the usage of BASS in an unlimited number of your
shareware products.

SINGLE COMMERCIAL: Allows the usage of BASS in a single commercial
product.

UNLIMITED COMMERCIAL: Allows the usage of BASS in an unlimited number
of your commercial products. This license is on a per site basis. So
if your company has two sites and both use BASS, then two licenses are
required.

In all cases there are no royalties to pay, and you can use all future
BASS updates without further cost. One license covers one person or
entity and is not transferable.

These licenses do not allow reselling of BASS, ie. as part of another
development library. If none of these licenses match your requirements,
or if you have any questions about using BASS in shareware/commercial
software, then please get in touch (email: bass@un4seen.com).

Visit the BASS website for the latest pricing:

        http://www.un4seen.com/music/

History
=======
These are the major (and not so major) changes at each version
stage. There are ofcourse bug fixes and other little improvements
made along the way too! To make upgrading simpler, all functions
affected by a change to the BASS interface are listed.

0.8a - 28/2/2000
----------------
* Updated Delphi API and samples
* A few fixes

0.8 - 24/1/2000
---------------
* Improved MP3 performance on P2/K6 and above CPUs - fast!
* User DSP functions on streams and MOD musics
    BASS_ChannelSetDSP
    BASS_ChannelRemoveDSP
* DX7 voice allocation & management
    BASS_SAMPLE_VAM (BASS_SampleLoad/Create flag)
    BASS_VAM_xxx flags
    BASS_SAMPLE (vam/priority members)
* DX7 software 3D algorithm selection
    BASS_Set3DAlgorithm
* DirectSound interface retrieval
    BASS_GetDSoundObject
* Log/linear volume & panning curves
    BASS_SetLogCurves
* User data passed to callback functions
    STREAMPROC - BASS_StreamCreate
    SYNCPROC - BASS_ChannelSetSync
* New synchronizer
    BASS_SYNC_MUSICFX
* New synchronizer flag
    BASS_SYNC_MIXTIME
* Disable synchronizers option - saves a little CPU time
    BASS_DEVICE_NOSYNC (BASS_Init flag)
* Hi-res floating-point CPU usage monitoring
    BASS_GetCPU
* Wait for playback to start when playing a CD
    BASS_CDPlay
* DirectSound (dsound.dll) version retrieval
    BASS_INFO (dsver member)
* Removed volume sliding functions (they were fairly pointless)
    BASS_SlideVolume
    BASS_IsSliding
* MO3: read/write encoder settings
* MO3: remove inst/samp/message texts now optional
* MO3: LAME encoder settings

0.7 - 3/10/1999
---------------
* MO3 (MP3 compressed MODs)
* A3D functions
    BASS_DEVICE_A3D (BASS_Init flag)
    BASS_INFO (a3d member)
    BASS_SetA3DResManager
    BASS_GetA3DResManager
    BASS_SetA3DHFAbsorbtion
    BASS_GetA3DHFAbsorbtion
* Music/stream immediate sample data retrieval
    BASS_ChannelGetData
* File stream (WAV/MP3) length retrieval
    BASS_StreamGetLength
    BASS_StreamGetBlockLength
* File stream seeking
    BASS_ChannelSetPosition
* Mono MP3 option (lower CPU usage)
    BASS_StreamCreateFile
* Music length retrieval
    BASS_MusicGetLength
* Music name retrieval
    BASS_MusicGetName
* Stop notes when moving MOD music position
    BASS_MUSIC_POSRESET (BASS_MusicLoad/BASS_MusicPlayEx flag)
* BASS_ERROR_FREQ - invalid sample rate error code
    BASS_SampleCreate
    BASS_SamplePlayEx
    BASS_SamplePlay3DEx
    BASS_StreamCreate
    BASS_ChannelSetAttributes
* Delphi and VB APIs

0.6a - 26/7/1999
----------------
* Half rate MP3 option (lower CPU usage)
    BASS_MP3_HALFRATE
* Loading/streaming from file offsets
    BASS_MusicLoad
    BASS_SampleLoad
    BASS_StreamCreateFile
* Global music/sample/stream volume levels
    BASS_SetGlobalVolumes
    BASS_GetGlobalVolumes
* Other new function
    BASS_SampleStop
* New synchronizer
    BASS_SYNC_END
* New sample overrider
    BASS_SAMPLE_OVER_DIST
* LoadLibrary/GetProcAddress instructions and example

0.5 - 4/7/1999
--------------
* Documentation!
* File streaming (MP3 and WAV)
    BASS_StreamCreateFile
* Custom generated samples
    BASS_SampleCreate
    BASS_SampleCreateDone
* Other new function
    BASS_MusicSetPositionScaler
* Renamed function
    BASS_ChannelClearSync -> BASS_ChannelRemoveSync
* Alterations made to
    BASS_ChannelGetPosition
    BASS_SampleLoad
    BASS_StreamPlay

0.4 - 30/3/1999
---------------
* Compressed WAV samples support (using audio CODECs)
* Updated CD volume handling - now works with SB Live
* More linear channel volume/pan scales (were slightly off before)
* "no sound" device option
* 3D sound functions
    BASS_Set3DFactors
    BASS_Get3DFactors
    BASS_Set3DPosition
    BASS_Get3DPosition
    BASS_Apply3D
    BASS_SamplePlay3D
    BASS_SamplePlay3DEx
    BASS_ChannelSet3DAttributes
    BASS_ChannelGet3DAttributes
    BASS_ChannelSet3DPosition
    BASS_ChannelGet3DPosition
* EAX functions
    BASS_SetEAXParameters
    BASS_GetEAXParameters
    BASS_ChannelSetEAXMix
    BASS_ChannelGetEAXMix
* Other new functions
    BASS_GetDeviceDescription
    BASS_SetBufferLen
    BASS_ChannelGetFlags
    BASS_ChannelPause
    BASS_ChannelResume
    BASS_ChannelSetPosition
* Replaced function
    BASS_CDResume -> BASS_ChannelResume
* Alterations made to
    BASS_Init
    BASS_CDInit
    BASS_SampleLoad
    BASS_StreamPlay
    BASS_INFO structure
    BASS_SAMPLE structure
    BASS_DEVICE_xxx flags
    BASS_SAMPLE_xxx flags

0.3 - 8/3/1999
--------------
* Synchronization functions
    BASS_ChannelSetSync
    BASS_ChannelClearSync
* Other new functions
    BASS_GetVersion
    BASS_ChannelGetPosition
    BASS_ChannelGetLevel
    BASS_ChannelGetAttributes
    BASS_ChannelSetAttributes
* Replaced functions
    BASS_MusicStop -> BASS_ChannelStop
    BASS_MusicSetVolume -> BASS_ChannelSetAttributes
    BASS_CDStop -> BASS_ChannelStop
    BASS_CDSetVolume -> BASS_ChannelSetAttributes
    BASS_CDGetVolume -> BASS_ChannelGetAttributes
    BASS_ChannelUpdate -> BASS_ChannelSetAttributes
* Alterations made to
    BASS_MusicPlayEx
    BASS_StreamPlay
    BASS_INFO structure

0.2 - 28/2/1999
---------------
* First public release

Credits
=======
Delphi API - Titus Miloi (titus.a.m@t-online.de)
VB API - Adam Hoult (admin@daedalusd.com)

Bug reports, Suggestions, Comments, Enquiries, etc...
=====================================================
If you have any of the aforementioned you can email:

        bass@un4seen.com


BASS_3DVECTOR structure

Structure used by the 3D functions to describe positions, velocities, and orientations.

typedef struct {
    float x;
    float y;
    float z;
} BASS_3DVECTOR;

Members
x | +ve = right, -ve = left.
y | +ve = up, -ve = down.
z | +ve = front, -ve = behind.

Remarks
As can be seen above, the left-handed coordinate system is used.


BASS_Apply3D

Applies changes made to the 3D system.

BOOL WINAPI BASS_Apply3D();

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NO3D BASS_Init has not been successfully called with BASS_DEVICE_3D specified in the flags parameter.

Remarks
This must be called to apply any changes made with BASS_Set3DFactors, BASS_Set3DPosition, BASS_ChannelSet3DAttributes or BASS_ChannelSet3DPosition. It improves performance to have DirectSound do all the required recalculating at the same time like this, rather than recalculating after every little change is made.

This function is automatically called when starting a 3D sample with BASS_SamplePlay3D or BASS_SamplePlay3DEx.

See also
BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_Set3DFactors, BASS_Set3DPosition


BASS_CDFree

Frees all resources used by the CD audio system.

void WINAPI BASS_CDFree();

Remarks
If you use the BASS CD audio system, then BASS_CDFree should be called before your program exits.

If you wish to change settings (ie. use a different drive), having already called BASS_CDInit, then BASS_CDFree must be called before calling BASS_CDInit again.


BASS_CDInDrive

Checks if there is a CD in the drive.

BOOL WINAPI BASS_CDInDrive();

Return value
If there is a CD in the drive, then TRUE is returned, else FALSE is returned. FALSE is also returned if BASS_CDInit has not been successfully called.

See also
BASS_CDPlay


BASS_CDInit

Initializes the BASS CD audio system.

BOOL WINAPI BASS_CDInit(
    char *drive
);

Parameters
drive The CD drive... NULL = use default drive.

Return value
If BASS was successfully initialized then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_ALREADY | The BASS CD system has already been initialized. You must call BASS_CDFree before calling BASS_CDInit again.
BASS_ERROR_INITCD | The CD could not be initialized. Either there is no CD drive, or it is in use by another application.

Remarks
This function must be successfully called before calling any other BASS CD functions.

Example
To initialize the CD audio system, using drive E.

BASS_CDInit("E:");

See also
BASS_CDFree, BASS_CDPlay, BASS_Init


BASS_CDPlay

Plays an audio CD track.

BOOL WINAPI BASS_CDPlay(
    DWORD track,
    BOOL loop,
    BOOL wait
);

Parameters
track | The track number to play... 1 = the first track.
loop | Loop the track?
wait | Wait for the track to start playing before returning?

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_CDINIT | BASS_CDInit has not been successfully called.
BASS_ERROR_CDTRACK | The track number is invalid.
BASS_ERROR_NOCD | There's no CD in the drive.
BASS_ERROR_NOTAUDIO | The track is not an audio track.

Remarks
There is always a slight delay in starting playback of CD tracks as the drive seeks to the start of the track. Some CD drives will always wait for playback to start before returning from this function, whether the wait option is used or not.

Use CDCHANNEL with BASS_ChannelStop to stop the CD.

See also
BASS_CDInDrive, BASS_ChannelIsActive, BASS_ChannelSetAttributes, BASS_ChannelPause, BASS_ChannelStop


BASS_ChannelGet3DAttributes

Retrieves the 3D attributes of a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelGet3DAttributes(
    DWORD handle,
    DWORD *mode,
    float *min,
    float *max,
    DWORD *iangle,
    DWORD *oangle,
    DWORD *outvol
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mode | The 3D processing mode... NULL = don't retrieve it.
min | The minimum distance... NULL = don't retrieve it.
max | The maximum distance... NULL = don't retrieve it.
iangle | The angle of the inside projection cone... NULL = don't retrieve it.
oangle | The angle of the outside projection cone... NULL = don't retrieve it.
outvol | The delta-volume outside the outer projection cone... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality... it wasn't created or loaded with the BASS_xxx_3D flag.

Remarks
The iangle and oangle parameters must both be retrieved in a single call to this function (ie. you can't retrieve one without the other). See BASS_ChannelSet3DAttributes for an explanation of the parameters.

See also
BASS_ChannelGet3DPosition, BASS_ChannelGetAttributes, BASS_ChannelSet3DAttributes


BASS_ChannelGet3DPosition

Retrieves the 3D position of a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelGet3DPosition(
    DWORD handle,
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
pos | Position of the sound... NULL = don't retrieve it.
orient | Orientation of the sound... NULL = don't retrieve it.
vel | Velocity of the sound... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality... it wasn't created or loaded with the BASS_xxx_3D flag.

See also
BASS_ChannelGet3DAttributes, BASS_ChannelGetAttributes, BASS_ChannelSet3DPosition, BASS_Get3DFactors, BASS_Get3DPosition, BASS_3DVECTOR structure


BASS_ChannelGetAttributes

Retrieves the basic attributes of a sample, stream, MOD music, or CD channel.

BOOL WINAPI BASS_ChannelGetAttributes(
    DWORD handle,
    DWORD *freq,
    DWORD *volume,
    int *pan,
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.
freq | The sample rate... NULL = don't retrieve it.
volume | The volume... NULL = don't retrieve it.
pan | The panning position... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_CDINIT | BASS_CDInit has not been successfully called.
BASS_ERROR_CDVOL | BASS could not find any volume control for the CD.

Remarks
Only the volume attribute is available for the CD channel, but not all soundcards/drivers have the ability to control the CD volume.

See also
BASS_ChannelGet3DAttributes, BASS_ChannelGetFlags, BASS_ChannelSetAttributes


BASS_ChannelGetData

Retrieves the immediate sample data of a playing stream, or MOD music channel.

DWORD WINAPI BASS_ChannelGetData(
    DWORD handle,
    void *buffer,
    DWORD length
);

Parameters
handle | The channel handle... a HMUSIC, HSTREAM.
buffer | Location to write the sample data.
length | Number of bytes wanted.

Return value
If an error occurs, 0xFFFFFFFF is returned, use BASS_ErrorGetCode to get the error code. If successful, the number of bytes actually written to the buffer will be returned.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOPLAY | The channel is not playing.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Remarks
This function can only return as much data as has been written to the channel's buffer, so it'll not always be possible to get the amount of data requested, especially if you request large amounts. If you really do need large amounts, then increase the buffer lengths (BASS_SetBufferLength).

This function is most useful if you wish to visualize (eg. spectrum analyze) the sound.

See also
BASS_ChannelGetLevel, BASS_ChannelIsActive


BASS_ChannelGetEAXMix

Retrieves the wet (reverb) / dry (no reverb) mix ratio on a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelGetEAXMix(
    DWORD handle,
    float *mix
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mix | Pointer to store the wet / dry ratio... 0.0 = reverb off - 1.0 = max reverb, -1.0 = let EAX calculate the reverb mix based on the distance (the default).

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOEAX | The channel does not have EAX support.

See also
BASS_ChannelSetEAXMix


BASS_ChannelGetFlags

Retrieves some information on a sample, stream, or MOD music channel.

DWORD WINAPI BASS_ChannelGetFlags(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM.

Return value
If an error occurs, 0xFFFFFFFF is returned, use BASS_ErrorGetCode to get the error code. If successful, a combination of these flags is returned.

BASS_SAMPLE_8BITS | The channel's resolution is 8 bit, else 16 bit.
BASS_SAMPLE_MONO | The channel is mono, else stereo.
BASS_SAMPLE_LOOP | The channel is looped.
BASS_SAMPLE_3D | The channel has 3D functionality enabled.
BASS_SAMPLE_SOFTWARE | The channel is NOT using hardware mixing... it doesn't benefit from any special hardware interpolation, etc...
BASS_SAMPLE_VAM | The channel is using the DX7 voice allocation and management features (HCHANNEL only).

Error codes
BASS_ERROR_HANDLE handle is not a valid channel.

Remarks
The BASS_SAMPLE_SOFTWARE flag indicates whether or not the channel's sample data is being mixed into the final output by the hardware. It does not indicate (in the case of a stream or MOD music) whether the processing required to generate the sample data is being done by the hardware, this processing is always done in software by BASS, a CODEC (WAV file stream), or a user defined function (user stream).

See also
BASS_ChannelGetAttributes


BASS_ChannelGetLevel

Retrieves the level of a playing stream, or MOD music channel.

DWORD WINAPI BASS_ChannelGetLevel(
    DWORD handle
);

Parameters
handle The channel handle... a HMUSIC, HSTREAM.

Return value
If an error occurs, 0xFFFFFFFF is returned, use BASS_ErrorGetCode to get the error code. If successful, the level of the left channel is returned in the low word (low 16 bits), and the level of the right channel is returned in the high word (high 16 bits). If the channel is mono, then the high word is 0. The level ranges linearly from 0 (silent) to 128 (max).

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOPLAY | The channel is not playing.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Remarks
The channel's volume (as set with BASS_ChannelSetAttributes) does not affect the value returned by this function... it measures the level of the channel's sample data and not the level of the channel in the final output mix.

Example
To get the left and right levels of a stereo channel.

DWORD level,left,right;
level=BASS_ChannelGetLevel(a_channel);
left=LOWORD(level); // the left level
right=HIWORD(level); // the right level

See also
BASS_ChannelGetData, BASS_ChannelIsActive


BASS_ChannelGetPosition

Retrieves the playback position of a sample, stream, MOD music, or CD channel.

DWORD WINAPI BASS_ChannelGetPosition(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.

Return value
If an error occurs, 0xFFFFFFFF is returned, use BASS_ErrorGetCode to get the error code. If successful, the position is returned as follows.

HCHANNEL | Position in bytes.
HMUSIC | LOWORD = order, HIWORD = row * scaler (see BASS_MusicSetPositionScaler).
HSTREAM | Total number of bytes played since the stream was last flushed. In the case of a file stream, it will be the playback position of the stream (the position will change if you use BASS_ChannelSetPosition).
CDCHANNEL | Position in milliseconds from the start of the track.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_CDINIT | BASS_CDInit has not been successfully called.

See also
BASS_ChannelGetLevel, BASS_ChannelIsActive, BASS_ChannelSetPosition


BASS_ChannelIsActive

Checks if a sample, stream, MOD music, or CD channel is active (playing).

BOOL WINAPI BASS_ChannelIsActive(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.

Return value
If the channel is not active, or if handle is not a valid channel, FALSE is returned. If the channel is active, TRUE is returned.


BASS_ChannelPause

Pauses a sample, stream, MOD music, or CD channel.

BOOL WINAPI BASS_ChannelPause(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOPLAY The channel is not playing (or handle is not a valid channel).

Remarks
Use BASS_ChannelResume to resume playback of a paused channel. BASS_ChannelStop can be used to stop a paused channel.

See also
BASS_ChannelResume, BASS_ChannelStop


BASS_ChannelRemoveDSP

Removes a DSP function from a MOD music or stream channel.

BOOL WINAPI BASS_ChannelRemoveDSP(
    DWORD handle,
    HDSP dsp
);

Parameters
handle | The channel handle... a HMUSIC or HSTREAM.
dsp | Handle of the DSP function to remove from the channel.

Return value
If succesful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE Atleast one of handle and sync is not valid.

See also
BASS_ChannelSetDSP


BASS_ChannelRemoveSync

Removes a synchronizer from a MOD music or stream channel.

BOOL WINAPI BASS_ChannelRemoveSync(
    DWORD handle,
    HSYNC sync
);

Parameters
handle | The channel handle... a HMUSIC or HSTREAM.
sync | Handle of the synchronizer to remove.

Return value
If succesful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE Atleast one of handle and dsp is not valid.

See also
BASS_ChannelSetSync


BASS_ChannelResume

Resumes a paused sample, stream, MOD music, or CD channel.

BOOL WINAPI BASS_ChannelResume(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not even been started.
BASS_ERROR_NOPAUSE | The channel is not paused.
BASS_ERROR_HANDLE | handle is not a valid channel.

See also
BASS_ChannelPause, BASS_ChannelStop


BASS_ChannelSet3DAttributes

Sets the 3D attributes of a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelSet3DAttributes(
    DWORD handle,
    int mode,
    float min,
    float max,
    int iangle,
    int oangle,
    int outvol
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mode The 3D processing mode... one of these flags.
BASS_3DMODE_NORMAL | Normal 3D processing.
BASS_3DMODE_RELATIVE | The channel's 3D position (position/velocity/orientation) is relative to the listener. When the listener's position/velocity/orientation is changed with BASS_Set3DPosition, the channel's position relative to the listener does not change.
BASS_3DMODE_OFF | Turn off 3D processing on the channel, the sound will be played in the center.
min | The minimum distance. The channel's volume stops increasing when the listener is within this distance.
max | The maximum distance. The channel's volume stops decreasing when the listener is past this distance.
iangle | The angle of the inside projection cone in degrees... 0 (no cone) - 360 (sphere).
oangle | The angle of the outside projection cone in degrees... 0 (no cone) - 360 (sphere).
outvol | The delta-volume outside the outer projection cone... 0 (silent) - 100 (same as inside the cone).

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality... it wasn't created or loaded with the BASS_xxx_3D flag.

Remarks
The iangle and oangle parameters must both be set in a single call to this function (ie. you can't set one without the other). The iangle and oangle angles decide how wide the sound is projected around the orientation angle. Within the inside angle the volume level is the channel volume, as set with BASS_ChannelSetAttributes. Outside the outer angle, the volume changes according to the outvol value. Between the inner and outer angles, the volume gradually changes between the inner and outer volume levels. If the inner and outer angles are 360 degrees, then the sound is transmitted equally in all directions.

As with all 3D functions, use BASS_Apply3D to apply the changes made.

See also
BASS_ChannelGet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttributes


BASS_ChannelSet3DPosition

Sets the 3D position of a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelSet3DPosition(
    DWORD handle,
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
pos | Position of the sound... NULL = leave current.
orient | Orientation of the sound... NULL = leave current.
vel | Velocity of the sound... NULL = leave current. This is only used to calculate the doppler effect, and has no effect on the sound's position.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality... it wasn't created or loaded with the BASS_xxx_3D flag.

Remarks
As with all 3D functions, BASS_Apply3D must be called to apply the changes made.

See also
BASS_Apply3D, BASS_ChannelGet3DPosition, BASS_ChannelSet3DAttributes, BASS_ChannelSetAttributes, BASS_Set3DFactors, BASS_Set3DPosition, BASS_3DVECTOR structure


BASS_ChannelSetAttributes

Sets the basic attributes of a sample, stream, MOD music, or CD channel.

BOOL WINAPI BASS_ChannelSetAttributes(
    DWORD handle,
    int freq,
    int volume,
    int pan
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.
freq | The sample rate... 100 (min) - 100000 (max), 0 = original rate (when the channel was created), -1 = leave current.
volume | The volume... 0 (silent) - 100 (max), -1 = leave current.
pan | The panning position... -100 (left) - 100 (right), -101 = leave current.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_CDINIT | BASS_CDInit has not been successfully called.
BASS_ERROR_CDVOL | BASS could not find any volume control for the CD.
BASS_ERROR_FREQ | freq is out of range... DirectSound only allows sample rates between 100 and 100000.

Remarks
Only the volume attribute can be adjusted for the CD channel, but not all soundcards allow controlling of the CD volume level.

It requires an increased amount of CPU processing to play MOD musics or streams at increased sample rates. If you plan to play MOD musics or streams at greatly increased sample rates, then you should increase the buffer lengths (using BASS_SetBufferLength) to avoid possible break-ups in the sound.

See also
BASS_ChannelGetAttributes, BASS_ChannelSet3DAttributes, BASS_SetGlobalVolumes


BASS_ChannelSetDSP

Sets up a user DSP function on a MOD music or file stream channel.

HDSP WINAPI BASS_ChannelSetDSP(
    DWORD handle,
    DSPPROC *proc,
    DWORD user
);

Parameters
handle | The channel handle... a HMUSIC or HSTREAM.
proc | The callback function.
user | User instance data to pass to the callback function.

Return value
If succesful, then the new DSP's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not a valid channel.

Remarks
The channel does not have to be playing to set a DSP function, you can set DSP functions before or while playing. Equally, you can also remove them at any time. Multiple DSP functions may be used per channel, in which case the functions are called in the order that they were added. Use BASS_ChannelRemoveDSP to remove a DSP function.

DSP functions can be applied to MOD musics and streams, but not samples. If you want to apply a DSP function to a sample, then you should stream the sample.

See also
BASS_ChannelRemoveDSP, DSPPROC callback


BASS_ChannelSetEAXMix

Sets the wet (reverb) / dry (no reverb) mix ratio on a sample, stream, or MOD music channel with 3D functionality.

BOOL WINAPI BASS_ChannelSetEAXMix(
    DWORD handle,
    float mix
);

Parameters
handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mix | The wet / dry ratio... 0.0 = reverb off - 1.0 = max reverb, -1.0 = let EAX calculate the reverb mix based on the distance (the default).

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOEAX | The channel does not have EAX support. EAX is only applied to 3D channels that are mixed by the hardware, you can check if a channel is being mixed by the hardware with BASS_ChannelGetFlags.

Remarks
Obviously, EAX functions have no effect if no EAX supporting device (ie. SB Live) is used. You can use BASS_GetInfo to check if the current device suports EAX. EAX only affects 3D channels, but EAX functions do NOT require BASS_Apply3D to apply the changes.

See also
BASS_ChannelGetEAXMix, BASS_SetEAXParameters


BASS_ChannelSetPosition

Sets the playback position of a sample, MOD music, file stream, or CD channel.

BOOL WINAPI BASS_ChannelSetPosition(
    DWORD handle,
    DWORD pos
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.
pos The position, as follows.
HCHANNEL | Position in bytes.
HMUSIC | LOWORD = order, HIWORD = row.
HSTREAM | Position in bytes. Obviously, only file streams can have the position moved. MP3s require the use of the BASS_MP3_SETPOS flag with BASS_StreamCreateFile to enable this.
CDCHANNEL | Position in milliseconds from the start of the track.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_CDINIT | BASS_CDInit has not been successfully called.
BASS_ERROR_POSITION | The requested position is illegal.
BASS_ERROR_NOTFILE | The stream is not a file stream... it was not created by using BASS_StreamCreateFile.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
Streams are usually encoded in blocks, so it will usually not be possible to seek to the exact byte position requested (positions are rounded down to the beginning of a block). The number of bytes per block can be retrieved with BASS_StreamGetBlockLength.

When changing the position of a MOD music, and the BASS_MUSIC_POSRESET flag is active on the channel, all notes that were playing before the position changed will be stopped. Otherwise, the notes will continue playing until they are stopped in the MOD music.

Example
To set the position of a MOD music to row 20 of order 10.

BASS_ChannelSetPosition(a_music,MAKELONG(10,20));

See also
BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_MusicGetLength, BASS_StreamGetLength


BASS_ChannelSetSync

Sets up a synchronizer on a MOD music or file stream channel.

HSYNC WINAPI BASS_ChannelSetSync(
    DWORD handle,
    DWORD type,
    DWORD param,
    SYNCPROC *proc,
    DWORD user
);

Parameters
handle | The channel handle... a HMUSIC or HSTREAM.
type The type of sync (see the table below), you may also use these flags.
BASS_SYNC_ONETIME | Call the sync only once.
BASS_SYNC_MIXTIME | Call the sync function when the sync occurs during mixing, instead of delaying the call until the sync is actually heard.
param | The sync parameters, depends on the sync type... see the table below.
proc | The callback function.
user | User instance data to pass to the callback function.

Sync types, with param and SYNCPROC data definitions.
BASS_SYNC_MUSICPOS | Sync when a MOD music reaches a position. param : LOWORD = order (0=first, -1=all), HIWORD = row (0=first, -1=all). data : LOWORD = order, HIWORD = row.
BASS_SYNC_MUSICINST | Sync when an instrument (sample for the MOD/S3M/MTM formats) is played in a MOD music (not including retrigs). param : LOWORD = instrument (1=first), HIWORD = note (0=c0...119=b9, -1=all). data : LOWORD = note, HIWORD = volume (0-64).
BASS_SYNC_END | Sync when a MOD music or file stream reaches the end. Note that some MOD musics never reach the end, they may jump to another position first. param : not used. data : not used.
BASS_SYNC_MUSICFX | Sync when the sync effect is used in a MOD music. The sync effect is E8x for the XM/MTM/MOD formats, and S0x for the IT/S3M formats (where x = any value). param : 0 = the position is passed to the callback (data : LOWORD = order, HIWORD = row), 1 = the value of x is passed to the callback (data : x value).

Return value
If succesful, then the new synchronizer's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOSYNC | Synchronizers have been disabled... the BASS_DEVICE_NOSYNC flag was used with BASS_Init.
BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLPARAM | An illegal param was specified.
BASS_ERROR_ILLTYPE | An illegal type was specified.

Remarks
Multiple synchronizers may be used per channel. Use BASS_ChannelRemoveSync to remove a synchronizer. If the BASS_SYNC_ONETIME flag is used, then the sync is automatically removed after it's occured (ie. there's no need to remove it manually).

The channel does not have to be playing to set a synchronizer, you can set synchronizers before or while playing. There is only one case where you can not set a synchronizer, and that is from within a callback function. But you can remove synchronizers at any time, including from inside a callback function.

The BASS_SYNC_MIXTIME flag is only really useful for using a sync to switch DSP functions on/off. You could, for example, use a BASS_SYNC_MUSICFX sync to switch a reverb effect on/off on a MOD music.

Example
To do some processing until a MOD music reaches the 10th order.

BOOL order10=FALSE; // the order 10 flag
...
// the sync callback
void CALLBACK MySyncProc(HSYNC handle, DWORD channel, DWORD data, DWORD user) {
    order10=TRUE; // set the order 10 flag
}
...
BASS_ChannelSetSync(a_music, BASS_SYNC_MUSICPOS|BASS_SYNC_ONETIME, MAKELONG(10,0), &MySyncProc, 0); // set the one-time order 10 sync
while (!order10) {
    // order 10 has not arrived, so do some processing
}
// order 10 has arrived!

See also
BASS_ChannelRemoveSync, SYNCPROC callback


BASS_ChannelStop

Stops a sample, stream, MOD music, or CD channel.

BOOL WINAPI BASS_ChannelStop(
    DWORD handle
);

Parameters
handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or CDCHANNEL.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not a valid channel.

Example
To stop the CD audio.

BASS_ChannelStop(CDCHANNEL);

See also
BASS_CDPlay, BASS_MusicPlay, BASS_MusicPlayEx, BASS_SamplePlay, BASS_SamplePlay3D, BASS_SamplePlay3DEx, BASS_SamplePlayEx, BASS_StreamPlay, BASS_SampleStop


BASS_ErrorGetCode

Retrieves the BASS error code for the most recent BASS function call.

DWORD WINAPI BASS_ErrorGetCode();

Return value
If no error occured during the last BASS function call then BASS_OK is returned, else one of the BASS_ERROR values is returned. See the function description for an explanation of what the error code means.


BASS_Free

Frees all resources used by the digital output, including all samples, MOD musics, and streams.

void WINAPI BASS_Free();

Remarks
BASS_Free should be called before your program exits. It's not necessary to individually free all the samples/streams/musics as these are all automatically freed by this function.

If you wish to change device settings, having already called BASS_Init, then BASS_Free must be called before calling BASS_Init again. You will also have to re-load/create the samples/streams/musics.

See also
BASS_Init


BASS_Get3DFactors

Retrieves the factors that affect the calculations of 3D sound.

BOOL WINAPI BASS_Get3DFactors(
    float *distf,
    float *rollf,
    float *doppf
);

Parameters
distf | The distance factor... NULL = don't retrieve it.
rollf | The rolloff factor... NULL = don't retrieve it.
doppf | The doppler factor... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NO3D BASS_Init has not been successfully called with BASS_DEVICE_3D specified in the flags parameter.

See also
BASS_Set3DFactors


BASS_Get3DPosition

Retrieves the position, velocity, and orientation of the listener.

BOOL WINAPI BASS_Get3DPosition(
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *vel,
    BASS_3DVECTOR *front
    BASS_3DVECTOR *top
);

Parameters
pos | The position of the listener... NULL = don't retrieve it.
vel | The listener's velocity... NULL = don't retrieve it.
front | The direction that the listener's front is pointing... NULL=don't retrieve it.
top | The direction that the listener's top is pointing... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NO3D BASS_Init has not been successfully called with BASS_DEVICE_3D specified in the flags parameter.

Remarks
The front and top parameters must both be retrieved in a single call, they can not be retrieved individually.

See also
BASS_Set3DPosition, BASS_3DVECTOR structure


BASS_GetA3DHFAbsorbtion

Retrieves the A3D high frequency absorption factor.

BOOL WINAPI BASS_GetA3DHFAbsorbtion(
    float *factor
);

Parameters
factor The HF absorbtion factor.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOA3D The current device does not support A3D, or BASS_DEVICE_A3D was not specified with BASS_Init.

See also
BASS_SetA3DHFAbsorbtion


BASS_GetA3DResManager

Retrieves the A3D resource management mode.

DWORD WINAPI BASS_GetA3DResManager();

Return value
If succesful, then the A3D resource management mode is returned, else 0xFFFFFFFF is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOA3D The current device does not support A3D, or BASS_DEVICE_A3D was not specified with BASS_Init.

See also
BASS_SetA3DResManager


BASS_GetCPU

Retrieves the current CPU usage of BASS.

float WINAPI BASS_GetCPU();

Return value
The BASS CPU usage as a percentage of total CPU time.

Remarks
This includes the time taken to mix the MOD musics and sample streams (both file streams and user streams). It also includes the time taken by any user DSP functions. It does not include plain sample mixing which is done by the output device (hardware accelerated) or DirectSound (emulated). Audio CD playback requires no CPU usage.


BASS_GetDeviceDescription

Retrieves the text description of a device.

BOOL WINAPI BASS_GetDeviceDescription(
    int devnum,
    char **desc
);

Parameters
devnum | The device to get the description of... 0 = first.
desc | Pointer to store pointer to text description at. You should not edit the text at the returned pointer.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_DEVICE The device number specified is invalid.

Remarks
This function can be used to enumerate the available devices for a setup dialog.

Example
To get the total number of devices present.

int count=0; // the device counter
char *dummy; // description pointer
while (BASS_GetDeviceDescription(count,&dummy)) count++;


BASS_GetDSoundObject

Retrieves a pointer to a DirectSound object interface.

void *WINAPI BASS_GetDSoundObject(
    DWORD object
);

Parameters
object The interface to retrieve, one of the following.
BASS_OBJECT_DS | Retrieve the IDirectSound interface.
BASS_OBJECT_DS3DL | Retrieve the IDirectSound3DListener interface.

Return value
If succesful, then a pointer to the requested object is returned, otherwise NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_ILLPARAM | object is invalid.
BASS_ERROR_NO3D | The device was not initialized with 3D support.

Remarks
This function allows those that are familiar with DirectSound to access to the internal DirectSound object interfaces, so that extra external functionality can be "plugged" into BASS. If you create any objects through a retrieved interface, make sure you release the objects before calling BASS_Free.

See the DirectX SDK for information on the DirectSound interfaces.

Example
To set the speaker configuration to "headphones".

#include <dsound.h>
...
IDirectSound *ds=BASS_GetDSoundObject(BASS_OBJECT_DS); // get object
IDirectSound_SetSpeakerConfig(ds,DSSPEAKER_HEADPHONE); // headphones

See also
BASS_Init


BASS_GetEAXParameters

Retrieves the current type of EAX environment and it's parameters.

BOOL WINAPI BASS_GetEAXParameters(
    DWORD *env,
    float *vol,
    float *decay
    float *damp
);

Parameters
env | The EAX environment... NULL = don't retrieve it. See BASS_SetEAXParameters for a list of the possible environments.
vol | The volume of the reverb... NULL = don't retrieve it.
decay | The decay duration... NULL = don't retrieve it.
damp | The damping... NULL = don't retrieve it.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOEAX The current device does not support EAX.

See also
BASS_SetEAXParameters


BASS_GetGlobalVolumes

Retrieves the global music/sample/stream volume levels.

void WINAPI BASS_GetGlobalVolumes(
    DWORD *musvol,
    DWORD *samvol,
    DWORD *strvol
);

Parameters
musvol | MOD music global volume level... NULL = don't retrieve it.
samvol | Sample global volume level... NULL = don't retrieve it.
strvol | Stream global volume level... NULL = don't retrieve it.

See also
BASS_SetGlobalVolumes


BASS_GetInfo

Retrieves information on the device being used.

void WINAPI BASS_GetInfo(
    BASS_INFO *info
);

Parameters
info Pointer to store the information at.

Remarks
The size member of the BASS_INFO structure must be initialized to the size of the structure before calling BASS_GetInfo (only the first size bytes of the structure will be filled). Obviously, BASS_Init must have been successfully called before calling BASS_GetInfo.

Example
To check if the current device has hardware support.

BASS_INFO info;
info.size=sizeof(BASS_INFO);
BASS_GetInfo(&info);
if (info.flags&DSCAPS_EMULDRIVER) {
    // device does NOT have hardware support
}

See also
BASS_INFO structure


BASS_GetVersion

Retrieves the version number of the BASS.DLL that is loaded.

DWORD WINAPI BASS_GetVersion();

Return value
The BASS version (LOWORD.HIWORD)

Remarks
There is no guarantee that a previous or future version of BASS supports all the BASS functions that you are using, so you should always call this function to make sure the correct version is loaded.

Example
To check that BASS 0.7 is loaded.

if (BASS_GetVersion()!=MAKELONG(0,7)) {
    // version 0.7 not loaded!
}


BASS_GetVolume

Retrieves the current digital master volume level.

int WINAPI BASS_GetVolume();

Return value
If successful, the volume level is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT BASS_Init has not been successfully called.

See also
BASS_SetVolume


BASS_INFO structure

Used with BASS_GetInfo to retrieve information on the current device.

typedef struct {
    DWORD size;
    DWORD flags;
    DWORD hwsize;
    DWORD hwfree;
    DWORD freesam;
    DWORD free3d;
    DWORD minrate;
    DWORD maxrate;
    BOOL eax;
    DWORD a3d;
    DWORD dsver;
} BASS_INFO;

Members
size | This must be initialized to the size of the structure before calling BASS_GetInfo.
flags The device's capabilities... a combination of these flags.
DSCAPS_CONTINUOUSRATE | The device supports all sample rates between min/maxrate.
DSCAPS_EMULDRIVER | The device does NOT have hardware DirectSound support. All other members of the structure are irrelevant if the device doesn't have hardware support.
DSCAPS_CERTIFIED | The device driver has been certified by Microsoft.
DSCAPS_SECONDARYMONO | Mono samples are supported by hardware mixing.
DSCAPS_SECONDARYSTEREO | Stereo samples are supported by hardware mixing.
DSCAPS_SECONDARY8BIT | 8 bit samples are supported by hardware mixing.
DSCAPS_SECONDARY16BIT | 16 bit samples are supported by hardware mixing.
hwsize | The device's total amount of hardware memory.
hwfree | The device's amount of free hardware memory.
freesam | The number of free sample slots in the hardware.
free3d | The number of free 3D sample slots in the hardware.
minrate | The minimum sample rate supported by the hardware.
maxrate | The maximum sample rate supported by the hardware.
eax | The device supports EAX? This is always FALSE if BASS_DEVICE_3D was not used when BASS_Init was called.
a3d | A3D driver version... 10 = A3D 1.0, 12 = A3D 1.2 or above, 0 = BASS_DEVICE_A3D was not used when BASS_Init was called.
dsver | DirectSound version... 5+ = DX5 features are available, 7+ = DX7 features are available.

Remarks
The DSCAPS_SECONDARY flags only indicate which sample formats are supported by hardware mixing. Mono/stereo 8/16 bit samples are all supported by software mixing.

The dsver value can be used check for the availability of functions that require a minimum version of DirectX. Note that this value is the DirectSound version, and it is not necessarily also the DirectX version. For example, DirectX 6 has DirectSound version 5 because no changes were made to the DirectSound interface in DirectX 6.

The only real difference between A3D 1.0 and A3D 1.2, from a functionality point of view, is the A3D_RESMODE_DYNAMIC_LOOPERS resource management mode. But there are also bug-fixes in A3D 1.2, so even if you do not use this resource management mode, you should still recommend that the user gets updated drivers if they have A3D 1.0 drivers.

See also
BASS_GetInfo


BASS_Init

Initializes the BASS digital output system.

BOOL WINAPI BASS_Init(
    int device,
    DWORD freq,
    DWORD flags,
    HWND win
);

Parameters
device | The device to use... 0 = first, -1 = default, -2 = no sound. BASS_GetDeviceDescription can be used to get the total number of devices.
freq | Output sample rate.
flags Any combination of these flags.
BASS_DEVICE_8BITS | Use 8 bit resolution, else 16 bit.
BASS_DEVICE_MONO | Use mono, else stereo.
BASS_DEVICE_3D | Enable 3D functionality. If this flag is not specified, then the 3D flags (BASS_SAMPLE_3D and BASS_MUSIC_3D) are ignored when loading/creating a sample/stream/music.
BASS_DEVICE_A3D | Enable A3D. This is the same as BASS_DEVICE_3D, except it also enables the A3D functions.
BASS_DEVICE_NOSYNC | Disable synchronizers. If you are not using any syncs, then you may as well use this flag to save a little CPU time.
win | The application's main window. If you're using the console, then you should use the handle returned by the GetForegroundWindow function.

Return value
If BASS was successfully initialized then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_ALREADY | BASS has already been initialized. You must call BASS_Free before calling BASS_Init again.
BASS_ERROR_DEVICE | The device number specified is invalid.
BASS_ERROR_DRIVER | There is no available device driver.
BASS_ERROR_FORMAT | The specified format is not supported by the device. Try changing the freq and flags parameters.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | The device has no 3D support.
BASS_ERROR_NOA3D | The device has no A3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
This function must be successfully called before calling any other BASS functions, except BASS_ErrorGetCode, BASS_GetDeviceDescription, BASS_GetGlobalVolumes, BASS_GetVersion, BASS_SetBufferLength, BASS_SetLogCurves, BASS_SetGlobalVolumes, and the CD functions.

The no sound device allows loading and "playing" of MOD musics only, all sample/stream functions and most other functions fail. This is so that you can still use the MOD musics as synchronizers when there is no soundcard present. When using the no sound device, you should still set the other parameters as you would do normally.

It is advisable to have a "lower quality" option (eg. 22050hz instead of 44100hz) in your software, for users with slower computers.

When requesting the default device with the BASS_DEVICE_A3D flag, the device used is not necessarily the same as would be used without the BASS_DEVICE_A3D flag. The A3D driver automatically searches for the best (most hardware channels) A3D device. So if your program supports both A3D and EAX, then you should let the user choose, otherwise users that have both an A3D device and an EAX device will be stuck with the A3D.

Example
To initialize BASS, falling back to no sound if no device is available.

// try initializing the default device, at 44100hz stereo 16 bits
if (!BASS_Init(-1,44100,0,hwnd)) {
    // couldn't initialize device, so use no sound
    BASS_Init(-2,44100,0,hwnd)
}

See also
BASS_CDInit, BASS_Free, BASS_GetDSoundObject, BASS_GetInfo, BASS_MusicLoad, BASS_Start, BASS_SampleLoad, BASS_SampleCreate, BASS_StreamCreate, BASS_StreamCreateFile


BASS_MusicFree

Frees a MOD music's resources.

void WINAPI BASS_MusicFree(
    HMUSIC handle
);

Parameters
handle The MOD music handle.

See also
BASS_MusicLoad


BASS_MusicGetLength

Retrieves the length (in orders) of a MOD music.

DWORD WINAPI BASS_MusicGetLength(
    HMUSIC handle
);

Parameters
handle The MOD music's handle.

Return value
If succesful, then the music's length is returned, else 0xFFFFFFFF is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not valid.

Example
To start playback of a MOD music from the beginning of the last order.

DWORD len=BASS_MusicGetLength(a_music); // get length
BASS_MusicPlayEx(a_music,MAKELONG(len-1,0),-1,TRUE); // play

See also
BASS_ChannelSetPosition, BASS_MusicPlayEx


BASS_MusicGetName

Retrieves a MOD music's name.

char *WINAPI BASS_MusicGetName(
    HMUSIC handle
);

Parameters
handle The MOD music's handle.

Return value
If succesful, then a pointer to the music's name is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not valid.


BASS_MusicLoad

Loads a MOD music.

HMUSIC WINAPI BASS_MusicLoad(
    BOOL mem,
    void *file,
    DWORD offset,
    DWORD length,
    DWORD flags
);

Parameters
mem | TRUE = load the MOD music from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to load the MOD music from (only used if mem = FALSE).
length | Data length (only used if mem = FALSE)... 0 = use all data up to the end of file. If length over-runs the end of the file, it'll automatically be lowered to the end of the file.
flags A combination of these flags.
BASS_MUSIC_LOOP | Loop the music.
BASS_MUSIC_RAMP | Use "normal" ramping (as used in FastTracker 2).
BASS_MUSIC_RAMPS | Use "sensitive" ramping.
BASS_MUSIC_FT2MOD | Play .MOD file as FastTracker 2 would.
BASS_MUSIC_PT1MOD | Play .MOD file as ProTracker 1 would.
BASS_MUSIC_MONO | Force mono mixing (uses less CPU than stereo).
BASS_MUSIC_3D | Enable 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init.
BASS_MUSIC_POSRESET | Stop all notes when moving position (using BASS_ChannelSetPosition or BASS_MusicPlayEx).

Return value
If successful, the loaded music'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_FILEOPEN | The file could not be opened.
BASS_ERROR_FORMAT | The file's format is not recognised/supported.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | Couldn't initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
BASS uses the XMPlay engine for it's MOD music support, giving the most accurate reproduction of XM / IT / MOD / S3M / MTM files available from any sound system. The samples are interpolated during mixing for a superior sound quality.

Ramping doesn't take a lot of extra processing and improves the sound quality by removing "clicks". Sensitive ramping leaves sharp attacked samples, while normal ramping can cause them to lose a bit of their impact. Generally, normal ramping is recommended for XMs, and sensitive ramping for the other formats. But, some XMs may also sound better using sensitive ramping.

When loading a MOD music from memory, BASS does not use the memory after it's loaded the MOD music. So you can do whatever you want with the memory after calling this function.

See also
BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttributes, BASS_ChannelSetSync, BASS_ChannelSetEAXMix, BASS_MusicFree, BASS_MusicGetLength, BASS_MusicGetName, BASS_MusicPlay, BASS_MusicPlayEx, BASS_MusicSetAmplify, BASS_MusicSetPanSep, BASS_MusicSetPositionScaler


BASS_MusicPlay

Plays a MOD music.

BOOL WINAPI BASS_MusicPlay(
    HMUSIC handle
);

Parameters
handle The MOD music's handle.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid MOD music handle.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Remarks
Playback continues from where it was last stopped or paused. If the MOD music has just been loaded, then playback starts from the beginning.

See also
BASS_ChannelGetLevel, BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_MusicLoad, BASS_MusicPlayEx


BASS_MusicPlayEx

Plays a MOD music, using the specified start position and flags.

BOOL WINAPI BASS_MusicPlayEx(
    HMUSIC handle,
    DWORD pos,
    int flags,
    BOOL reset
);

Parameters
handle | The MOD music's handle.
pos | Position to start playback from... LOWORD = order, HIWORD = row.
flags Override the MOD music's current flags... -1 = use current flags, else a combination of these flags.
BASS_MUSIC_LOOP | Loop the music.
BASS_MUSIC_RAMP | Use "normal" ramping (as used in FastTracker 2).
BASS_MUSIC_RAMPS | Use "sensitive" ramping.
BASS_MUSIC_FT2MOD | Play .MOD file as FastTracker 2 would.
BASS_MUSIC_PT1MOD | Play .MOD file as ProTracker 1 would.
BASS_MUSIC_POSRESET | Stop all notes when moving position (using BASS_ChannelSetPosition or this function).
reset | TRUE = Stop all playing notes and reset BPM, etc...

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid MOD music handle.
BASS_ERROR_POSITION | pos is invalid.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Example
To reset and start playback of a MOD music at row 10 of order 5.

BASS_MusicPlayEx(a_music,MAKELONG(5,10),-1,TRUE);

See also
BASS_ChannelGetLevel, BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_MusicGetLength, BASS_MusicLoad, BASS_MusicPlay


BASS_MusicSetAmplify

Sets a MOD music's amplification level.

BOOL WINAPI BASS_MusicSetAmplify(
    HMUSIC handle,
    DWORD amp
);

Parameters
handle | The MOD music's handle.
amp | Amplification level... 0 (min) - 100 (max)... the default when a MOD music is loaded is 50.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not valid.

Remarks
As the amplification level get's higher, the sample data's range increases, and therefore, the resolution increases. But if the level is set too high, then clipping can occur, which can result in distortion of the sound.

You can check the current level of a MOD music at any time by using BASS_ChannelGetLevel. By doing so, you can decide if a MOD music's amplification level needs adjusting.

See also
BASS_ChannelGetLevel, BASS_MusicSetPanSep


BASS_MusicSetPanSep

Sets a MOD music's pan seperation level.

BOOL WINAPI BASS_MusicSetPanSep(
    HMUSIC handle,
    DWORD pan
);

Parameters
handle | The MOD music's handle.
pan | Pan seperation... 0 (min) - 100 (max), 50 = linear (which is the default when a MOD music is loaded).

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not valid.

Remarks
By default BASS uses a linear panning "curve". If you want to use the panning of FT2, use a pan seperation setting of around 35. To use the Amiga panning (ie. full left and right) set it to 100.

See also
BASS_MusicSetAmplify


BASS_MusicSetPositionScaler

Sets a MOD music's BASS_ChannelGetPosition scaler.

BOOL WINAPI BASS_MusicSetPositionScaler(
    HMUSIC handle,
    DWORD scale
);

Parameters
handle | The MOD music's handle.
scale | The scaler... 1 (min) - 256 (max)... the default when a MOD music is loaded is 1.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not valid.

Remarks
When you call BASS_ChannelGetPosition, the row (HIWORD) will be scaled by this value. By using a higher scaler, you can get a more precise position indication.

Example
To get the position of a MOD music accurate to within a 10th of a row.

DWORD pos,order,row,row10th;
BASS_MusicSetPositionScaler(a_music,10); // set the scaler
pos=BASS_ChannelGetPosition(a_music);
order=LOWORD(pos); // the order
row=HIWORD(pos)/10; // the row
row10th=HIWORD(pos)%10; // the 10th of a row

See also
BASS_ChannelGetPosition


BASS_Pause

Stops the digital output, pausing all musics/samples/streams.

BOOL WINAPI BASS_Pause();

Return value
If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks
Use BASS_Start to resume the paused channels.

See also
BASS_Start, BASS_Stop


BASS_SAMPLE structure

Used with BASS_SampleGetInfo and BASS_SampleSetInfo to retrieve and set the default playback attributes of a sample.

typedef struct {
    DWORD freq;
    DWORD volume;
    int pan;
    DWORD flags;
    DWORD length;
    DWORD max;
    DWORD mode3d;
    float mindist;
    float maxdist;
    DWORD iangle;
    DWORD oangle;
    DWORD outvol;
    DWORD vam;
    DWORD priority;
} BASS_SAMPLE;

Members
freq | Default playback rate.
volume | Default volume... 0 (silent) - 100 (max).
pan | Default panning position... -100 (left) - 100 (right).
flags A combination of these flags.
BASS_SAMPLE_8BITS | 8 bit resolution, else 16 bit.
BASS_SAMPLE_MONO | Mono, else stereo.
BASS_SAMPLE_LOOP | Looped?
BASS_SAMPLE_3D | The sample has 3D functionality enabled.
BASS_SAMPLE_SOFTWARE | The sample is not using hardware mixing... it is being mixed in software by DirectSound.
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overriden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overriden.
length | The length in samples (not bytes).
max | Maximum number of simultaneous playbacks.
The following are the sample's default 3D attributes (if the sample is 3D).
mode3d The 3D processing mode... one of these flags.
BASS_3DMODE_NORMAL | Normal 3D processing.
BASS_3DMODE_RELATIVE | The sample's 3D position (position/velocity/orientation) is relative to the listener. When the listener's position/velocity/orientation is changed with BASS_Set3DPosition, the sample's position relative to the listener does not change.
BASS_3DMODE_OFF | Turn off 3D processing on the sample, the sound will be played in the center.
mindist | The minimum distance. The sample's volume stops increasing when the listener is within this distance.
maxdist | The maximum distance. The sample's volume stops decreasing when the listener is past this distance.
iangle | The angle of the inside projection cone in degrees... 0 (no cone) - 360 (sphere).
oangle | The angle of the outside projection cone in degrees... 0 (no cone) - 360 (sphere).
outvol | The delta-volume outside the outer projection cone... 0 (silent) - 100 (same as inside the cone).
The following are the sample's default DX7 voice allocation/management settings (if VAM is enabled).
vam voice allocation/management flags... a combination of these
BASS_VAM_HARDWARE | Play the sample in hardware. If no hardware voices are available then the play call will fail.
BASS_VAM_SOFTWARE | Play the sample in software (ie. non-accelerated). No other VAM flags may be used together with this flag.
The following flags enable hardware resource stealing... if the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. Only samples with VAM enabled are considered for termination.
BASS_VAM_TERM_TIME | If there are no free hardware voices, the buffer to be terminated will be the one with the least time left to play.
BASS_VAM_TERM_DIST | If there are no free hardware voices, the buffer to be terminated will be one that was loaded/created with the BASS_SAMPLE_MUTEMAX flag and is beyond it's max distance (maxdist). If there are no buffers that match this criteria, then the play call will fail.
BASS_VAM_TERM_PRIO | If there are no free hardware voices, the buffer to be terminated will be the one with the lowest priority. This flag may be used with the TERM_TIME or TERM_DIST flag, if multiple voices have the same priority then the time or distance is used to decide which voice to terminate.
priority | Priority, used with the BASS_VAM_TERM_PRIO flag... 0 (min) - 0xFFFFFFFF (max).

Remarks
When a sample has 3D functionality, the iangle and oangle angles decide how wide the sound is projected around the orientation angle (as specified when calling BASS_SamplePlay3D, or as set with BASS_ChannelSet3DPosition when the sample is playing). Within the inside angle the volume level is the level set in the volume member (or as set with BASS_ChannelSetAttributes when the sample is playing). Outside the outer angle, the volume changes according to the outvol value. Between the inner and outer angles, the volume gradually changes between the inner and outer volume levels. If the inner and outer angles are 360 degrees, then the sound is transmitted equally in all directions.

When VAM is enabled, and neither the BASS_VAM_HARDWARE or BASS_VAM_SOFTWARE flags are specified, then the sample will be played in hardware if resources are available, and in software if no hardware resources are available.

See also
BASS_SampleCreate, BASS_SampleGetInfo, BASS_SampleLoad, BASS_SampleSetInfo


BASS_SampleCreate

Initiates the creation of a custom generated sample.

void* WINAPI BASS_SampleCreate(
    DWORD length,
    DWORD freq,
    DWORD max,
    DWORD flags
);

Parameters
length | The sample's length, in samples (ie. not bytes).
freq | The default sample rate... 100 (min) - 100000 (max)
max | Maximum number of simultaneous playbacks... 1 (min) - 65535 (max)... use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).
flags A combination of these flags.
BASS_SAMPLE_8BITS | Use 8 bit resolution, else 16 bit.
BASS_SAMPLE_MONO | Mono, else stereo.
BASS_SAMPLE_LOOP | Looped? Note that only complete sample loops are allowed by DirectSound (ie. you can't loop just part of a sample).
BASS_SAMPLE_SOFTWARE | Force the sample to not use hardware mixing.
BASS_SAMPLE_VAM requires DirectX 7.0 or above | Enables the DX7 voice allocation and management features on the sample, which allows the sample to be played in software or hardware. Do not use together with the BASS_SAMPLE_SOFTWARE flag.
BASS_SAMPLE_3D | Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init.
BASS_SAMPLE_MUTEMAX | Mute the sample when it is at (or beyond) it's max distance (3D samples only).
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overriden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overriden.
BASS_SAMPLE_OVER_DIST | Override: the channel furthest away (from the listener) is overriden (3D samples only).

Return value
If successful, a pointer to the memory location at which the sample data should be written is returned. If an error occured, NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_ALREADY | A sample is already being created. BASS_SampleCreateDone must be called to finish creating the previous sample, before trying to create another one.
BASS_ERROR_FREQ | freq is out of range... DirectSound only allows sample rates between 100 and 100000.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | Couldn't initialize 3D support for the sample.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
After writing the sample data to the memory location returned, call BASS_SampleCreateDone to finish the sample's creation and get a handle for the new sample.

The BASS_SAMPLE_VAM flag is ignored if the version of DirectX used is less than 7.0, you can check which version of DirectSound is being used with BASS_GetInfo.

Example
To create a 440hz sine-wave.

HSAMPLE handle;
int a;
short *data=BASS_SampleCreate(128, 28160, 1, BASS_SAMPLE_MONO|BASS_SAMPLE_LOOP|BASS_SAMPLE_OVER_POS);
for (a=0;a<128;a++)
    *data++=(int)(32767.0*sin((double)a*6.283185/64.0));
handle=BASS_SampleCreateDone(); // get the new sample's handle

See also
BASS_SampleCreateDone, BASS_SampleLoad


BASS_SampleCreateDone

Completes the creation of a custom generated sample.

HSAMPLE WINAPI BASS_SampleCreateDone();

Return value
If successful, the new sample's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
Use BASS_SampleGetInfo and BASS_SampleSetInfo to set the default attributes (volume, etc...) of the sample.

See also
BASS_SampleCreate, BASS_SampleFree, BASS_SampleGetInfo, BASS_SampleLoad, BASS_SamplePlay, BASS_SamplePlay3D, BASS_SamplePlay3DEx, BASS_SamplePlayEx


BASS_SampleFree

Frees a sample's resources.

void WINAPI BASS_SampleFree(
    HSAMPLE handle
);

Parameters
handle The sample handle.

See also
BASS_SampleCreate, BASS_SampleLoad


BASS_SampleGetInfo

Retrieves a sample's default attributes and other information.

BOOL WINAPI BASS_SampleGetInfo(
    HSAMPLE handle,
    BASS_SAMPLE *info
);

Parameters
handle | The sample handle.
info | Pointer to store the sample information at.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE The handle is invalid.

Remarks
Use this function and BASS_SampleSetInfo to edit a sample's default attributes.

See also
BASS_SampleSetInfo, BASS_SAMPLE structure


BASS_SampleLoad

Loads a WAV sample.

HSAMPLE WINAPI BASS_SampleLoad(
    BOOL mem,
    void *file,
    DWORD offset,
    DWORD length,
    DWORD max,
    DWORD flags
);

Parameters
mem | TRUE = load the sample from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to load the sample from (only used if mem = FALSE).
length | Data length (only used if mem = FALSE)... 0 = use all data up to the end of file. If length over-runs the end of the file, it'll automatically be lowered to the end of the file.
max | Maximum number of simultaneous playbacks... 1 (min) - 65535 (max)... use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).
flags A combination of these flags.
BASS_SAMPLE_LOOP | Looped? Note that only complete sample loops are allowed by DirectSound (ie. you can't loop just part of a sample).
BASS_SAMPLE_SOFTWARE | Force the sample to not use hardware mixing.
BASS_SAMPLE_VAM requires DirectX 7.0 or above | Enables the DX7 voice allocation and management features on the sample, which allows the sample to be played in software or hardware. Do not use together with the BASS_SAMPLE_SOFTWARE flag.
BASS_SAMPLE_3D | Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init.
BASS_SAMPLE_MUTEMAX | Mute the sample when it is at (or beyond) it's max distance (3D samples only).
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overriden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overriden.
BASS_SAMPLE_OVER_DIST | Override: the channel furthest away (from the listener) is overriden (3D samples only).

Return value
If successful, the loaded sample'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_FILEOPEN | The file could not be opened.
BASS_ERROR_FORMAT | The file's format is not recognised/supported.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | Couldn't initialize 3D support for the sample.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
WAV files can be in standard Windows PCM format or they can be compressed with any CODEC, but the CODEC is required to be installed on the user's computer for the WAV to be decoded. So, you should either distribute the CODEC with your software, or use a CODEC that comes with Windows (eg. Microsoft ADPCM).

The BASS_SAMPLE_VAM flag is ignored if the version of DirectX used is less than 7.0, you can check which version of DirectSound is being used with BASS_GetInfo.

Use BASS_SampleGetInfo and BASS_SampleSetInfo to set the default attributes (volume, etc...) of the sample.

See also
BASS_SampleCreate, BASS_SampleFree, BASS_SampleGetInfo, BASS_SamplePlay, BASS_SamplePlay3D, BASS_SamplePlay3DEx, BASS_SamplePlayEx


BASS_SamplePlay

Plays a sample, using the sample's default attributes.

HCHANNEL WINAPI BASS_SamplePlay(
    HSAMPLE handle
);

Parameters
handle Handle of the sample to play.

Return value
If successful, the handle of the channel used to play the sample is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid sample handle.
BASS_ERROR_NO3D | The sample has 3D functionality... BASS_SamplePlay3D should be used to play it.
BASS_ERROR_NOCHAN | The sample has no free channel on which to be played... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specfied for the sample.
BASS_ERROR_NOHW | No hardware voices are available... this only occurs if the sample was loaded or created with the BASS_SAMPLE_VAM flag, and BASS_VAM_HARDWARE is set in the sample's VAM mode, and there are no hardware voices available to play it.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Remarks
Use BASS_SampleGetInfo and BASS_SampleSetInfo to set a sample's default attributes.

See also
BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_SampleCreate, BASS_SampleLoad, BASS_SamplePlayEx, BASS_SampleStop


BASS_SamplePlay3D

Plays a sample with 3D functionality, using the sample's default attributes.

HCHANNEL WINAPI BASS_SamplePlay3D(
    HSAMPLE handle
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
);

Parameters
handle | Handle of the sample to play.
pos | Position of the sound... NULL = x / y / z = 0.
orient | Orientation of the sound... NULL = x / y / z = 0.
vel | Velocity of the sound... NULL = x / y / z = 0. This is only used to calculate the doppler effect, and has no effect on the sound's position.

Return value
If successful, the handle of the channel used to play the sample is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid sample handle.
BASS_ERROR_NO3D | The sample does not have 3D functionality... BASS_SamplePlay should be used to play it.
BASS_ERROR_NOCHAN | The sample has no free channel on which to be played... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specfied for the sample.
BASS_ERROR_NOHW | No hardware voices are available... this only occurs if the sample was loaded or created with the BASS_SAMPLE_VAM flag, and BASS_VAM_HARDWARE is set in the sample's VAM mode, and there are no hardware voices available to play it.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

Remarks
Use BASS_SampleGetInfo and BASS_SampleSetInfo to set a sample's default attributes.

See also
BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_SampleCreate, BASS_SampleLoad, BASS_SamplePlay3DEx, BASS_SampleStop


BASS_SamplePlay3DEx

Plays a sample with 3D functionality from an offset, overriding the sample's default attributes with those specified.

HCHANNEL WINAPI BASS_SamplePlay3DEx(
    HSAMPLE handle
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
    DWORD start,
    int freq,
    int volume,
    BOOL loop
);

Parameters
handle | Handle of the sample to play.
pos | Position of the sound... NULL = x / y / z = 0.
orient | Orientation of the sound... NULL = x / y / z = 0.
vel | Velocity of the sound... NULL = x / y / z = 0. This is only used to calculate the doppler effect, and has no effect on the sound's position.
start | Playback start position in samples (not bytes).
freq | The sample rate... 100 (min) - 100000 (max), -1 = use sample's default.
volume | The volume... 0 (silent) - 100 (max), -1 = use sample's default.
loop | TRUE = Loop the sample... -1 = use sample's default.

Return value
If successful, the handle of the channel used to play the sample is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid sample handle.
BASS_ERROR_FREQ | freq is out of range... DirectSound only allows sample rates between 100 and 100000.
BASS_ERROR_NO3D | The sample does not have 3D functionality... BASS_SamplePlayEx should be used to play it.
BASS_ERROR_NOCHAN | The sample has no free channel on which to be played... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specfied for the sample.
BASS_ERROR_NOHW | No hardware voices are available... this only occurs if the sample was loaded or created with the BASS_SAMPLE_VAM flag, and BASS_VAM_HARDWARE is set in the sample's VAM mode, and there are no hardware voices available to play it.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

See also
BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_SampleCreate, BASS_SampleLoad, BASS_SamplePlay3D, BASS_SampleStop


BASS_SamplePlayEx

Plays a sample from an offset, overriding the sample's default attributes with those specified.

HCHANNEL WINAPI BASS_SamplePlayEx(
    HSAMPLE handle,
    DWORD start,
    int freq,
    int volume,
    int pan,
    BOOL loop
);

Parameters
handle | Handle of the sample to play.
start | Playback start position in samples (not bytes).
freq | The sample rate... 100 (min) - 100000 (max), -1 = use sample's default.
volume | The volume... 0 (silent) - 100 (max), -1 = use sample's default.
pan | The panning position... -100 (left) - 100 (right), -101 = use sample's default.
loop | TRUE = Loop the sample... -1 = use sample's default.

Return value
If successful, the handle of the channel used to play the sample is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid sample handle.
BASS_ERROR_FREQ | freq is out of range... DirectSound only allows sample rates between 100 and 100000.
BASS_ERROR_NO3D | The sample has 3D functionality... BASS_SamplePlay3DEx should be used to play it.
BASS_ERROR_NOCHAN | The sample has no free channel on which to be played... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specfied for the sample.
BASS_ERROR_POSITION | The start position is beyond the end of the sample.
BASS_ERROR_NOHW | No hardware voices are available... this only occurs if the sample was loaded or created with the BASS_SAMPLE_VAM flag, and BASS_VAM_HARDWARE is set in the sample's VAM mode, and there are no hardware voices available to play it.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

See also
BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_SampleCreate, BASS_SampleLoad, BASS_SamplePlay, BASS_SampleStop


BASS_SampleSetInfo

Sets a sample's default attributes.

BOOL WINAPI BASS_SampleSetInfo(
    HSAMPLE handle,
    BASS_SAMPLE *info
);

Parameters
handle | The sample handle.
info | Pointer to the sample information structure.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE The handle is invalid.

Remarks
Use this function and BASS_SampleGetInfo to edit a sample's default attributes. Changing a sample's default attributes does not affect any currently playing instances of the sample, it only affects subsequent playings of the sample. Use BASS_ChannelSetAttributes and BASS_ChannelSet3DAttributes to change the attributes of a playing sample.

Only the freq, volume, pan, flags (LOOP and OVER_xxx only) and the 3D attribute members of the BASS_SAMPLE structure are editable.

See also
BASS_ChannelSet3DAttributes, BASS_ChannelSetAttributes, BASS_SampleGetInfo, BASS_SAMPLE structure


BASS_SampleStop

Stops all instances of a sample.

BOOL WINAPI BASS_SampleStop(
    HSAMPLE handle
);

Parameters
handle The sample handle.

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE handle is not a valid sample.

Remarks
If a sample is playing simultaneously multiple times, calling this function will stop them all, which is obviously simpler than calling BASS_ChannelStop multiple times.

See also
BASS_ChannelStop, BASS_SamplePlay, BASS_SamplePlay3D, BASS_SamplePlay3DEx, BASS_SamplePlayEx


BASS_Set3DAlgorithm
requires DirectX 7.0 or above

Sets the 3D algorithm for software mixed 3D channels.

void WINAPI BASS_Set3DAlgorithm(
    DWORD algo
);

Parameters
algo One of these algorithms.
BASS_3DALG_DEFAULT | The default algorithm... currently translates to BASS_3DALG_OFF.
BASS_3DALG_OFF | Uses normal left and right panning. The vertical axis is ignored except for scaling of volume due to distance. Doppler shift and volume scaling are still applied, but the 3D filtering is not performed. This is the most CPU efficient algorithm, but provides no virtual 3D audio effect. Head Related Transfer Function processing will not be done. Since only normal stereo panning is used, a channel using this algorithm may be accelerated by a 2D hardware voice if no free 3D hardware voices are available.
BASS_3DALG_FULL | This algorithm gives the highest quality 3D audio effect, but uses more CPU. This algorithm requires Windows 98 2nd Edition or Windows 2000 and WDM drivers, if it's not available then BASS_3DALG_OFF will automatically be used instead.
BASS_3DALG_LIGHT | This algorithm gives a good 3D audio effect, and uses less CPU than the FULL algorithm. This algorithm also requires Windows 98 2nd Edition or Windows 2000 and WDM drivers, if it's not available then BASS_3DALG_OFF will automatically be used instead.

Remarks
These algorithms only affect 3D channels that are being mixed in software. You can test for the BASS_SAMPLE_SOFTWARE flag with BASS_ChannelGetFlags to check if a channel is being software mixed.

This function allows you to use higher quality 3D processing on more powerful CPUs, and more efficient 3D processing on less powerful CPUs. Changing the algorithm only affects subsequently created or loaded samples, musics or streams, it does not affect those that already exist.

See also
BASS_ChannelGetFlags, BASS_SampleCreate, BASS_SampleLoad


BASS_Set3DFactors

Sets the factors that affect the calculations of 3D sound.

BOOL WINAPI BASS_Set3DFactors(
    float distf,
    float rollf,
    float doppf
);

Parameters
distf | The distance factor... less than 0.0 = leave current... examples: 1.0 = use meters, 0.9144 = use yards, 0.3048 = use feet. By default BASS measures distances in meters, you can change this setting if you are using a different unit of measurement.
rollf | The rolloff factor, how fast the sound quietens with distance... 0.0 (min) - 10.0 (max), less than 0.0 = leave current... examples: 0.0 = no rolloff, 1.0 = real world, 2.0 = 2x real.
doppf | The doppler factor... 0.0 (min) - 10.0 (max), less than 0.0 = leave current... examples: 0.0 = no doppler, 1.0 = real world, 2.0 = 2x real. The doppler effect is the way a sound appears to change pitch when it is moving towards or away from you. The listener and sound velocity settings are used to calculate this effect, this doppf value can be used to lessen or exaggerate the effect.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NO3D BASS_Init has not been successfully called with BASS_DEVICE_3D specified in the flags parameter.

Remarks
As with all 3D functions, use BASS_Apply3D to apply the changes.

Example
To use yards as the distance measurement unit, while leaving the current rolloff and doppler factors untouched.

BASS_Set3DFactors(0.9144, -1.0, -1.0);
BASS_Apply3D(); // apply the change

See also
BASS_Apply3D, BASS_Get3DFactors


BASS_Set3DPosition

Sets the position, velocity, and orientation of the listener (ie. the player).

BOOL WINAPI BASS_Set3DPosition(
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *vel,
    BASS_3DVECTOR *front
    BASS_3DVECTOR *top
);

Parameters
pos | The position of the listener... NULL = leave current.
vel | The listener's velocity in units (as set with BASS_Set3DFactors) per second... NULL = leave current. This is only used to calculate the doppler effects, and in no way affects the listener's position.
front | The direction that the listener's front is pointing... NULL=leave current.
top | The direction that the listener's top is pointing... NULL = leave current.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NO3D BASS_Init has not been successfully called with BASS_DEVICE_3D specified in the flags parameter.

Remarks
The front and top parameters must both be set in a single call, they can not be set individually. As with all 3D functions, use BASS_Apply3D to apply the changes.

See also
BASS_Apply3D, BASS_Get3DPosition, BASS_Set3DFactors, BASS_3DVECTOR structure


BASS_SetA3DHFAbsorbtion

Sets the A3D high frequency absorption factor.

BOOL WINAPI BASS_SetA3DHFAbsorbtion(
    float factor
);

Parameters
factor HF absorbtion factor... 0.0 = disable, 1.0 = normal (default), less than 1.0 = diminish, higher than 1.0 = exaggerate.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOA3D | The current device does not support A3D, or BASS_DEVICE_A3D was not specified with BASS_Init.
BASS_ERROR_ILLPARAM | The factor is invalid.

Remarks
The HF factor can be manipulated to simulate different atmospheric environments, such as thick fog or underwater. The default HF factor is 1.0, which provides normal HF attenuation for air. Setting the HF factor to 0.0 disables the HF absorption.

See also
BASS_GetA3DHFAbsorbtion


BASS_SetA3DResManager

Sets the A3D resource management mode.

BOOL WINAPI BASS_SetA3DResManager(
    DWORD mode
);

Parameters
mode One of these modes.
A3D_RESMODE_OFF | Disables resource management... the standard DirectSound method, and the default mode.
A3D_RESMODE_DYNAMIC | Non-looping sound playback is optimized via the resource manager. If a channel is played and there are no available resources, another channel will be stopped and replaced with the new one. Looping channels will not be stopped and are never automatically switched out.
A3D_RESMODE_DYNAMIC_LOOPERS requires A3D 1.2 | Identical to the previous mode, except looping channels are also managed. Management is handled by limiting the number of looping channels to half the hardware's capacity. The loudest channels are always given priority... as sounds move around in the 3D world, the most prevalent sounds are always playing.
A3D_RESMODE_NOTIFY | If there aren't any hardware resources left, trying to play a channel will fail and return an error to indicate this. Stopping one or more playing channels (channels of different formats can take up more or less hardware resources) will then allow the target channel to play. This mode is helpful for applications that do their own resource management.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOA3D | The current device does not support A3D, or BASS_DEVICE_A3D was not specified with BASS_Init.
BASS_ERROR_ILLPARAM | The mode is invalid.

Remarks
For best performance, always use 22kHz, 16-bit mono samples. Using the same format samples optimizes resource management, and 22kHz, 16-bit is the optimal format for most A3D sound cards. Other formats and sample rates could reduce the number of available A3D channels, or otherwise degrade the sound quality. When the resource manager is enabled, many A3D sound cards will down-sample 44kHz samples to 22kHz. This assures the number of concurrent A3D sources are maximized.

See also
BASS_GetA3DResManager, BASS_GetInfo


BASS_SetBufferLength

Sets the amount that BASS mixes ahead new musics and streams.

void WINAPI BASS_SetBufferLength(
    float length
);

Parameters
length The buffer length in seconds... limited to between 0.3s and 2.0s.

Remarks
Increasing the buffer length, decreases the chance of the sound possibly breaking-up on slower computers, but also requires more memory. Changing this setting only affects the musics/streams that you load/create afterwards, not the ones that have already been loaded/created. The default length is 0.5 secs.

This setting does not represent the latency (the delay between playing and hearing the sound). The latency primarily depends on the output device and it's drivers. If a driver has hardware support, then the latency should be very small. You can use BASS_GetInfo to check if a device has hardware support drivers.

The power of the CPU, and the complexity of what's being mixed (eg. an IT using filters requires more processing than a plain 4 channel MOD), also has an effect on the time taken to perform the initial processing required to start the playback of a music or stream.


BASS_SetEAXParameters

Sets the type of EAX environment and it's parameters.

BOOL WINAPI BASS_SetEAXParameters(
    int env,
    float vol,
    float decay,
    float damp
);

Parameters
env | The EAX environment... -1 = leave current, or one of the these. EAX_ENVIRONMENT_GENERIC, EAX_ENVIRONMENT_PADDEDCELL, EAX_ENVIRONMENT_ROOM, EAX_ENVIRONMENT_BATHROOM, EAX_ENVIRONMENT_LIVINGROOM, EAX_ENVIRONMENT_STONEROOM, EAX_ENVIRONMENT_AUDITORIUM, EAX_ENVIRONMENT_CONCERTHALL, EAX_ENVIRONMENT_CAVE, EAX_ENVIRONMENT_ARENA, EAX_ENVIRONMENT_HANGAR, EAX_ENVIRONMENT_CARPETEDHALLWAY, EAX_ENVIRONMENT_HALLWAY, EAX_ENVIRONMENT_STONECORRIDOR, EAX_ENVIRONMENT_ALLEY, EAX_ENVIRONMENT_FOREST, EAX_ENVIRONMENT_CITY, EAX_ENVIRONMENT_MOUNTAINS, EAX_ENVIRONMENT_QUARRY, EAX_ENVIRONMENT_PLAIN, EAX_ENVIRONMENT_PARKINGLOT, EAX_ENVIRONMENT_SEWERPIPE, EAX_ENVIRONMENT_UNDERWATER, EAX_ENVIRONMENT_DRUGGED, EAX_ENVIRONMENT_DIZZY, EAX_ENVIRONMENT_PSYCHOTIC.
vol | The volume of the reverb... 0.0 (off) - 1.0 (max), less than 0.0 = leave current.
decay | The time in seconds it takes the reverb to diminish by 60dB... 0.1 (min) - 20.0 (max), less than 0.0 = leave current.
damp | The damping, high or low frequencies decay faster... 0.0 = high decays quickest, 1.0 = low/high decay equally, 2.0 = low decays quickest, less than 0.0 = leave current.

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_NOEAX The current device does not support EAX.

Remarks
Obviously, EAX functions have no effect if no EAX supporting device (ie. SB Live) is used. You can use BASS_GetInfo to check if the current device suports EAX. EAX only affects 3D channels, but EAX functions do NOT require BASS_Apply3D to apply the changes.

Presets are provided for all the EAX environments. To use a preset, simply call BASS_SetEAXParameters(preset), where preset is one of these.
EAX_PRESET_GENERIC, EAX_PRESET_PADDEDCELL, EAX_PRESET_ROOM, EAX_PRESET_BATHROOM, EAX_PRESET_LIVINGROOM, EAX_PRESET_STONEROOM, EAX_PRESET_AUDITORIUM, EAX_PRESET_CONCERTHALL, EAX_PRESET_CAVE, EAX_PRESET_ARENA, EAX_PRESET_HANGAR, EAX_PRESET_CARPETEDHALLWAY, EAX_PRESET_HALLWAY, EAX_PRESET_STONECORRIDOR, EAX_PRESET_ALLEY, EAX_PRESET_FOREST, EAX_PRESET_CITY, EAX_PRESET_MOUNTAINS, EAX_PRESET_QUARRY, EAX_PRESET_PLAIN, EAX_PRESET_PARKINGLOT, EAX_PRESET_SEWERPIPE, EAX_PRESET_UNDERWATER, EAX_PRESET_DRUGGED, EAX_PRESET_DIZZY, EAX_PRESET_PSYCHOTIC.

Example
To use the EAX_PRESET_ARENA preset.

BASS_SetEAXParameters(EAX_PRESET_ARENA);

See also
BASS_ChannelSetEAXMix, BASS_GetEAXParameters


BASS_SetGlobalVolumes

Sets the global music/sample/stream volume levels.

void WINAPI BASS_SetGlobalVolumes(
    int musvol,
    int samvol,
    int strvol
);

Parameters
musvol | MOD music global volume level... 0 (silent) - 100 (max), -1 = leave current.
samvol | Sample global volume level... 0 (silent) - 100 (max), -1 = leave current.
strvol | Stream global volume level... 0 (silent) - 100 (max), -1 = leave current.

Remarks
This function allows you to have control over the volume levels of all the MOD musics, samples and streams, which is useful for setup options (eg. seperate music and fx volume controls).

A channel's final volume = channel volume * global volume / 100. So, for example, if a stream channel's volume is 50 and the global stream volume is 80, then effectively the stream's volume level is 40 (50 * 80 / 100 = 40).

See also
BASS_GetGlobalVolumes, BASS_ChannelSetAttributes


BASS_SetLogCurves

Sets the translation curves of the volume and panning values to either logarithmic or linear.

void WINAPI BASS_SetGlobalVolumes(
    BOOL volume,
    BOOL pan
);

Parameters
volume | Volume curve... FALSE = linear, TRUE = logarithmic.
pan | Panning curve... FALSE = linear, TRUE = logarithmic.

Remarks
DirectSound uses logarithmic volume and panning curves, which can be very awkward to work with. For example, with a logarithmic curve, the audible difference between 100 and 90, is not the same as between 90 and 80. With a linear "curve" the audible difference is spread equally across the whole range of values, so in the previous example the audible difference between 100 and 90, and between 90 and 80 would be identical.

Most people will find it much easier working with a linear curve, so this is what BASS uses by default. But if you want to use the DirectSound logarithmic curve then you can do so by switching to the logarithmic curve with this function.


BASS_SetVolume

Sets the digital output master volume.

BOOL WINAPI BASS_SetVolume(
    DWORD volume
);

Parameters
volume The volume level... 0 (min) - 100 (max).

Return value
If succesful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks
The "digital output master volume" affects the output level of all samples/streams/musics, but not the CD audio. To adjust the CD volume level use BASS_ChannelSetAttributes.

See also
BASS_GetVolume


BASS_Start

Starts (or resumes) the digital output.

BOOL WINAPI BASS_Start();

Return value
If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT The BASS digital output has not been initialized. You must successfully call BASS_Init before calling BASS_Start.

See also
BASS_Pause, BASS_Stop


BASS_Stop

Stops the digital output, stopping all musics/samples/streams.

BOOL WINAPI BASS_Stop();

Return value
If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks
You can use BASS_Stop after BASS_Pause to stop the paused channels, so that they will not be resumed the next time you call BASS_Start.

See also
BASS_Pause, BASS_Start


BASS_StreamCreate

Creates a user sample stream.

HSTREAM WINAPI BASS_StreamCreate(
    DWORD freq,
    DWORD flags,
    STREAMPROC *proc
    DWORD user
);

Parameters
freq | The default sample rate (between 100 and 100000). The sample rate can be changed at any time using BASS_ChannelSetAttributes.
flags Any combination of these flags.
BASS_SAMPLE_8BITS | Use 8 bit resolution, else 16 bit.
BASS_SAMPLE_MONO | Use mono, else stereo.
BASS_SAMPLE_3D | Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init.
proc | The user defined stream writing function.
user | User instance data to pass to the callback function.

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_FREQ | freq is out of range... DirectSound only allows sample rates between 100 and 100000.
BASS_ERROR_FORMAT | The specified format is not supported.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | Couldn't initialize 3D support for the stream.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
Sample streams allow any sample format to be played through BASS, and are particularly useful for playing a large amount of sample data without requiring a large amount of memory. If you wish to play a sample format that BASS does not support, then you can create a stream and decode the sample data into it.

BASS can automatically stream MP3 and WAV files, see BASS_StreamCreateFile for details.

See also
BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttributes, BASS_ChannelSetEAXMix, BASS_StreamCreateFile, BASS_StreamFree, BASS_StreamPlay, STREAMPROC callback


BASS_StreamCreateFile

Creates a sample stream from an MP3 or WAV file.

HSTREAM WINAPI BASS_StreamCreateFile(
    BOOL mem,
    void *file,
    DWORD offset,
    DWORD length,
    DWORD flags
);

Parameters
mem | TRUE = stream the file from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to begin streaming from (only used if mem = FALSE).
length | Data length... 0 = use all data up to the end of the file (if mem = FALSE).
flags Any combination of these flags.
BASS_SAMPLE_3D | Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init.
BASS_SAMPLE_MONO | Play the stream (MP3 only) in mono, reducing the CPU usage (if it was originally stereo). This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_MP3_HALFRATE | Half the MP3's sample rate, reducing the CPU usage. This flag is automatically applied if the halved rate is equal to or above the output rate specified when calling BASS_Init.
BASS_MP3_SETPOS | Enable seeking on the MP3 (it's always enabled on WAVs), using BASS_ChannelSetPosition. This also increases the time taken to initialize the MP3.

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_FILEOPEN | The file could not be opened.
BASS_ERROR_ILLPARAM | The length must be specified when streaming from memory.
BASS_ERROR_FORMAT | The file's format is not recognised/supported.
BASS_ERROR_MEM | There is insufficent memory.
BASS_ERROR_NO3D | Couldn't initialize 3D support for the stream.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks
MPEG 1.0 and 2.0 layer 3 files are supported, layers 1 and 2 are not. But they have worse quality and compression ratios, so it's no big loss!

WAV files can be in standard Windows PCM format or they can be compressed with any CODEC, but the CODEC is required to be installed on the user's computer for the WAV to be decoded. So, you should either distribute the CODEC with your software, or use a CODEC that comes with Windows (eg. Microsoft ADPCM).

Use BASS_ChannelGetAttributes and BASS_ChannelGetFlags to retrieve information on the format (sample rate, resolution, channels) of the stream. The total length of the stream can be retrieved using BASS_StreamGetLength.

Example
To stream an MP3 file, using reduced quality.

BASS_StreamFileCreate(FALSE,"afile.mp3",0,0,BASS_MP3_HALFRATE);

See also
BASS_ChannelGetAttributes, BASS_ChannelGetFlags, BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttributes, BASS_ChannelSetEAXMix, BASS_ChannelSetPosition, BASS_StreamCreate, BASS_StreamFree, BASS_StreamGetLength, BASS_StreamPlay


BASS_StreamFree

Frees a sample stream's resources.

void WINAPI BASS_StreamFree(
    HSTREAM handle
);

Parameters
handle The stream handle.

See also
BASS_StreamCreate, BASS_StreamCreateFile


BASS_StreamGetBlockLength

Retrieves the playback length (in bytes) of a block in a file stream (WAV/MP3).

DWORD WINAPI BASS_StreamGetBlockLength(
    HSTREAM handle
);

Parameters
handle The stream's handle.

Return value
If succesful, then the stream's block length is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTFILE | The stream is not a file stream... it was not created by using BASS_StreamCreateFile.
BASS_ERROR_POSITION | The BASS_MP3_SETPOS flag was not specified when calling BASS_StreamCreateFile (MP3 only).

Remarks
When calling BASS_ChannelSetPosition, the position is rounded down to the beginning of a block, so you can use this function to calculate the minimum position increase required to move a stream forward.

Example
To move a stream forward by the smallest possible amount.

DWORD pos=BASS_ChannelGetPosition(a_stream); // get current pos
pos+=BASS_StreamGetBlockLength(a_stream); // add block length
BASS_ChannelSetPosition(a_stream,pos); // set new position

See also
BASS_ChannelSetPosition, BASS_StreamGetLength


BASS_StreamGetLength

Retrieves the playback length (in bytes) of a file stream (WAV/MP3).

DWORD WINAPI BASS_StreamGetLength(
    HSTREAM handle
);

Parameters
handle The stream's handle.

Return value
If succesful, then the stream's length is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTFILE | The stream is not a file stream... it was not created by using BASS_StreamCreateFile.

Remarks
It's not always possible to 100% accurately estimate the length of a stream, so the length returned may be only an approximation when using some WAV codecs. The length is always accurate for MP3s when the BASS_MP3_SETPOS flag is used with BASS_StreamCreateFile. When the BASS_MP3_SETPOS flag is not used, the length is an estimation based on the file size.

Example
To get the duration (in seconds) of a file stream.

DWORD len,freq,flags,time;
len=BASS_StreamGetLength(a_stream); // length in bytes
BASS_ChannelGetAttributes(a_stream,&freq,0,0); // sample rate
flags=BASS_ChannelGetFlags(a_stream); // stereo/mono, 8/16 bit flags
time=len/(freq*(flags&BASS_SAMPLE_MONO?1:2)*(flags&BASS_SAMPLE_8BITS?1:2)); // the time length

See also
BASS_ChannelSetPosition, BASS_StreamGetBlockLength


BASS_StreamPlay

Plays a sample stream.

BOOL WINAPI BASS_StreamPlay(
    HSTREAM handle,
    BOOL flush,
    DWORD flags
);

Parameters
handle | Handle of the stream to play.
flush | Flush buffer contents?.. If you stop a stream and then want to continue it from where it stopped, don't flush it. Flushing a file stream (created with BASS_StreamCreateFile) causes it to be restarted from the beginning.
flags Any combination of these flags.
BASS_SAMPLE_LOOP Loop the file. (file streams only)

Return value
If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes
BASS_ERROR_START | The digital output has not been started. Use BASS_Start to do so.
BASS_ERROR_HANDLE | handle is not a valid stream handle.
BASS_ERROR_BUFLOST | Should not happen, but... PLEASE REPORT IT IF YOU DO GET THIS ERROR!

See also
BASS_ChannelGetLevel, BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelStop, BASS_StreamCreate, BASS_StreamCreateFile


What is a channel?
A "channel" can be a playing sample (HCHANNEL), a MOD music (HMUSIC), a sample stream (HSTREAM), or the CD (CDCHANNEL). Each BASS_Channel function can be used with one or more of these channel types.

The types of channel
HCHANNEL | Returned by BASS_SamplePlay, BASS_SamplePlayEx, BASS_SamplePlay3D, BASS_SamplePlay3DEx.
HMUSIC | Returned by BASS_MusicLoad.
HSTREAM | Returned by BASS_StreamCreate, BASS_StreamCreateFile.
CDCHANNEL | A handle reserved for the CD channel.


DSPPROC callback

User defined DSP callback function.

void CALLBACK YourDSPProc(
    HDSP handle,
    DWORD channel,
    void *buffer,
    DWORD length,
    DWORD user
);

Parameters
handle | The DSP handle.
channel | Channel that the DSP is being applied to.
buffer | The buffer to apply the DSP to. The sample data is in standard Windows PCM format... 8 bit samples are unsigned, 16 bit samples are signed.
length | The number of BYTES to process.
user | The user instance data given when BASS_ChannelSetDSP was called.

Remarks
A DSP function should obviously be as quick as possible... streams, MOD musics and other DSP functions can not be processed until it has finished.

Example
A simple DSP callback function to swap the left/right channels of a 16-bit stereo source.

void CALLBACK MyDSPProc(HDSP handle, DWORD channel, void *buffer, DWORD length, DWORD user) {
    short *s=buffer;
    for (;length;length-=4,s+=2) {
        short temp=s[0];
        s[0]=s[1];
        s[1]=temp;
    }
}

See also
BASS_ChannelSetDSP


BASS.TXT
BASS functions
BASS_ErrorGetCode
BASS_Free
BASS_GetCPU
BASS_GetDeviceDescription
BASS_GetDSoundObject
BASS_GetGlobalVolumes
BASS_GetInfo
BASS_GetVersion
BASS_GetVolume
BASS_Init
BASS_Pause
BASS_SetBufferLength
BASS_SetGlobalVolumes
BASS_SetLogCurves
BASS_SetVolume
BASS_Start
BASS_Stop
3D/A3D/EAX functions
BASS_Apply3D
BASS_Get3DFactors
BASS_Get3DPosition
BASS_GetA3DHFAbsorbtion
BASS_GetA3DResManager
BASS_GetEAXParameters
BASS_Set3DAlgorithm
BASS_Set3DFactors
BASS_Set3DPosition
BASS_SetA3DHFAbsorbtion
BASS_SetA3DResManager
BASS_SetEAXParameters
CD audio functions
BASS_CDFree
BASS_CDInDrive
BASS_CDInit
BASS_CDPlay
Sample functions
BASS_SampleCreate
BASS_SampleCreateDone
BASS_SampleFree
BASS_SampleGetInfo
BASS_SampleLoad
BASS_SamplePlay
BASS_SamplePlay3D
BASS_SamplePlay3DEx
BASS_SamplePlayEx
BASS_SampleSetInfo
BASS_SampleStop
Stream functions
BASS_StreamCreate
BASS_StreamCreateFile
BASS_StreamFree
BASS_StreamGetBlockLength
BASS_StreamGetLength
BASS_StreamPlay
MOD/3 music functions
BASS_MusicFree
BASS_MusicGetLength
BASS_MusicGetName
BASS_MusicLoad
BASS_MusicPlay
BASS_MusicPlayEx
BASS_MusicSetAmplify
BASS_MusicSetPanSep
BASS_MusicSetPositionScaler
Channel functions
What is a channel? BASS_ChannelGet3DAttributes
BASS_ChannelGet3DPosition
BASS_ChannelGetAttributes
BASS_ChannelGetData
BASS_ChannelGetEAXMix
BASS_ChannelGetFlags
BASS_ChannelGetLevel
BASS_ChannelGetPosition
BASS_ChannelIsActive
BASS_ChannelPause
BASS_ChannelRemoveDSP
BASS_ChannelRemoveSync
BASS_ChannelResume
BASS_ChannelSet3DAttributes
BASS_ChannelSet3DPosition
BASS_ChannelSetAttributes
BASS_ChannelSetDSP
BASS_ChannelSetEAXMix
BASS_ChannelSetPosition
BASS_ChannelSetSync
BASS_ChannelStop
BASS structures
BASS_3DVECTOR
BASS_INFO
BASS_SAMPLE
Callback functions
DSPPROC
STREAMPROC
SYNCPROC
©1999-2000 Ian Luck.


STREAMPROC callback

User stream writing callback function.

DWORD CALLBACK YourStreamProc{
    HSTREAM handle,
    void *buffer,
    DWORD length
    DWORD user
);

Parameters
handle | The stream that needs writing.
buffer | The buffer to write the sample data in. The sample data must be written in standard Windows PCM format... 8 bit samples are unsigned, 16 bit samples are signed.
length | The number of BYTES to write.
user | The user instance data given when BASS_StreamCreate was called.

Return value
The number of bytes written by the function. If this number is less than length, then the stream is assumed to be at the end, and is stopped.

Remarks
A stream writing function should obviously be as quick as possible, other streams (and MOD musics) can't be mixed until it's finished.

Example
A callback function to stream a file, in 44100hz 16 bit stereo.

FILE *file;
...
// the stream writing callback
DWORD CALLBACK MyStreamWriter(HSTREAM handle, void *buf, DWORD len, DWORD user) {
    DWORD c=fread(buf,1,len,file); // read the file into the buffer
    return c; // return the number of bytes written to the buffer
}
...
BASS_StreamCreate(44100,0,&MyStreamWriter,0); // create the stream

See also
BASS_StreamCreate


SYNCPROC callback

User defined synchronizer callback function.

void CALLBACK YourSyncProc(
    HSYNC handle,
    DWORD channel,
    DWORD data
    DWORD user
);

Parameters
handle | The sync that has occured.
channel | The channel that the sync occured on.
data | Additional data associated with the sync's occurance.
user | The user instance data given when BASS_ChannelSetSync was called.

Remarks
A sync callback function should be very quick (eg. just posting a message) as other syncs can't be processed until it has finished.

See also
BASS_ChannelSetSync