Miles Sound System SDK 7.2a

MILES_PREFERENCES

The basic type MILES_PREFERENCES describes the Miles Sound System Preferences.

Fundamental Values

Value	Description
DIG_MAX_PREDELAY_MS	This preference controls the maximum predelay you can use when applying 2D digital reverb. The longer the predelay, the more memory is required (4 bytes * the output frequency). This preference value must be changed before calling AIL_open_digital_driver. Environment: DOS/Win32/Win64/MacOS. Units: Milliseconds. Default Value: 500 (ms).
DIG_ENABLE_RESAMPLE_FILTER	This preference determines the whether the MSS mixer should perform sound filtering when upsampling or downsampling a sound effect. This is a very low overhead operation, so you should generally just leave this preference turned on. Environment: DOS/Win32/Win64/MacOS. Units: Boolean ( YES / NO ). Default Value: YES.
DIG_MIXER_CHANNELS	DIG_MIXER_CHANNELS determines the number of HSAMPLE sample handles which may be allocated with the AIL_allocate_sample_handle function. The AIL_create_wave_synthesizer function also allocates a number of sample handles which is determined by its polyphony parameter value. At any moment in time, each instance of a playing digital sound effect requires one HSAMPLE handle. The value of this preference may be increased if desired, but system performance may be degraded if too many samples are played simultaneously. The practical limit depends on the hardware DMA data rate in use and the system's capabilities. For example, it may be possible to play hundreds of samples simultaneously with an 11- kHz 8-bit mono driver configuration running on a high-end PC system, while only one or two simultaneous samples should be played on a 386-class system whose sound driver is configured for 16-bit stereo 44 Khz DMA transfers. Because scaling source sample data to a given hardware configuration consumes a relatively small amount of CPU time, the hardware (DMA) data rate being used affects system performance to a much greater extent than does the playback rate, number of channels, and word size of the source sample data. Any changes made to the DIG_MIXER_CHANNELS preference value must be made prior to installing the digital driver in question. Environment: DOS/Win32/Win64/MacOS. Units: # of simultaneous digital sound effects permitted. Default Value: 64.
DIG_RESAMPLING_TOLERANCE	When the playback rate of a sample passed to MSS differs from the hardware sample rate in use (as defined by the DIG_HARDWARE_SAMPLE_RATE preference), the data must be resampled to play at its normal speed and pitch. This resampling process requires a minute amount of CPU time beyond that required to play data which does not need to be resampled. By setting the DIG_RESAMPLING_TOLERANCE preference prior to initializing a digital audio driver, the application can specify that no resampling is to occur if the source sample data does not vary from the hardware data rate by more than a certain percentage. Environment: DOS/Win32/Win64/MacOS. Units: Tolerance percentage expressed as (n / 65536). Default Value: 0% (0).
AIL_TIMERS	This preference value determines how many HTIMER handles may be allocated with AIL_register_timer. Any changes to this preference value must be made immediately after AIL_startup is called. AIL_TIMERS should not normally need to be changed by the application, except in cases where more than 16 timer service clients, including XMIDI drivers and application callback functions, must be serviced. Environment: DOS/Win32/Win64/MacOS. Units: Number of timers which can be allocated with AIL_register_timer. Default Value: 16.
AIL_CPU_AFFINITY	On some platforms (currently limited to Xbox 360), this preference can be used to bind the Miles background thread to a specified CPU core. This background thread is responsible for executing all of Miles's audio processing and mixing code on the Xbox 360, including any user-registered timers and other callback functions. Any changes to this preference value must be made immediately after AIL_startup is called. Environment: Xbox 360. Units: CPU index passed to the Microsoft XSetThreadProcessor API when Miles creates its background thread. Default Value: 2.
MDI_SERVICE_RATE	When an XMIDI music driver is loaded, the MSS API arranges to receive background timer interrupt service at a rate governed by the MDI_SERVICE_RATE preference. The timer routine is responsible for background playback of XMIDI sequences. This preference also controls the rate at which sequences are converted with the AIL_MIDI_to_XMI function. Any changes to the MDI_SERVICE_RATE preference must be made prior to XMIDI driver installation. Environment: DOS/Win32/Win64/MacOS. Units: Frequency in hertz (interrupts per second). Default Value: 120.
MDI_SEQUENCES	MDI_SEQUENCES determines the number of HSEQUENCE sequence handles which may be allocated with the AIL_allocate_sequence_handle function. At any moment in time, each instance of a playing XMIDI sequence requires one HSEQUENCE handle. The value of this preference may be increased if desired, but the set of 16 physical MIDI channels may limit the number of sequences which can be played simultaneously. Most applications should not need to increase the MDI_SEQUENCES limit. Any changes made to the MDI_SEQUENCES preference value must be made prior to installing the XMIDI driver. Environment: DOS/Win32/Win64/MacOS. Units: # of simultaneously playing XMIDI sequences permissible. Default Value: 8.
MDI_DEFAULT_VOLUME	The MDI_DEFAULT_VOLUME preference value determines the default volume-scaling factor assigned to all channels of all sequences by the AIL_init_sequence function. By default, the individual channel volume controller values in XMIDI sequences are not scaled by MSS. This preference value does not ordinarily need to be changed, since the volume-scaling factor for any XMIDI sequence may be altered at any time by use of the AIL_set_sequence_volume function. Environment: DOS/Win32/Win64/MacOS. Units: MIDI-compatible volume controller units (0-127). Default Value: 127.
MDI_QUANT_ADVANCE	This preference value allows the AIL_sequence_position function to report the XMIDI beat and measure count for a given sequence in advance of their actual occurrences. For more information about this preference, refer to the description of the AIL_sequence_position function. Environment: DOS/Win32/Win64/MacOS. Units: XMIDI quantization intervals (0...n). Default Value: 1.
MDI_ALLOW_LOOP_BRANCHING	When an AIL_branch_index function call is issued, or an XMIDI Sequence Branch controller (109) is encountered in a playing XMIDI sequence, any XMIDI For...Next/Break loops defined with controllers 116 and 117 are canceled in the sequence in question. This is done to prevent errors caused by branches into or out of loops. In cases where branching within a looped portion of a sequence is required, and the musician and programmer are willing to ensure that branches across loop boundaries never occur, the MDI_ALLOW_LOOP_BRANCHING preference may be set to YES to avoid loss of loop information when a branch is taken. Environment: DOS/Win32/Win64/MacOS. Units: Boolean (YES / NO). Default Value: NO.
MDI_DEFAULT_BENDER_RANGE	One important feature introduced with the MSS version 3.00 release was the official support of the Roland Sound Canvas's de facto General MIDI implementation as the baseline standard for XMIDI performance parameters, replacing the obsolete Roland MT-32 standard under which the older libraries were designed. The default pitch bender range under the MT-32 MIDI standard was plus or minus 12 notes, or semitones, but the Sound Canvas established a new default value of two semitones. It is possible to adjust the pitch bend range in a MIDI channel at performance time by setting MIDI Registered Parameter Number 0's data MSB to the new bender range value. However, existing sequences composed under MSS 2.X are not likely to contain RPN 0 controller values, since the older Roland-derived MIDI standard did not recognize RPN events. It may be desirable to set the MDI_DEFAULT_BENDER_RANGE preference to 12 when porting MSS 2.X applications to the current MSS, if adding RPN controllers to all of the application's MIDI sequences is impractical. Changes to MDI_DEFAULT_BENDER_RANGE take effect during XMIDI driver initialization. This function may not be supported by all Windows midiOut drivers. Environment: DOS/Win32/Win64/MacOS. Units: MIDI semitones (discrete note increments). Default Value: 2.
MDI_SYSEX_BUFFER_SIZE	This preference value determines the size of the largest System Exclusive message which can be transmitted from an XMIDI file or from the AIL_send_sysex_message function. MDI_SYSEX_BUFFER_SIZE should not normally need to be changed by the application. Environment: Win32/Win64/MacOS. Units: Bytes. Default Value: 512.
MDI_DOUBLE_NOTE_OFF	This preference value is present to help you work around a nasty bug in the Sound Blaster 16 General MIDI daughter cards. Occasionally the interface portion of the Sound Blaster 16 can drop General MIDI commands when there is busy MIDI traffic. Most MIDI commands can be dropped without a problem, but if a "Note-Off" is missed, then your MIDI notes can "stick". When you turn this preference on, then MSS will send all Note-Off commands to the MIDI card twice (creating less of a chance that the Note-Off will be missed). This preference will nearly double the MIDI traffic, so use it if you have problems with stuck notes on Sound Blaster 16 daughter cards with very complicated MIDI songs. Environment: DOS/Win32/Win64/MacOS. Units: Boolean (YES / NO). Default Value: NO.
DLS_TIMEBASE	Governs the rate at which the DLS software synthesizer receives periodic timer service from the system. Lower rates may yield slightly better CPU performance in some cases; higher rates yield less "quantization" of MIDI traffic. There is no benefit in setting the DLS_TIMEBASE preference value higher than the MDI_SERVICE_RATE preference value, as MIDI events cannot be interpreted faster than they arrive from the synthesizer driver. This preference value must be altered before calling AIL_DLS_open. Environment: DOS/Win32/Win64/MacOS. Units: Frequency in hertz (interrupts per second). Default Value: 120.
DLS_VOICE_LIMIT	Sets the maximum number of simultaneous DLS synthesizer voices available. The default value of 24 complies with MMA guidelines, and is sufficient for most applications. This preference value must be altered before calling AIL_DLS_open. Environment: DOS/Win32/Win64/MacOS. Units: Number of simultaneous DLS voices permissible. Default Value: 24.
DLS_BANK_SELECT_ALIAS	By default, the XMIDI Patch Bank Select controller (114) is not used as an alias for the General MIDI bank select controllers (0 and 32). The XMIDI Patch Bank Select controller has been de-emphasized by RAD Game Tools as of the MSS 4.0 release, and should not be used for future compositions. Legacy compositions which use XMIDI Patch Bank Select may be made DLS-compatible by setting this preference to YES. If this preference is set to YES, the General MIDI Bank MSB value for a given channel (controller 0) will be set to 0 whenever a Patch Bank Select controller is encountered in that channel. This preference value may be altered on demand at runtime. Environment: DOS/Win32/Win64/MacOS. Units: Boolean (YES / NO). Default Value: NO.
DLS_VOLUME_BOOST	DLS-synthesized instruments contain numerous level scalars and articulators, all of which, when interpreted by the synthesizer, result in a reduction of overall output volume compared to the levels at which the wave data were originally recorded. By default, the synthesizer output level is boosted by 10 dB in the final mixing stage, to help keep DLS-synthesized music from being drowned out by digital sound effects and other sources of sound in an application. This preference value may be altered on demand at runtime. Environment: DOS/Win32/Win64/MacOS. Units: Decibels. Default Value: 10.
DLS_GM_PASSTHROUGH	By default, MIDI data which is not interpreted by the DLS software synthesizer is passed on to the default MIDI hardware synthesizer driver. Setting this preference to NO causes uninterpreted data to be discarded. Many applications which deal with "legacy" sequence data may benefit from setting this preference to NO, to avoid unwanted or inappropriate output from the MIDI hardware synthesizer in response to events in tracks which are not properly configured with bank- and/or patch-change messages. This preference value may be altered on demand at runtime. Environment: DOS/Win32/Win64/MacOS. Units: Boolean (YES / NO). Default Value: YES.
AIL_ENABLE_MMX_SUPPORT	By default, Intel MMX support is enabled to provide a CPU performance increase. Most applications should not need to alter this preference value. This preference value may be altered on demand at runtime. Environment: DOS/Win32/Win64. Units: Boolean (YES / NO). Default Value: YES.
DIG_USE_WAVEOUT	This preference is used under Win32 and Win64 if the AIL_OPEN_DIGITAL_FORCE_PREFERENCE flag is used with AIL_open_digital_driver. It determines whether MSS will use DirectSound or the low-level Windows multimedia extensions (MME). By default, MSS tries to load DirectSound and only falls back to waveOut if DirectSound fails to load or if DirectSound is using emulation mode. This preference allows you to control specifically which technology Miles uses. Environment: Win32/Win64. Units: Boolean ( YES / NO ). Default Value: NO.
DIG_PREFERRED_WO_DEVICE	When the Win32 or Win64 version uses waveOut for output, this preference determines the waveOut device ID it opens. Environment: Win32/Win64. Units: A DWORD device ID. Default Value: WAVE_MAPPER.
DIG_PREFERRED_DS_DEVICE	When the Win32 or Win64 version uses DirectSound for output, this preference determines the LPGUID it passes to DirectSoundCreate. Environment: Win32/Win64. Units: A pointer to a DirectSound device GUID. Default Value: NULL.
DIG_LEVEL_RAMP_SAMPLES	This preference value determines the number of samples in each software-mixing buffer over which sample volume level changes (including 3D attenuation) take effect. Smaller values may exacerbate "zipper noise" under some conditions, while larger values take (slightly) more CPU time. The default value of 128 represents a good performance-versus-quality compromise for most applications. Environment: All software-mixed platforms. Units: An integer number of samples. Default value: 128.
DIG_ENCODE_QUALITY_PERCENT	This preference value provides a quality "hint" to any real-time encoder modules installed. It can range from 0 (lowest quality, least resource usage) to 100 (highest quality, most resource usage). Currently only the DTS encoder in the Sony PS2 version of Miles uses this preference. The default value of 50% represents a good performance-versus-quality compromise for most applications. Environment: The Sony PS2's DTS encoder is currently the only platform that supports this preference. Units: An integer percentage from 0 to 100. Default value: 50.
DIG_OUTPUT_BUFFER_SIZE	This preference value determines how large the output buffers are allocated by AIL_open_digital_driver under Windows in waveOut mode or MacOS. See AIL_open_digital_driver for details. DIG_OUTPUT_BUFFER_SIZE should not normally need to be changed by the application, except in cases where extremely long periods of time can elapse without yielding to other tasks or calling AIL_serve. Environment: Win32/Win64 with waveOut Units: Bytes. Default Value: 49,152 (48K).
AIL_MM_PERIOD	This preference value determines the shortest possible timer period which may be requested with AIL_set_timer_period, AIL_set_timer_frequency, or AIL_set_timer_divisor. AIL_MM_PERIOD should not normally need to be changed by the application, except in cases where background timer services at rates faster than 200 Hz are required. Environment: Win32/Win64 and MacOS. Units: Milliseconds. Default Value: 5 (200 Hz).
AIL_MUTEX_PROTECTION	Under Win32, this preference value determines whether MSS will lock calls from different threads with a system mutex. This is an alternate method to the AIL_LOCK_PROTECTION preference. If you turn on AIL_LOCK_PROTECTION, then you need to turn off AIL_MUTEX_PROTECTION, unless your main thread must continue to execute and you specifically protect against MSS being called re-entrantly. You will probably never need to use this preference. Environment: Win32/Win64/MacOS. Units: Boolean (YES / NO). Default Value: NO.
AIL_LOCK_PROTECTION	Under Win32, this preference value determines whether MSS will lock the foreground thread while executing its callbacks. This is an alternate method to the AIL_MUTEX_PROTECTION preference. If you turn off AIL_MUTEX_PROTECTION, then you need to turn on AIL_LOCK_PROTECTION, unless your main thread must continue to execute and you specifically protect against MSS being called re-entrantly. You will probably never need to use this preference. Environment: Win32/Win64. Units: Boolean (YES / NO). Default Value: NO.
DIG_DS_USE_PRIMARY	This preference determines the whether the MSS mixer should mix into a DirectSound secondary buffer, or whether it should mix directly into the primary sound buffer. The primary sound buffer is the very fastest method, but not all sound cards are compatible with primary buffer use. Using the primary buffer also prevents 3D providers and Smacker from playing their output. Environment: Win32/Win64 only. Units: Boolean ( YES / NO ). Default Value: NO.
DIG_DS_FRAGMENT_SIZE	This preference determines the big each Miles mixer fragment is. On Win32, this preference and DIG_DS_MIX_FRAGMENT_COUNT control how far ahead the MSS mixer will mix when replacing the DirectSound mixer. Decreasing this value may lower latency, but can cause skipping problems on some sound cards. On original Xbox, fragments are only used the audio is compressed with IMA ADCPM, Ogg Vorbis, or MP3 compression, or you are streaming the audio. These fragments are used as the DirectSound looping buffers. By default, there are 32 of these fragments available per HDIGDRIVER, but you can increase this with the DIG_DS_FRAGMENT_CNT preference. Environment: Win32/Win64 and Xbox. Units: Milliseconds. Default Value: 8 on Win32, 12 on Xbox.
DIG_DS_FRAGMENT_CNT	On Win32, this preference determines the maximum buffer fragments that the MSS mixer uses when it replaces the DirectSound mixer. This preference doesn't have any effect on latency - it just controls the maximum value that the DIG_DS_MIX_FRAGMENT_CNT can be set to. On Xbox, this preference controls how many fragment buffers that are allocated to play IMA ADPCM, MP3, Ogg Vorbis, or streaming audio data per HDIGDRIVER. Environment: Win32/Win64 and Xbox. Units: Buffer fragments. Default Value: 96 on Win32, 32 on Xbox.
DIG_DS_MIX_FRAGMENT_CNT	This preference determines the number of buffer fragments that the MSS mixer mixes ahead when it replaces the DirectSound mixer. This preference multiplied by the DIG_DS_FRAGMENT_SIZE determines the current digital latency. You can change this preference at runtime, so if you are getting skipping during a CPU intensive operation, you can bump up this preference, call AIL_serve to fill the digital buffers, run the CPU intensive operation, and then set this preference back to its default. This will eliminate virtually all skipping problems. This value must be less than DIG_DS_FRAGMENT_CNT. Environment: Win32/Win64 only. Units: Buffer fragments. Default Value: 8.
DIG_SM_FRAGMENT_SIZE	This preference determines the big each Miles mixer fragment is. Together with the DIG_SM_MIX_FRAGMENT_COUNT controls how far ahead the MSS mixer will mix when replacing the Sound Manager mixer. Decreasing this value may lower latency, but can cause skipping problems on some sound cards. You should never need to change this preference. Environment: MacOS only. Units: Milliseconds. Default Value: 20.
DIG_SM_FRAGMENT_CNT	This preference determines the maximum buffer fragments that the MSS mixer uses when it replaces the Sound Manager mixer. This preference doesn't have any effect on latency - it just controls the maximum value that the DIG_SM_MIX_FRAGMENT_CNT can be set to. You should never need to change this preference. Environment: MacOS only. Units: Buffer fragments. Default Value: 16.
DIG_SM_MIX_FRAGMENT_CNT	This preference determines the number of buffer fragments that the MSS mixer mixes ahead when it replaces the Sound Manager mixer. This preference multiplied by the DIG_SM_FRAGMENT_SIZE determines the current digital latency. You can change this preference at runtime, so if you are getting skipping during a CPU intensive operation, you can bump up this preference, call AIL_serve to fill the digital buffers, run the CPU intensive operation, and then set this preference back to its default. This will eliminate virtually all skipping problems. This value must be less than DIG_SM_FRAGMENT_CNT. Environment: MacOS only. Units: Buffer fragments. Default Value: 2.
DIG_SERVICE_RATE	Under DOS, when a digital audio driver is loaded, the MSS API arranges to receive background timer interrupt service at a rate governed by the DIG_SERVICE_RATE preference. The timer routine is responsible for polling the driver's low-level buffer status to determine which, if either, of the two half-buffers is ready to be filled with the next block of output audio data. In general, to ensure that MSS has enough time to prepare the next audio data block for the driver, DIG_SERVICE_RATE should be set to a frequency which is substantially faster than the driver's half-buffer playback period. As an example, consider a hardware driver which is configured to play 16-bit audio at 20,000 Hz with a pair of 1,000-byte half-buffers. The driver's data rate is 40,000 bytes per second, implying a half-buffer playback frequency of 40,000 / 1,000, or 40 Hz. (The half-buffer playback frequency is referred to as the driver's DMA latency, and can be controlled by the use of the DIG_LATENCY preference described below.) For reliable performance in this example, DIG_SERVICE_RATE should be set to a value which is greater than 40 by a comfortable margin - at least a factor of two, or 80, would be appropriate here. DIG_SERVICE_RATE must be set prior to calling the AIL_install_DIG_driver_file or AIL_install_DIG_driver_image function. The default DIG_SERVICE_RATE value of 200 Hz has been chosen as a conservative compromise between CPU overhead and audio reliability with most applications. This value should be increased only when extremely low DMA latencies are specified by use of the DIG_LATENCY preference, or if very brief fragments of audio seem to be "repeated" unnaturally. Environment: DOS only. Units: Frequency in hertz (interrupts per second). Default Value: 200.
DIG_HARDWARE_SAMPLE_RATE	Under DOS, this preference governs the actual DMA or simulated-DMA transfer rate used by digital audio drivers. When a driver is loaded by the application, MSS must choose one of three sample rates supported by the driver, and initialize the driver for DMA or simulated-DMA playback at that sample rate. MSS's choice of sample rates is based on the DIG_HARDWARE_SAMPLE_RATE value. The three sample rates permitted by the driver represent the minimum, nominal, and maximum values supported by the hardware device for which the driver was developed. For example, the minimum, nominal, and maximum hardware sample rate values for SBLASTER.DIG are 4000, 11111, and 22222 Hz, respectively; while the values supported by SB16.DIG are 11025, 22050, and 44100 Hz, respectively. Of course, the application may specify any desired sample rate for playback of its audio data; it is MSS's responsibility to resample the application's audio data to conform to the driver's hardware playback rate. (See the description of the AIL_set_sample_playback_rate function for more information about oversampling and undersampling, and their potential effects on audio quality). By default, the nominal sample rate (NOM_VAL) value is selected when initializing each digital audio driver. Prior to driver initialization with the AIL_install_DIG_driver_file or AIL_install_DIG_driver_image function, this preference may be set to the MIN_VAL, NOM_VAL, or MAX_VAL. Alternatively, an explicit sample rate value may be supplied to the AIL_set_preference function for the DIG_HARDWARE_SAMPLE_RATE preference. In this case, MSS will select the closest match from the three sample rate choices offered by the driver. Use of MIN_VAL for this preference is not recommended except in cases where only low-frequency sound effect samples are to be played, or when system performance constraints cause severe problems at higher data rates. Similarly, use of MAX_VAL may impose a significant burden on foreground CPU performance when drivers capable of 44 kHz operation are loaded. A few system-board and video-adapter combinations exhibit impaired DMA performance at higher physical sample rates, especially when monochrome text adapters are installed alongside ISA-based VGA adapters operating in high-resolution modes. Additionally, many sound adapters incorporate low-pass antialiasing filters which adapt themselves to the hardware sample rate. On these adapters, use of higher-than-necessary hardware sample rates will often result in a loss of playback fidelity when MSS must oversample the application's data. In general, best fidelity will be obtained by matching the hardware DMA and source sample data rates as closely as possible. Consequently, it is strongly recommended that the application select an explicit value for the DIG_HARDWARE_SAMPLE_RATE preference which is equal to the playback rate of the majority of the samples to be played, and let MSS's resampling capability handle the others. This preference is only used under DOS. Under other platforms, the values specified in the call to AIL_open_digital_driver govern the final sound output quality. Note that MSS does not permit hardware sample rates to be changed at any time after driver initialization. To establish a different hardware sample rate, it is necessary to shut down and reinitialize the driver. Note also that MSS drivers must be shut down in their opposite order of initialization. Environment: DOS only. Units: MIN_VAL, NOM_VAL, or MAX_VAL; or explicit frequency in hertz (samples per second). Default Value: NOM_VAL.
DIG_USE_STEREO	Under DOS, the DIG_USE_STEREO preference value determines whether or not stereo-capable hardware is actually used in stereo mode. By default, DIG_USE_STEREO is set to the value NO, to keep DMA data rates at a minimum. An application which uses stereo digital audio samples, or which needs to control the stereo panning placement of mono samples, must include an AIL_set_preference(DIG_USE_STEREO,YES) statement before loading its digital audio driver(s). If stereo samples are played on a monaural sound card, or on a stereo sound card with the DIG_USE_STEREO preference set to NO, the right-channel source data will be ignored. As a rule, lower DMA data rates result in improved reliability in marginal situations. In particular, frequent video memory accesses - especially in super-VGA modes with ISA-based video subsystems - may interfere with high-speed DMA traffic, or vice versa. Disk or network traffic can also interfere with high-bandwidth DMA transfers, especially in the presence of virtual DMA hosts. DMA data rates may be kept to a minimum by setting DIG_HARDWARE_SAMPLE_RATE to NOM_VAL, or an explicit value of 22 Khz or less; leaving the DIG_USE_16_BITS preference value set to its default value of NO; and setting DIG_USE_STEREO to YES only in applications which can actually take advantage of stereo panning or stereo sample playback. This should not be taken as a warning to leave MSS's more advanced features unused, but rather as encouragement to keep hardware DMA rates no higher than necessary to meet the application's needs. There is no benefit in playing typical 11-or-22-Khz mono 8-bit samples with DIG_USE_16_BITS set to YES and DIG_HARDWARE_SAMPLE_RATE set to 44100 or MAX_VAL - in fact, sound quality may actually be degraded by the necessary resampling process. This preference is only used under DOS. Under the other Miles platforms, the values specified by in call to AIL_open_digital_driver govern the final sound output quality. Environment: DOS only. Units: Boolean (YES / NO). Default Value: NO.
DIG_USE_16_BITS	Under DOS, the DIG_USE_16_BITS preference value determines whether or not 16-bit capable hardware is actually used in 16-bit mode. By default, DIG_USE_16_BITS is set to the value NO, to keep DMA data rates at a minimum. An application which requires the absolute optimum fidelity available with a given sound card may wish to include an AIL_set_preference(DIG_USE_16_BITS,YES) statement before loading its digital audio driver(s). As a rule, lower DMA data rates result in improved reliability in marginal situations. In particular, frequent video memory accesses - especially in super-VGA modes with ISA-based video subsystems - may interfere with high-speed DMA traffic, or vice versa. Disk or network traffic can also interfere with high-bandwidth DMA transfers, especially in the presence of virtual DMA hosts. DMA data rates may be kept to a minimum by setting DIG_HARDWARE_SAMPLE_RATE to NOM_VAL, or an explicit value of 22 Khz or less; leaving the DIG_USE_16_BITS preference value set to its default value of NO; and setting DIG_USE_STEREO to YES only in applications which can actually take advantage of stereo panning or stereo sample playback. This should not be taken as a warning to leave MSS's more advanced features unused, but rather as encouragement to keep hardware DMA rates no higher than necessary to meet the application's needs. There is no benefit in playing typical 11-or-22-Khz mono 8-bit samples with DIG_USE_16_BITS set to YES and DIG_HARDWARE_SAMPLE_RATE set to 44100 or MAX_VAL - in fact, sound quality may actually be degraded by the necessary resampling process. See the DIG_ALLOW_16_BIT_DMA preference for more information about 16-bit DMA-based audio configuration. This preference is only used under DOS. Under the other Miles platforms, the values specified by in call to AIL_open_digital_driver govern the final sound output quality. Environment: DOS only. Units: Boolean (YES / NO). Default Value: NO.
DIG_DMA_RESERVE	Under DOS, this preference determines the amount of physical (lower-1MB) memory set aside for DMA buffer construction at driver initialization time. It does not normally need to be changed unless memory in the lower 1MB of address space is at a premium. This value will never need to exceed 32,768 bytes. Space which is not used for the DMA half-buffer pair is reserved for internal use. Any changes made to this preference value must be made prior to digital driver installation. Environment: DOS only. Units: Bytes. Default Value: 32,768.
DIG_ALLOW_16_BIT_DMA	Under DOS, the DIG_ALLOW_16_BIT_DMA preference value determines whether or not 16-bit DMA channels may be used for 16-bit DMA transfers. Many 16-bit PC sound cards can be configured to use one or more 16-bit DMA channels (5,6, and 7) to help ease the DMA bandwidth problems associated with 16-bit audio playback. By default, MSS allows these channels to be used if the driver supports them. However, certain PC clones do not implement 16-bit DMA properly. Use of 16-bit DMA channels on these systems may cause lockups, noise, or other symptoms of audio system failure. If 16-bit digital audio is enabled by setting the DIG_USE_16_BITS preference to YES, end-users should be offered an opportunity to override the DIG_ALLOW_16_BIT_DMA preference via an installation option or command-line switch. Any changes made to the DIG_ALLOW_16_BIT_DMA preference value must be made prior to installing the digital driver in question. Environment: DOS only. Units: Boolean (YES / NO). Default Value: YES.
AIL_SCAN_FOR_HARDWARE	Under DOS, if this preference value is set to NO, the MSS driver installation functions will not attempt to "auto-detect" sound hardware by using the list of common I/O configurations which is present in most MSS-compatible drivers. Environment variable-based detection will still be performed, as will any detection attempt based on an explicit IO_PARMS structure passed to the driver initialization function. This preference may be useful to well-behaved application installation programs which ask permission from the user before attempting to verify the presence of a given sound card. RAD Game Tools recommends this practice in all cases. Environment: DOS only. Units: Boolean (YES / NO). Default Value: YES.
AIL_ALLOW_VDM_EXECUTION	Under DOS, MSS is unique among 32-bit PC sound systems in that its architecture permits it to be compatible with Microsoft Windows virtual DOS machines, or "DOS boxes." When AIL_ALLOW_VDM_EXECUTION is set to YES prior to loading any digital audio drivers, MSS will abide by certain rules involving DMA configuration for compatibility with Windows and other virtual-DMA hosts. AIL_ALLOW_VDM_EXECUTION will not prevent dialog boxes with messages such as "The Sound Blaster is in use by another application" from appearing upon application startup. This message can often be avoided by waiting for a short period of time after the last sound is played by the Windows Multimedia Extensions before launching the MSS application's DOS session. The error which causes the dialog box to appear stems from design inadequacies in the Microsoft multimedia system, and is not a symptom of a problem with MSS (or any other DOS-based PC sound system). Environment: DOS only. Units: Boolean (YES / NO). Default Value: YES.
DIG_LATENCY	Under DOS, this preference governs the "lag time" between the execution of an MSS function call which affects digital audio playback, and the actual execution of the requested command. It determines the DMA half-buffer size to be configured when digital drivers are installed, as expressed in terms of the half-buffer playback time in milliseconds based on the DMA data rate in use. The Miles Sound System digital audio mixer operates on the application's audio data in small chunks, called blocks. Part of the system's responsibility is to poll the hardware buffers in the background to determine when the next block of audio data from the application should be processed and copied into an empty DMA half-buffer. As an example, consider a hardware driver which is configured to play 16-bit audio at 20,000 Hz with a pair of 1,000-byte half-buffers. The driver's data rate is 40,000 bytes per second, implying a half-buffer playback rate of 40,000 / 1,000, or 40 buffer transitions per second. At a rate of 40 times per second, then, a sample block equivalent to one half-buffer's worth of data is fetched from the application's sample data buffer at the current playback position. The samples are resampled if necessary to conform to the driver's hardware rate, converted between 8-bit and 16-bit formats where appropriate, mathematically scaled for volume and panpot control, algebraically added to data from other active samples, clipped, and copied into the driver's empty half-buffer to be played as soon as the other half-buffer finishes playing. Consequently, any change made to a sample's playback characteristics - be it a change in volume, panpot value, pitch, start/stop status, or playback position - must wait until the next DMA half-buffer transition occurs before it can take effect. The DMA latency setting represents a compromise between the ability of the system to maintain consistent sound quality in the presence of heavy interrupt loads associated with disk access and other sources, and its ability to respond quickly to requests from the application to start, stop, or otherwise affect the playback of digital audio samples. If too high a latency time is requested, annoying delays may occur between the time a sample is started and the time the user actually hears the sound. High DMA latency times are particularly undesirable when using "virtual wave synthesis" to trigger digital drum or instrument sounds with XMIDI sequence events. Conversely, too low a DMA latency setting may cause brief dropouts and "skips" during digital audio playback which takes place while disk, CD, or network access is occurring. This symptom may become quite pronounced on slower systems. MSS's default DMA latency setting is 100 milliseconds, which is the longest recommended DMA latency period. (If the AIL_ALLOW_VDM_EXECUTION preference is set to its default value of YES, the DMA half-buffer size is limited to 2KB rather than 16KB. With higher sample rates, especially in combination with an 8-bit mono hardware channel, the actual DMA latency time will be much less than 100 milliseconds). The minimum acceptable DMA latency figure will generally be in the range of 15-25 milliseconds. If extremely small DMA latency values are used, it may be necessary to increase the value of the DIG_SERVICE_RATE preference to give the system enough time to respond to the driver's DMA half-buffer transitions. It is important to note that the DIG_LATENCY preference value is used during driver installation as a guideline only. Under the MSS architecture, DMA half-buffer sizes must be chosen from among the set of binary powers between 16 and 16,384 bytes. The DIG_LATENCY value, in conjunction with the DIG_HARDWARE_SAMPLE_RATE, DIG_USE_STEREO, and DIG_USE_16_BITS values, determines which of the possible buffer sizes is used. In most cases, the chosen buffer size will be only an approximation to the size which corresponds to the requested half-buffer playback time. If a change to DIG_LATENCY seems to have no effect as compared to the previous value, try making a slightly larger change in the same direction until the desired result is achieved. Environment: DOS only. Units: Milliseconds. Default Value: 100.

Group: Preferences
Related Sections: Callbacks under Xbox 360, Miles DTS Provider for the Sony PS2, Sharing the CPU under Xbox 360, XMIDI For Loop Controller (116), XMIDI Sequence Branch (109)
Related Functions: AIL_DLS_open, AIL_MIDI_to_XMI, AIL_allocate_sample_handle, AIL_allocate_sequence_handle, AIL_branch_index, AIL_create_wave_synthesizer, AIL_get_preference, AIL_get_timer_highest_delay, AIL_init_sequence, AIL_install_DIG_driver_file, AIL_install_DIG_driver_image, AIL_open_digital_driver, AIL_register_timer, AIL_sample_output_levels, AIL_send_sysex_message, AIL_sequence_position, AIL_serve, AIL_set_preference, AIL_set_sample_playback_rate, AIL_set_sequence_volume, AIL_set_timer_divisor, AIL_set_timer_frequency, AIL_set_timer_period, AIL_startup
Related Basic Types: MILES_OPEN_DIGITAL_FLAGS
Related Structures: IO_PARMS
Related FAQs: How much latency does Miles have?, I'm setting a preference and it isn't having any effect - what's going on?, My sound is skipping on Windows or MacOS X - what can I do?, What's the best way to port my older Miles application to MSS 7?