-- Allegro 4.4.2 - Sound init routines
package Allegro.Sound is
-- for passing to install_sound()
DIGI_AUTODETECT : constant := -1;
DIGI_NONE : constant := 0;
MIDI_AUTODETECT : constant := -1;
MIDI_NONE : constant := 0;
-- Detects whether the specified digital sound device is available. This
-- function must be called _before_ install_sound().
-- Returns the maximum number of voices that the driver can provide, or zero
-- if the hardware is not present.
function Detect_Digi_Driver( driver_id : Integer ) return Integer;
-- Detects whether the specified MIDI sound device is available. This
-- function must be called _before_ install_sound().
-- Returns the maximum number of voices that the driver can provide, or zero
-- if the hardware is not present.
--
-- There are two special-case return values that you should watch out for:
-- if this function returns -1 it is a note-stealing driver (eg. DIGMID)
-- that shares voices with the current digital sound driver, and if it
-- returns 0xFFFF it is an external device like an MPU-401 where there is no
-- way to determine how many voices are available.
function Detect_MIDI_Driver( driver_id : Integer ) return Integer;
-- Retrieves the hardware sound output volume, both for digital samples and
-- MIDI playback, as integers from 0 to 255, or -1 if the information is not
-- available. Parameters digi_volume and midi_volume must be valid pointers
-- to int, or NULL if not interested in specific value.
procedure Get_Hardware_Volume( digi_volume, midi_volume : access Integer );
-- Retrieves the global sound output volume, both for digital samples and
-- MIDI playback, as integers from 0 to 255. Parameters digi_volume and
-- midi_volume must be valid pointers to int, or NULL if not interested in
-- specific value.
procedure Get_Volume( digi_volume, midi_volume : access Integer );
-- Initialises the sound module. You should normally pass DIGI_AUTODETECT
-- and MIDI_AUTODETECT as the driver parameters to this function, in which
-- case Allegro will read hardware settings from the current configuration
-- file. This allows the user to select different values with the setup
-- utility: see the config section for details. Alternatively, see the
-- platform specific documentation for a list of the available drivers. The
-- cfg_path parameter is only present for compatibility with previous
-- versions of Allegro, and has no effect on anything.
-- Returns zero if the sound is successfully installed, and -1 on failure.
-- If it fails it will store a description of the problem in allegro_error.
function Install_Sound( digi, midi : Integer; cfg_path : String ) return Boolean;
-- Cleans up after you are finished with the sound routines. You don't
-- normally need to call this, because allegro_exit() will do it for you.
procedure Remove_Sound;
-- Call this function to specify the number of voices that are to be used by
-- the digital and MIDI sound drivers respectively. This must be done
-- _before_ calling install_sound(). If you reserve too many voices,
-- subsequent calls to install_sound() will fail. How many voices are
-- available depends on the driver, and in some cases you will actually get
-- more than you reserve (eg. the FM synth drivers will always provide 9
-- voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round
-- the number of voices up to the nearest power of two). Pass negative
-- values to restore the default settings. You should be aware that the
-- sound quality is usually inversely related to how many voices you use, so
-- don't reserve any more than you really need.
procedure Reserve_Voices( digi_voices, midi_voices : Natural );
-- Alters the hardware sound output volume. Specify volumes for both digital
-- samples and MIDI playback, as integers from 0 to 255, or pass a negative
-- value to leave one of the settings unchanged. Values bigger than 255 will
-- be reduced to 255. This routine will use the hardware mixer to control
-- the volume if it exists (i.e. the volume of all the applications on your
-- machine will be affected), otherwise do nothing.
procedure Set_Hardware_Volume( digi_volume, midi_volume : Natural );
-- Alters the global sound output volume. Specify volumes for both digital
-- samples and MIDI playback, as integers from 0 to 255, or pass a negative
-- value to leave one of the settings unchanged. Values bigger than 255 will
-- be reduced to 255. This routine will not alter the volume of the hardware
-- mixer if it exists (i.e. only your application will be affected).
procedure Set_Volume( digi_volume, midi_volume : Natural );
-- By default, Allegro will play a centered sample at half volume on both
-- the left and right channel. A sample panned to the far right or left will
-- be played at maximum volume on that channel only. This is done so you can
-- play a single panned sample without distortion. If you play multiple
-- samples at full volume, the mixing process can result in clipping, a
-- noticeable form of distortion. The more samples, the more likely clipping
-- is to occur, and the more clipping, the worse the output will sound.
--
-- If clipping is a problem - or if the output is too quiet - this function
-- can be used to adjust the volume of each voice. You should first check
-- that your speakers are at a reasonable volume, Allegro's global volume is
-- at maximum (see set_volume() below), and any other mixers such as the
-- Windows Volume Control are set reasonably. Once you are sure that
-- Allegro's output level is unsuitable for your application, use this
-- function to adjust it.
--
-- Each time you increase the parameter by one, the volume of each voice
-- will halve. For example, if you pass 4, you can play up to 16 centred
-- samples at maximum volume without distortion.
--
-- If you pass 0 to this function, each centred sample will play at the
-- maximum volume possible without distortion, as will all samples played
-- through a mono driver. Samples at the extreme left and right will distort
-- if played at full volume. If you wish to play panned samples at full
-- volume without distortion, you should pass 1 to this function. Note: this
-- is different from the function's behaviour in WIPs 3.9.34, 3.9.35 and
-- 3.9.36. If you used this function under one of these WIPs, you will have
-- to increase your parameter by one to get the same volume.
--
-- Note: The default behaviour has changed as of Allegro 4.1.15. If you
-- would like the behaviour of earlier versions of Allegro, pass -1 to this
-- function. Allegro will choose a value dependent on the number of voices,
-- so that if you reserve n voices, you can play up to n/2 normalised
-- samples with centre panning without risking distortion. The exception is
-- when you have fewer than 8 voices, where the volume remains the same as
-- for 8 voices. Here are the values, dependent on the number of voices:
--
-- 1-8 voices - set_volume_per_voice(2)
-- 16 voices - set_volume_per_voice(3)
-- 32 voices - set_volume_per_voice(4)
-- 64 voices - set_volume_per_voice(5)
--
-- Of course this function does not override the volume you specify with
-- play_sample() or voice_set_volume(). It simply alters the overall output
-- of the program. If you play samples at lower volumes, or if they are not
-- normalised, then you can play more of them without distortion.
--
-- It is recommended that you hard-code the parameter into your program,
-- rather than offering it to the user. The user can alter the volume with
-- the configuration file instead, or you can provide for this with
-- set_volume().
--
-- To restore volume per voice to its default behaviour, pass 1.
procedure Set_Volume_Per_Voice( scale : Integer );
private
pragma Import( C, Detect_Digi_Driver, "detect_digi_driver" );
pragma Import( C, Detect_MIDI_Driver, "detect_midi_driver" );
pragma Import( C, Get_Hardware_Volume, "get_hardware_volume" );
pragma Import( C, Get_Volume, "get_volume" );
pragma Import( C, Remove_Sound, "remove_sound" );
pragma Import( C, Reserve_Voices, "reserve_voices" );
pragma Import( C, Set_Hardware_Volume, "set_hardware_volume" );
pragma Import( C, Set_Volume, "set_volume" );
pragma Import( C, Set_Volume_Per_Voice, "set_volume_per_voice" );
end Allegro.Sound;