1Graphics(3) OCaml library Graphics(3)
2
6 Graphics - Machine-independent graphics primitives.
7
9 Module Graphics
10
12 Module Graphics
13 : sig end
14 Machine-independent graphics primitives.
17 exception Graphic_failure of string
24 Raised by the functions below when they encounter an error.
27 === Initializations ===
32 val open_graph : string -> unit
35 Show the graphics window or switch the screen to graphic mode. The
37 graphics window is cleared and the current point is set to (0, 0). The
38 string argument is used to pass optional information on the desired
39 graphics mode, the graphics window size, and so on. Its interpretation
40 is implementation-dependent. If the empty string is given, a sensible
41 default is selected.
42 val close_graph : unit -> unit
46 Delete the graphics window or switch the screen back to text mode.
48 val set_window_title : string -> unit
52 Set the title of the graphics window.
54 val resize_window : int -> int -> unit
58 Resize and erase the graphics window.
60 val clear_graph : unit -> unit
64 Erase the graphics window.
66 val size_x : unit -> int
70 See Graphics.size_y .
72 val size_y : unit -> int
76 Return the size of the graphics window. Coordinates of the screen pix‐
78 els range over 0 .. size_x()-1 and 0 .. size_y()-1 . Drawings outside
79 of this rectangle are clipped, without causing an error. The origin
80 (0,0) is at the lower left corner. Some implementation (e.g. X Win‐
81 dows) represent coordinates by 16-bit integers, hence wrong clipping
82 may occur with coordinates below -32768 or above 32676 .
83 === Colors ===
88 type color = int
91 A color is specified by its R, G, B components. Each component is in
94 the range 0..255 . The three components are packed in an int : 0xRRGGBB
95 , where RR are the two hexadecimal digits for the red component, GG for
96 the green component, BB for the blue component.
97 val rgb : int -> int -> int -> color
101 rgb r g b returns the integer encoding the color with red component r ,
104 green component g , and blue component b . r , g and b are in the
105 range 0..255 .
106 val set_color : color -> unit
110 Set the current drawing color.
112 val background : color
116 See Graphics.foreground .
118 val foreground : color
122 Default background and foreground colors (usually, either black fore‐
124 ground on a white background or white foreground on a black back‐
125 ground). Graphics.clear_graph fills the screen with the background
126 color. The initial drawing color is foreground .
127 === Some predefined colors ===
132 val black : color
135 val white : color
140 val red : color
145 val green : color
150 val blue : color
155 val yellow : color
160 val cyan : color
165 val magenta : color
170 === Point and line drawing ===
176 val plot : int -> int -> unit
179 Plot the given point with the current drawing color.
181 val plots : (int * int) array -> unit
185 Plot the given points with the current drawing color.
187 val point_color : int -> int -> color
191 Return the color of the given point in the backing store (see "Double
193 buffering" below).
194 val moveto : int -> int -> unit
198 Position the current point.
200 val rmoveto : int -> int -> unit
204 rmoveto dx dy translates the current point by the given vector.
207 val current_x : unit -> int
211 Return the abscissa of the current point.
213 val current_y : unit -> int
217 Return the ordinate of the current point.
219 val current_point : unit -> int * int
223 Return the position of the current point.
225 val lineto : int -> int -> unit
229 Draw a line with endpoints the current point and the given point, and
231 move the current point to the given point.
232 val rlineto : int -> int -> unit
236 Draw a line with endpoints the current point and the current point
238 translated of the given vector, and move the current point to this
239 point.
240 val curveto : int * int -> int * int -> int * int -> unit
244 curveto b c d draws a cubic Bezier curve starting from the current
247 point to point d , with control points b and c , and moves the current
248 point to d .
249 val draw_rect : int -> int -> int -> int -> unit
253 draw_rect x y w h draws the rectangle with lower left corner at x,y ,
256 width w and height h . The current point is unchanged. Raise
257 Invalid_argument if w or h is negative.
258 val draw_poly_line : (int * int) array -> unit
262 draw_poly_line points draws the line that joins the points given by the
265 array argument. The array contains the coordinates of the vertices of
266 the polygonal line, which need not be closed. The current point is
267 unchanged.
268 val draw_poly : (int * int) array -> unit
272 draw_poly polygon draws the given polygon. The array contains the
275 coordinates of the vertices of the polygon. The current point is
276 unchanged.
277 val draw_segments : (int * int * int * int) array -> unit
281 draw_segments segments draws the segments given in the array argument.
284 Each segment is specified as a quadruple (x0, y0, x1, y1) where (x0,
285 y0) and (x1, y1) are the coordinates of the end points of the segment.
286 The current point is unchanged.
287 val draw_arc : int -> int -> int -> int -> int -> int -> unit
291 draw_arc x y rx ry a1 a2 draws an elliptical arc with center x,y , hor‐
294 izontal radius rx , vertical radius ry , from angle a1 to angle a2 (in
295 degrees). The current point is unchanged. Raise Invalid_argument if rx
296 or ry is negative.
297 val draw_ellipse : int -> int -> int -> int -> unit
301 draw_ellipse x y rx ry draws an ellipse with center x,y , horizontal
304 radius rx and vertical radius ry . The current point is unchanged.
305 Raise Invalid_argument if rx or ry is negative.
306 val draw_circle : int -> int -> int -> unit
310 draw_circle x y r draws a circle with center x,y and radius r . The
313 current point is unchanged. Raise Invalid_argument if r is negative.
314 val set_line_width : int -> unit
318 Set the width of points and lines drawn with the functions above.
320 Under X Windows, set_line_width 0 selects a width of 1 pixel and a
321 faster, but less precise drawing algorithm than the one used when
322 set_line_width 1 is specified. Raise Invalid_argument if the argument
323 is negative.
324 === Text drawing ===
329 val draw_char : char -> unit
332 See Graphics.draw_string .
334 val draw_string : string -> unit
338 Draw a character or a character string with lower left corner at cur‐
340 rent position. After drawing, the current position is set to the lower
341 right corner of the text drawn.
342 val set_font : string -> unit
346 Set the font used for drawing text. The interpretation of the argument
348 to set_font is implementation-dependent.
349 val set_text_size : int -> unit
353 Set the character size used for drawing text. The interpretation of
355 the argument to set_text_size is implementation-dependent.
356 val text_size : string -> int * int
360 Return the dimensions of the given text, if it were drawn with the cur‐
362 rent font and size.
363 === Filling ===
368 val fill_rect : int -> int -> int -> int -> unit
371 fill_rect x y w h fills the rectangle with lower left corner at x,y ,
374 width w and height h , with the current color. Raise Invalid_argument
375 if w or h is negative.
376 val fill_poly : (int * int) array -> unit
380 Fill the given polygon with the current color. The array contains the
382 coordinates of the vertices of the polygon.
383 val fill_arc : int -> int -> int -> int -> int -> int -> unit
387 Fill an elliptical pie slice with the current color. The parameters are
389 the same as for Graphics.draw_arc .
390 val fill_ellipse : int -> int -> int -> int -> unit
394 Fill an ellipse with the current color. The parameters are the same as
396 for Graphics.draw_ellipse .
397 val fill_circle : int -> int -> int -> unit
401 Fill a circle with the current color. The parameters are the same as
403 for Graphics.draw_circle .
404 === Images ===
409 type image
412 The abstract type for images, in internal representation. Externally,
415 images are represented as matrices of colors.
416 val transp : color
420 In matrices of colors, this color represent a 'transparent' point: when
422 drawing the corresponding image, all pixels on the screen corresponding
423 to a transparent pixel in the image will not be modified, while other
424 points will be set to the color of the corresponding point in the
425 image. This allows superimposing an image over an existing background.
426 val make_image : color array array -> image
430 Convert the given color matrix to an image. Each sub-array represents
432 one horizontal line. All sub-arrays must have the same length; other‐
433 wise, exception Graphic_failure is raised.
434 val dump_image : image -> color array array
438 Convert an image to a color matrix.
440 val draw_image : image -> int -> int -> unit
444 Draw the given image with lower left corner at the given point.
446 val get_image : int -> int -> int -> int -> image
450 Capture the contents of a rectangle on the screen as an image. The
452 parameters are the same as for Graphics.fill_rect .
453 val create_image : int -> int -> image
457 create_image w h returns a new image w pixels wide and h pixels tall,
460 to be used in conjunction with blit_image . The initial image contents
461 are random, except that no point is transparent.
462 val blit_image : image -> int -> int -> unit
466 blit_image img x y copies screen pixels into the image img , modifying
469 img in-place. The pixels copied are those inside the rectangle with
470 lower left corner at x,y , and width and height equal to those of the
471 image. Pixels that were transparent in img are left unchanged.
472 === Mouse and keyboard events ===
477 type status = {
480 mouse_x : int ; (* X coordinate of the mouse
481 *)
482 mouse_y : int ; (* Y coordinate of the mouse
483 *)
484 button : bool ; (* true if a mouse button is pressed
485 *)
486 keypressed : bool ; (* true if a key has been pressed
487 *)
488 key : char ; (* the character for the key pressed
489 *)
490 }
491 To report events.
494 type event =
497 | Button_down (* A mouse button is pressed
498 *)
499 | Button_up (* A mouse button is released
500 *)
501 | Key_pressed (* A key is pressed
502 *)
503 | Mouse_motion (* The mouse is moved
504 *)
505 | Poll (* Don't wait; return immediately
506 *)
507 To specify events to wait for.
510 val wait_next_event : event list -> status
514 Wait until one of the events specified in the given event list occurs,
516 and return the status of the mouse and keyboard at that time. If Poll
517 is given in the event list, return immediately with the current status.
518 If the mouse cursor is outside of the graphics window, the mouse_x and
519 mouse_y fields of the event are outside the range 0..size_x()-1,
520 0..size_y()-1 . Keypresses are queued, and dequeued one by one when the
521 Key_pressed event is specified and the Poll event is not specified.
522 val loop_at_exit : event list -> (status -> unit) -> unit
526 Loop before exiting the program, the list given as argument is the list
528 of handlers and the events on which these handlers are called. To exit
529 cleanly the loop, the handler should raise Exit. Any other exception
530 will be propagated outside of the loop.
531 Since 4.01
534 === Mouse and keyboard polling ===
539 val mouse_pos : unit -> int * int
542 Return the position of the mouse cursor, relative to the graphics win‐
544 dow. If the mouse cursor is outside of the graphics window, mouse_pos()
545 returns a point outside of the range 0..size_x()-1, 0..size_y()-1 .
546 val button_down : unit -> bool
550 Return true if the mouse button is pressed, false otherwise.
552 val read_key : unit -> char
556 Wait for a key to be pressed, and return the corresponding character.
558 Keypresses are queued.
559 val key_pressed : unit -> bool
563 Return true if a keypress is available; that is, if read_key would not
565 block.
566 === Sound ===
571 val sound : int -> int -> unit
574 sound freq dur plays a sound at frequency freq (in hertz) for a dura‐
577 tion dur (in milliseconds).
578 === Double buffering ===
583 val auto_synchronize : bool -> unit
586 By default, drawing takes place both on the window displayed on screen,
588 and in a memory area (the 'backing store'). The backing store image is
589 used to re-paint the on-screen window when necessary.
590 To avoid flicker during animations, it is possible to turn off
592 on-screen drawing, perform a number of drawing operations in the back‐
593 ing store only, then refresh the on-screen window explicitly.
594 auto_synchronize false turns on-screen drawing off. All subsequent
597 drawing commands are performed on the backing store only.
598 auto_synchronize true refreshes the on-screen window from the backing
601 store (as per synchronize ), then turns on-screen drawing back on. All
602 subsequent drawing commands are performed both on screen and in the
603 backing store.
604 The default drawing mode corresponds to auto_synchronize true .
606 val synchronize : unit -> unit
610 Synchronize the backing store and the on-screen window, by copying the
612 contents of the backing store onto the graphics window.
613 val display_mode : bool -> unit
617 Set display mode on or off. When turned on, drawings are done in the
619 graphics window; when turned off, drawings do not affect the graphics
620 window. This occurs independently of drawing into the backing store
621 (see the function Graphics.remember_mode below). Default display mode
622 is on.
623 val remember_mode : bool -> unit
627 Set remember mode on or off. When turned on, drawings are done in the
629 backing store; when turned off, the backing store is unaffected by
630 drawings. This occurs independently of drawing onto the graphics win‐
631 dow (see the function Graphics.display_mode above). Default remember
632 mode is on.
633OCamldoc 2019-02-02 Graphics(3)