home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Tools / Languages / Caml Light 0.61 / Source / src / lib / graphics.mli < prev    next >
Encoding:
Text File  |  1993-10-01  |  9.8 KB  |  225 lines  |  [TEXT/MPS ]

  1. (* Machine-independent graphics primitives *)
  2.  
  3. exception Graphic_failure of string;;
  4.         (* Raised by the functions below when they encounter an error. *)
  5.  
  6. (*** Initializations *)
  7.  
  8. value open_graph: string -> unit = 1 "open_graph"
  9.         (* Show the graphics window or switch the screen to graphic mode.
  10.            The graphics window is cleared. The string argument is used to
  11.            pass optional information on the desired graphics mode, the
  12.            graphics window size, and so on. Its interpretation is
  13.            implementation-dependent. If the empty string is given, a sensible
  14.            default is selected. *)
  15.   and close_graph: unit -> unit = 1 "close_graph"
  16.         (* Delete the graphics window or switch the screen back to
  17.            text mode. *)
  18.   and clear_graph : unit -> unit = 1 "clear_graph"
  19.         (* Erase the graphic window. *)
  20.   and size_x : unit -> int = 1 "size_x"
  21.   and size_y : unit -> int = 1 "size_y"
  22.         (* Return the size of the graphics window. Coordinates of the screen
  23.            pixels range over [0 .. size_x()-1] and [0 .. size_y()-1].
  24.            Drawings outside of this rectangle are clipped, without causing
  25.            an error. The origin (0,0) is at the lower left corner. *)
  26. ;;
  27.  
  28. (*** Colors *)
  29.  
  30. type color == int
  31.         (* A color is specified by its R, G, B components. Each component
  32.            is in the range [0..255]. The three components are packed in
  33.            an [int]: [0xRRGGBB], where [RR] are the two hexadecimal digits for
  34.            the red component, [GG] for the green component, [BB] for the
  35.            blue component. *)
  36. ;;
  37.  
  38. value rgb: int -> int -> int -> int
  39.         (* [rgb r g b] returns the integer encoding the color with red
  40.            component [r], green component [g], and blue component [b].
  41.            [r], [g] and [b] are in the range [0..255]. *)
  42. ;;
  43.  
  44. value set_color : color -> unit = 1 "set_color"
  45.         (* Set the current drawing color *)
  46. ;;
  47.  
  48. value black : color
  49.   and white : color
  50.   and red : color
  51.   and green : color
  52.   and blue : color
  53.   and yellow : color
  54.   and cyan : color
  55.   and magenta : color
  56. ;;
  57.         (* Some predefined colors. *)
  58.  
  59. value background: color
  60.   and foreground: color
  61. ;;
  62.         (* Default background and foreground colors (usually, either black
  63.            foreground on a white background or white foreground on a
  64.            black background).
  65.            [clear_graph] fills the screen with the [background] color.
  66.            The initial drawing color is [foreground]. *)
  67.  
  68. (*** Point and line drawing *)
  69.  
  70. value plot : int -> int -> unit = 2 "plot"
  71.         (* Plot the given point with the current drawing color. *)
  72.   and point_color : int -> int -> color = 2 "point_color"
  73.         (* Return the color of the given point. *)
  74.   and moveto : int -> int -> unit = 2 "moveto"
  75.         (* Position the current point. *)
  76.   and current_point : unit -> int * int = 1 "current_point"
  77.         (* Return the position of the current point. *)
  78.   and lineto : int -> int -> unit = 2 "lineto"
  79.         (* Draw a line with endpoints the current point and the given point,
  80.            and move the current point to the given point. *)
  81.   and draw_arc : int -> int -> int -> int -> int -> int -> unit = 6 "draw_arc"
  82.         (* [draw_arc x y rx ry a1 a2] draws an elliptical arc with center
  83.            [x,y], horizontal radius [rx], vertical radius [ry], from angle
  84.            [a1] to angle [a2] (in degrees). The current point is unchanged. *)
  85.   and draw_ellipse : int -> int -> int -> int -> unit
  86.         (* [draw_ellipse x y rx ry] draws an ellipse with center
  87.            [x,y], horizontal radius [rx] and vertical radius [ry].
  88.            The current point is unchanged.  *)
  89.   and draw_circle : int -> int -> int -> unit
  90.         (* [draw_circle x y r] draws a circle with center [x,y] and
  91.            radius [r]. The current point is unchanged. *)
  92.   and set_line_width : int -> unit = 1 "set_line_width"
  93.         (* Set the width of points and lines drawn with the functions above. *)
  94. ;;
  95.  
  96. (*** Text drawing *)
  97.  
  98. value draw_char : char -> unit = 1 "draw_char"
  99.   and draw_string : string -> unit = 1 "draw_string"
  100.         (* Draw a character or a character string with lower left corner
  101.            at current position. After drawing, the current position is set
  102.            to the lower right corner of the text drawn. *)
  103.   and set_font : string -> unit = 1 "set_font"
  104.   and set_text_size : int -> unit = 1 "set_text_size"
  105.         (* Set the font and character size used for drawing text.
  106.            The interpretation of the arguments to [set_font] and
  107.            [set_text_size] is implementation-dependent. *)
  108.   and text_size : string -> int * int = 1 "text_size"
  109.         (* Return the dimensions of the given text, if it were drawn with
  110.            the current font and size. *)
  111. ;;
  112.  
  113. (*** Filling *)
  114.  
  115. value fill_rect : int -> int -> int -> int -> unit = 4 "fill_rect"
  116.         (* [fill_rect x y w h] fills the rectangle with lower left corner
  117.            at [x,y], width [w] and heigth [h], with the current color. *)
  118.   and fill_poly : (int * int) vect -> unit = 1 "fill_poly"
  119.         (* Fill the given polygon with the current color. The array
  120.            contains the coordinates of the vertices of the polygon. *)
  121.   and fill_arc : int -> int -> int -> int -> int -> int -> unit = 6 "fill_arc"
  122.         (* Fill an elliptical pie slice with the current color. The
  123.            parameters are the same as for [draw_arc]. *)
  124.   and fill_ellipse : int -> int -> int -> int -> unit
  125.         (* Fill an ellipse with the current color. The
  126.            parameters are the same as for [draw_ellipse]. *)
  127.   and fill_circle : int -> int -> int -> unit
  128.         (* Fill a circle with the current color. The
  129.            parameters are the same as for [draw_circle]. *)
  130. ;;
  131.  
  132. (*** Images *)
  133.  
  134. type image;;
  135.         (* The abstract type for images, in internal representation.
  136.            Externally, images are represented as matrices of colors. *)
  137.  
  138. value transp : color;;
  139.         (* In matrices of colors, this color represents a ``transparent''
  140.            point: when drawing the corresponding image, all pixels on the
  141.            screen corresponding to a transparent pixel in the image will
  142.            not be modified, while other points will be set to the color
  143.            of the corresponding point in the image. This allows superimposing
  144.            an image over an existing background. *)
  145.  
  146. value make_image : color vect vect -> image = 1 "make_image"
  147.         (* Convert the given color matrix to an image.
  148.            Each sub-array represents one horizontal line. All sub-arrays
  149.            must have the same length; otherwise, exception [Graphic_failure]
  150.            is raised. *)
  151.   and dump_image : image -> color vect vect = 1 "dump_image"
  152.         (* Convert an image to a color matrix. *)
  153.   and draw_image : image -> int -> int -> unit = 3 "draw_image"
  154.         (* Draw the given image with lower left corner at the given point. *)
  155.   and get_image : int -> int -> int -> int -> image
  156.         (* Capture the contents of a rectangle on the screen as an image.
  157.            The parameters are the same as for [fill_rect]. *)
  158.   and create_image : int -> int -> image = 2 "create_image"
  159.         (* [create_image w h] returns a new image [w] pixels wide and [h]
  160.            pixels tall, to be used in conjunction with [blit_image].
  161.            The initial image contents are random. *)
  162.   and blit_image : image -> int -> int -> unit = 3 "blit_image"
  163.         (* [blit_image img x y] copies screen pixels into the image [img],
  164.            modifying [img] in-place. The pixels copied are those inside the
  165.            rectangle with lower left corner at [x,y], and width and height
  166.            equal to those of the image. *)
  167. ;;
  168.  
  169. (*** Mouse and keyboard events *)
  170.  
  171. type status =
  172.   { mouse_x : int;        (* X coordinate of the mouse *)
  173.     mouse_y : int;        (* Y coordinate of the mouse *)
  174.     button : bool;        (* true if a mouse button is pressed *)
  175.     keypressed : bool;  (* true if a key has been pressed *)
  176.     key : char }        (* the character for the key pressed *)
  177. ;;
  178.         (* To report events. *)
  179.  
  180. type event =
  181.     Button_down            (* A mouse button is pressed *)
  182.   | Button_up            (* A mouse button is released *)
  183.   | Key_pressed            (* A key is pressed *)
  184.   | Mouse_motion        (* The mouse is moved *)
  185.   | Poll                (* Don't wait; return immediately *)
  186. ;;
  187.         (* To specify events to wait for. *)
  188.  
  189. value wait_next_event : event list -> status = 1 "wait_event"
  190.         (* Wait until one of the events specified in the given event list
  191.            occurs, and return the status of the mouse and keyboard at
  192.            that time. If [Poll] is given in the event list, return immediately
  193.            with the current status. If the mouse cursor is outside of the
  194.            graphics window, the [mouse_x] and [mouse_y] fields of the event are
  195.            outside the range [0..size_x()-1, 0..size_y()-1]. Keypresses
  196.            are queued, and dequeued one by one when the [Key_pressed]
  197.            event is specified. *)
  198. ;;
  199.  
  200. (*** Mouse and keyboard polling *)
  201.  
  202. value mouse_pos : unit -> int * int
  203.         (* Return the position of the mouse cursor, relative to the
  204.            graphics window. If the mouse cursor is outside of the graphics
  205.            window, [mouse_pos()] returns a point outside of the range
  206.            [0..size_x()-1, 0..size_y()-1]. *)
  207.   and button_down : unit -> bool
  208.         (* Return [true] if the mouse button is pressed, [false] otherwise. *)
  209.   and read_key : unit -> char
  210.         (* Wait for a key to be pressed (in the graphics window), and return
  211.            the corresponding character. Keypresses are queued. *)
  212.   and key_pressed : unit -> bool
  213.         (* Return [true] if a keypress is available; that is, if [read_key]
  214.            would not block. *)
  215. ;;
  216.  
  217. (*** Sound *)
  218.  
  219. value sound : int -> int -> unit = 2 "sound"
  220.         (* [sound freq dur] plays a sound at frequency [freq] (in hertz)
  221.            for a duration [dur] (in milliseconds). On the Macintosh, for
  222.            obscure technical reasons, the frequency is rounded to the
  223.            nearest note in the equal-tempered scale. *)
  224. ;;
  225.