Module Graphics
Machine-independent graphics primitives.
Initializations
val open_graph : string -> unit
Show the graphics window or switch the screen to graphic mode. The graphics window is cleared and the current point is set to (0, 0). The string argument is used to pass optional information on the desired graphics mode, the graphics window size, and so on. Its interpretation is implementation-dependent. If the empty string is given, a sensible default is selected.
val size_x : unit -> int
See
Graphics.size_y
.
val size_y : unit -> int
Return the size of the graphics window. Coordinates of the screen pixels range over
0 .. size_x()-1
and0 .. size_y()-1
. Drawings outside of this rectangle are clipped, without causing an error. The origin (0,0) is at the lower left corner. Some implementation (e.g. X Windows) represent coordinates by 16-bit integers, hence wrong clipping may occur with coordinates below-32768
or above32676
.
Colors
type color
= int
A color is specified by its R, G, B components. Each component is in the range
0..255
. The three components are packed in anint
:0xRRGGBB
, whereRR
are the two hexadecimal digits for the red component,GG
for the green component,BB
for the blue component.
val rgb : int -> int -> int -> color
rgb r g b
returns the integer encoding the color with red componentr
, green componentg
, and blue componentb
.r
,g
andb
are in the range0..255
.
val set_color : color -> unit
Set the current drawing color.
val background : color
See
Graphics.foreground
.
val foreground : color
Default background and foreground colors (usually, either black foreground on a white background or white foreground on a black background).
Graphics.clear_graph
fills the screen with thebackground
color. The initial drawing color isforeground
.
Some predefined colors
Point and line drawing
val point_color : int -> int -> color
Return the color of the given point in the backing store (see "Double buffering" below).
val lineto : int -> int -> unit
Draw a line with endpoints the current point and the given point, and move the current point to the given point.
val rlineto : int -> int -> unit
Draw a line with endpoints the current point and the current point translated of the given vector, and move the current point to this point.
val curveto : (int * int) -> (int * int) -> (int * int) -> unit
curveto b c d
draws a cubic Bezier curve starting from the current point to pointd
, with control pointsb
andc
, and moves the current point tod
.
val draw_rect : int -> int -> int -> int -> unit
draw_rect x y w h
draws the rectangle with lower left corner atx,y
, widthw
and heighth
. The current point is unchanged. RaiseInvalid_argument
ifw
orh
is negative.
val draw_poly_line : (int * int) array -> unit
draw_poly_line points
draws the line that joins the points given by the array argument. The array contains the coordinates of the vertices of the polygonal line, which need not be closed. The current point is unchanged.
val draw_poly : (int * int) array -> unit
draw_poly polygon
draws the given polygon. The array contains the coordinates of the vertices of the polygon. The current point is unchanged.
val draw_segments : (int * int * int * int) array -> unit
draw_segments segments
draws the segments given in the array argument. Each segment is specified as a quadruple(x0, y0, x1, y1)
where(x0, y0)
and(x1, y1)
are the coordinates of the end points of the segment. The current point is unchanged.
val draw_arc : int -> int -> int -> int -> int -> int -> unit
draw_arc x y rx ry a1 a2
draws an elliptical arc with centerx,y
, horizontal radiusrx
, vertical radiusry
, from anglea1
to anglea2
(in degrees). The current point is unchanged. RaiseInvalid_argument
ifrx
orry
is negative.
val draw_ellipse : int -> int -> int -> int -> unit
draw_ellipse x y rx ry
draws an ellipse with centerx,y
, horizontal radiusrx
and vertical radiusry
. The current point is unchanged. RaiseInvalid_argument
ifrx
orry
is negative.
val draw_circle : int -> int -> int -> unit
draw_circle x y r
draws a circle with centerx,y
and radiusr
. The current point is unchanged. RaiseInvalid_argument
ifr
is negative.
val set_line_width : int -> unit
Set the width of points and lines drawn with the functions above. Under X Windows,
set_line_width 0
selects a width of 1 pixel and a faster, but less precise drawing algorithm than the one used whenset_line_width 1
is specified. RaiseInvalid_argument
if the argument is negative.
Text drawing
val draw_char : char -> unit
See
Graphics.draw_string
.
val draw_string : string -> unit
Draw a character or a character string with lower left corner at current position. After drawing, the current position is set to the lower right corner of the text drawn.
val set_font : string -> unit
Set the font used for drawing text. The interpretation of the argument to
set_font
is implementation-dependent.
Filling
val fill_rect : int -> int -> int -> int -> unit
fill_rect x y w h
fills the rectangle with lower left corner atx,y
, widthw
and heighth
, with the current color. RaiseInvalid_argument
ifw
orh
is negative.
val fill_poly : (int * int) array -> unit
Fill the given polygon with the current color. The array contains the coordinates of the vertices of the polygon.
val fill_arc : int -> int -> int -> int -> int -> int -> unit
Fill an elliptical pie slice with the current color. The parameters are the same as for
Graphics.draw_arc
.
val fill_ellipse : int -> int -> int -> int -> unit
Fill an ellipse with the current color. The parameters are the same as for
Graphics.draw_ellipse
.
val fill_circle : int -> int -> int -> unit
Fill a circle with the current color. The parameters are the same as for
Graphics.draw_circle
.
Images
type image
The abstract type for images, in internal representation. Externally, images are represented as matrices of colors. Images are bound to the current graphics window and should not be reused after closing this graphics window with
close_graph
.
val transp : color
In matrices of colors, this color represent a 'transparent' point: when drawing the corresponding image, all pixels on the screen corresponding to a transparent pixel in the image will not be modified, while other points will be set to the color of the corresponding point in the image. This allows superimposing an image over an existing background.
val make_image : color array array -> image
Convert the given color matrix to an image. Each sub-array represents one horizontal line. All sub-arrays must have the same length; otherwise, exception
Graphic_failure
is raised.
val draw_image : image -> int -> int -> unit
Draw the given image with lower left corner at the given point.
val get_image : int -> int -> int -> int -> image
Capture the contents of a rectangle on the screen as an image. The parameters are the same as for
Graphics.fill_rect
.
val create_image : int -> int -> image
create_image w h
returns a new imagew
pixels wide andh
pixels tall, to be used in conjunction withblit_image
. The initial image contents are random, except that no point is transparent.
val blit_image : image -> int -> int -> unit
blit_image img x y
copies screen pixels into the imageimg
, modifyingimg
in-place. The pixels copied are those inside the rectangle with lower left corner atx,y
, and width and height equal to those of the image. Pixels that were transparent inimg
are left unchanged.
Mouse and keyboard events
type status
=
{
}
To report events.
type event
=
|
Button_down
A mouse button is pressed
|
Button_up
A mouse button is released
|
Key_pressed
A key is pressed
|
Mouse_motion
The mouse is moved
|
Poll
Don't wait; return immediately
To specify events to wait for.
val wait_next_event : event list -> status
Wait until one of the events specified in the given event list occurs, and return the status of the mouse and keyboard at that time. If
Poll
is given in the event list, return immediately with the current status. If the mouse cursor is outside of the graphics window, themouse_x
andmouse_y
fields of the event are outside the range0..size_x()-1, 0..size_y()-1
. Keypresses are queued, and dequeued one by one when theKey_pressed
event is specified and thePoll
event is not specified.
val loop_at_exit : event list -> (status -> unit) -> unit
Loop before exiting the program, the list given as argument is the list of handlers and the events on which these handlers are called. To exit cleanly the loop, the handler should raise Exit. Any other exception will be propagated outside of the loop.
- since
- 4.01
Mouse and keyboard polling
val mouse_pos : unit -> int * int
Return the position of the mouse cursor, relative to the graphics window. If the mouse cursor is outside of the graphics window,
mouse_pos()
returns a point outside of the range0..size_x()-1, 0..size_y()-1
.
Sound
Double buffering
val auto_synchronize : bool -> unit
By default, drawing takes place both on the window displayed on screen, and in a memory area (the 'backing store'). The backing store image is used to re-paint the on-screen window when necessary.
To avoid flicker during animations, it is possible to turn off on-screen drawing, perform a number of drawing operations in the backing store only, then refresh the on-screen window explicitly.
auto_synchronize false
turns on-screen drawing off. All subsequent drawing commands are performed on the backing store only.auto_synchronize true
refreshes the on-screen window from the backing store (as persynchronize
), then turns on-screen drawing back on. All subsequent drawing commands are performed both on screen and in the backing store.The default drawing mode corresponds to
auto_synchronize true
.
val synchronize : unit -> unit
Synchronize the backing store and the on-screen window, by copying the contents of the backing store onto the graphics window.
val display_mode : bool -> unit
Set display mode on or off. When turned on, drawings are done in the graphics window; when turned off, drawings do not affect the graphics window. This occurs independently of drawing into the backing store (see the function
Graphics.remember_mode
below). Default display mode is on.
val remember_mode : bool -> unit
Set remember mode on or off. When turned on, drawings are done in the backing store; when turned off, the backing store is unaffected by drawings. This occurs independently of drawing onto the graphics window (see the function
Graphics.display_mode
above). Default remember mode is on.