Miles Sound System SDK 7.2a

AIL_DLS_open

The function AIL_DLS_open opens a handle to a downloadable sample device.

HDLSDEVICE AIL_DLS_open(
  HMDIDRIVER mdi,
  HDIGDRIVER dig,
  char const * DLS_dll_name,
  U32 flags,
  U32 rate,
  U32 bits,
  U32 channels
);

In Parameters

mdi: indicates the Miles MIDI handle that will be used for the DLS playback (this is only necessary for the software synthesizer).
dig: indicates the Miles digital sound handle that will be used for the DLS playback (this is only necessary for the software synthesizer).
DLS_dll_name: indicates the DLS provider DLL name to use. This should be NULL for the software synthesizer, "S3BASE.DLL" for the Sonic Vibes hardware DLS card, or "VORT_DLS.DLL" for Aureal Vortex DLS cards. In the future, RAD plans to create other DLS provider DLLs, so you should have some method for your application to accept new DLS provider filenames.
flags: should currently be zero.
rate: indicates the rate that the software synthesizer should use. Note that you don't have to match the output rate of the digital driver, so if you need to improve performance, you can slow down the digital MIDI synthesis without affecting the sound quality of the rest of the game. You should generally use the same rate that the DLS file's samples use, and you shouldn't run the synthesizer any faster than the digital driver is running.
bits: indicates the bit quality to use for the software synthesizer (8 or 16 bits). Note that switching from 16-bit output mode to 8-bit output mode won't improve performance all that much. You should generally use the same bit size that the DLS file's samples use, and you shouldn't run the synthesizer in 16-bit mode if the digital driver is in 8-bit mode.
channels: indicates the number of channels to use for the software synthesizer (1 is mono, 2 is stereo). Running the software synthesizer in mono mode increases performance, but you will lose any intended stereo effects in the sequence. You shouldn't run the synthesizer in stereo mode if the digital driver is in mono.

Returns

The DLS device handle to be used with the other Miles DLS functions.

Discussion

Hardware systems are usually very limited in amount of DLS memory that you can use. In fact, to be DLS-1 compatible, a DLS synthesizer need only provide 512K of memory.

In the future, RAD plans to create other DLS provider DLLs, so you should have some method for your application to accept new DLS provider filenames.

The higher the quality of the sound, the higher the CPU usage. If you plan to support a wide range of CPUs, then you should provide a method of allowing the performance to be scaled (from 11Khz, mono, 8-bit with no filtering and no reverb up to 44 Khz, stereo, 16-bit with filtering and reverb). You can use the Miles Sound Player to gauge the performance hit of the various options with your own sequences.

Group: DLS Services
Related Functions: AIL_DLS_close, AIL_quick_handles
Related Basic Types: HDIGDRIVER, HDLSDEVICE, HMDIDRIVER, MILES_OPEN_XMIDI_FLAGS, MILES_PREFERENCES, U32, char const *
Related FAQs: How do I play an XMIDI file with a DLS instrument set?