OCamlSDL 0.9.1 : Sdlvideo

# Module Sdlvideo

    module Sdlvideo: sig .. end

Module for video manipulations

    exception Video_exn of string

### Rectangles

`type ``rect = {`

`` | `mutable r_x : `int`;`
`` | `mutable r_y : `int`;`
`` | `mutable r_w : `int`;`
`` | `mutable 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

### 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

    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.

### 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 : `surface_flags list`;`
`` | `w : `int`;` | `(*` | width | `*)`
`` | `h : `int`;` | `(*` | height | `*)`
`` | `pitch : `int`;` | `(*` | pitch | `*)`
`` | `clip_rect : `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`

### 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`.
Returns the current display `surface`
`bpp` : if omited, it is treated as the current display bits per pixel

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

`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`

### 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

#### 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`.
`flag` : defaults to LOGPHYSPAL
`firstcolor` : where to blit the color array given as argument (defaults to 0)

#### 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

### 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

### 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`

### 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.

### 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.

### 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`

### 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.

### 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`.
`src_rect` : the width and height determine the size of the copied rectangle. If omitted, the entire surface is copied.
`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.
`alpha` : if `true`, include an alpha channel in the new surface