Module Sdl.Video

module Video: sig .. end

Flags that determine properties of video surfaces

type surface 

A surface is a software or hardware framebuffer

val surface_pixels : surface -> Sdl.byte_array

Get a byte_array containing the raw pixel data. Non-copying

val surface_width : surface -> int

Get the surface width in pixels

val surface_height : surface -> int

Get the surface height in pixels

val surface_flags : surface -> video_flag list

Get a list of the surface flags

val surface_bpp : surface -> int

Get the number bits per pixel for the surface

val surface_rmask : surface -> int

Get the mask for the red color component for each pixel for the surface

val surface_gmask : surface -> int

Get the mask for the green color component for each pixel for the surface

val surface_bmask : surface -> int

Get the mask for the blue color component for each pixel for the surface

val surface_amask : surface -> int

Get the mask for the alpha component for each pixel for the surface

val free_surface : surface -> unit

Free a surface. Note: after freeing a surface it cannot be used again.

val must_lock : surface -> bool

True if the surface passed in should be locked, else false

val lock_surface : surface -> unit

lock_surface () sets up a surface for directly accessing the pixels. Between calls to lock_surface () and unlock_surface (), you can write to and read from (surface_pixels _), using the pixel format stored in (surface_format _). Once you are done accessing the surface, you should use unlock_surface () to release it. Not all surfaces require locking. If (must_lock surface) is false, then you can read and write to the surface at any time, and the pixel format of the surface will not change. No operating system or library calls should be made between lock/unlock pairs, as critical system locks may be held during this time. It should be noted, that since SDL 1.1.8 surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have a match unlock.

val unlock_surface : surface -> unit

Unlock surface

val video_mode_ok : int -> int -> int -> video_flag list -> bool

video_mode_ok width height bpp_flags -> true/false video_mode_ok returns false if the requested mode is not supported under any bit depth, or returns true if a closest available mode with the given width, height and requested surface flags exists (see set_video_mode). You can usually request any bpp you want when setting the video mode and SDL will emulate that color depth with a shadow video surface. The arguments to video_mode_ok are the same ones you would pass to set_video_mode

val set_video_mode : int -> int -> int -> video_flag list -> surface

set_video_mode width height bpp flags -> surface Set up a video mode with the specified width, height and bitsperpixel. If bpp is 0, it is treated as the current display bits per pixel. The flags parameter is the same as the flags field of the SDL surface structure. A list containing one or more of the following values are valid.

• SWSURFACE Create the video surface in system memory
• HWSURFACE Create the video surface in video memory
• ASYNCBLIT Enables the use of asynchronous updates of the display surface. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.
• ANYFORMAT Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface. Passing ANYFORMAT prevents this and causes SDL to use the video surface, regardless of its pixel depth.
• HWPALETTE Give SDL exclusive palette access. Without this flag you may not always get the the colors you request with SDL_SetColors or SDL_SetPalette.
• DOUBLEBUF Enable hardware double buffering; only valid with HWSURFACE. Calling flip will flip the buffers and update the screen. All drawing will take place on the surface that is not displayed at the moment. If double buffering could not be enabled then flip will just perform a update_rect on the entire screen.
• FULLSCREEN SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason), the next higher resolution will be used and the display window centered on a black background.
• OPENGL Create an OpenGL rendering context. You should have previously set OpenGL video attributes with set_attribute.
• OPENGLBLIT Create an OpenGL rendering context, like above, but allow normal blitting operations. The screen (2D) surface may have an alpha channel, and update_rects must be used for updating changes to the screen surface.
• RESIZABLE Create a resizable window. When the window is resized by the user a VIDEORESIZE event is generated and set_video_mode can be called again with the new size.
• NOFRAME If possible, NOFRAME causes SDL to create a window with no title bar or frame decoration. Fullscreen modes automatically have this flag set. Note: Whatever flags set_video_mode could satisfy are set in the flags member of the returned surface. Note: The bpp parameter is the number of bits per pixel, so a bpp of 24 uses the packed representation of 3 bytes/pixel. For the more common 4 bytes/pixel mode, use a bpp of 32. Somewhat oddly, both 15 and 16 will request a 2 bytes/pixel mode, but different pixel formats. Note: Use SWSURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. When you use hardware surfaces (HWSURFACE), SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them. This can cause a major performance hit. (Be aware that you may request a hardware surface, but receive a software surface. Many platforms can only provide a hardware surface when using FULLSCREEN.) HWSURFACE is best used when the surfaces you'll be blitting can also be stored in video memory. Note: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment variables "SDL_VIDEO_CENTERED=center" or "SDL_VIDEO_WINDOW_POS=x,y". You can set them via putenv. The framebuffer surface; if it fails it raises SDL_failure. The surface returned is freed by quit and should not be freed by the caller. Note: This rule includes consecutive calls to set_video_mode (i.e. resize or rez change) - the pre-existing surface will be released automatically.

val create_rgb_surface : video_flag list -> int -> int -> int -> surface

create_rgb_surface video_flag_list width height bitsperpixel -> surface Allocate an empty surface (must be called after set_video_mode) If bitsPerPixel is 8 an empty palette is allocated for the surface, otherwise a 'packed-pixel' pixel format is created using internal RGBA masks based on standard 15,16,24 and 32 bitperpixel formats, and taking platform endianness into account. The flags specifies the type of surface that should be created, it is alist containing one or more of the following possible values.

• SWSURFACE SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.
• HWSURFACE SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated).
• SRCCOLORKEY This flag turns on color keying for blits from this surface. If HWSURFACE is also specified and color keyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. If the screen is a hardware surface and color keyed blits are hardware-accelerated then the HWSURFACE flag will be set. Use set_color_key to set or clear this flag after surface creation.
• SRCALPHA This flag turns on alpha-blending for blits from this surface. If HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. If the screen is a hardware surface and alpha-blending blits are hardware-accelerated then the HWSURFACE flag will be set. Use set_alpha to set or clear this flag after surface creation.

val load_bmp : string -> surface

load_bmp file -> surface Loads a surface from a named Windows BMP file. Note: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect).

val save_bmp : surface -> string -> unit

save_bmp surface file Saves the SDL_Surface surface as a Windows BMP file named file

val set_color_key : surface -> video_flag list -> int32 -> unit

set_color_key surf flag key Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration. RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value). The key must be of the same pixel format as the surface, map_rgb is often useful for obtaining an acceptable value. If flag is SRCCOLORKEY then key is the transparent pixel value in the source image of a blit. If flag contains RLEACCEL then the surface will be draw using RLE acceleration when drawn with blit_surface. The surface will actually be encoded for RLE acceleration the first time blit_surface or display_format is called on the surface.

val set_alpha : surface -> video_flag list -> int -> unit

set_alpha surf flag alpha Note: This function and the semantics of SDL alpha blending have changed since version 1.1.4. Up until version 1.1.5, an alpha value of 0 was considered opaque and a value of 255 was considered transparent. This has now been inverted: 0 (ALPHA_TRANSPARENT) is now considered transparent and 255 (SALPHA_OPAQUE) is now considered opaque.

set_alpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.

The surface parameter specifies which surface whose alpha attributes you wish to adjust. flags is used to specify whether alpha blending should be used (SSRCALPHA) and whether the surface should use RLE acceleration for blitting (RLEACCEL). flags can contain both of these two options, one of these options or none. If SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface. The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with RLEACCEL.

Note: The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.

Alpha affects surface blitting in the following ways:

• RGBA->RGB with SRCALPHA The source is alpha-blended with the destination, using the alpha channel. SRCCOLORKEY and the per-surface alpha are ignored.
• RGBA->RGB without SRCALPHA The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
• RGB->RGBA with SRCALPHA The source is alpha-blended with the destination using the per-surface alpha value. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied. The alpha channel of the copied pixels is set to opaque.
• RGB->RGBA without SRCALPHA The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
• RGBA->RGBA with SRCALPHA The source is alpha-blended with the destination using the source alpha channel. The alpha channel in the destination surface is left untouched. SRCCOLORKEY is ignored.
• RGBA->RGBA without SRCALPHA The RGBA data is copied to the destination surface. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
• RGB->RGB with SRCALPHA The source is alpha-blended with the destination using the per-surface alpha value. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
• RGB->RGB without SRCALPHA The RGB data is copied from the source. If SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied. Note: When blitting, the presence or absence of SRCALPHA is relevant only on the source surface, not the destination. Note: Note that RGBA->RGBA blits (with SRCALPHA set) keep the alpha of the destination surface. This means that you cannot compose two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask. Note: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available.

val set_clipping : surface -> int -> int -> int -> int -> unit

set_clipping surf top left bottom right Sets the clipping rectangle for a surface. When this surface is the destination of a blit, only the area within the clip rectangle will be drawn into. The rectangle pointed to by the coordinates (top left bottom right) will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall outside the edges of the surface.

val disable_clipping : surface -> unit

disable_clipping surface Disables clipping to the clipping rectangle set for a surface

val display_format : surface -> surface

display_format src_surface -> dest_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. It calls convert_surface. If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function. If you want an alpha channel, see display_format_alpha.

val get_rgb : surface -> int32 -> int * int * int

get_rgb surface -> pixel -> red * green * blue Get RGB component values from a pixel stored in the specified pixel format. This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).

val get_rgba : surface -> int32 -> int * int * int * int

get_rgba surface -> pixel -> red * green * blue * alpha Get RGBA component values from a pixel stored in the specified pixel format. This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]). If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque).

val map_rgb : surface -> int -> int -> int -> int32

map_rgb surface -> red -> green -> blue -> pixel Maps the RGB color value to the specified pixel format and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

val map_rgba : surface -> int -> int -> int -> int -> int32

map_rgba surface -> red -> green -> blue -> alpha -> pixel Maps the RGBA color value to the specified pixel format and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

Rectangle type, used for clipping and blitting operations

val fill_surface : surface -> int32 -> unit

fill_surface surface pixel Fills the surface with pixels of the given color

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

fill_rect surface dstrect pixel This function performs a fast fill of the given rectangle with color. The color should be a pixel of the format used by the surface, and can be generated by the map_rgb or map_rgba functions. If the color value contains an alpha value then the destination is simply "filled" with that alpha information, no blending takes place. If there is a clip rectangle set on the destination (set via set_clip_rect), then this function will clip based on the intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually filled. If you call this on the video surface (ie: the value of get_video_surface ()) you may have to update the video surface to see the result. This can happen if you are using a shadowed surface that is not double buffered in Windows XP using build 1.2.9.

val update_surface : surface -> unit

update_surface surface Makes sure the screen is updated

val update_rect : surface -> int -> int -> int -> int -> unit

update_rect surface left top width height Makes sure the given area is updated on the given screen. The rectangle must be confined within the screen boundaries (no clipping is done). This function should not be called while 'screen' is locked (lock_surface).

val update_rects : surface -> rect array -> unit

update_rects surface rect_array 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). WARNING : passing rectangles not confined within the screen boundaries to this function can cause very nasty crashes, at least with SDL 1.2.8, at least in Windows and Linux. This function should not be called while screen is locked. Note: It is advised to call this function only once per frame, since each call has some processing overhead. This is no restriction since you can pass any number of rectangles each time. The rectangles are not automatically merged or checked for overlap. In general, the programmer can use his or her knowledge about his or her particular rectangles to merge them in an efficient way, to avoid overdraw.

val flip : surface -> unit

flip surface On hardware that supports double-buffering, 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_surface screen) The DOUBLEBUF flag must have been passed to set_video_mode, when setting the video mode for this function to perform hardware flipping.

val blit_surface : surface ->
       rect option -> surface -> rect option -> unit

blit_surface source_surface srcrect dest_surface dstrect This performs a fast blit from the source surface to the destination surface. The width and height in srcrect determine the size of the copied rectangle. Only the position is used in the dstrect (the width and height are ignored). If srcrect is None, the entire surface is copied. If dstrect is None, then the destination position (upper left corner) is (0, 0). The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified). The blit function should not be called on a locked surface. I.e. when you use your own drawing functions you may need to lock a surface, but this is not the case with blit_surface. Like most surface manipulation functions in SDL, it should not be used together with OpenGL. The results of blitting operations vary greatly depending on whether SRCAPLHA is set or not. See set_alpha for an explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting..

Color type

val set_colors : surface -> color array -> int -> int -> bool

set_colors surf colors firstcolor ncolors Sets a portion of the colormap for the given 8-bit surface.

When surface is the surface associated with the current display, the display colormap will be updated with the requested colors. If HWPALETTE was set in set_video_mode flags, set_colors will always return true, and the palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.

The color components of a color structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.

Palettized (8-bit) screen surfaces with the HWPALETTE flag have two palettes, a logical palette that is used for mapping blits to/from the surface and a physical palette (that determines how the hardware will map the colors to the display). set_colors modifies both palettes (if present), and is equivalent to calling set_palette with the flags set to [LOGPAL ; PHYSPAL].

val show_cursor : bool -> unit

show_cursor true\false Toggle whether or not the cursor is shown on the screen.

val warp_mouse : int -> int -> unit

warp_mouse x y Set the position of the mouse cursor (generates a mouse motion event).

val string_of_pixels : surface -> string

string_of_pixels surface -> string Returns a copy of the raw pixel data in a surface as a string.