1Graphics(3) OCaml library Graphics(3)
2
3
4
6 Graphics - Machine-independent graphics primitives.
7
9 Module Graphics
10
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)