   This file was generated by Ocamldoc using the Texinfo generator.

OCamlSDL 0.7.2
**************

Documentation for OCamlSDL 0.7.2

Indices :

1 Module `Sdl'
**************

1.1 Description
===============

This module contains functions for initializing/quitting the library

1.2 Interface
=============

 - exception SDL_init_exception of string

   Exception for reporting errors during initialization

1.2.1 Main functions
--------------------

 - type subsystem = [ `AUDIO | `CDROM | `JOYSTICK | `TIMER | `VIDEO ]

   Initialization flag type

 - val init :
     ?auto_clean:bool ->
       [< `AUDIO
        | `CDROM
        | `EVENTTHREAD
        | `EVERYTHING
        | `JOYSTICK
        | `NOPARACHUTE
        | `TIMER
        | `VIDEO ]
       list -> unit

   Initialize the SDL library. This should be called before all other
SDL functions.  The flags parameter specifies what part(s) of SDL to
initialize.
   * `NOPARACHUTE : Don't catch fatal signals

   * `EVENTTHREAD : Automatically pump events in a separate threads

   * `EVERYTHING  : initialize all subsystems

 - val init_subsystem :
     subsystem list -> unit

 - val was_init :
     unit -> subsystem list

 - val quit :
     unit -> unit

   `quit' shuts down all SDL subsystems and frees the resources
allocated to them. This should always be called before you exit.

 - val quit_subsystem :
     subsystem list -> unit

1.2.2 Versioning information
----------------------------

 - type version = {
  major : int ;
  minor : int ;
  patch : int ;
 }

 - val version :
     unit -> version

   version of the SDL library

 - val string_of_version :
     version -> string

1.2.3 Environment variables
---------------------------

 - val getenv :
     string -> string

 - val putenv :
     string -> string -> unit

2 Module `Sdlcdrom'
*******************

2.1 Description
===============

This module provides CD-ROM handling

2.2 Interface
=============

 - exception SDLcdrom_exception of string

   Exception used to report errors

 - exception Trayempty

   Exception to report that thre's no cd in the drive

2.2.1 Types
-----------

 - type cdrom_drive

   abstract type for handling cdrom

 - type cdrom_drive_status =
  | CD_TRAYEMPTY
     (* cdrom drive is empty *)
  | CD_STOPPED
     (* cdrom drive is stopped *)
  | CD_PLAYING
     (* cdrom drive is playing *)
  | CD_PAUSED
     (* cdrom drive is paused *)

   enumeration of different status cdrom drive

 - type track_type =
  | TRACK_AUDIO
     (* audio track type *)
  | TRACK_DATA
     (* data track type *)

   the types of CD-ROM track possible

 - type track = {
  id : int ;
  kind : Sdlcdrom.track_type ;
  length : int ;
  offset : int ;
 }

 - type cdrom_info = {
  num_tracks : int ;
  curr_track : int ;
  curr_frame : int ;
  tracks : Sdlcdrom.track array ;
 }

2.2.2 General API
-----------------

An SDLcdrom_exception is raised on errors

 - val get_num_drives :
     unit -> int

   `get_num_drives' returns the number of CD-ROM drives on the system

 - val drive_name :
     int -> string

   `drive_name drive' returns a human-readable, system-dependent
identifier for the CD-ROM.  `drive' is the index of the drive. Drive
indices start to 0 and end at `get_num_drives()-1'.

2.2.3 CD-ROM drive handling
---------------------------

 - val cd_open :
     int -> cdrom_drive

   `cd_open drive' open a CD-ROM drive for access

 - val cd_close :
     cdrom_drive -> unit

   Closes the handle for the cdrom_drive

 - val cd_status :
     cdrom_drive -> cdrom_drive_status

*Returns* the current status of the given drive.

 - val cd_info :
     cdrom_drive -> cdrom_info

*Raises* `Trayempty' if there's no cd in the drive
*Returns* the table of contents of the CD and current play position

2.2.4 Playing audio tracks
--------------------------

 - val msf_of_frames :
     int -> int * int * int

 - val frames_of_msf :
     int * int * int -> int

 - val cd_play_tracks :
     cdrom_drive ->
       start_track:int ->
       start_frame:int -> num_tracks:int -> num_frames:int -> unit

   `cd_play_tracks cdrom_drive start_track start_frame num_tracks
num_frames' play the given CD with these parameters
*Parameters* start_track: the starting track
*Parameters* start_frame: the starting frame
*Parameters* num_tracks: the number of tracks to play
*Parameters* num_frames: the number of frames to play
*Raises* `Trayempty' if there's no cd in the drive

 - val cd_play_track :
     cdrom_drive -> track -> unit

   Play the track n on the given cdrom_drive

 - val cd_pause :
     cdrom_drive -> unit

   Pause play

 - val cd_resume :
     cdrom_drive -> unit

   Resume play

 - val cd_stop :
     cdrom_drive -> unit

   Stop play

 - val cd_eject :
     cdrom_drive -> unit

   Eject CD-ROM

3 Module `Sdltimer'
*******************

3.1 Description
===============

Time-related functions

3.2 Interface
=============

 - val delay :
     int -> unit

   Wait a specified number of milliseconds before returning

 - val get_ticks :
     unit -> int

   Get the number of milliseconds since the SDL library initialization.

4 Module `Sdljoystick'
**********************

4.1 Description
===============

Module for SDL joystick event handling

4.2 Interface
=============

In order to use these functions, Sdl.init must have been called    with
the `JOYSTICK flag.  This causes SDL to scan the system    for
joysticks, and load appropriate drivers.

 - exception SDLjoystick_exception of string

   exception for error reporting

 - type t

   The joystick abstract type used to identify an SDL joystick

 - val num_joysticks :
     unit -> int

   Count the number of joysticks attached to the system

 - val name :
     int -> string

   Get the implementation dependent name of a joystick.  This can be
called before any joysticks are opened.

 - val open_joystick :
     int -> t

   Open a joystick for use - the index passed as an argument refers to
the N'th joystick on the system.  This index is the value which will
identify this joystick in future joystick events.
*Raises* `SDLjoystick_exception' if an error occurred

 - val opened :
     int -> bool

*Returns* `true' if joystick has been opened

 - val index :
     t -> int

   Get the device index of an opened joystick

 - val num_axes :
     t -> int

   Get the number of general axis controls on a joystick

 - val num_balls :
     t -> int

   Get the number of trackballs on a joystick Joystick trackballs have
only relative motion events associated with them and their state cannot
be polled.

 - val num_hats :
     t -> int

   Get the number of POV hats on a joystick

 - val num_buttons :
     t -> int

   Get the number of buttons on a joystick

4.2.1 Joystick state
--------------------

 - val update :
     t -> unit

   Update the current state of the open joysticks.  This is called
automatically by the event loop if any joystick events are enabled.

   Enable/disable joystick event polling.     If joystick events are
disabled, you must call Sdljoystick.update    yourself and check the
state of the joystick when you want joystick    information.

 - val set_event_state :
     bool -> unit

 - val get_event_state :
     unit -> bool

 - type hat_value = int

 - val hat_centered :
     hat_value

 - val hat_up :
     hat_value

 - val hat_right :
     hat_value

 - val hat_down :
     hat_value

 - val hat_left :
     hat_value

 - val hat_rightup :
     hat_value

 - val hat_rightdown :
     hat_value

 - val hat_leftup :
     hat_value

 - val hat_leftdown :
     hat_value

 - val get_axis :
     t -> int -> int

 - val get_hat :
     t -> int -> hat_value

 - val get_ball :
     t -> int -> int * int

 - val get_button :
     t -> int -> bool

 - val close :
     t -> unit

   Close a joystick previously opened with Sdljoystick.open_joystick

5 Module `Sdlkey'
*****************

5.1 Description
===============

Keyboard handling and key symbols

5.2 Interface
=============

5.2.1 Keysyms
-------------

 - type t =
  | KEY_UNKNOWN
  | KEY_BACKSPACE
  | KEY_TAB
  | KEY_CLEAR
  | KEY_RETURN
  | KEY_PAUSE
  | KEY_ESCAPE
  | KEY_SPACE
  | KEY_EXCLAIM
  | KEY_QUOTEDBL
  | KEY_HASH
  | KEY_DOLLAR
  | KEY_AMPERSAND
  | KEY_QUOTE
  | KEY_LEFTPAREN
  | KEY_RIGHTPAREN
  | KEY_ASTERISK
  | KEY_PLUS
  | KEY_COMMA
  | KEY_MINUS
  | KEY_PERIOD
  | KEY_SLASH
  | KEY_0
  | KEY_1
  | KEY_2
  | KEY_3
  | KEY_4
  | KEY_5
  | KEY_6
  | KEY_7
  | KEY_8
  | KEY_9
  | KEY_COLON
  | KEY_SEMICOLON
  | KEY_LESS
  | KEY_EQUALS
  | KEY_GREATER
  | KEY_QUESTION
  | KEY_AT
     (* Skip uppercase letters *)
  | KEY_LEFTBRACKET
  | KEY_BACKSLASH
  | KEY_RIGHTBRACKET
  | KEY_CARET
  | KEY_UNDERSCORE
  | KEY_BACKQUOTE
  | KEY_a
  | KEY_b
  | KEY_c
  | KEY_d
  | KEY_e
  | KEY_f
  | KEY_g
  | KEY_h
  | KEY_i
  | KEY_j
  | KEY_k
  | KEY_l
  | KEY_m
  | KEY_n
  | KEY_o
  | KEY_p
  | KEY_q
  | KEY_r
  | KEY_s
  | KEY_t
  | KEY_u
  | KEY_v
  | KEY_w
  | KEY_x
  | KEY_y
  | KEY_z
  | KEY_DELETE
     (* End of ASCII mapped keysyms *)
  | KEY_WORLD_0
     (* International keyboard syms *)
  | KEY_WORLD_1
  | KEY_WORLD_2
  | KEY_WORLD_3
  | KEY_WORLD_4
  | KEY_WORLD_5
  | KEY_WORLD_6
  | KEY_WORLD_7
  | KEY_WORLD_8
  | KEY_WORLD_9
  | KEY_WORLD_10
  | KEY_WORLD_11
  | KEY_WORLD_12
  | KEY_WORLD_13
  | KEY_WORLD_14
  | KEY_WORLD_15
  | KEY_WORLD_16
  | KEY_WORLD_17
  | KEY_WORLD_18
  | KEY_WORLD_19
  | KEY_WORLD_20
  | KEY_WORLD_21
  | KEY_WORLD_22
  | KEY_WORLD_23
  | KEY_WORLD_24
  | KEY_WORLD_25
  | KEY_WORLD_26
  | KEY_WORLD_27
  | KEY_WORLD_28
  | KEY_WORLD_29
  | KEY_WORLD_30
  | KEY_WORLD_31
  | KEY_WORLD_32
  | KEY_WORLD_33
  | KEY_WORLD_34
  | KEY_WORLD_35
  | KEY_WORLD_36
  | KEY_WORLD_37
  | KEY_WORLD_38
  | KEY_WORLD_39
  | KEY_WORLD_40
  | KEY_WORLD_41
  | KEY_WORLD_42
  | KEY_WORLD_43
  | KEY_WORLD_44
  | KEY_WORLD_45
  | KEY_WORLD_46
  | KEY_WORLD_47
  | KEY_WORLD_48
  | KEY_WORLD_49
  | KEY_WORLD_50
  | KEY_WORLD_51
  | KEY_WORLD_52
  | KEY_WORLD_53
  | KEY_WORLD_54
  | KEY_WORLD_55
  | KEY_WORLD_56
  | KEY_WORLD_57
  | KEY_WORLD_58
  | KEY_WORLD_59
  | KEY_WORLD_60
  | KEY_WORLD_61
  | KEY_WORLD_62
  | KEY_WORLD_63
  | KEY_WORLD_64
  | KEY_WORLD_65
  | KEY_WORLD_66
  | KEY_WORLD_67
  | KEY_WORLD_68
  | KEY_WORLD_69
  | KEY_WORLD_70
  | KEY_WORLD_71
  | KEY_WORLD_72
  | KEY_WORLD_73
  | KEY_WORLD_74
  | KEY_WORLD_75
  | KEY_WORLD_76
  | KEY_WORLD_77
  | KEY_WORLD_78
  | KEY_WORLD_79
  | KEY_WORLD_80
  | KEY_WORLD_81
  | KEY_WORLD_82
  | KEY_WORLD_83
  | KEY_WORLD_84
  | KEY_WORLD_85
  | KEY_WORLD_86
  | KEY_WORLD_87
  | KEY_WORLD_88
  | KEY_WORLD_89
  | KEY_WORLD_90
  | KEY_WORLD_91
  | KEY_WORLD_92
  | KEY_WORLD_93
  | KEY_WORLD_94
  | KEY_WORLD_95
  | KEY_KP0
     (* Numeric keypad *)
  | KEY_KP1
  | KEY_KP2
  | KEY_KP3
  | KEY_KP4
  | KEY_KP5
  | KEY_KP6
  | KEY_KP7
  | KEY_KP8
  | KEY_KP9
  | KEY_KP_PERIOD
  | KEY_KP_DIVIDE
  | KEY_KP_MULTIPLY
  | KEY_KP_MINUS
  | KEY_KP_PLUS
  | KEY_KP_ENTER
  | KEY_KP_EQUALS
  | KEY_UP
     (* Arrows + Home/End pad *)
  | KEY_DOWN
  | KEY_RIGHT
  | KEY_LEFT
  | KEY_INSERT
  | KEY_HOME
  | KEY_END
  | KEY_PAGEUP
  | KEY_PAGEDOWN
  | KEY_F1
     (* Function keys *)
  | KEY_F2
  | KEY_F3
  | KEY_F4
  | KEY_F5
  | KEY_F6
  | KEY_F7
  | KEY_F8
  | KEY_F9
  | KEY_F10
  | KEY_F11
  | KEY_F12
  | KEY_F13
  | KEY_F14
  | KEY_F15
  | KEY_NUMLOCK
     (* Key state modifier keys *)
  | KEY_CAPSLOCK
  | KEY_SCROLLOCK
  | KEY_RSHIFT
  | KEY_LSHIFT
  | KEY_RCTRL
  | KEY_LCTRL
  | KEY_RALT
  | KEY_LALT
  | KEY_RMETA
  | KEY_LMETA
  | KEY_LSUPER
     (* Left "Windows" key *)
  | KEY_RSUPER
     (* Right "Windows" key *)
  | KEY_MODE
     (* "Alt Gr" key *)
  | KEY_COMPOSE
     (* Multi-key compose key *)
  | KEY_HELP
     (* Miscellaneous function keys *)
  | KEY_PRINT
  | KEY_SYSREQ
  | KEY_BREAK
  | KEY_MENU
  | KEY_POWER
     (* Power Macintosh power key *)
  | KEY_EURO
     (* Some european keyboards *)
  | KEY_UNDO
     (* Atari keyboard has Undo *)

   Concrete type describing keyboard keys ("keysym")

 - val int_of_key :
     t -> int

   get the SDL keysym of the key

 - val key_of_int :
     int -> t

   get the key corresponding to a SDL keysym
*Raises* `Invalid_arg' if not a valid SDL keysym

 - val char_of_key :
     t -> char

   Returns a (iso-8859-1) character corresponding to a key
*Raises* `Invalid_arg' if corresponding SDL keysym is > 255

 - val num_keys :
     int

   number of keys in the Sdlkey.t variant type : should be `232'

 - val max_code :
     int

   highest SDL keysym : should be `322'

 - val name :
     t -> string

*Returns* a short string describing the key

5.2.2 Keyboard handling
-----------------------

 - val enable_unicode :
     bool -> unit

   Enable unicode translation of keysyms for keyboard events

 - val query_unicode :
     unit -> bool

 - val disable_key_repeat :
     unit -> unit

   Disable keyboard repeat

 - val enable_key_repeat :
     ?delay:int -> ?interval:int -> unit -> unit

   Enable keyboard repeat
*Parameters* delay: initial delay in ms between the time when a key is
 pressed, and keyboard repeat begins
*Parameters* interval: the time in ms between keyboard repeat events

 - val get_key_state :
     unit ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

   Get a snapshot of the current state of the keyboard.
*Returns* an array of keystates, indexed by the SDL keysyms    (cf
Sdlkey.int_of_key)

 - val is_key_pressed :
     t -> bool

   Checks wether a key is currently pressed on the keyboard.

5.2.3 Key modifiers
-------------------

 - type mod_state = int

   The following values are flags. Use with `land', `lor', etc.

 - val kmod_none :
     mod_state

 - val kmod_lshift :
     mod_state

 - val kmod_rshift :
     mod_state

 - val kmod_lctrl :
     mod_state

 - val kmod_rctrl :
     mod_state

 - val kmod_lalt :
     mod_state

 - val kmod_ralt :
     mod_state

 - val kmod_lmeta :
     mod_state

 - val kmod_rmeta :
     mod_state

 - val kmod_num :
     mod_state

 - val kmod_caps :
     mod_state

 - val kmod_mode :
     mod_state

 - val kmod_ctrl :
     mod_state

 - val kmod_shift :
     mod_state

 - val kmod_alt :
     mod_state

 - val kmod_meta :
     mod_state

 - val get_mod_state :
     unit -> mod_state

   Get the current key modifier state

 - val set_mod_state :
     mod_state -> unit

   Set the current key modifier state This does not change the keyboard
state, only the key modifier flags.

6 Module `Sdlmouse'
*******************

6.1 Description
===============

Mouse event handling and cursors

6.2 Interface
=============

6.2.1 Mouse state
-----------------

 - type button =
  | BUTTON_LEFT
  | BUTTON_MIDDLE
  | BUTTON_RIGHT
  | BUTTON_WHEELUP
  | BUTTON_WHEELDOWN

 - val get_state :
     ?relative:bool -> unit -> int * int * button list

   Retrieve the current state of the mouse : current mouse position and
list of pressed buttons
*Parameters* relative: if true returns mouse delta instead of position

 - val warp :
     int -> int -> unit

   Set the position of the mouse cursor (generates a mouse motion event)

6.2.2 Cursors
-------------

 - type cursor

   abstract type for cursors

 - type cursor_data = {
  data : (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array2.t ;
     (* B/W cursor data *)
  mask : (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array2.t ;
     (* B/W cursor mask *)
  w : int ;
     (* width in pixels *)
  h : int ;
     (* height in pixels *)
  hot_x : int ;
     (* the "tip" of the cursor *)
  hot_y : int ;
     (* the "tip" of the cursor *)
 }

 - val make_cursor :
     data:(int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array2.t ->
       mask:(int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array2.t ->
       hot_x:int -> hot_y:int -> cursor

   Create a cursor using the specified data and mask (in MSB format).

   The cursor is created in black and white according to the following:
data  mask     resulting pixel on screen     0     1       White     1
  1       Black     0     0       Transparent     1     0
Inverted color if possible, black if not.

   Cursors created with this function must be freed with
Sdlmouse.free_cursor.

 - val free_cursor :
     cursor -> unit

   Deallocates a cursor.

 - val set_cursor :
     cursor -> unit

   Set the currently active cursor to the specified one.  If the cursor
is currently visible, the change will be immediately represented on the
display.

 - val get_cursor :
     unit -> cursor

   Returns the currently active cursor.

 - val cursor_visible :
     unit -> bool

   Tests if cursor is shown on screen

 - val show_cursor :
     bool -> unit

   Toggle cursor display

 - val cursor_data :
     cursor -> cursor_data

   converts an abstract cursor value to concrete cursor data

 - val pprint_cursor :
     cursor -> unit

   for debugging : prints on stdout

 - val convert_to_cursor :
     data:int array ->
       mask:int array -> w:int -> h:int -> hot_x:int -> hot_y:int -> cursor

7 Module `Sdlevent'
*******************

7.1 Description
===============

SDL event handling

Subparts
========

7.2 Interface
=============

 - exception Event_exn of string

   The exception used for reporting events-related errors.

7.2.1 Application focus
-----------------------

 - type active_state =
  | MOUSEFOCUS
     (* The app has mouse coverage *)
  | INPUTFOCUS
     (* The app has input focus *)
  | APPACTIVE
     (* The application is active *)

   The available application states

 - val get_app_state :
     unit -> active_state list

   This function returns the current state of the application. If
ACTIVE is set, then the user is able to see your application, otherwise
it has been iconified or disabled.

7.2.2 Events datatypes
----------------------

 - type active_event = {
  gain : bool ;
     (* Whether given states were gained or lost *)
  ae_state : Sdlevent.active_state list ;
     (* A list of the focus states *)
 }

   Application visibility event record

 - type switch_state =
  | RELEASED
  | PRESSED

 - type keyboard_event = {
  ke_which : int ;
     (* The keyboard device index *)
  ke_state : Sdlevent.switch_state ;
     (* PRESSED or RELEASED *)
  keysym : Sdlkey.t ;
     (* SDL virtual keysym *)
  keymod : Sdlkey.mod_state ;
     (* current key modifiers *)
  keycode : char ;
     (* translated character *)
 }

   Keyboard event record

 - type mousemotion_event = {
  mme_which : int ;
     (* The mouse device index *)
  mme_state : Sdlmouse.button list ;
     (* The current button state *)
  mme_x : int ;
     (* The X/Y coordinates of the mouse *)
  mme_y : int ;
  mme_xrel : int ;
     (* The relative motion in the X direction *)
  mme_yrel : int ;
     (* The relative motion in the Y direction *)
 }

   Mouse motion event record

 - type mousebutton_event = {
  mbe_which : int ;
     (* The mouse device index *)
  mbe_button : Sdlmouse.button ;
     (* The mouse button index *)
  mbe_state : Sdlevent.switch_state ;
     (* PRESSED or RELEASED *)
  mbe_x : int ;
     (* The X/Y coordinates of the mouse at press time *)
  mbe_y : int ;
 }

   Mouse button event record

 - type joyaxis_event = {
  jae_which : int ;
     (* The joystick device index *)
  jae_axis : int ;
     (* The joystick axis index *)
  jae_value : int ;
     (* The axis value (range: -32768 to 32767) *)
 }

   Joystick axis motion event record

 - type joyball_event = {
  jle_which : int ;
     (* The joystick device index *)
  jle_ball : int ;
     (* The joystick trackball index *)
  jle_xrel : int ;
     (* The relative motion in the X direction *)
  jle_yrel : int ;
     (* The relative motion in the Y direction *)
 }

   Joystick axis motion event record

 - type joyhat_event = {
  jhe_which : int ;
     (* The joystick device index *)
  jhe_hat : int ;
     (* The joystick hat index *)
  jhe_value : int ;
     (* The hat position value:                           8   1   2
                          7   0   3
                          6   5   4
        Note that zero means the POV is centered. *)
 }

   Joystick hat position change event record

 - type joybutton_event = {
  jbe_which : int ;
     (* The joystick device index *)
  jbe_button : int ;
     (* The joystick button index *)
  jbe_state : Sdlevent.switch_state ;
     (* PRESSED or RELEASED *)
 }

   Joystick button event record

 - type event =
  | ACTIVE of Sdlevent.active_event
     (* Application loses/gains visibility *)
  | KEYDOWN of Sdlevent.keyboard_event
     (* Keys pressed *)
  | KEYUP of Sdlevent.keyboard_event
     (* Keys released *)
  | MOUSEMOTION of Sdlevent.mousemotion_event
     (* Mouse moved *)
  | MOUSEBUTTONDOWN of Sdlevent.mousebutton_event
     (* Mouse button pressed *)
  | MOUSEBUTTONUP of Sdlevent.mousebutton_event
     (* Mouse button released *)
  | JOYAXISMOTION of Sdlevent.joyaxis_event
     (* Joystick axis motion *)
  | JOYBALLMOTION of Sdlevent.joyball_event
     (* Joystick trackball motion *)
  | JOYHATMOTION of Sdlevent.joyhat_event
     (* Joystick hat position change *)
  | JOYBUTTONDOWN of Sdlevent.joybutton_event
     (* Joystick button pressed *)
  | JOYBUTTONUP of Sdlevent.joybutton_event
     (* Joystick button released *)
  | QUIT
     (* User-requested quit *)
  | SYSWM
     (* System specific event *)
  | VIDEORESIZE of (int * int)
     (* User resized video mode *)
  | VIDEOEXPOSE
     (* Screen needs to be redrawn *)
  | USER of int
     (* for your use ! *)

   The main event type

 - val string_of_event :
     event -> string

   Returns a short string descriptive of the event type, for debugging

7.2.3 Event masks
-----------------

 - type event_mask = int

   Event masks values are ints and should be manipulated with `lor',
`land', etc.

 - val active_mask :
     event_mask

 - val keydown_mask :
     event_mask

 - val keyup_mask :
     event_mask

 - val mousemotion_mask :
     event_mask

 - val mousebuttondown_mask :
     event_mask

 - val mousebuttonup_mask :
     event_mask

 - val joyaxismotion_mask :
     event_mask

 - val joyballmotion_mask :
     event_mask

 - val joyhatmotion_mask :
     event_mask

 - val joybuttondown_mask :
     event_mask

 - val joybuttonup_mask :
     event_mask

 - val quit_mask :
     event_mask

 - val syswmevent_mask :
     event_mask

 - val videoresize_mask :
     event_mask

 - val videoexpose_mask :
     event_mask

 - val userevent_mask :
     event_mask

 - val keyboard_event_mask :
     event_mask

 - val mouse_event_mask :
     event_mask

 - val joystick_event_mask :
     event_mask

 - val all_events_mask :
     event_mask

 - type event_kind =
  | ACTIVE_EVENT
  | KEYDOWN_EVENT
  | KEYUP_EVENT
  | MOUSEMOTION_EVENT
  | MOUSEBUTTONDOWN_EVENT
  | MOUSEBUTTONUP_EVENT
  | JOYAXISMOTION_EVENT
  | JOYBALL_EVENT
  | JOYHAT_EVENT
  | JOYBUTTONDOWN_EVENT
  | JOYBUTTONUP_EVENT
  | QUIT_EVENT
  | SYSWM_EVENT
  | RESIZE_EVENT
  | EXPOSE_EVENT
  | USER_EVENT

 - val make_mask :
     event_kind list -> event_mask

 - val of_mask :
     event_mask -> event_kind list

7.2.4 Enabling/Disabling event collecting
-----------------------------------------

 - val enable_events :
     event_mask -> unit

   Specified events are collected and added to the event queue (when
`pump' is called).

 - val disable_events :
     event_mask -> unit

   Specified events are not collected and won't appear in the event
queue.

 - val get_enabled_events :
     unit -> event_mask

   The mask of currently reported events.

 - val get_state :
     event_kind -> bool

   Query the reporting state of an event type.

 - val set_state :
     bool -> event_kind -> unit

   Set the reporting state of one individual event type.

7.2.5 Handling events
---------------------

 - val pump :
     unit -> unit

   Pumps the event loop, gathering events from the input devices.  This
function updates the event queue and internal input device state.  This
should only be run in the thread that sets the video mode.

 - val wait_event :
     unit -> event

   Wait indefinitely for the next available event and return it.

 - val wait :
     unit -> unit

   Wait indefinitely for the next available event but leave it in the
queue.

 - val poll :
     unit -> event option

   Poll for currently pending events and return one if available.

 - val has_event :
     unit -> bool

   Poll for currently pending events and return `false' if the queue is
empty.

 - val peek :
     ?mask:event_mask -> int -> event list

   Checks the event queue for messages : up to 'numevents' events at
the front of the event queue, matching 'mask', will be returned and
will not be removed from the queue.

 - val get :
     ?mask:event_mask -> int -> event list

   Checks the event queue for messages : up to 'numevents' events at
the front of the event queue, matching 'mask', will be returned and
will be removed from the queue.

 - val add :
     event list -> unit

   Add events to the back of the event queue.

7.2.6 Old event-handling interface
----------------------------------

 - module Old
Module Old.

   Deprecated. this interface was used in version of ocamlsdl < 0.6

   Callback-based event handling.

7.3 Module `Sdlevent.Old'
=========================

7.3.1 Description
-----------------

Deprecated. this interface was used in version of ocamlsdl < 0.6

   Callback-based event handling.

7.3.2 Interface
---------------

7.3.2.1 Definition of the event callbacks
.........................................

 - type keyboard_event_func = Sdlkey.t -> Sdlevent.switch_state -> int -> int -> unit

   Keyboard event called with the activated key, its state and the
coordinates of the mouse pointer

 - type mouse_event_func = Sdlmouse.button -> Sdlevent.switch_state -> int -> int -> unit

   Mouse button event called with the activated button, its state and
the coordinates of the mouse pointer

 - type mousemotion_event_func = int -> int -> unit

   Mouse motion event called with the coordinates of the mouse pointer

 - type idle_event_func = unit -> unit

 - type resize_event_func = int -> int -> unit

7.3.2.2 Functions for setting the current event callbacks
.........................................................

 - val set_keyboard_event_func :
     keyboard_event_func -> unit

 - val set_mouse_event_func :
     mouse_event_func -> unit

 - val set_mousemotion_event_func :
     mousemotion_event_func -> unit

 - val set_idle_event_func :
     idle_event_func -> unit

 - val set_resize_event_func :
     resize_event_func -> unit

7.3.2.3 Event loop
..................

 - val start_event_loop :
     unit -> unit

 - val exit_event_loop :
     unit -> unit

8 Module `Sdlvideo'
*******************

8.1 Description
===============

Module for video manipulations

8.2 Interface
=============

 - exception Video_exn of string

8.2.1 Rectangles
----------------

 - type rect = {
  r_x : int ;
  r_y : int ;
  r_w : int ;
  r_h : int ;
 }

   rectangular area (x, y, w, h)

 - val rect :
     x:int -> y:int -> w:int -> h:int -> rect

 - val copy_rect :
     rect -> rect

*Returns* a copy of the rectangle

8.2.2 Video mode informations
-----------------------------

 - type pixel_format_info = {
  palette : bool ;
  bits_pp : int ;
     (* bits per pixel *)
  bytes_pp : int ;
     (* bytes per pixel *)
  rmask : int32 ;
     (* red mask value *)
  gmask : int32 ;
     (* green mask value *)
  bmask : int32 ;
     (* blue mask value *)
  amask : int32 ;
     (* alpha mask value *)
  rshift : int ;
  gshift : int ;
  bshift : int ;
  ashift : int ;
  rloss : int ;
  gloss : int ;
  bloss : int ;
  aloss : int ;
  colorkey : int32 ;
     (* RGB color key information *)
  alpha : int ;
     (* Alpha value information (per-surface alpha) *)
 }

   Structure describing how color are encoded as pixels

 - type video_info = {
  hw_available : bool ;
     (* Hardware surfaces? *)
  wm_available : bool ;
     (* Window manager present? *)
  blit_hw : bool ;
     (* Accelerated blits HW -> HW *)
  blit_hw_color_key : bool ;
     (* Accelerated blits with color key *)
  blit_hw_alpha : bool ;
     (* Accelerated blits with alpha *)
  blit_sw : bool ;
     (* Accelerated blits SW -> HW *)
  blit_sw_color_key : bool ;
     (* Accelerated blits with color key *)
  blit_sw_alpha : bool ;
     (* Accelerated blits with alpha *)
  blit_fill : bool ;
     (* Accelerated color fill *)
  video_mem : int ;
     (* Total amount of video memory (Ko) *)
 }

   Information on either the 'best' available mode (if called before
`set_video_mode') or the current video mode.

 - val get_video_info :
     unit -> video_info

*Returns* information about the video hardware

 - val get_video_info_format :
     unit -> pixel_format_info

*Returns* information about the pixel format

 - val driver_name :
     unit -> string

*Returns* the name of the video driver

 - type video_flag = [ `ANYFORMAT
  | `ASYNCBLIT
  | `DOUBLEBUF
  | `FULLSCREEN
  | `HWPALETTE
  | `HWSURFACE
  | `NOFRAME
  | `OPENGL
  | `OPENGLBLIT
  | `RESIZABLE
  | `SWSURFACE ]

 - type modes =
  | NOMODE
     (* no dimensions available for the requested format *)
  | ANY
     (* any dimension okay *)
  | DIM of (int * int) list

 - val list_modes :
     ?bpp:int -> video_flag list -> modes

*Returns* a list of available screen dimensions for the given format
and video flags, sorted largest to smallest or NOMODE or ANY

 - val video_mode_ok :
     w:int -> h:int -> bpp:int -> video_flag list -> int

   Check to see if a particular video mode is supported.
*Returns* 0 if the requested mode is not supported or returns the
bits-per-pixel of the closest available mode with the given width
and height.  If this bits-per-pixel is different from the one used
when setting the video mode, set_video_mode will succeed, but will
emulate the requested bits-per-pixel with a shadow surface.

8.2.3 Surfaces
--------------

 - type surface

   Graphical surface datatype

 - type surface_flags = [ `ANYFORMAT
  | `ASYNCBLIT
  | `DOUBLEBUF
  | `FULLSCREEN
  | `HWACCEL
  | `HWPALETTE
  | `HWSURFACE
  | `NOFRAME
  | `OPENGL
  | `OPENGLBLIT
  | `PREALLOC
  | `RESIZABLE
  | `RLEACCEL
  | `SRCALPHA
  | `SRCCOLORKEY
  | `SWSURFACE ]

 - type surface_info = {
  flags : Sdlvideo.surface_flags list ;
  w : int ;
     (* width *)
  h : int ;
     (* height *)
  pitch : int ;
     (* pitch *)
  clip_rect : Sdlvideo.rect ;
     (* clipping information *)
  refcount : int ;
     (* reference count *)
 }

 - val surface_info :
     surface -> surface_info

*Returns* information for the given `surface'

 - val surface_format :
     surface -> pixel_format_info

*Returns* pixel format information for the given `surface'

 - val surface_dims :
     surface -> int * int * int

*Returns* width, height and pitch of the given `surface'

 - val surface_flags :
     surface -> surface_flags list

*Returns* flag list for the given `surface'

 - val surface_bpp :
     surface -> int

*Returns* bits-per-pixel for the given `surface'

8.2.4 Video modes-related functions
-----------------------------------

 - val get_video_surface :
     unit -> surface

*Returns* the current display `surface'

 - val set_video_mode :
     w:int -> h:int -> ?bpp:int -> video_flag list -> surface

   Set up a video mode with the specified `width', `height' and
`bits-per-pixel'.
*Parameters* bpp: if omited, it is treated as the current display bits
per    pixel
*Returns* the current display `surface'

 - val update_rect :
     ?rect:rect -> surface -> unit

*Parameters* rect: makes sure the given area is updated on the given
screen. The rectangle must be confined within the screen boundaries
(no clipping is done). Updates the entire screen if omitted

 - val update_rects :
     rect list -> surface -> unit

   Makes sure the given list of rectangles is updated on the given
screen. The rectangles must all be confined within the screen
boundaries (no clipping is done).  This function should not be called
while screen is locked.

 - val flip :
     surface -> unit

   Swaps screen buffers.

   On hardware that supports double-buffering (``DOUBLEBUF'), this
function sets up a flip and returns. The hardware will wait for
vertical retrace, and then swap video buffers before the next video
surface blit or lock will return.

   On hardware that doesn't support double-buffering, this is
equivalent to calling `update_rect'

8.2.5 Color manipulation
------------------------

 - val set_gamma :
     r:float -> g:float -> b:float -> unit

   Set the gamma correction for each of the color channels.  The gamma
values range (approximately) between 0.1 and 10.0 If this function
isn't supported directly by the hardware, it will be emulated using
gamma ramps, if available.

 - type color = int * int * int

   Format independent color description `(r,g,b)' are 8 bits unsigned
integers

 - val black :
     color

 - val white :
     color

 - val red :
     color

 - val green :
     color

 - val blue :
     color

 - val yellow :
     color

 - val cyan :
     color

 - val magenta :
     color

8.2.5.1 Palettes
................

 - val use_palette :
     surface -> bool

*Returns* `true' if surface use indexed colors

 - val palette_ncolors :
     surface -> int

   Number of colors in the surface's palette

 - val get_palette_color :
     surface -> int -> color

   Retrieve a color by its index in a surface's palette

 - type palette_flag =
  | LOGPAL
     (* set logical palette, which controls how blits are mapped
        to/from the surface *)
  | PHYSPAL
     (* set physical palette, which controls how pixels
        look on the screen *)
  | LOGPHYSPAL

 - val set_palette :
     surface ->
       ?flag:palette_flag ->
       ?firstcolor:int -> color array -> unit

   Sets a portion of the palette for a given 8-bit `surface'.
*Parameters* flag: defaults to LOGPHYSPAL
*Parameters* firstcolor: where to blit the color array given as argument
  (defaults to 0)

8.2.5.2 Conversions
...................

 - val map_RGB :
     surface -> ?alpha:int -> color -> int32

   Maps an RGB triple or an RGBA quadruple to a pixel value for a given
pixel format

 - val get_RGB :
     surface -> int32 -> color

   Maps a pixel value into the RGB components for a given pixel format
*Returns* RGB color

 - val get_RGBA :
     surface -> int32 -> color * int

   Maps a pixel value into the RGBA components for a given pixel format
*
*Returns* RGB color and alpha value

8.2.6 Creating RGB surface
--------------------------

 - val create_RGB_surface :
     [ `ASYNCBLIT | `HWSURFACE | `SRCALPHA | `SRCCOLORKEY | `SWSURFACE ] list ->
       w:int ->
       h:int ->
       bpp:int ->
       rmask:int32 -> gmask:int32 -> bmask:int32 -> amask:int32 -> surface

   Creates a RGB surface.  If the depth is 4 or 8 bits, an empty
palette is allocated for the surface. If the depth is greater than 8
bits, the pixel format is set using the given masks.
*Returns* the new surface

 - val create_RGB_surface_format :
     surface ->
       [ `ASYNCBLIT | `HWSURFACE | `SRCALPHA | `SRCCOLORKEY | `SWSURFACE ] list ->
       w:int -> h:int -> surface

   Creates a RGB surface with the same pixel format as the first
parameter.

 - val create_RGB_surface_from_32 :
     (int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array1.t ->
       w:int ->
       h:int ->
       pitch:int ->
       rmask:int32 -> gmask:int32 -> bmask:int32 -> amask:int32 -> surface

 - val create_RGB_surface_from_24 :
     (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t ->
       w:int ->
       h:int ->
       pitch:int ->
       rmask:int -> gmask:int -> bmask:int -> amask:int -> surface

 - val create_RGB_surface_from_16 :
     (int, Bigarray.int16_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t ->
       w:int ->
       h:int ->
       pitch:int ->
       rmask:int -> gmask:int -> bmask:int -> amask:int -> surface

 - val create_RGB_surface_from_8 :
     (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t ->
       w:int ->
       h:int ->
       pitch:int ->
       rmask:int -> gmask:int -> bmask:int -> amask:int -> surface

8.2.7 Locking/Unlocking surface
-------------------------------

 - val must_lock :
     surface -> bool

*Returns* `true' if the surface should be locked before accessing
its pixels

 - val lock :
     surface -> unit

   Sets up a surface for directly accessing the pixels.

 - val unlock :
     surface -> unit

   Releases the lock on the given `surface'

8.2.8 Accessing surface pixels
------------------------------

 - val pixel_data :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

 - val pixel_data_8 :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

 - val pixel_data_16 :
     surface ->
       (int, Bigarray.int16_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

 - val pixel_data_24 :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t

 - val pixel_data_32 :
     surface ->
       (int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array1.t

 - val get_pixel :
     surface -> x:int -> y:int -> int32

 - val get_pixel_color :
     surface -> x:int -> y:int -> color

   Access an individual pixel on a surface and returns is as a `color'.
The surface may have to be locked before access.

 - val put_pixel :
     surface -> x:int -> y:int -> int32 -> unit

 - val put_pixel_color :
     surface -> x:int -> y:int -> color -> unit

   Sets an individual pixel on a surface.  The surface may have to be
locked before access.

8.2.9 Reading/writing in BMP files
----------------------------------

 - val load_BMP :
     string -> surface

   Loads a surface from a named Windows BMP file.

 - val load_BMP_from_mem :
     string -> surface

   Loads a BMP image from a memory buffer.

 - val save_BMP :
     surface -> string -> unit

   Saves the `surface' as a Windows BMP file named file.

8.2.10 Colorkey and alpha stuff
-------------------------------

 - val unset_color_key :
     surface -> unit

 - val set_color_key :
     surface -> ?rle:bool -> int32 -> unit

   Sets the color key (transparent pixel) in a blittable `surface'.

 - val get_color_key :
     surface -> int32

*Returns* the color key of the given `surface'

 - val unset_alpha :
     surface -> unit

 - val set_alpha :
     surface -> ?rle:bool -> int -> unit

   sets the alpha value for the entire `surface', as opposed to using
the alpha component of each pixel.

 - val get_alpha :
     surface -> int

*Returns* the alpha value of the given `surface'

8.2.11 Clipping
---------------

 - val unset_clip_rect :
     surface -> unit

   disable clipping for the given `surface'

 - val set_clip_rect :
     surface -> rect -> unit

   Sets the clipping rectangle for the destination `surface' in a blit.

 - val get_clip_rect :
     surface -> rect

*Returns* the clipping rectangle for the destination `surface' in a
blit.

8.2.12 Blitting
---------------

 - val blit_surface :
     src:surface ->
       ?src_rect:rect ->
       dst:surface -> ?dst_rect:rect -> unit -> unit

   Performs a fast blit from the source `surface' to the destination
`surface'.
*Parameters* src_rect: the width and height determine the size of the
copied rectangle. If omitted, the entire surface is copied.
*Parameters* dst_rect: only the position is used (the width and height
are    ignored). If omitted, the detination position (upper left corner)
  is (0, 0).

   The final blit rectangles are saved in `src_rect' and `dst_rect'
after all clipping is performed.

   The blit function should not be called on a locked surface.

 - val fill_rect :
     ?rect:rect -> surface -> int32 -> unit

   performs a fast fill of the given rectangle with 'color'

 - val display_format :
     ?alpha:bool -> surface -> surface

   This function takes a surface and copies it to a new surface of the
pixel format and colors of the video framebuffer, suitable for fast
blitting onto the display surface.
*Parameters* alpha: if `true', include an alpha channel in the new
surface

9 Module `Sdlwm'
****************

9.1 Description
===============

Window Manager interaction

9.2 Interface
=============

 - val set_caption :
     title:string -> icon:string -> unit

   Sets the title and icon text of the display window

 - val get_caption :
     unit -> string * string

   Gets the title and icon text of the display window

 - val set_icon :
     Sdlvideo.surface -> unit

   Sets the icon for the display window.  This function must be called
before the first call to Sdlvideo.set_video_mode.

 - val iconify :
     unit -> bool

   This function iconifies the window, and returns `true' if it
succeeded.  If the function succeeds, it generates an
Sdlevent.active_event loss event.  This function is a noop and returns
`false' in non-windowed environments.

 - val toggle_fullscreen :
     unit -> bool

   Toggle fullscreen mode without changing the contents of the screen.
If this function was able to toggle fullscreen mode (change from
running in a window to fullscreen, or vice-versa), it will return
`true'.  If it is not implemented, or fails, it returns `false'.

 - val grab_input :
     bool -> unit

   Set the input grab state of the application.  Grabbing means that
the mouse is confined to the application window, and nearly all
keyboard input is passed directly to the application, and not
interpreted by a window manager, if any.

 - val query_grab :
     unit -> bool

10 Module `Sdlgl'
*****************

10.1 Description
================

LablGL interaction

10.2 Interface
==============

 - val swap_buffers :
     unit -> unit

 - type attr =
  | RED_SIZE of int
  | GREEN_SIZE of int
  | BLUE_SIZE of int
  | ALPHA_SIZE of int
  | BUFFER_SIZE of int
  | DOUBLEBUFFER of bool
  | DEPTH_SIZE of int
  | STENCIL_SIZE of int
  | ACCUM_RED_SIZE of int
  | ACCUM_GREEN_SIZE of int
  | ACCUM_BLUE_SIZE of int
  | ACCUM_ALPHA_SIZE of int
  | STEREO of int

 - val set_attr :
     attr list -> unit

 - val get_attr :
     unit -> attr list

 - val to_raw :
     Sdlvideo.surface -> [ `ubyte ] Raw.t

11 Module `Sdlttf'
******************

11.1 Description
================

This module provides TTF (TrueType Font) support

11.2 Interface
==============

 - exception SDLttf_exception of string

   Exception for reporting errors

 - val init :
     unit -> unit

   Initialise SDL_tff and freetype

 - val quit :
     unit -> unit

   Quits the system

11.2.1 General operations on font datatype
------------------------------------------

 - type font

   abstract font datatype

 - val open_font :
     string -> ?index:int -> int -> font

   open a font file and create a font of the specified point size
*Returns* font datatype

   Set and retrieve the font style    This font style is implemented by
modifying the font glyphs, and    doesn't reflect any inherent
properties of the truetype font file.

 - type font_style =
  | NORMAL
  | BOLD
  | ITALIC
  | UNDERLINE

 - val get_font_style :
     font -> font_style list

   Retrieve the font style : either `NORMAL' or a combination of
`BOLD', `ITALIC' and `UNDERLINE'

 - val set_font_style :
     font -> font_style list -> unit

11.2.2 Font information
-----------------------

 - val font_height :
     font -> int

*Returns* the total height(int) of the font (usually equal to point
size)

 - val font_ascent :
     font -> int

*Returns* the offset(int) from the baseline to the top of the font
this is a positive value, relative to the baseline

 - val font_descent :
     font -> int

*Returns* the offset from the baseline to the bottom of the font
this is a negative value, relative to the baseline

 - val font_lineskip :
     font -> int

   Get the recommended spacing between lines of text for this font

 - val font_faces :
     font -> int

   Get the number of faces of the font

   Get some font face attributes, if any

 - val is_fixed_width :
     font -> bool

 - val family_name :
     font -> string

 - val style_name :
     font -> string

11.2.3 Text rendering functions
-------------------------------

 - val size_text :
     font -> string -> int * int

   Get the dimensions of a rendered string of text

 - val glyph_metrics :
     font -> char -> int * int * int * int

*Returns* the metrics (minx,maxx,miny,maxy) of a glyph

 - type render_kind =
  | SOLID of Sdlvideo.color
  | SHADED of (Sdlvideo.color * Sdlvideo.color)
  | BLENDED of Sdlvideo.color

   Variant type for the generic rendering functions

11.2.3.1 Text rendering functions
.................................

 - val render_text_solid :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface

 - val render_text_shaded :
     font ->
       string -> fg:Sdlvideo.color -> bg:Sdlvideo.color -> Sdlvideo.surface

 - val render_text_blended :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface

 - val render_text :
     font -> render_kind -> string -> Sdlvideo.surface

11.2.3.2 Glyph rendering functions
..................................

 - val render_glyph_solid :
     font -> char -> fg:Sdlvideo.color -> Sdlvideo.surface

 - val render_glyph_shaded :
     font ->
       char -> fg:Sdlvideo.color -> bg:Sdlvideo.color -> Sdlvideo.surface

 - val render_glyph_blended :
     font -> char -> fg:Sdlvideo.color -> Sdlvideo.surface

 - val render_glyph :
     font -> render_kind -> char -> Sdlvideo.surface

12 Module `Sdlloader'
*********************

12.1 Description
================

Image loader module

12.2 Interface
==============

 - exception SDLloader_exception of string

   Exception to report errors

 - val load_image :
     string -> Sdlvideo.surface

   load an image as a surface

 - val load_image_from_mem :
     string -> Sdlvideo.surface

 - val read_XPM_from_array :
     string array -> Sdlvideo.surface

   creates a surface from an array of strings (in the source code)

13 Module `Sdlmixer'
********************

13.1 Description
================

Simple multi-channel audio mixer

13.2 Interface
==============

 - exception SDLmixer_exception of string

   Exception used to report errors

13.2.1 General API
------------------

 - val version :
     unit -> Sdl.version

   Get the version of the dynamically linked SDL_mixer library

 - type format =
  | AUDIO_FORMAT_U8
     (* Unsigned 8-bit samples *)
  | AUDIO_FORMAT_S8
     (* Signed 8-bit samples *)
  | AUDIO_FORMAT_U16LSB
     (* Unsigned 16-bit samples *)
  | AUDIO_FORMAT_S16LSB
     (* Signed 16-bit samples *)
  | AUDIO_FORMAT_U16MSB
     (* As above, but big-endian byte order *)
  | AUDIO_FORMAT_S16MSB
     (* As above, but big-endian byte order *)
  | AUDIO_FORMAT_U16SYS
     (* Unsigned, native audio byte ordering *)
  | AUDIO_FORMAT_S16SYS
     (* Signed, native audio byte ordering *)

   Audio format flags

 - type channels =
  | MONO
  | STEREO

 - val open_audio :
     ?freq:int ->
       ?format:format ->
       ?chunksize:int -> ?channels:channels -> unit -> unit

   `open_audio frequency format chunksize channels ()' opens the mixer
with a certain audio format.
   * frequency could be 8000 11025 22050 44100 ; defaults to 22050

   * format defaults to AUDIO_FORMAT_S16SYS

   * chunksize defaults to 4096

   * channels defaults to STEREO

 - val close_audio :
     unit -> unit

   Close the mixer, halting all playing audio

 - type specs = {
  frequency : int ;
  format : Sdlmixer.format ;
  channels : Sdlmixer.channels ;
 }

 - val query_specs :
     unit -> specs

   Find out what the actual audio device parameters are.
*Raises* `SDLmixer_exception' if the audio has not been opened

13.2.2 Samples
--------------

 - type chunk

 - val loadWAV :
     string -> chunk

   Load a wave file

 - val loadWAV_from_mem :
     string -> chunk

 - val load_string :
     string -> chunk

   Load a wave file of the mixer format from a memory buffer

 - val volume_chunk :
     chunk -> float

 - val setvolume_chunk :
     chunk -> float -> unit

 - val free_chunk :
     chunk -> unit

   Free an audio chunk previously loaded

13.2.3 Channels
---------------

 - type channel = int

 - val all_channels :
     channel

   A special value for representing all channels (-1 actually).

 - val num_channels :
     unit -> int

*Returns* the number of channels currently allocated

 - val allocate_channels :
     int -> int

   Dynamically change the number of channels managed by the mixer.  If
decreasing the number of channels, the upper channels are stopped.
*Returns* the new number of allocated channels

 - val play_channel :
     ?channel:channel ->
       ?loops:int -> ?ticks:float -> chunk -> unit

   `play_channel channel loops ticks chunk ' Play an audio chunk.
*Parameters* channel: channel to play on. If not specified, play on the
 first free channel.
*Parameters* loops: number of times to play the chunk. If `-1', loop
infinitely (~65000 times).
*Parameters* ticks: if specified, play for at most 'ticks' seconds.

 - val play_sound :
     chunk -> unit

   Play an audio chunk. Same as above, without the optional parameters

 - val fadein_channel :
     ?channel:channel ->
       ?loops:int -> ?ticks:float -> chunk -> float -> unit

   `fadein_channel channel loops ticks chunck ms' : same as
`play_channel' but fades in a over `ms' seconds.

 - val volume_channel :
     channel -> float

   Returns the original volume of a specific channel, chunk or music
*Returns* float between 0 and 1.

 - val setvolume_channel :
     channel -> float -> unit

   Sets the volume for specified channel or chunk.  Volume is a float
between 0 and 1.  If lower than 0, nothing is done.  If greater than 1,
volume is set to 1

 - val pause_channel :
     channel -> unit

 - val resume_channel :
     channel -> unit

 - val halt_channel :
     channel -> unit

 - val expire_channel :
     channel -> float option -> unit

   `expire_channel channel ticks' Change the expiration delay for a
particular channel.  The sample will stop playing after the 'ticks'
seconds have elapsed, or remove the expiration if 'ticks' is `None'

 - val fadeout_channel :
     channel -> float -> unit

   `fadeout_channel channel ticks' Halt a channel, fading it out
progressively till it's silent The ms parameter indicates the number of
seconds the fading will take.

 - val playing_channel :
     channel -> bool

 - val num_playing_channel :
     unit -> int

 - val paused_channel :
     channel -> bool

 - val num_paused_channel :
     unit -> int

 - type fade_status =
  | NO_FADING
  | FADING_OUT
  | FADING_IN

   The different fading types supported

 - val fading_channel :
     channel -> fade_status

   Query the fading status of a channel

13.2.4 Groups
-------------

 - type group = int

 - val default_group :
     group

   The group tag used to represent the group of all the channels.  Used
to remove a group tag

 - val reserve_channels :
     int -> int

   Reserve the first channels (0 -> n-1) for the application, i.e.
don't allocate them dynamically to the next sample if no channel is
specified (see Sdlmixer.play_channel).
*Returns* the number of reserved channels

 - val group_channel :
     channel -> group -> unit

   Attach a group tag to a channel. A group tag can be assigned to
several mixer channels, to form groups of channels.  If group is
`default_group', the tag is removed.

 - val group_channels :
     from_c:channel -> to_c:channel -> group -> unit

   Same as above but for a range of channels.

 - val group_count :
     group -> int

   Returns the number of channels in a group.  This is also a subtle
way to get the total number of channels when `group' is `default_group'.

 - val group_available :
     group -> channel

   Finds the first available `channel' in a `group' of channels
*Raises* `Not_found' if none are available.

 - val group_oldest :
     group -> channel

   Finds the "oldest" sample playing in a `group' of channels

 - val group_newer :
     group -> channel

   Finds the "most recent" (i.e. last) sample playing in a `group' of
channels

 - val fadeout_group :
     group -> float -> unit

   `fadeout_group group ticks' Halt a group of channel, fading it out
progressively till it's silent The ms parameter indicates the number of
seconds the fading will take.

 - val halt_group :
     group -> unit

13.2.5 Music
------------

 - type music

 - type music_kind =
  | NONE
  | CMD
  | WAV
  | MOD
  | MID
  | OGG
  | MP3

   The different music types supported

 - val load_music :
     string -> music

   Load a music file (.mod .s3m .it .xm .ogg)

 - val free_music :
     music -> unit

   Free music previously loaded

 - val play_music :
     ?loops:int -> music -> unit

   Play a music chunk.
*Parameters* loops: number of times to play through the music

 - val fadein_music :
     ?loops:int -> music -> float -> unit

   `fadein_music chunck loops music ms' : fade in music over `ms'
seconds, same semantics as the `play_music' function

 - val volume_music :
     music -> float

 - val setvolume_music :
     music -> float -> unit

 - val pause_music :
     unit -> unit

 - val resume_music :
     unit -> unit

 - val rewind_music :
     unit -> unit

 - val set_music_cmd :
     string -> unit

   Stop music and set external music playback command

 - val unset_music_cmd :
     unit -> unit

   Turn off using an external command for music, returning to the
internal music playing functionality

 - val halt_music :
     unit -> unit

 - val fadeout_music :
     float -> unit

   `fadeout_music ticks' Halt the music, fading it out progressively
till it's silent.  The ms parameter indicates the number of seconds the
fading will take.

 - val music_type :
     music option -> music_kind

   Find out the music format of a mixer music, or the currently playing
music, if parameter is `None'.

 - val playing_music :
     unit -> bool

 - val paused_music :
     unit -> bool

 - val fading_music :
     unit -> fade_status

   Query the fading status of a music