\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ocamlsdl.info
@settitle OCamlSDL 0.9.1
@c %**end of header
@defcodeindex va
@defcodeindex ty
@defcodeindex ex
@defcodeindex mo
@dircategory Objective Caml
@direntry
* OCamlSDL 0.9.1: (ocamlsdl).
@end direntry
@ifinfo
This file was generated by Ocamldoc using the Texinfo generator.
@end ifinfo
@c no titlepage.
@node Top, , , (dir)
@top OCamlSDL 0.9.1
@ifinfo
Documentation for OCamlSDL 0.9.1
@end ifinfo
@menu
* Sdl::                            Module
* Sdlcdrom::                       Module
* Sdltimer::                       Module
* Sdljoystick::                    Module
* Sdlkey::                         Module
* Sdlmouse::                       Module
* Sdlevent::                       Module
* Sdlvideo::                       Module
* Sdlwm::                          Module
* Sdlttf::                         Module
* Sdlloader::                      Module
* Sdlmixer::                       Module
* Sdlgfx::                         Module

Indices :
* Types index::
* Exceptions index::
* Values index::
* Modules index::
@end menu
@node Sdl,
@chapter Module @code{Sdl}
@moindex Sdl

@section Description
This module contains functions for initializing/quitting the library

@section Interface
@format
@t{
 @minus{} exception SDL_init_exception of string}
@end format
@exindex SDL_init_exception

Exception for reporting errors during initialization


@subsection Main functions

@format
@t{
 @minus{} type subsystem = [ `AUDIO | `CDROM | `JOYSTICK | `TIMER | `VIDEO ]
}
@end format
@tyindex subsystem

Initialization flag type

@format
@t{
 @minus{} val init :
     ?auto_clean:bool ->
       [< `AUDIO
        | `CDROM
        | `EVENTTHREAD
        | `EVERYTHING
        | `JOYSTICK
        | `NOPARACHUTE
        | `TIMER
        | `VIDEO ]
       list -> unit}
@end format
@vaindex init

Initialize the SDL library. This should be called before all other 
SDL functions. 
The flags parameter specifies what part(s) of SDL to initialize.
@itemize
@item
`NOPARACHUTE : Don't catch fatal signals
@item
`EVENTTHREAD : Automatically pump events in a separate threads
@item
`EVERYTHING  : initialize all subsystems
@end itemize


@format
@t{
 @minus{} val init_subsystem :
     subsystem list -> unit}
@end format
@vaindex init_subsystem

@format
@t{
 @minus{} val was_init :
     unit -> subsystem list}
@end format
@vaindex was_init

@format
@t{
 @minus{} val quit :
     unit -> unit}
@end format
@vaindex quit

@code{quit} shuts down all SDL subsystems and frees the resources allocated 
to them. This should always be called before you exit.

@format
@t{
 @minus{} val quit_subsystem :
     subsystem list -> unit}
@end format
@vaindex quit_subsystem


@subsection Versioning information

@format
@t{
 @minus{} type version = @{
  major : int ;
  minor : int ;
  patch : int ;
 @}}
@end format
@tyindex version

@format
@t{
 @minus{} val version :
     unit -> version}
@end format
@vaindex version

version of the SDL library

@format
@t{
 @minus{} val string_of_version :
     version -> string}
@end format
@vaindex string_of_version


@subsection Environment variables

@format
@t{
 @minus{} val getenv :
     string -> string}
@end format
@vaindex getenv

@format
@t{
 @minus{} val putenv :
     string -> string -> unit}
@end format
@vaindex putenv

@node Sdlcdrom,
@chapter Module @code{Sdlcdrom}
@moindex Sdlcdrom

@section Description
This module provides CD-ROM handling

@section Interface
@format
@t{
 @minus{} exception SDLcdrom_exception of string}
@end format
@exindex SDLcdrom_exception

Exception used to report errors

@format
@t{
 @minus{} exception Trayempty}
@end format
@exindex Trayempty

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


@subsection Types

@format
@t{
 @minus{} type cdrom_drive
}
@end format
@tyindex cdrom_drive

abstract type for handling cdrom

@format
@t{
 @minus{} 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 *)
}
@end format
@tyindex cdrom_drive_status

enumeration of different status cdrom drive

@format
@t{
 @minus{} type track_type =
  | TRACK_AUDIO     
     (* audio track type *)
  | TRACK_DATA     
     (* data track type *)
}
@end format
@tyindex track_type

the types of CD-ROM track possible

@format
@t{
 @minus{} type track = @{
  id : int ;
  kind : Sdlcdrom.track_type ;
  length : int ;
  offset : int ;
 @}}
@end format
@tyindex track

@format
@t{
 @minus{} type cdrom_info = @{
  num_tracks : int ;
  curr_track : int ;
  curr_frame : int ;
  tracks : Sdlcdrom.track array ;
 @}}
@end format
@tyindex cdrom_info


@subsection General API


An SDLcdrom_exception is raised on errors
@format
@t{
 @minus{} val get_num_drives :
     unit -> int}
@end format
@vaindex get_num_drives

@code{get_num_drives} returns the number of CD-ROM drives on the system

@format
@t{
 @minus{} val drive_name :
     int -> string}
@end format
@vaindex drive_name

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


@subsection CD-ROM drive handling

@format
@t{
 @minus{} val cd_open :
     int -> cdrom_drive}
@end format
@vaindex cd_open

@code{cd_open drive} open a CD-ROM drive for access

@format
@t{
 @minus{} val cd_close :
     cdrom_drive -> unit}
@end format
@vaindex cd_close

Closes the handle for the cdrom_drive

@format
@t{
 @minus{} val cd_status :
     cdrom_drive -> cdrom_drive_status}
@end format
@vaindex cd_status

@*
@strong{Returns} the current status of the given drive.

@format
@t{
 @minus{} val cd_info :
     cdrom_drive -> cdrom_info}
@end format
@vaindex cd_info

@*
@strong{Raises} @code{Trayempty} if there's no cd in the drive
@*
@strong{Returns} the table of contents of the CD and current play position


@subsection Playing audio tracks 

@format
@t{
 @minus{} val msf_of_frames :
     int -> int * int * int}
@end format
@vaindex msf_of_frames

@format
@t{
 @minus{} val frames_of_msf :
     int * int * int -> int}
@end format
@vaindex frames_of_msf

@format
@t{
 @minus{} val cd_play_tracks :
     cdrom_drive ->
       start_track:int ->
       start_frame:int -> num_tracks:int -> num_frames:int -> unit}
@end format
@vaindex cd_play_tracks

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

@format
@t{
 @minus{} val cd_play_track :
     cdrom_drive -> track -> unit}
@end format
@vaindex cd_play_track

Play the track n on the given cdrom_drive

@format
@t{
 @minus{} val cd_pause :
     cdrom_drive -> unit}
@end format
@vaindex cd_pause

Pause play

@format
@t{
 @minus{} val cd_resume :
     cdrom_drive -> unit}
@end format
@vaindex cd_resume

Resume play

@format
@t{
 @minus{} val cd_stop :
     cdrom_drive -> unit}
@end format
@vaindex cd_stop

Stop play

@format
@t{
 @minus{} val cd_eject :
     cdrom_drive -> unit}
@end format
@vaindex cd_eject

Eject CD-ROM

@node Sdltimer,
@chapter Module @code{Sdltimer}
@moindex Sdltimer

@section Description
Time-related functions

@section Interface
@format
@t{
 @minus{} val delay :
     int -> unit}
@end format
@vaindex delay

Wait a specified number of milliseconds before returning

@format
@t{
 @minus{} val get_ticks :
     unit -> int}
@end format
@vaindex get_ticks

Get the number of milliseconds since the SDL library initialization.

@node Sdljoystick,
@chapter Module @code{Sdljoystick}
@moindex Sdljoystick

@section Description
Module for SDL joystick event handling

@section 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.
@format
@t{
 @minus{} exception SDLjoystick_exception of string}
@end format
@exindex SDLjoystick_exception

exception for error reporting

@format
@t{
 @minus{} type t
}
@end format
@tyindex t

The joystick abstract type used to identify an SDL joystick

@format
@t{
 @minus{} val num_joysticks :
     unit -> int}
@end format
@vaindex num_joysticks

Count the number of joysticks attached to the system

@format
@t{
 @minus{} val name :
     int -> string}
@end format
@vaindex name

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

@format
@t{
 @minus{} val open_joystick :
     int -> t}
@end format
@vaindex open_joystick

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.
@*
@strong{Raises} @code{SDLjoystick_exception} if an error occurred

@format
@t{
 @minus{} val opened :
     int -> bool}
@end format
@vaindex opened

@*
@strong{Returns} @code{true} if joystick has been opened

@format
@t{
 @minus{} val index :
     t -> int}
@end format
@vaindex index

Get the device index of an opened joystick

@format
@t{
 @minus{} val num_axes :
     t -> int}
@end format
@vaindex num_axes

Get the number of general axis controls on a joystick

@format
@t{
 @minus{} val num_balls :
     t -> int}
@end format
@vaindex num_balls

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

@format
@t{
 @minus{} val num_hats :
     t -> int}
@end format
@vaindex num_hats

Get the number of POV hats on a joystick

@format
@t{
 @minus{} val num_buttons :
     t -> int}
@end format
@vaindex num_buttons

Get the number of buttons on a joystick


@subsection Joystick state 

@format
@t{
 @minus{} val update :
     t -> unit}
@end format
@vaindex update

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.
@format
@t{
 @minus{} val set_event_state :
     bool -> unit}
@end format
@vaindex set_event_state

@format
@t{
 @minus{} val get_event_state :
     unit -> bool}
@end format
@vaindex get_event_state

@format
@t{
 @minus{} type hat_value = int
}
@end format
@tyindex hat_value

@format
@t{
 @minus{} val hat_centered :
     hat_value}
@end format
@vaindex hat_centered

@format
@t{
 @minus{} val hat_up :
     hat_value}
@end format
@vaindex hat_up

@format
@t{
 @minus{} val hat_right :
     hat_value}
@end format
@vaindex hat_right

@format
@t{
 @minus{} val hat_down :
     hat_value}
@end format
@vaindex hat_down

@format
@t{
 @minus{} val hat_left :
     hat_value}
@end format
@vaindex hat_left

@format
@t{
 @minus{} val hat_rightup :
     hat_value}
@end format
@vaindex hat_rightup

@format
@t{
 @minus{} val hat_rightdown :
     hat_value}
@end format
@vaindex hat_rightdown

@format
@t{
 @minus{} val hat_leftup :
     hat_value}
@end format
@vaindex hat_leftup

@format
@t{
 @minus{} val hat_leftdown :
     hat_value}
@end format
@vaindex hat_leftdown

@format
@t{
 @minus{} val get_axis :
     t -> int -> int}
@end format
@vaindex get_axis

@format
@t{
 @minus{} val get_hat :
     t -> int -> hat_value}
@end format
@vaindex get_hat

@format
@t{
 @minus{} val get_ball :
     t -> int -> int * int}
@end format
@vaindex get_ball

@format
@t{
 @minus{} val get_button :
     t -> int -> bool}
@end format
@vaindex get_button

@format
@t{
 @minus{} val close :
     t -> unit}
@end format
@vaindex close

Close a joystick previously opened with Sdljoystick.open_joystick

@node Sdlkey,
@chapter Module @code{Sdlkey}
@moindex Sdlkey

@section Description
Keyboard handling and key symbols

@section Interface

@subsection Keysyms 

@format
@t{
 @minus{} 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 *)
}
@end format
@tyindex t

Concrete type describing keyboard keys ("keysym")

@format
@t{
 @minus{} val int_of_key :
     t -> int}
@end format
@vaindex int_of_key

get the SDL keysym of the key

@format
@t{
 @minus{} val key_of_int :
     int -> t}
@end format
@vaindex key_of_int

get the key corresponding to a SDL keysym
@*
@strong{Raises} @code{Invalid_arg} if not a valid SDL keysym

@format
@t{
 @minus{} val char_of_key :
     t -> char}
@end format
@vaindex char_of_key

Returns a (iso-8859-1) character corresponding to a key
@*
@strong{Raises} @code{Invalid_arg} if corresponding SDL keysym is > 255

@format
@t{
 @minus{} val num_keys :
     int}
@end format
@vaindex num_keys

number of keys in the Sdlkey.t variant type : should be @code{232}

@format
@t{
 @minus{} val max_code :
     int}
@end format
@vaindex max_code

highest SDL keysym : should be @code{322}

@format
@t{
 @minus{} val name :
     t -> string}
@end format
@vaindex name

@*
@strong{Returns} a short string describing the key


@subsection Keyboard handling 

@format
@t{
 @minus{} val enable_unicode :
     bool -> unit}
@end format
@vaindex enable_unicode

Enable unicode translation of keysyms for keyboard events

@format
@t{
 @minus{} val query_unicode :
     unit -> bool}
@end format
@vaindex query_unicode

@format
@t{
 @minus{} val disable_key_repeat :
     unit -> unit}
@end format
@vaindex disable_key_repeat

Disable keyboard repeat

@format
@t{
 @minus{} val enable_key_repeat :
     ?delay:int -> ?interval:int -> unit -> unit}
@end format
@vaindex enable_key_repeat

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

@format
@t{
 @minus{} val get_key_state :
     unit ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex get_key_state

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

@format
@t{
 @minus{} val is_key_pressed :
     t -> bool}
@end format
@vaindex is_key_pressed

Checks wether a key is currently pressed on the keyboard.


@subsection Key modifiers 

@format
@t{
 @minus{} type mod_state = int
}
@end format
@tyindex mod_state


The following values are flags. Use with @code{land}, @code{lor}, etc.
@format
@t{
 @minus{} val kmod_none :
     mod_state}
@end format
@vaindex kmod_none

@format
@t{
 @minus{} val kmod_lshift :
     mod_state}
@end format
@vaindex kmod_lshift

@format
@t{
 @minus{} val kmod_rshift :
     mod_state}
@end format
@vaindex kmod_rshift

@format
@t{
 @minus{} val kmod_lctrl :
     mod_state}
@end format
@vaindex kmod_lctrl

@format
@t{
 @minus{} val kmod_rctrl :
     mod_state}
@end format
@vaindex kmod_rctrl

@format
@t{
 @minus{} val kmod_lalt :
     mod_state}
@end format
@vaindex kmod_lalt

@format
@t{
 @minus{} val kmod_ralt :
     mod_state}
@end format
@vaindex kmod_ralt

@format
@t{
 @minus{} val kmod_lmeta :
     mod_state}
@end format
@vaindex kmod_lmeta

@format
@t{
 @minus{} val kmod_rmeta :
     mod_state}
@end format
@vaindex kmod_rmeta

@format
@t{
 @minus{} val kmod_num :
     mod_state}
@end format
@vaindex kmod_num

@format
@t{
 @minus{} val kmod_caps :
     mod_state}
@end format
@vaindex kmod_caps

@format
@t{
 @minus{} val kmod_mode :
     mod_state}
@end format
@vaindex kmod_mode

@format
@t{
 @minus{} val kmod_ctrl :
     mod_state}
@end format
@vaindex kmod_ctrl

@format
@t{
 @minus{} val kmod_shift :
     mod_state}
@end format
@vaindex kmod_shift

@format
@t{
 @minus{} val kmod_alt :
     mod_state}
@end format
@vaindex kmod_alt

@format
@t{
 @minus{} val kmod_meta :
     mod_state}
@end format
@vaindex kmod_meta

@format
@t{
 @minus{} val get_mod_state :
     unit -> mod_state}
@end format
@vaindex get_mod_state

Get the current key modifier state

@format
@t{
 @minus{} val set_mod_state :
     mod_state -> unit}
@end format
@vaindex set_mod_state

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

@node Sdlmouse,
@chapter Module @code{Sdlmouse}
@moindex Sdlmouse

@section Description
Mouse event handling and cursors

@section Interface

@subsection Mouse state

@format
@t{
 @minus{} type button =
  | BUTTON_LEFT
  | BUTTON_MIDDLE
  | BUTTON_RIGHT
  | BUTTON_WHEELUP
  | BUTTON_WHEELDOWN
  | BUTTON_X of int     
     (* BUTTON_X is only seen in a Sdlevent.mousebutton_event,
        it is not returned by Sdlmouse.get_state *)
}
@end format
@tyindex button

@format
@t{
 @minus{} val get_state :
     ?relative:bool -> unit -> int * int * button list}
@end format
@vaindex get_state

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

@format
@t{
 @minus{} val warp :
     int -> int -> unit}
@end format
@vaindex warp

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


@subsection Cursors 

@format
@t{
 @minus{} type cursor
}
@end format
@tyindex cursor

abstract type for cursors

@format
@t{
 @minus{} 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 *)
 @}}
@end format
@tyindex cursor_data

@format
@t{
 @minus{} 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}
@end format
@vaindex make_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.

@format
@t{
 @minus{} val free_cursor :
     cursor -> unit}
@end format
@vaindex free_cursor

Deallocates a cursor.

@format
@t{
 @minus{} val set_cursor :
     cursor -> unit}
@end format
@vaindex set_cursor

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

@format
@t{
 @minus{} val get_cursor :
     unit -> cursor}
@end format
@vaindex get_cursor

Returns the currently active cursor.

@format
@t{
 @minus{} val cursor_visible :
     unit -> bool}
@end format
@vaindex cursor_visible

Tests if cursor is shown on screen

@format
@t{
 @minus{} val show_cursor :
     bool -> unit}
@end format
@vaindex show_cursor

Toggle cursor display

@format
@t{
 @minus{} val cursor_data :
     cursor -> cursor_data}
@end format
@vaindex cursor_data

converts an abstract cursor value to concrete cursor data

@format
@t{
 @minus{} val pprint_cursor :
     cursor -> unit}
@end format
@vaindex pprint_cursor

for debugging : prints on stdout

@format
@t{
 @minus{} val convert_to_cursor :
     data:int array ->
       mask:int array -> w:int -> h:int -> hot_x:int -> hot_y:int -> cursor}
@end format
@vaindex convert_to_cursor

@node Sdlevent,
@chapter Module @code{Sdlevent}
@moindex Sdlevent

@section Description
SDL event handling

@ifinfo
@heading Subparts

@end ifinfo
@menu
* Old: Sdlevent/Old.               Module
@end menu
@section Interface
@format
@t{
 @minus{} exception Event_exn of string}
@end format
@exindex Event_exn

The exception used for reporting events-related errors.


@subsection Application focus

@format
@t{
 @minus{} type active_state =
  | MOUSEFOCUS     
     (* The app has mouse coverage *)
  | INPUTFOCUS     
     (* The app has input focus *)
  | APPACTIVE     
     (* The application is active *)
}
@end format
@tyindex active_state

The available application states

@format
@t{
 @minus{} val get_app_state :
     unit -> active_state list}
@end format
@vaindex get_app_state

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.


@subsection Events datatypes

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

Application visibility event record

@format
@t{
 @minus{} type switch_state =
  | RELEASED
  | PRESSED
}
@end format
@tyindex switch_state

@format
@t{
 @minus{} 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 *)
  unicode : int ;
 @}}
@end format
@tyindex keyboard_event

Keyboard event record

@format
@t{
 @minus{} 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 *)
 @}}
@end format
@tyindex mousemotion_event

Mouse motion event record

@format
@t{
 @minus{} 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 ;
 @}}
@end format
@tyindex mousebutton_event

Mouse button event record

@format
@t{
 @minus{} 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) *)
 @}}
@end format
@tyindex joyaxis_event

Joystick axis motion event record

@format
@t{
 @minus{} 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 *)
 @}}
@end format
@tyindex joyball_event

Joystick axis motion event record

@format
@t{
 @minus{} 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. *)
 @}}
@end format
@tyindex joyhat_event

Joystick hat position change event record

@format
@t{
 @minus{} 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 *)
 @}}
@end format
@tyindex joybutton_event

Joystick button event record

@format
@t{
 @minus{} 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 ! *)
}
@end format
@tyindex event

The main event type

@format
@t{
 @minus{} val string_of_event :
     event -> string}
@end format
@vaindex string_of_event

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


@subsection Event masks 

@format
@t{
 @minus{} type event_mask = int
}
@end format
@tyindex event_mask


Event masks values are ints and should be manipulated with @code{lor},
   @code{land}, etc.
@format
@t{
 @minus{} val active_mask :
     event_mask}
@end format
@vaindex active_mask

@format
@t{
 @minus{} val keydown_mask :
     event_mask}
@end format
@vaindex keydown_mask

@format
@t{
 @minus{} val keyup_mask :
     event_mask}
@end format
@vaindex keyup_mask

@format
@t{
 @minus{} val mousemotion_mask :
     event_mask}
@end format
@vaindex mousemotion_mask

@format
@t{
 @minus{} val mousebuttondown_mask :
     event_mask}
@end format
@vaindex mousebuttondown_mask

@format
@t{
 @minus{} val mousebuttonup_mask :
     event_mask}
@end format
@vaindex mousebuttonup_mask

@format
@t{
 @minus{} val joyaxismotion_mask :
     event_mask}
@end format
@vaindex joyaxismotion_mask

@format
@t{
 @minus{} val joyballmotion_mask :
     event_mask}
@end format
@vaindex joyballmotion_mask

@format
@t{
 @minus{} val joyhatmotion_mask :
     event_mask}
@end format
@vaindex joyhatmotion_mask

@format
@t{
 @minus{} val joybuttondown_mask :
     event_mask}
@end format
@vaindex joybuttondown_mask

@format
@t{
 @minus{} val joybuttonup_mask :
     event_mask}
@end format
@vaindex joybuttonup_mask

@format
@t{
 @minus{} val quit_mask :
     event_mask}
@end format
@vaindex quit_mask

@format
@t{
 @minus{} val syswmevent_mask :
     event_mask}
@end format
@vaindex syswmevent_mask

@format
@t{
 @minus{} val videoresize_mask :
     event_mask}
@end format
@vaindex videoresize_mask

@format
@t{
 @minus{} val videoexpose_mask :
     event_mask}
@end format
@vaindex videoexpose_mask

@format
@t{
 @minus{} val userevent_mask :
     event_mask}
@end format
@vaindex userevent_mask

@format
@t{
 @minus{} val keyboard_event_mask :
     event_mask}
@end format
@vaindex keyboard_event_mask

@format
@t{
 @minus{} val mouse_event_mask :
     event_mask}
@end format
@vaindex mouse_event_mask

@format
@t{
 @minus{} val joystick_event_mask :
     event_mask}
@end format
@vaindex joystick_event_mask

@format
@t{
 @minus{} val all_events_mask :
     event_mask}
@end format
@vaindex all_events_mask

@format
@t{
 @minus{} 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
}
@end format
@tyindex event_kind

@format
@t{
 @minus{} val make_mask :
     event_kind list -> event_mask}
@end format
@vaindex make_mask

@format
@t{
 @minus{} val of_mask :
     event_mask -> event_kind list}
@end format
@vaindex of_mask


@subsection Enabling/Disabling event collecting

@format
@t{
 @minus{} val enable_events :
     event_mask -> unit}
@end format
@vaindex enable_events

Specified events are collected and added to the event queue (when
@code{pump} is called).

@format
@t{
 @minus{} val disable_events :
     event_mask -> unit}
@end format
@vaindex disable_events

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

@format
@t{
 @minus{} val get_enabled_events :
     unit -> event_mask}
@end format
@vaindex get_enabled_events

The mask of currently reported events.

@format
@t{
 @minus{} val get_state :
     event_kind -> bool}
@end format
@vaindex get_state

Query the reporting state of an event type.

@format
@t{
 @minus{} val set_state :
     bool -> event_kind -> unit}
@end format
@vaindex set_state

Set the reporting state of one individual event type.


@subsection Handling events

@format
@t{
 @minus{} val pump :
     unit -> unit}
@end format
@vaindex pump

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.

@format
@t{
 @minus{} val wait_event :
     unit -> event}
@end format
@vaindex wait_event

Wait indefinitely for the next available event and return it.

@format
@t{
 @minus{} val wait :
     unit -> unit}
@end format
@vaindex wait

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

@format
@t{
 @minus{} val poll :
     unit -> event option}
@end format
@vaindex poll

Poll for currently pending events and return one if available.

@format
@t{
 @minus{} val has_event :
     unit -> bool}
@end format
@vaindex has_event

Poll for currently pending events and return @code{false} if the queue is empty.

@format
@t{
 @minus{} val peek :
     ?mask:event_mask -> int -> event list}
@end format
@vaindex peek

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.

@format
@t{
 @minus{} val get :
     ?mask:event_mask -> int -> event list}
@end format
@vaindex get

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.

@format
@t{
 @minus{} val add :
     event list -> unit}
@end format
@vaindex add

Add events to the back of the event queue.


@subsection Old event-handling interface 

@format
@t{
 @minus{} module Old}
@end format
@xref{Sdlevent/Old,Module Old}.

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

Callback-based event handling.

@node Sdlevent/Old,
@section Module @code{Sdlevent.Old}
@moindex Old

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

Callback-based event handling.

@subsection Interface

@subsubsection Definition of the event callbacks

@format
@t{
 @minus{} type keyboard_event_func = Sdlkey.t -> Sdlevent.switch_state -> int -> int -> unit
}
@end format
@tyindex keyboard_event_func

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

@format
@t{
 @minus{} type mouse_event_func = Sdlmouse.button -> Sdlevent.switch_state -> int -> int -> unit
}
@end format
@tyindex mouse_event_func

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

@format
@t{
 @minus{} type mousemotion_event_func = int -> int -> unit
}
@end format
@tyindex mousemotion_event_func

Mouse motion event called with the coordinates of the mouse
pointer

@format
@t{
 @minus{} type idle_event_func = unit -> unit
}
@end format
@tyindex idle_event_func

@format
@t{
 @minus{} type resize_event_func = int -> int -> unit
}
@end format
@tyindex resize_event_func


@subsubsection Functions for setting the current event callbacks

@format
@t{
 @minus{} val set_keyboard_event_func :
     keyboard_event_func -> unit}
@end format
@vaindex set_keyboard_event_func

@format
@t{
 @minus{} val set_mouse_event_func :
     mouse_event_func -> unit}
@end format
@vaindex set_mouse_event_func

@format
@t{
 @minus{} val set_mousemotion_event_func :
     mousemotion_event_func -> unit}
@end format
@vaindex set_mousemotion_event_func

@format
@t{
 @minus{} val set_idle_event_func :
     idle_event_func -> unit}
@end format
@vaindex set_idle_event_func

@format
@t{
 @minus{} val set_resize_event_func :
     resize_event_func -> unit}
@end format
@vaindex set_resize_event_func


@subsubsection Event loop

@format
@t{
 @minus{} val start_event_loop :
     unit -> unit}
@end format
@vaindex start_event_loop

@format
@t{
 @minus{} val exit_event_loop :
     unit -> unit}
@end format
@vaindex exit_event_loop

@node Sdlvideo,
@chapter Module @code{Sdlvideo}
@moindex Sdlvideo

@section Description
Module for video manipulations

@section Interface
@format
@t{
 @minus{} exception Video_exn of string}
@end format
@exindex Video_exn


@subsection Rectangles

@format
@t{
 @minus{} type rect = @{
  r_x : int ;
  r_y : int ;
  r_w : int ;
  r_h : int ;
 @}}
@end format
@tyindex rect

rectangular area (x, y, w, h)

@format
@t{
 @minus{} val rect :
     x:int -> y:int -> w:int -> h:int -> rect}
@end format
@vaindex rect

@format
@t{
 @minus{} val copy_rect :
     rect -> rect}
@end format
@vaindex copy_rect

@*
@strong{Returns} a copy of the rectangle


@subsection Video mode informations

@format
@t{
 @minus{} 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) *)
 @}}
@end format
@tyindex pixel_format_info

Structure describing how color are encoded as pixels

@format
@t{
 @minus{} 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) *)
 @}}
@end format
@tyindex video_info

Information on either the 'best' available mode (if called before
@code{set_video_mode}) or the current video mode.

@format
@t{
 @minus{} val get_video_info :
     unit -> video_info}
@end format
@vaindex get_video_info

@format
@t{
 @minus{} val get_video_info_format :
     unit -> pixel_format_info}
@end format
@vaindex get_video_info_format

@*
@strong{Returns} information about the pixel format

@format
@t{
 @minus{} val driver_name :
     unit -> string}
@end format
@vaindex driver_name

@*
@strong{Returns} the name of the video driver

@format
@t{
 @minus{} type video_flag = [ `ANYFORMAT
  | `ASYNCBLIT
  | `DOUBLEBUF
  | `FULLSCREEN
  | `HWPALETTE
  | `HWSURFACE
  | `NOFRAME
  | `OPENGL
  | `OPENGLBLIT
  | `RESIZABLE
  | `SWSURFACE ]
}
@end format
@tyindex video_flag

@format
@t{
 @minus{} type modes =
  | NOMODE     
     (* no dimensions available for the requested format *)
  | ANY     
     (* any dimension okay *)
  | DIM of (int * int) list
}
@end format
@tyindex modes

@format
@t{
 @minus{} val list_modes :
     ?bpp:int -> video_flag list -> modes}
@end format
@vaindex list_modes

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

@format
@t{
 @minus{} val video_mode_ok :
     w:int -> h:int -> bpp:int -> video_flag list -> int}
@end format
@vaindex video_mode_ok

Check to see if a particular video mode is supported.
@*
@strong{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.


@subsection Surfaces

@format
@t{
 @minus{} type surface
}
@end format
@tyindex surface

Graphical surface datatype

@format
@t{
 @minus{} type surface_flags = [ `ANYFORMAT
  | `ASYNCBLIT
  | `DOUBLEBUF
  | `FULLSCREEN
  | `HWACCEL
  | `HWPALETTE
  | `HWSURFACE
  | `NOFRAME
  | `OPENGL
  | `OPENGLBLIT
  | `PREALLOC
  | `RESIZABLE
  | `RLEACCEL
  | `SRCALPHA
  | `SRCCOLORKEY
  | `SWSURFACE ]
}
@end format
@tyindex surface_flags

@format
@t{
 @minus{} 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 *)
 @}}
@end format
@tyindex surface_info

@format
@t{
 @minus{} val surface_info :
     surface -> surface_info}
@end format
@vaindex surface_info

@*
@strong{Returns} information for the given @code{surface}

@format
@t{
 @minus{} val surface_format :
     surface -> pixel_format_info}
@end format
@vaindex surface_format

@*
@strong{Returns} pixel format information for the given @code{surface}

@format
@t{
 @minus{} val surface_dims :
     surface -> int * int * int}
@end format
@vaindex surface_dims

@*
@strong{Returns} width, height and pitch of the given @code{surface}

@format
@t{
 @minus{} val surface_flags :
     surface -> surface_flags list}
@end format
@vaindex surface_flags

@*
@strong{Returns} flag list for the given @code{surface}

@format
@t{
 @minus{} val surface_bpp :
     surface -> int}
@end format
@vaindex surface_bpp

@*
@strong{Returns} bits-per-pixel for the given @code{surface}


@subsection Video modes-related functions

@format
@t{
 @minus{} val get_video_surface :
     unit -> surface}
@end format
@vaindex get_video_surface

@*
@strong{Returns} the current display @code{surface}

@format
@t{
 @minus{} val set_video_mode :
     w:int -> h:int -> ?bpp:int -> video_flag list -> surface}
@end format
@vaindex set_video_mode

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

@format
@t{
 @minus{} val update_rect :
     ?rect:rect -> surface -> unit}
@end format
@vaindex update_rect

@*
@strong{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

@format
@t{
 @minus{} val update_rects :
     rect list -> surface -> unit}
@end format
@vaindex update_rects

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.

@format
@t{
 @minus{} val flip :
     surface -> unit}
@end format
@vaindex flip

Swaps screen buffers.

On hardware that supports double-buffering (@code{`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 @code{update_rect}


@subsection Color manipulation

@format
@t{
 @minus{} val set_gamma :
     r:float -> g:float -> b:float -> unit}
@end format
@vaindex set_gamma

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.

@format
@t{
 @minus{} type color = int * int * int
}
@end format
@tyindex color

Format independent color description @code{(r,g,b)} are 8 bits unsigned
integers

@format
@t{
 @minus{} val black :
     color}
@end format
@vaindex black

@format
@t{
 @minus{} val white :
     color}
@end format
@vaindex white

@format
@t{
 @minus{} val red :
     color}
@end format
@vaindex red

@format
@t{
 @minus{} val green :
     color}
@end format
@vaindex green

@format
@t{
 @minus{} val blue :
     color}
@end format
@vaindex blue

@format
@t{
 @minus{} val yellow :
     color}
@end format
@vaindex yellow

@format
@t{
 @minus{} val cyan :
     color}
@end format
@vaindex cyan

@format
@t{
 @minus{} val magenta :
     color}
@end format
@vaindex magenta


@subsubsection Palettes

@format
@t{
 @minus{} val use_palette :
     surface -> bool}
@end format
@vaindex use_palette

@*
@strong{Returns} @code{true} if surface use indexed colors

@format
@t{
 @minus{} val palette_ncolors :
     surface -> int}
@end format
@vaindex palette_ncolors

Number of colors in the surface's palette

@format
@t{
 @minus{} val get_palette_color :
     surface -> int -> color}
@end format
@vaindex get_palette_color

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

@format
@t{
 @minus{} 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
}
@end format
@tyindex palette_flag

@format
@t{
 @minus{} val set_palette :
     surface ->
       ?flag:palette_flag ->
       ?firstcolor:int -> color array -> unit}
@end format
@vaindex set_palette

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


@subsubsection Conversions

@format
@t{
 @minus{} val map_RGB :
     surface -> ?alpha:int -> color -> int32}
@end format
@vaindex map_RGB

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

@format
@t{
 @minus{} val get_RGB :
     surface -> int32 -> color}
@end format
@vaindex get_RGB

Maps a pixel value into the RGB components for a given pixel format
@*
@strong{Returns} RGB color

@format
@t{
 @minus{} val get_RGBA :
     surface -> int32 -> color * int}
@end format
@vaindex get_RGBA

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


@subsection Creating RGB surface

@format
@t{
 @minus{} 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}
@end format
@vaindex create_RGB_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.
@*
@strong{Returns} the new surface

@format
@t{
 @minus{} val create_RGB_surface_format :
     surface ->
       [ `ASYNCBLIT | `HWSURFACE | `SRCALPHA | `SRCCOLORKEY | `SWSURFACE ] list ->
       w:int -> h:int -> surface}
@end format
@vaindex create_RGB_surface_format

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

@format
@t{
 @minus{} 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}
@end format
@vaindex create_RGB_surface_from_32

@format
@t{
 @minus{} 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}
@end format
@vaindex create_RGB_surface_from_24

@format
@t{
 @minus{} 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}
@end format
@vaindex create_RGB_surface_from_16

@format
@t{
 @minus{} 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}
@end format
@vaindex create_RGB_surface_from_8


@subsection Locking/Unlocking surface

@format
@t{
 @minus{} val must_lock :
     surface -> bool}
@end format
@vaindex must_lock

@*
@strong{Returns} @code{true} if the surface should be locked before accessing
   its pixels

@format
@t{
 @minus{} val lock :
     surface -> unit}
@end format
@vaindex lock

Sets up a surface for directly accessing the pixels.

@format
@t{
 @minus{} val unlock :
     surface -> unit}
@end format
@vaindex unlock

Releases the lock on the given @code{surface}


@subsection Accessing surface pixels

@format
@t{
 @minus{} val pixel_data :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex pixel_data

@format
@t{
 @minus{} val pixel_data_8 :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex pixel_data_8

@format
@t{
 @minus{} val pixel_data_16 :
     surface ->
       (int, Bigarray.int16_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex pixel_data_16

@format
@t{
 @minus{} val pixel_data_24 :
     surface ->
       (int, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex pixel_data_24

@format
@t{
 @minus{} val pixel_data_32 :
     surface ->
       (int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array1.t}
@end format
@vaindex pixel_data_32

@format
@t{
 @minus{} val get_pixel :
     surface -> x:int -> y:int -> int32}
@end format
@vaindex get_pixel

@format
@t{
 @minus{} val get_pixel_color :
     surface -> x:int -> y:int -> color}
@end format
@vaindex get_pixel_color

Access an individual pixel on a surface and returns is as a @code{color}.
The surface may have to be locked before access.

@format
@t{
 @minus{} val put_pixel :
     surface -> x:int -> y:int -> int32 -> unit}
@end format
@vaindex put_pixel

@format
@t{
 @minus{} val put_pixel_color :
     surface -> x:int -> y:int -> color -> unit}
@end format
@vaindex put_pixel_color

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


@subsection Reading/writing in BMP files

@format
@t{
 @minus{} val load_BMP :
     string -> surface}
@end format
@vaindex load_BMP

Loads a surface from a named Windows BMP file.

@format
@t{
 @minus{} val load_BMP_from_mem :
     string -> surface}
@end format
@vaindex load_BMP_from_mem

Loads a BMP image from a memory buffer.

@format
@t{
 @minus{} val save_BMP :
     surface -> string -> unit}
@end format
@vaindex save_BMP

Saves the @code{surface} as a Windows BMP file named file.


@subsection Colorkey and alpha stuff

@format
@t{
 @minus{} val unset_color_key :
     surface -> unit}
@end format
@vaindex unset_color_key

@format
@t{
 @minus{} val set_color_key :
     surface -> ?rle:bool -> int32 -> unit}
@end format
@vaindex set_color_key

Sets the color key (transparent pixel) in a blittable @code{surface}.

@format
@t{
 @minus{} val get_color_key :
     surface -> int32}
@end format
@vaindex get_color_key

@*
@strong{Returns} the color key of the given @code{surface}

@format
@t{
 @minus{} val unset_alpha :
     surface -> unit}
@end format
@vaindex unset_alpha

@format
@t{
 @minus{} val set_alpha :
     surface -> ?rle:bool -> int -> unit}
@end format
@vaindex set_alpha

sets the alpha value for the entire @code{surface}, as opposed to
using the alpha component of each pixel.

@format
@t{
 @minus{} val get_alpha :
     surface -> int}
@end format
@vaindex get_alpha

@*
@strong{Returns} the alpha value of the given @code{surface}


@subsection Clipping

@format
@t{
 @minus{} val unset_clip_rect :
     surface -> unit}
@end format
@vaindex unset_clip_rect

disable clipping for the given @code{surface}

@format
@t{
 @minus{} val set_clip_rect :
     surface -> rect -> unit}
@end format
@vaindex set_clip_rect

Sets the clipping rectangle for the destination @code{surface} in a blit.

@format
@t{
 @minus{} val get_clip_rect :
     surface -> rect}
@end format
@vaindex get_clip_rect

@*
@strong{Returns} the clipping rectangle for the destination @code{surface} in a blit.


@subsection Blitting

@format
@t{
 @minus{} val blit_surface :
     src:surface ->
       ?src_rect:rect ->
       dst:surface -> ?dst_rect:rect -> unit -> unit}
@end format
@vaindex blit_surface

Performs a fast blit from the source @code{surface} 
to the destination @code{surface}.
@*
@strong{Parameters} src_rect: the width and height determine the size of the
   copied rectangle. If omitted, the entire surface is copied.
@*
@strong{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 @code{src_rect} and @code{dst_rect}
   after all clipping is performed.

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

@format
@t{
 @minus{} val fill_rect :
     ?rect:rect -> surface -> int32 -> unit}
@end format
@vaindex fill_rect

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

@format
@t{
 @minus{} val display_format :
     ?alpha:bool -> surface -> surface}
@end format
@vaindex display_format

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.
@*
@strong{Parameters} alpha: if @code{true}, include an alpha channel in the new surface

@node Sdlwm,
@chapter Module @code{Sdlwm}
@moindex Sdlwm

@section Description
Window Manager interaction

@section Interface
@format
@t{
 @minus{} val set_caption :
     title:string -> icon:string -> unit}
@end format
@vaindex set_caption

Sets the title and icon text of the display window

@format
@t{
 @minus{} val get_caption :
     unit -> string * string}
@end format
@vaindex get_caption

Gets the title and icon text of the display window

@format
@t{
 @minus{} val set_icon :
     Sdlvideo.surface -> unit}
@end format
@vaindex set_icon

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

@format
@t{
 @minus{} val iconify :
     unit -> bool}
@end format
@vaindex iconify

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

@format
@t{
 @minus{} val toggle_fullscreen :
     unit -> bool}
@end format
@vaindex toggle_fullscreen

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 @code{true}.  If it is not implemented, or fails, it returns
@code{false}.

@format
@t{
 @minus{} val grab_input :
     bool -> unit}
@end format
@vaindex grab_input

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.

@format
@t{
 @minus{} val query_grab :
     unit -> bool}
@end format
@vaindex query_grab

@node Sdlttf,
@chapter Module @code{Sdlttf}
@moindex Sdlttf

@section Description
This module provides TTF (TrueType Font) support

@section Interface
@format
@t{
 @minus{} exception SDLttf_exception of string}
@end format
@exindex SDLttf_exception

Exception for reporting errors

@format
@t{
 @minus{} val init :
     unit -> unit}
@end format
@vaindex init

Initialise SDL_tff and freetype

@format
@t{
 @minus{} val quit :
     unit -> unit}
@end format
@vaindex quit

Quits the system


@subsection General operations on font datatype

@format
@t{
 @minus{} type font
}
@end format
@tyindex font

abstract font datatype

@format
@t{
 @minus{} val open_font :
     string -> ?index:int -> int -> font}
@end format
@vaindex open_font

open a font file and create a font of the specified point size
@*
@strong{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.
@format
@t{
 @minus{} type font_style =
  | NORMAL
  | BOLD
  | ITALIC
  | UNDERLINE
}
@end format
@tyindex font_style

@format
@t{
 @minus{} val get_font_style :
     font -> font_style list}
@end format
@vaindex get_font_style

Retrieve the font style : either @code{NORMAL} or a combination of 
@code{BOLD}, @code{ITALIC} and @code{UNDERLINE}

@format
@t{
 @minus{} val set_font_style :
     font -> font_style list -> unit}
@end format
@vaindex set_font_style


@subsection Font information 

@format
@t{
 @minus{} val font_height :
     font -> int}
@end format
@vaindex font_height

@*
@strong{Returns} the total height(int) of the font (usually equal to point size)

@format
@t{
 @minus{} val font_ascent :
     font -> int}
@end format
@vaindex font_ascent

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

@format
@t{
 @minus{} val font_descent :
     font -> int}
@end format
@vaindex font_descent

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

@format
@t{
 @minus{} val font_lineskip :
     font -> int}
@end format
@vaindex font_lineskip

Get the recommended spacing between lines of text for this font

@format
@t{
 @minus{} val font_faces :
     font -> int}
@end format
@vaindex font_faces

Get the number of faces of the font


Get some font face attributes, if any
@format
@t{
 @minus{} val is_fixed_width :
     font -> bool}
@end format
@vaindex is_fixed_width

@format
@t{
 @minus{} val family_name :
     font -> string}
@end format
@vaindex family_name

@format
@t{
 @minus{} val style_name :
     font -> string}
@end format
@vaindex style_name


@subsection Text rendering functions

@format
@t{
 @minus{} val size_text :
     font -> string -> int * int}
@end format
@vaindex size_text

Get the dimensions of a rendered string of text

@format
@t{
 @minus{} val size_utf8 :
     font -> string -> int * int}
@end format
@vaindex size_utf8

@format
@t{
 @minus{} val glyph_metrics :
     font -> char -> int * int * int * int}
@end format
@vaindex glyph_metrics

@*
@strong{Returns} the metrics (minx,maxx,miny,maxy) of a glyph

@format
@t{
 @minus{} type render_kind =
  | SOLID of Sdlvideo.color
  | SHADED of (Sdlvideo.color * Sdlvideo.color)
  | BLENDED of Sdlvideo.color
}
@end format
@tyindex render_kind

Variant type for the generic rendering functions


@subsubsection Text rendering functions

@format
@t{
 @minus{} val render_text_solid :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_text_solid

@format
@t{
 @minus{} val render_text_shaded :
     font ->
       string -> fg:Sdlvideo.color -> bg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_text_shaded

@format
@t{
 @minus{} val render_text_blended :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_text_blended

@format
@t{
 @minus{} val render_utf8_solid :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_utf8_solid

@format
@t{
 @minus{} val render_utf8_shaded :
     font ->
       string -> fg:Sdlvideo.color -> bg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_utf8_shaded

@format
@t{
 @minus{} val render_utf8_blended :
     font -> string -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_utf8_blended

@format
@t{
 @minus{} val render_text :
     font -> render_kind -> string -> Sdlvideo.surface}
@end format
@vaindex render_text


@subsubsection Glyph rendering functions

@format
@t{
 @minus{} val render_glyph_solid :
     font -> char -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_glyph_solid

@format
@t{
 @minus{} val render_glyph_shaded :
     font ->
       char -> fg:Sdlvideo.color -> bg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_glyph_shaded

@format
@t{
 @minus{} val render_glyph_blended :
     font -> char -> fg:Sdlvideo.color -> Sdlvideo.surface}
@end format
@vaindex render_glyph_blended

@format
@t{
 @minus{} val render_glyph :
     font -> render_kind -> char -> Sdlvideo.surface}
@end format
@vaindex render_glyph

@node Sdlloader,
@chapter Module @code{Sdlloader}
@moindex Sdlloader

@section Description
Image loader module

@section Interface
@format
@t{
 @minus{} exception SDLloader_exception of string}
@end format
@exindex SDLloader_exception

Exception to report errors

@format
@t{
 @minus{} val load_image :
     string -> Sdlvideo.surface}
@end format
@vaindex load_image

load an image as a surface

@format
@t{
 @minus{} val load_image_from_mem :
     string -> Sdlvideo.surface}
@end format
@vaindex load_image_from_mem

@format
@t{
 @minus{} val read_XPM_from_array :
     string array -> Sdlvideo.surface}
@end format
@vaindex read_XPM_from_array

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

@node Sdlmixer,
@chapter Module @code{Sdlmixer}
@moindex Sdlmixer

@section Description
Simple multi-channel audio mixer

@section Interface
@format
@t{
 @minus{} exception SDLmixer_exception of string}
@end format
@exindex SDLmixer_exception

Exception used to report errors


@subsection General API

@format
@t{
 @minus{} val version :
     unit -> Sdl.version}
@end format
@vaindex version

Get the version of the dynamically linked SDL_mixer library

@format
@t{
 @minus{} 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 *)
}
@end format
@tyindex format

Audio format flags

@format
@t{
 @minus{} type channels =
  | MONO
  | STEREO
}
@end format
@tyindex channels

@format
@t{
 @minus{} val open_audio :
     ?freq:int ->
       ?format:format ->
       ?chunksize:int -> ?channels:channels -> unit -> unit}
@end format
@vaindex open_audio

@code{open_audio frequency format chunksize channels ()} opens the mixer
with a certain audio format.  
@itemize
@item
frequency could be 8000 11025 22050 44100 ; defaults to 22050
@item
format defaults to AUDIO_FORMAT_S16SYS
@item
chunksize defaults to 4096
@item
channels defaults to STEREO
@end itemize


@format
@t{
 @minus{} val close_audio :
     unit -> unit}
@end format
@vaindex close_audio

Close the mixer, halting all playing audio

@format
@t{
 @minus{} type specs = @{
  frequency : int ;
  format : Sdlmixer.format ;
  channels : Sdlmixer.channels ;
 @}}
@end format
@tyindex specs

@format
@t{
 @minus{} val query_specs :
     unit -> specs}
@end format
@vaindex query_specs

Find out what the actual audio device parameters are.
@*
@strong{Raises} @code{SDLmixer_exception} if the audio has not been opened


@subsection Samples

@format
@t{
 @minus{} type chunk
}
@end format
@tyindex chunk

@format
@t{
 @minus{} val loadWAV :
     string -> chunk}
@end format
@vaindex loadWAV

Load a wave file

@format
@t{
 @minus{} val loadWAV_from_mem :
     string -> chunk}
@end format
@vaindex loadWAV_from_mem

@format
@t{
 @minus{} val load_string :
     string -> chunk}
@end format
@vaindex load_string

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

@format
@t{
 @minus{} val load_string_raw :
     string -> chunk}
@end format
@vaindex load_string_raw

Load raw audio data of the mixer format from a memory buffer

@format
@t{
 @minus{} val volume_chunk :
     chunk -> float}
@end format
@vaindex volume_chunk

@format
@t{
 @minus{} val setvolume_chunk :
     chunk -> float -> unit}
@end format
@vaindex setvolume_chunk

@format
@t{
 @minus{} val free_chunk :
     chunk -> unit}
@end format
@vaindex free_chunk

Free an audio chunk previously loaded


@subsection Channels

@format
@t{
 @minus{} type channel = int
}
@end format
@tyindex channel

@format
@t{
 @minus{} val all_channels :
     channel}
@end format
@vaindex all_channels

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

@format
@t{
 @minus{} val num_channels :
     unit -> int}
@end format
@vaindex num_channels

@*
@strong{Returns} the number of channels currently allocated

@format
@t{
 @minus{} val allocate_channels :
     int -> int}
@end format
@vaindex allocate_channels

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

@format
@t{
 @minus{} val play_channel :
     ?channel:channel ->
       ?loops:int -> ?ticks:float -> chunk -> unit}
@end format
@vaindex play_channel

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

@format
@t{
 @minus{} val play_sound :
     chunk -> unit}
@end format
@vaindex play_sound

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

@format
@t{
 @minus{} val fadein_channel :
     ?channel:channel ->
       ?loops:int -> ?ticks:float -> chunk -> float -> unit}
@end format
@vaindex fadein_channel

@code{fadein_channel channel loops ticks chunck ms} :
same as @code{play_channel} but fades in a over @code{ms} seconds.

@format
@t{
 @minus{} val volume_channel :
     channel -> float}
@end format
@vaindex volume_channel

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

@format
@t{
 @minus{} val setvolume_channel :
     channel -> float -> unit}
@end format
@vaindex setvolume_channel

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

@format
@t{
 @minus{} val pause_channel :
     channel -> unit}
@end format
@vaindex pause_channel

@format
@t{
 @minus{} val resume_channel :
     channel -> unit}
@end format
@vaindex resume_channel

@format
@t{
 @minus{} val halt_channel :
     channel -> unit}
@end format
@vaindex halt_channel

@format
@t{
 @minus{} val expire_channel :
     channel -> float option -> unit}
@end format
@vaindex expire_channel

@code{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 @code{None}

@format
@t{
 @minus{} val fadeout_channel :
     channel -> float -> unit}
@end format
@vaindex fadeout_channel

@code{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.

@format
@t{
 @minus{} val playing_channel :
     channel -> bool}
@end format
@vaindex playing_channel

@format
@t{
 @minus{} val num_playing_channel :
     unit -> int}
@end format
@vaindex num_playing_channel

@format
@t{
 @minus{} val paused_channel :
     channel -> bool}
@end format
@vaindex paused_channel

@format
@t{
 @minus{} val num_paused_channel :
     unit -> int}
@end format
@vaindex num_paused_channel

@format
@t{
 @minus{} type fade_status =
  | NO_FADING
  | FADING_OUT
  | FADING_IN
}
@end format
@tyindex fade_status

The different fading types supported

@format
@t{
 @minus{} val fading_channel :
     channel -> fade_status}
@end format
@vaindex fading_channel

Query the fading status of a channel


@subsection Groups

@format
@t{
 @minus{} type group = int
}
@end format
@tyindex group

@format
@t{
 @minus{} val default_group :
     group}
@end format
@vaindex default_group

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

@format
@t{
 @minus{} val reserve_channels :
     int -> int}
@end format
@vaindex reserve_channels

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).
@*
@strong{Returns} the number of reserved channels

@format
@t{
 @minus{} val group_channel :
     channel -> group -> unit}
@end format
@vaindex group_channel

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 @code{default_group}, the tag is removed.

@format
@t{
 @minus{} val group_channels :
     from_c:channel -> to_c:channel -> group -> unit}
@end format
@vaindex group_channels

Same as above but for a range of channels.

@format
@t{
 @minus{} val group_count :
     group -> int}
@end format
@vaindex group_count

Returns the number of channels in a group. 
This is also a subtle way to get the total number of channels 
when @code{group} is @code{default_group}.

@format
@t{
 @minus{} val group_available :
     group -> channel}
@end format
@vaindex group_available

Finds the first available @code{channel} in a @code{group} of channels
@*
@strong{Raises} @code{Not_found} if none are available.

@format
@t{
 @minus{} val group_oldest :
     group -> channel}
@end format
@vaindex group_oldest

Finds the "oldest" sample playing in a @code{group} of channels

@format
@t{
 @minus{} val group_newer :
     group -> channel}
@end format
@vaindex group_newer

Finds the "most recent" (i.e. last) sample playing in a @code{group} of
channels

@format
@t{
 @minus{} val fadeout_group :
     group -> float -> unit}
@end format
@vaindex fadeout_group

@code{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.

@format
@t{
 @minus{} val halt_group :
     group -> unit}
@end format
@vaindex halt_group


@subsection Music

@format
@t{
 @minus{} type music
}
@end format
@tyindex music

@format
@t{
 @minus{} type music_kind =
  | NONE
  | CMD
  | WAV
  | MOD
  | MID
  | OGG
  | MP3
}
@end format
@tyindex music_kind

The different music types supported

@format
@t{
 @minus{} val load_music :
     string -> music}
@end format
@vaindex load_music

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

@format
@t{
 @minus{} val free_music :
     music -> unit}
@end format
@vaindex free_music

Free music previously loaded

@format
@t{
 @minus{} val play_music :
     ?loops:int -> music -> unit}
@end format
@vaindex play_music

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

@format
@t{
 @minus{} val fadein_music :
     ?loops:int -> music -> float -> unit}
@end format
@vaindex fadein_music

@code{fadein_music chunck loops music ms} :
fade in music over @code{ms} seconds, same semantics as the @code{play_music}
function

@format
@t{
 @minus{} val volume_music :
     unit -> float}
@end format
@vaindex volume_music

@format
@t{
 @minus{} val setvolume_music :
     float -> unit}
@end format
@vaindex setvolume_music

@format
@t{
 @minus{} val pause_music :
     unit -> unit}
@end format
@vaindex pause_music

@format
@t{
 @minus{} val resume_music :
     unit -> unit}
@end format
@vaindex resume_music

@format
@t{
 @minus{} val rewind_music :
     unit -> unit}
@end format
@vaindex rewind_music

@format
@t{
 @minus{} val set_music_cmd :
     string -> unit}
@end format
@vaindex set_music_cmd

Stop music and set external music playback command

@format
@t{
 @minus{} val unset_music_cmd :
     unit -> unit}
@end format
@vaindex unset_music_cmd

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

@format
@t{
 @minus{} val halt_music :
     unit -> unit}
@end format
@vaindex halt_music

@format
@t{
 @minus{} val fadeout_music :
     float -> unit}
@end format
@vaindex fadeout_music

@code{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.

@format
@t{
 @minus{} val music_type :
     music option -> music_kind}
@end format
@vaindex music_type

Find out the music format of a mixer music, or the currently
playing music, if parameter is @code{None}.

@format
@t{
 @minus{} val playing_music :
     unit -> bool}
@end format
@vaindex playing_music

@format
@t{
 @minus{} val paused_music :
     unit -> bool}
@end format
@vaindex paused_music

@format
@t{
 @minus{} val fading_music :
     unit -> fade_status}
@end format
@vaindex fading_music

Query the fading status of a music

@node Sdlgfx,
@chapter Module @code{Sdlgfx}
@moindex Sdlgfx

@section Interface
@format
@t{
 @minus{} val pixelColor :
     Sdlvideo.surface -> int -> int -> int32 -> bool}
@end format
@vaindex pixelColor

@format
@t{
 @minus{} val pixelRGBA :
     Sdlvideo.surface -> int -> int -> Sdlvideo.color -> int -> bool}
@end format
@vaindex pixelRGBA

@format
@t{
 @minus{} val rectangleColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex rectangleColor

@format
@t{
 @minus{} val rectangleRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex rectangleRGBA

@format
@t{
 @minus{} val boxColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex boxColor

@format
@t{
 @minus{} val boxRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex boxRGBA

@format
@t{
 @minus{} val lineColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex lineColor

@format
@t{
 @minus{} val lineRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex lineRGBA

@format
@t{
 @minus{} val aalineColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex aalineColor

@format
@t{
 @minus{} val aalineRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex aalineRGBA

@format
@t{
 @minus{} val circleColor :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> int32 -> bool}
@end format
@vaindex circleColor

@format
@t{
 @minus{} val circleRGBA :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> Sdlvideo.color -> int -> bool}
@end format
@vaindex circleRGBA

@format
@t{
 @minus{} val aacircleColor :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> int32 -> bool}
@end format
@vaindex aacircleColor

@format
@t{
 @minus{} val aacircleRGBA :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> Sdlvideo.color -> int -> bool}
@end format
@vaindex aacircleRGBA

@format
@t{
 @minus{} val filledCircleColor :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> int32 -> bool}
@end format
@vaindex filledCircleColor

@format
@t{
 @minus{} val filledCircleRGBA :
     Sdlvideo.surface -> Sdlvideo.rect -> int -> Sdlvideo.color -> int -> bool}
@end format
@vaindex filledCircleRGBA

@format
@t{
 @minus{} val ellipseColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex ellipseColor

@format
@t{
 @minus{} val ellipseRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex ellipseRGBA

@format
@t{
 @minus{} val aaellipseColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex aaellipseColor

@format
@t{
 @minus{} val aaellipseRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex aaellipseRGBA

@format
@t{
 @minus{} val filledEllipseColor :
     Sdlvideo.surface -> Sdlvideo.rect -> Sdlvideo.rect -> int32 -> bool}
@end format
@vaindex filledEllipseColor

@format
@t{
 @minus{} val filledEllipseRGBA :
     Sdlvideo.surface ->
       Sdlvideo.rect -> Sdlvideo.rect -> Sdlvideo.color -> int -> bool}
@end format
@vaindex filledEllipseRGBA

@format
@t{
 @minus{} val characterColor :
     Sdlvideo.surface -> Sdlvideo.rect -> char -> int32 -> bool}
@end format
@vaindex characterColor

@format
@t{
 @minus{} val characterRGBA :
     Sdlvideo.surface -> Sdlvideo.rect -> char -> Sdlvideo.color -> int -> bool}
@end format
@vaindex characterRGBA

@format
@t{
 @minus{} val stringColor :
     Sdlvideo.surface -> Sdlvideo.rect -> string -> int32 -> bool}
@end format
@vaindex stringColor

@format
@t{
 @minus{} val stringRGBA :
     Sdlvideo.surface -> Sdlvideo.rect -> string -> Sdlvideo.color -> int -> bool}
@end format
@vaindex stringRGBA

@format
@t{
 @minus{} val gfxPrimitivesSetFont :
     string -> int -> int -> unit}
@end format
@vaindex gfxPrimitivesSetFont

@format
@t{
 @minus{} val rotozoomSurface :
     Sdlvideo.surface -> float -> float -> bool -> Sdlvideo.surface}
@end format
@vaindex rotozoomSurface

@format
@t{
 @minus{} val rotozoomSurfaceXY :
     Sdlvideo.surface -> float -> float -> float -> bool -> Sdlvideo.surface}
@end format
@vaindex rotozoomSurfaceXY

@format
@t{
 @minus{} val zoomSurface :
     Sdlvideo.surface -> float -> float -> bool -> Sdlvideo.surface}
@end format
@vaindex zoomSurface


@node Types index,
@unnumbered Types index
@printindex ty
@node Exceptions index,
@unnumbered Exceptions index
@printindex ex
@node Values index,
@unnumbered Values index
@printindex va
@node Modules index,
@unnumbered Modules index
@printindex mo
@contents
@bye
