1Graphics(3)                      OCaml library                     Graphics(3)
2
3
4

NAME

6       Graphics - Machine-independent graphics primitives.
7

Module

9       Module   Graphics
10

Documentation

12       Module Graphics
13        : sig end
14
15
16       Machine-independent graphics primitives.
17
18
19
20
21
22
23       exception Graphic_failure of string
24
25
26       Raised by the functions below when they encounter an error.
27
28
29
30
31   Initializations
32       val open_graph : string -> unit
33
34       Show  the  graphics  window  or switch the screen to graphic mode.  The
35       graphics window is cleared and the current point is set to (0, 0).  The
36       string  argument  is  used  to pass optional information on the desired
37       graphics mode, the graphics window size, and so on. Its  interpretation
38       is  implementation-dependent.  If the empty string is given, a sensible
39       default is selected.
40
41
42
43       val close_graph : unit -> unit
44
45       Delete the graphics window or switch the screen back to text mode.
46
47
48
49       val set_window_title : string -> unit
50
51       Set the title of the graphics window.
52
53
54
55       val resize_window : int -> int -> unit
56
57       Resize and erase the graphics window.
58
59
60
61       val clear_graph : unit -> unit
62
63       Erase the graphics window.
64
65
66
67       val size_x : unit -> int
68
69       See Graphics.size_y .
70
71
72
73       val size_y : unit -> int
74
75       Return the size of the graphics window. Coordinates of the screen  pix‐
76       els  range over 0 .. size_x()-1 and 0 .. size_y()-1 .  Drawings outside
77       of this rectangle are clipped, without causing  an  error.  The  origin
78       (0,0)  is  at  the lower left corner.  Some implementation (e.g. X Win‐
79       dows) represent coordinates by 16-bit integers,  hence  wrong  clipping
80       may occur with coordinates below -32768 or above 32676 .
81
82
83
84
85   Colors
86       type color = int
87
88
89       A  color  is  specified by its R, G, B components. Each component is in
90       the range 0..255 . The three components are packed in an int : 0xRRGGBB
91       , where RR are the two hexadecimal digits for the red component, GG for
92       the green component, BB for the blue component.
93
94
95
96       val rgb : int -> int -> int -> color
97
98
99       rgb r g b returns the integer encoding the color with red component r ,
100       green  component  g  ,  and  blue component b .  r , g and b are in the
101       range 0..255 .
102
103
104
105       val set_color : color -> unit
106
107       Set the current drawing color.
108
109
110
111       val background : color
112
113       See Graphics.foreground .
114
115
116
117       val foreground : color
118
119       Default background and foreground colors (usually, either  black  fore‐
120       ground  on  a  white  background  or  white foreground on a black back‐
121       ground).  Graphics.clear_graph fills the  screen  with  the  background
122       color.  The initial drawing color is foreground .
123
124
125
126
127   Some predefined colors
128       val black : color
129
130
131
132
133       val white : color
134
135
136
137
138       val red : color
139
140
141
142
143       val green : color
144
145
146
147
148       val blue : color
149
150
151
152
153       val yellow : color
154
155
156
157
158       val cyan : color
159
160
161
162
163       val magenta : color
164
165
166
167
168
169   Point and line drawing
170       val plot : int -> int -> unit
171
172       Plot the given point with the current drawing color.
173
174
175
176       val plots : (int * int) array -> unit
177
178       Plot the given points with the current drawing color.
179
180
181
182       val point_color : int -> int -> color
183
184       Return  the  color of the given point in the backing store (see "Double
185       buffering" below).
186
187
188
189       val moveto : int -> int -> unit
190
191       Position the current point.
192
193
194
195       val rmoveto : int -> int -> unit
196
197
198       rmoveto dx dy translates the current point by the given vector.
199
200
201
202       val current_x : unit -> int
203
204       Return the abscissa of the current point.
205
206
207
208       val current_y : unit -> int
209
210       Return the ordinate of the current point.
211
212
213
214       val current_point : unit -> int * int
215
216       Return the position of the current point.
217
218
219
220       val lineto : int -> int -> unit
221
222       Draw a line with endpoints the current point and the given  point,  and
223       move the current point to the given point.
224
225
226
227       val rlineto : int -> int -> unit
228
229       Draw  a  line  with  endpoints  the current point and the current point
230       translated of the given vector, and move  the  current  point  to  this
231       point.
232
233
234
235       val curveto : int * int -> int * int -> int * int -> unit
236
237
238       curveto  b  c  d  draws  a cubic Bezier curve starting from the current
239       point to point d , with control points b and c , and moves the  current
240       point to d .
241
242
243
244       val draw_rect : int -> int -> int -> int -> unit
245
246
247       draw_rect  x  y w h draws the rectangle with lower left corner at x,y ,
248       width w and  height  h  .   The  current  point  is  unchanged.   Raise
249       Invalid_argument if w or h is negative.
250
251
252
253       val draw_poly_line : (int * int) array -> unit
254
255
256       draw_poly_line points draws the line that joins the points given by the
257       array argument.  The array contains the coordinates of the vertices  of
258       the  polygonal  line,  which  need not be closed.  The current point is
259       unchanged.
260
261
262
263       val draw_poly : (int * int) array -> unit
264
265
266       draw_poly polygon draws the given  polygon.   The  array  contains  the
267       coordinates  of  the  vertices  of  the  polygon.  The current point is
268       unchanged.
269
270
271
272       val draw_segments : (int * int * int * int) array -> unit
273
274
275       draw_segments segments draws the segments given in the array  argument.
276       Each  segment  is  specified as a quadruple (x0, y0, x1, y1) where (x0,
277       y0) and (x1, y1) are the coordinates of the end points of the  segment.
278       The current point is unchanged.
279
280
281
282       val draw_arc : int -> int -> int -> int -> int -> int -> unit
283
284
285       draw_arc x y rx ry a1 a2 draws an elliptical arc with center x,y , hor‐
286       izontal radius rx , vertical radius ry , from angle a1 to angle a2  (in
287       degrees). The current point is unchanged.  Raise Invalid_argument if rx
288       or ry is negative.
289
290
291
292       val draw_ellipse : int -> int -> int -> int -> unit
293
294
295       draw_ellipse x y rx ry draws an ellipse with center  x,y  ,  horizontal
296       radius  rx  and  vertical  radius ry .  The current point is unchanged.
297       Raise Invalid_argument if rx or ry is negative.
298
299
300
301       val draw_circle : int -> int -> int -> unit
302
303
304       draw_circle x y r draws a circle with center x,y and  radius  r  .  The
305       current point is unchanged.  Raise Invalid_argument if r is negative.
306
307
308
309       val set_line_width : int -> unit
310
311       Set  the  width  of  points  and  lines drawn with the functions above.
312       Under X Windows, set_line_width 0 selects a width  of  1  pixel  and  a
313       faster,  but  less  precise  drawing  algorithm  than the one used when
314       set_line_width 1 is specified.  Raise Invalid_argument if the  argument
315       is negative.
316
317
318
319
320   Text drawing
321       val draw_char : char -> unit
322
323       See Graphics.draw_string .
324
325
326
327       val draw_string : string -> unit
328
329       Draw  a  character or a character string with lower left corner at cur‐
330       rent position. After drawing, the current position is set to the  lower
331       right corner of the text drawn.
332
333
334
335       val set_font : string -> unit
336
337       Set the font used for drawing text.  The interpretation of the argument
338       to set_font is implementation-dependent.
339
340
341
342       val set_text_size : int -> unit
343
344       Set the character size used for drawing text.   The  interpretation  of
345       the argument to set_text_size is implementation-dependent.
346
347
348
349       val text_size : string -> int * int
350
351       Return the dimensions of the given text, if it were drawn with the cur‐
352       rent font and size.
353
354
355
356
357   Filling
358       val fill_rect : int -> int -> int -> int -> unit
359
360
361       fill_rect x y w h fills the rectangle with lower left corner at  x,y  ,
362       width  w and height h , with the current color.  Raise Invalid_argument
363       if w or h is negative.
364
365
366
367       val fill_poly : (int * int) array -> unit
368
369       Fill the given polygon with the current color. The array  contains  the
370       coordinates of the vertices of the polygon.
371
372
373
374       val fill_arc : int -> int -> int -> int -> int -> int -> unit
375
376       Fill an elliptical pie slice with the current color. The parameters are
377       the same as for Graphics.draw_arc .
378
379
380
381       val fill_ellipse : int -> int -> int -> int -> unit
382
383       Fill an ellipse with the current color. The parameters are the same  as
384       for Graphics.draw_ellipse .
385
386
387
388       val fill_circle : int -> int -> int -> unit
389
390       Fill  a  circle  with the current color. The parameters are the same as
391       for Graphics.draw_circle .
392
393
394
395
396   Images
397       type image
398
399
400       The abstract type for images, in internal representation.   Externally,
401       images  are represented as matrices of colors.  Images are bound to the
402       current graphics window and should not be  reused  after  closing  this
403       graphics window with Graphics.close_graph .
404
405
406
407       val transp : color
408
409       In matrices of colors, this color represent a 'transparent' point: when
410       drawing the corresponding image, all pixels on the screen corresponding
411       to  a  transparent pixel in the image will not be modified, while other
412       points will be set to the color  of  the  corresponding  point  in  the
413       image. This allows superimposing an image over an existing background.
414
415
416
417       val make_image : color array array -> image
418
419       Convert  the given color matrix to an image.  Each sub-array represents
420       one horizontal line. All sub-arrays must have the same  length;  other‐
421       wise, exception Graphic_failure is raised.
422
423
424
425       val dump_image : image -> color array array
426
427       Convert an image to a color matrix.
428
429
430
431       val draw_image : image -> int -> int -> unit
432
433       Draw the given image with lower left corner at the given point.
434
435
436
437       val get_image : int -> int -> int -> int -> image
438
439       Capture  the  contents  of  a rectangle on the screen as an image.  The
440       parameters are the same as for Graphics.fill_rect .
441
442
443
444       val create_image : int -> int -> image
445
446
447       create_image w h returns a new image w pixels wide and h  pixels  tall,
448       to be used in conjunction with blit_image .  The initial image contents
449       are random, except that no point is transparent.
450
451
452
453       val blit_image : image -> int -> int -> unit
454
455
456       blit_image img x y copies screen pixels into the image img ,  modifying
457       img  in-place.  The  pixels  copied are those inside the rectangle with
458       lower left corner at x,y , and width and height equal to those  of  the
459       image. Pixels that were transparent in img are left unchanged.
460
461
462
463
464   Mouse and keyboard events
465       type status = {
466        mouse_x : int ;  (* X coordinate of the mouse
467        *)
468        mouse_y : int ;  (* Y coordinate of the mouse
469        *)
470        button : bool ;  (* true if a mouse button is pressed
471        *)
472        keypressed : bool ;  (* true if a key has been pressed
473        *)
474        key : char ;  (* the character for the key pressed
475        *)
476        }
477
478
479       To report events.
480
481
482       type event =
483        | Button_down  (* A mouse button is pressed
484        *)
485        | Button_up  (* A mouse button is released
486        *)
487        | Key_pressed  (* A key is pressed
488        *)
489        | Mouse_motion  (* The mouse is moved
490        *)
491        | Poll  (* Don't wait; return immediately
492        *)
493
494
495       To specify events to wait for.
496
497
498
499       val wait_next_event : event list -> status
500
501       Wait  until one of the events specified in the given event list occurs,
502       and return the status of the mouse and keyboard at that time.  If  Poll
503       is given in the event list, return immediately with the current status.
504       If the mouse cursor is outside of the graphics window, the mouse_x  and
505       mouse_y  fields  of  the  event  are  outside  the range 0..size_x()-1,
506       0..size_y()-1 . Keypresses are queued, and dequeued one by one when the
507       Key_pressed event is specified and the Poll event is not specified.
508
509
510
511       val loop_at_exit : event list -> (status -> unit) -> unit
512
513       Loop before exiting the program, the list given as argument is the list
514       of handlers and the events on which these handlers are called.  To exit
515       cleanly  the  loop,  the handler should raise Exit. Any other exception
516       will be propagated outside of the loop.
517
518
519       Since 4.01
520
521
522
523
524   Mouse and keyboard polling
525       val mouse_pos : unit -> int * int
526
527       Return the position of the mouse cursor, relative to the graphics  win‐
528       dow. If the mouse cursor is outside of the graphics window, mouse_pos()
529       returns a point outside of the range 0..size_x()-1, 0..size_y()-1 .
530
531
532
533       val button_down : unit -> bool
534
535       Return true if the mouse button is pressed, false otherwise.
536
537
538
539       val read_key : unit -> char
540
541       Wait for a key to be pressed, and return the  corresponding  character.
542       Keypresses are queued.
543
544
545
546       val key_pressed : unit -> bool
547
548       Return  true if a keypress is available; that is, if read_key would not
549       block.
550
551
552
553
554   Sound
555       val sound : int -> int -> unit
556
557
558       sound freq dur plays a sound at frequency freq (in hertz) for  a  dura‐
559       tion dur (in milliseconds).
560
561
562
563
564   Double buffering
565       val auto_synchronize : bool -> unit
566
567       By default, drawing takes place both on the window displayed on screen,
568       and in a memory area (the 'backing store').  The backing store image is
569       used to re-paint the on-screen window when necessary.
570
571       To  avoid  flicker  during  animations,  it  is  possible  to  turn off
572       on-screen drawing, perform a number of drawing operations in the  back‐
573       ing store only, then refresh the on-screen window explicitly.
574
575
576       auto_synchronize  false  turns  on-screen  drawing off.  All subsequent
577       drawing commands are performed on the backing store only.
578
579
580       auto_synchronize true refreshes the on-screen window from  the  backing
581       store (as per synchronize ), then turns on-screen drawing back on.  All
582       subsequent drawing commands are performed both on  screen  and  in  the
583       backing store.
584
585       The default drawing mode corresponds to auto_synchronize true .
586
587
588
589       val synchronize : unit -> unit
590
591       Synchronize  the backing store and the on-screen window, by copying the
592       contents of the backing store onto the graphics window.
593
594
595
596       val display_mode : bool -> unit
597
598       Set display mode on or off. When turned on, drawings are  done  in  the
599       graphics  window;  when turned off, drawings do not affect the graphics
600       window.  This occurs independently of drawing into  the  backing  store
601       (see  the  function Graphics.remember_mode below). Default display mode
602       is on.
603
604
605
606       val remember_mode : bool -> unit
607
608       Set remember mode on or off. When turned on, drawings are done  in  the
609       backing  store;  when  turned  off,  the backing store is unaffected by
610       drawings.  This occurs independently of drawing onto the graphics  win‐
611       dow  (see  the function Graphics.display_mode above).  Default remember
612       mode is on.
613
614
615
616
617
618OCamldoc                          2019-07-30                       Graphics(3)
Impressum