1. -- Allegro 4.4.2 - Sound init routines 
  2. package Allegro.Sound is 
  3.  
  4.     -- for passing to install_sound() 
  5.     DIGI_AUTODETECT : constant := -1; 
  6.     DIGI_NONE       : constant := 0; 
  7.  
  8.     MIDI_AUTODETECT : constant := -1; 
  9.     MIDI_NONE       : constant := 0; 
  10.  
  11.     -- Detects whether the specified digital sound device is available. This 
  12.     -- function must be called _before_ install_sound(). 
  13.     -- Returns the maximum number of voices that the driver can provide, or zero 
  14.     -- if the hardware is not present. 
  15.     function Detect_Digi_Driver( driver_id : Integer ) return Integer; 
  16.  
  17.     -- Detects whether the specified MIDI sound device is available. This 
  18.     -- function must be called _before_ install_sound(). 
  19.     -- Returns the maximum number of voices that the driver can provide, or zero 
  20.     -- if the hardware is not present. 
  21.     -- 
  22.     -- There are two special-case return values that you should watch out for: 
  23.     -- if this function returns -1 it is a note-stealing driver (eg. DIGMID) 
  24.     -- that shares voices with the current digital sound driver, and if it 
  25.     -- returns 0xFFFF it is an external device like an MPU-401 where there is no 
  26.     -- way to determine how many voices are available. 
  27.     function Detect_MIDI_Driver( driver_id : Integer ) return Integer; 
  28.  
  29.     -- Retrieves the hardware sound output volume, both for digital samples and 
  30.     -- MIDI playback, as integers from 0 to 255, or -1 if the information is not 
  31.     -- available. Parameters digi_volume and midi_volume must be valid pointers 
  32.     -- to int, or NULL if not interested in specific value. 
  33.     procedure Get_Hardware_Volume( digi_volume, midi_volume : access Integer ); 
  34.  
  35.     -- Retrieves the global sound output volume, both for digital samples and 
  36.     -- MIDI playback, as integers from 0 to 255. Parameters digi_volume and 
  37.     -- midi_volume must be valid pointers to int, or NULL if not interested in 
  38.     -- specific value. 
  39.     procedure Get_Volume( digi_volume, midi_volume : access Integer ); 
  40.  
  41.     -- Initialises the sound module. You should normally pass DIGI_AUTODETECT 
  42.     -- and MIDI_AUTODETECT as the driver parameters to this function, in which 
  43.     -- case Allegro will read hardware settings from the current configuration 
  44.     -- file. This allows the user to select different values with the setup 
  45.     -- utility: see the config section for details. Alternatively, see the 
  46.     -- platform specific documentation for a list of the available drivers. The 
  47.     -- cfg_path parameter is only present for compatibility with previous 
  48.     -- versions of Allegro, and has no effect on anything. 
  49.     -- Returns zero if the sound is successfully installed, and -1 on failure. 
  50.     -- If it fails it will store a description of the problem in allegro_error. 
  51.     function Install_Sound( digi, midi : Integer; cfg_path : String ) return Boolean; 
  52.  
  53.     -- Cleans up after you are finished with the sound routines. You don't 
  54.     -- normally need to call this, because allegro_exit() will do it for you. 
  55.     procedure Remove_Sound; 
  56.  
  57.     -- Call this function to specify the number of voices that are to be used by 
  58.     -- the digital and MIDI sound drivers respectively. This must be done 
  59.     -- _before_ calling install_sound(). If you reserve too many voices, 
  60.     -- subsequent calls to install_sound() will fail. How many voices are 
  61.     -- available depends on the driver, and in some cases you will actually get 
  62.     -- more than you reserve (eg. the FM synth drivers will always provide 9 
  63.     -- voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round 
  64.     -- the number of voices up to the nearest power of two). Pass negative 
  65.     -- values to restore the default settings. You should be aware that the 
  66.     -- sound quality is usually inversely related to how many voices you use, so 
  67.     -- don't reserve any more than you really need. 
  68.     procedure Reserve_Voices( digi_voices, midi_voices : Natural ); 
  69.  
  70.     -- Alters the hardware sound output volume. Specify volumes for both digital 
  71.     -- samples and MIDI playback, as integers from 0 to 255, or pass a negative 
  72.     -- value to leave one of the settings unchanged. Values bigger than 255 will 
  73.     -- be reduced to 255. This routine will use the hardware mixer to control 
  74.     -- the volume if it exists (i.e. the volume of all the applications on your 
  75.     -- machine will be affected), otherwise do nothing. 
  76.     procedure Set_Hardware_Volume( digi_volume, midi_volume : Natural ); 
  77.  
  78.     -- Alters the global sound output volume. Specify volumes for both digital 
  79.     -- samples and MIDI playback, as integers from 0 to 255, or pass a negative 
  80.     -- value to leave one of the settings unchanged. Values bigger than 255 will 
  81.     -- be reduced to 255. This routine will not alter the volume of the hardware 
  82.     -- mixer if it exists (i.e. only your application will be affected). 
  83.     procedure Set_Volume( digi_volume, midi_volume : Natural ); 
  84.  
  85.     -- By default, Allegro will play a centered sample at half volume on both 
  86.     -- the left and right channel. A sample panned to the far right or left will 
  87.     -- be played at maximum volume on that channel only. This is done so you can 
  88.     -- play a single panned sample without distortion. If you play multiple 
  89.     -- samples at full volume, the mixing process can result in clipping, a 
  90.     -- noticeable form of distortion. The more samples, the more likely clipping 
  91.     -- is to occur, and the more clipping, the worse the output will sound. 
  92.     -- 
  93.     -- If clipping is a problem - or if the output is too quiet - this function 
  94.     -- can be used to adjust the volume of each voice. You should first check 
  95.     -- that your speakers are at a reasonable volume, Allegro's global volume is 
  96.     -- at maximum (see set_volume() below), and any other mixers such as the 
  97.     -- Windows Volume Control are set reasonably. Once you are sure that 
  98.     -- Allegro's output level is unsuitable for your application, use this 
  99.     -- function to adjust it. 
  100.     -- 
  101.     -- Each time you increase the parameter by one, the volume of each voice 
  102.     -- will halve. For example, if you pass 4, you can play up to 16 centred 
  103.     -- samples at maximum volume without distortion. 
  104.     -- 
  105.     -- If you pass 0 to this function, each centred sample will play at the 
  106.     -- maximum volume possible without distortion, as will all samples played 
  107.     -- through a mono driver. Samples at the extreme left and right will distort 
  108.     -- if played at full volume. If you wish to play panned samples at full 
  109.     -- volume without distortion, you should pass 1 to this function. Note: this 
  110.     -- is different from the function's behaviour in WIPs 3.9.34, 3.9.35 and 
  111.     -- 3.9.36. If you used this function under one of these WIPs, you will have 
  112.     -- to increase your parameter by one to get the same volume. 
  113.     -- 
  114.     -- Note: The default behaviour has changed as of Allegro 4.1.15. If you 
  115.     -- would like the behaviour of earlier versions of Allegro, pass -1 to this 
  116.     -- function. Allegro will choose a value dependent on the number of voices, 
  117.     -- so that if you reserve n voices, you can play up to n/2 normalised 
  118.     -- samples with centre panning without risking distortion. The exception is 
  119.     -- when you have fewer than 8 voices, where the volume remains the same as 
  120.     -- for 8 voices. Here are the values, dependent on the number of voices: 
  121.     -- 
  122.     --     1-8 voices - set_volume_per_voice(2) 
  123.     --      16 voices - set_volume_per_voice(3) 
  124.     --      32 voices - set_volume_per_voice(4) 
  125.     --      64 voices - set_volume_per_voice(5) 
  126.     -- 
  127.     -- Of course this function does not override the volume you specify with 
  128.     -- play_sample() or voice_set_volume(). It simply alters the overall output 
  129.     -- of the program. If you play samples at lower volumes, or if they are not 
  130.     -- normalised, then you can play more of them without distortion. 
  131.     -- 
  132.     -- It is recommended that you hard-code the parameter into your program, 
  133.     -- rather than offering it to the user. The user can alter the volume with 
  134.     -- the configuration file instead, or you can provide for this with 
  135.     -- set_volume(). 
  136.     -- 
  137.     -- To restore volume per voice to its default behaviour, pass 1. 
  138.     procedure Set_Volume_Per_Voice( scale : Integer ); 
  139.  
  140. private 
  141.  
  142.     pragma Import( C, Detect_Digi_Driver,   "detect_digi_driver" ); 
  143.     pragma Import( C, Detect_MIDI_Driver,   "detect_midi_driver" ); 
  144.     pragma Import( C, Get_Hardware_Volume,  "get_hardware_volume" ); 
  145.     pragma Import( C, Get_Volume,           "get_volume" ); 
  146.     pragma Import( C, Remove_Sound,         "remove_sound" ); 
  147.     pragma Import( C, Reserve_Voices,       "reserve_voices" ); 
  148.     pragma Import( C, Set_Hardware_Volume,  "set_hardware_volume" ); 
  149.     pragma Import( C, Set_Volume,           "set_volume" ); 
  150.     pragma Import( C, Set_Volume_Per_Voice, "set_volume_per_voice" ); 
  151.  
  152. end Allegro.Sound;