   This file documents the MIT Scheme system.

   Copyright (C) 1988-2002 Massachusetts Institute of Technology

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

Condition-Type Taxonomy
=======================

   The MIT Scheme error system provides a rich set of predefined
condition types.  These are organized into a forest through taxonomic
links providing the relationships for "specializes" and "generalizes".
The chart appearing below shows these relationships by indenting all the
specializations of a given type relative to the type.  Note that the
variables that are bound to these condition types are prefixed by
`condition-type:'; for example, the type appearing in the following
table as `simple-error' is stored in the variable
`condition-type:simple-error'.  Users are encouraged to add new
condition types by creating specializations of existing ones.

   Following the chart are detailed descriptions of the predefined
condition types.  Some of these types are marked as "abstract" types.
Abstract types are not intended to be used directly as the type of a
condition; they are to be used as generalizations of other types, and
for binding condition handlers.  Types that are not marked as abstract
are "concrete"; they are intended to be explicitly used as a
condition's type.

     serious-condition
         error
             simple-error
             illegal-datum
                 wrong-type-datum
                     wrong-type-argument
                     wrong-number-of-arguments
                 datum-out-of-range
                     bad-range-argument
                 inapplicable-object
             file-error
                 file-operation-error
                 derived-file-error
             port-error
                 derived-port-error
             variable-error
                 unbound-variable
                 unassigned-variable
             arithmetic-error
                 divide-by-zero
                 floating-point-overflow
                 floating-point-underflow
             control-error
                 no-such-restart
             not-loading
             primitive-procedure-error
                 system-call-error
     warning
         simple-warning
     simple-condition
     breakpoint

 - condition type: condition-type:serious-condition
     This is an abstract type.  All serious conditions that require
     some form of intervention should inherit from this type.  In
     particular, all errors inherit from this type.

 - condition type: condition-type:error
     This is an abstract type.  All errors should inherit from this
     type.

 - condition type: condition-type:simple-error message irritants
     This is the condition generated by the `error' procedure when its
     first argument is not a condition or condition type.  The fields
     MESSAGE and IRRITANTS are taken directly from the arguments to
     `error'; MESSAGE contains an object (usually a string) and
     IRRITANTS contains a list of objects.  The reporter for this type
     uses `format-error-message' to generate its output from MESSAGE
     and IRRITANTS.

 - condition type: condition-type:illegal-datum datum
     This is an abstract type.  This type indicates the class of errors
     in which a program discovers an object that lacks specific required
     properties.  Most commonly, the object is of the wrong type or is
     outside a specific range.  The DATUM field contains the offending
     object.

 - condition type: condition-type:wrong-type-datum datum type
     This type indicates the class of errors in which a program
     discovers an object that is of the wrong type.  The TYPE field
     contains a string describing the type that was expected, and the
     DATUM field contains the object that is of the wrong type.

     (error:wrong-type-datum 3.4 "integer")  error-->
     ;The object 3.4 is not an integer.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:wrong-type-datum datum type
     This procedure signals a condition of type
     `condition-type:wrong-type-datum'.  The DATUM and TYPE fields of
     the condition are filled in from the corresponding arguments to
     the procedure.

 - condition type: condition-type:wrong-type-argument datum type
          operator operand
     This type indicates that a procedure was passed an argument of the
     wrong type.  The OPERATOR field contains the procedure (or a symbol
     naming the procedure), the OPERAND field indicates the argument
     position that was involved (this field contains either a symbol, a
     non-negative integer, or `#f'), the TYPE field contains a string
     describing the type that was expected, and the DATUM field
     contains the offending argument.

     (+ 'a 3)                                error-->
     ;The object a, passed as the first argument to integer-add,
     ; is not the correct type.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify an argument to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.

     (list-copy 3)
     ;The object 3, passed as an argument to list-copy, is not a list.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:wrong-type-argument datum type operator
     This procedure signals a condition of type
     `condition-type:wrong-type-argument'.  The DATUM, TYPE and
     OPERATOR fields of the condition are filled in from the
     corresponding arguments to the procedure; the OPERAND field of the
     condition is set to `#f'.

 - condition type: condition-type:wrong-number-of-arguments datum type
          operands
     This type indicates that a procedure was called with the wrong
     number of arguments.  The DATUM field contains the procedure being
     called, the TYPE field contains the number of arguments that the
     procedure accepts, and the OPERANDS field contains a list of the
     arguments that were passed to the procedure.

     (car 3 4)                               error-->
     ;The procedure car has been called with 2 arguments;
     ; it requires exactly 1 argument.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:wrong-number-of-arguments datum type operands
     This procedure signals a condition of type
     `condition-type:wrong-number-of-arguments'.  The DATUM, TYPE and
     OPERANDS fields of the condition are filled in from the
     corresponding arguments to the procedure.

 - condition type: condition-type:datum-out-of-range datum
     This type indicates the class of errors in which a program
     discovers an object that is of the correct type but is otherwise
     out of range.  Most often, this type indicates that an index to
     some data structure is outside of the range of indices for that
     structure.  The DATUM field contains the offending object.

     (error:datum-out-of-range 3)            error-->
     ;The object 3 is not in the correct range.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:datum-out-of-range datum
     This procedure signals a condition of type
     `condition-type:datum-out-of-range'.  The DATUM field of the
     condition is filled in from the corresponding argument to the
     procedure.

 - condition type: condition-type:bad-range-argument datum operator
          operand
     This type indicates that a procedure was passed an argument that
     is of the correct type but is otherwise out of range.  Most often,
     this type indicates that an index to some data structure is
     outside of the range of indices for that structure.  The OPERATOR
     field contains the procedure (or a symbol naming the procedure),
     the OPERAND field indicates the argument position that was
     involved (this field contains either a symbol, a non-negative
     integer, or `#f'), and the DATUM field is the offending argument.

     (string-ref "abc" 3)                    error-->
     ;The object 3, passed as the second argument to string-ref,
     ; is not in the correct range.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify an argument to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:bad-range-argument datum operator
     This procedure signals a condition of type
     `condition-type:bad-range-argument'.  The DATUM and OPERATOR
     fields of the condition are filled in from the corresponding
     arguments to the procedure; the OPERAND field of the condition is
     set to `#f'.

 - condition type: condition-type:inapplicable-object datum operands
     This type indicates an error in which a program attempted to apply
     an object that is not a procedure.  The object being applied is
     saved in the DATUM field, and the arguments being passed to the
     object are saved as a list in the OPERANDS field.

     (3 4)                                   error-->
     ;The object 3 is not applicable.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify a procedure to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.

 - condition type: condition-type:file-error filename
     This is an abstract type.  It indicates that an error associated
     with a file has occurred.  For example, attempting to delete a
     nonexistent file will signal an error.  The FILENAME field
     contains a filename or pathname associated with the operation that
     failed.

 - condition type: condition-type:file-operation-error filename verb
          noun reason operator operands
     This is the most common condition type for file system errors.  The
     FILENAME field contains the filename or pathname that was being
     operated on.  The VERB field contains a string which is the verb
     or verb phrase describing the operation being performed, and the
     NOUN field contains a string which is a noun or noun phrase
     describing the object being operated on.  The REASON field
     contains a string describing the error that occurred.  The
     OPERATOR field contains the procedure performing the operation (or
     a symbol naming that procedure), and the OPERANDS field contains a
     list of the arguments that were passed to that procedure.  For
     example, an attempt to delete a nonexistent file would have the
     following field values:

          filename        "/zu/cph/tmp/no-such-file"
          verb            "delete"
          noun            "file"
          reason          "no such file or directory"
          operator        file-remove
          operands        ("/zu/cph/tmp/no-such-file")

     and would generate a message like this:

          (delete-file "/zu/cph/tmp/no-such-file") error-->
          ;Unable to delete file "/zu/cph/tmp/no-such-file" because:
          ; No such file or directory.
          ;To continue, call RESTART with an option number:
          ; (RESTART 3) => Try to delete the same file again.
          ; (RESTART 2) => Try to delete a different file.
          ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:file-operation-error filename verb noun reason
          operator operands
     This procedure signals a condition of type
     `condition-type:file-operation-error'.  The fields of the condition
     are filled in from the corresponding arguments to the procedure.

 - condition type: condition-type:derived-file-error filename condition
     This is another kind of file error, which is generated by obscure
     file-system errors that do not fit into the standard categories.
     The FILENAME field contains the filename or pathname that was being
     operated on, and the CONDITION field contains a condition
     describing the error in more detail.  Usually the CONDITION field
     contains a condition of type `condition-type:system-call-error'.

 - procedure: error:derived-file filename condition
     This procedure signals a condition of type
     `condition-type:derived-file-error'.  The FILENAME and CONDITION
     fields of the condition are filled in from the corresponding
     arguments to the procedure.

 - condition type: condition-type:port-error port
     This is an abstract type.  It indicates that an error associated
     with a I/O port has occurred.  For example, writing output to a
     file port can signal an error if the disk containing the file is
     full; that error would be signalled as a port error.  The PORT
     field contains the associated port.

 - condition type: condition-type:derived-port-error port condition
     This is a concrete type that is signalled when port errors occur.
     The PORT field contains the port associated with the error, and the
     CONDITION field contains a condition object that describes the
     error in more detail.  Usually the CONDITION field contains a
     condition of type `condition-type:system-call-error'.

 - procedure: error:derived-port port condition
     This procedure signals a condition of type
     `condition-type:derived-port-error'.  The PORT and CONDITION
     fields of the condition are filled in from the corresponding
     arguments to the procedure.

 - condition type: condition-type:variable-error location environment
     This is an abstract type.  It indicates that an error associated
     with a variable has occurred.  The LOCATION field contains the
     name of the variable, and the ENVIRONMENT field contains the
     environment in which the variable was referenced.

 - condition type: condition-type:unbound-variable location environment
     This type is generated when a program attempts to access or modify
     a variable that is not bound.  The LOCATION field contains the name
     of the variable, and the ENVIRONMENT field contains the
     environment in which the reference occurred.

     foo                                     error-->
     ;Unbound variable: foo
     ;To continue, call RESTART with an option number:
     ; (RESTART 3) => Specify a value to use instead of foo.
     ; (RESTART 2) => Define foo to a given value.
     ; (RESTART 1) => Return to read-eval-print level 1.

 - condition type: condition-type:unassigned-variable location
          environment
     This type is generated when a program attempts to access a
     variable that is not assigned.  The LOCATION field contains the
     name of the variable, and the ENVIRONMENT field contains the
     environment in which the reference occurred.

     foo                                     error-->
     ;Unassigned variable: foo
     ;To continue, call RESTART with an option number:
     ; (RESTART 3) => Specify a value to use instead of foo.
     ; (RESTART 2) => Set foo to a given value.
     ; (RESTART 1) => Return to read-eval-print level 1.

 - condition type: condition-type:arithmetic-error operator operands
     This is an abstract type.  It indicates that a numerical operation
     was unable to complete because of an arithmetic error.  (For
     example, division by zero.)  The OPERATOR field contains the
     procedure that implements the operation (or a symbol naming the
     procedure), and the OPERANDS field contains a list of the
     arguments that were passed to the procedure.

 - condition type: condition-type:divide-by-zero operator operands
     This type is generated when a program attempts to divide by zero.
     The OPERATOR field contains the procedure that implements the
     failing operation (or a symbol naming the procedure), and the
     OPERANDS field contains a list of the arguments that were passed
     to the procedure.

     (/ 1 0)
     ;Division by zero signalled by /.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:divide-by-zero operator operands
     This procedure signals a condition of type
     `condition-type:divide-by-zero'.  The OPERATOR and OPERANDS fields
     of the condition are filled in from the corresponding arguments to
     the procedure.

 - condition type: condition-type:floating-point-overflow operator
          operands
     This type is generated when a program performs an arithmetic
     operation that results in a floating-point overflow.  The OPERATOR
     field contains the procedure that implements the operation (or a
     symbol naming the procedure), and the OPERANDS field contains a
     list of the arguments that were passed to the procedure.

 - condition type: condition-type:floating-point-underflow operator
          operands
     This type is generated when a program performs an arithmetic
     operation that results in a floating-point underflow.  The
     OPERATOR field contains the procedure that implements the
     operation (or a symbol naming the procedure), and the OPERANDS
     field contains a list of the arguments that were passed to the
     procedure.

 - condition type: condition-type:primitive-procedure-error operator
          operands
     This is an abstract type.  It indicates that an error was
     generated by a primitive procedure call.  Primitive procedures are
     distinguished from ordinary procedures in that they are not
     written in Scheme but instead in the underlying language of the
     Scheme implementation.  The OPERATOR field contains the procedure
     that implements the operation (or a symbol naming the procedure),
     and the OPERANDS field contains a list of the arguments that were
     passed to the procedure.

 - condition type: condition-type:system-call-error operator operands
          system-call error-type
     This is the most common condition type generated by primitive
     procedures.  A condition of this type indicates that the primitive
     made a system call to the operating system, and that the system
     call signalled an error.  The system-call error is reflected back
     to Scheme as a condition of this type, except that many common
     system-call errors are automatically translated by the Scheme
     implementation into more useful forms; for example, a system-call
     error that occurs while trying to delete a file will be translated
     into a condition of type `condition-type:file-operation-error'.
     The OPERATOR field contains the procedure that implements the
     operation (or a symbol naming the procedure), and the OPERANDS
     field contains a list of the arguments that were passed to the
     procedure.  The SYSTEM-CALL and ERROR-TYPE fields contain symbols
     that describe the specific system call that was being made and the
     error that occurred, respectively; these symbols are completely
     operating-system dependent.

 - condition type: condition-type:control-error
     This is an abstract type.  It describes a class of errors relating
     to program control flow.

 - condition type: condition-type:no-such-restart name
     This type indicates that a named restart was not active when it was
     expected to be.  Conditions of this type are signalled by several
     procedures that look for particular named restarts, for example
     `muffle-warning'.  The NAME field contains the name that was being
     searched for.

     (muffle-warning)                        error-->
     ;The restart named muffle-warning is not bound.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - procedure: error:no-such-restart name
     This procedure signals a condition of type
     `condition-type:no-such-restart'.  The NAME field of the condition
     is filled in from the corresponding argument to the procedure.

 - condition type: condition-type:not-loading
     A condition of this type is generated when the procedure
     `current-load-pathname' is called from somewhere other than inside
     a file being loaded.

     (current-load-pathname)                 error-->
     ;No file being loaded.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.

 - condition type: condition-type:warning
     This is an abstract type.  All warnings should inherit from this
     type.  Warnings are a class of conditions that are usually handled
     by informing the user of the condition and proceeding the
     computation normally.

 - condition type: condition-type:simple-warning message irritants
     This is the condition generated by the `warn' procedure.  The
     fields MESSAGE and IRRITANTS are taken directly from the arguments
     to `warn'; MESSAGE contains an object (usually a string) and
     IRRITANTS contains a list of objects.  The reporter for this type
     uses `format-error-message' to generate its output from MESSAGE
     and IRRITANTS.

 - condition type: condition-type:simple-condition message irritants
     This is an unspecialized condition that does not fall into any of
     the standard condition classes.  The MESSAGE field contains an
     object (usually a string) and IRRITANTS contains a list of
     objects.  The reporter for this type uses `format-error-message'
     to generate its output from MESSAGE and IRRITANTS.

 - condition type: condition-type:breakpoint environment message prompt
     A condition of this type is generated by the breakpoint mechanism.
     The contents of its fields are beyond the scope of this document.

Graphics
********

   MIT Scheme has a simple two-dimensional line-graphics interface that
is suitable for many graphics applications.  In particular it is often
used for plotting data points from experiments.  The interface is
generic in that it can support different types of graphics devices in a
uniform manner.  At the present time only one type of graphics device
is implemented on each operating system.

   Procedures are available for drawing points, lines, and text;
defining the coordinate system; clipping graphics output; controlling
some of the drawing characteristics; and controlling the output buffer
(for devices that perform buffering).  Additionally, devices may
support custom operations, such as control of colors.

   There are some constraints on the arguments to the procedures
described in this chapter.  Any argument named GRAPHICS-DEVICE must be a
graphics device object that was returned from a call to
`make-graphics-device'.  Any argument that is a coordinate must be
either an exact integer or an inexact real.

Opening and Closing of Graphics Devices
=======================================

 - procedure: graphics-type-available? graphics-device-type
     This predicate returns `#t' if the graphics system named by the
     symbol GRAPHICS-DEVICE-TYPE is implemented by the Scheme system.
     Otherwise it returns `#f', in which case it is an error to attempt
     to make a graphics device using GRAPHICS-DEVICE-TYPE.

 - procedure: enumerate-graphics-types
     This procedure returns a list of symbols which are the names of
     all the graphics device types that are supported by the Scheme
     system.  The result is useful in deciding what additional
     arguments to supply to `make-graphics-device', as each device type
     typically has a unique way of specifying the initial size, shape
     and other attributes.

 - procedure: make-graphics-device graphics-device-type object ...
     This operation creates and returns a graphics device object.
     GRAPHICS-DEVICE-TYPE is a symbol naming a graphics device type,
     and both the number and the meaning of the remaining arguments is
     determined by that type (see the description of each device type
     for details); GRAPHICS-DEVICE-TYPE must satisfy
     `graphics-type-available?'.  GRAPHICS-DEVICE-TYPE may also be
     `#f', in which case the graphics device type is chosen by the
     system from what is available.  This allows completely portable
     graphics programs to be written provided no custom graphics
     operations are used.  When GRAPHICS-DEVICE-TYPE is `#f' no further
     arguments may be given; each graphics device type will use some
     "sensible" defaults.  If more control is required then the program
     should use one of the two procedures above to dispatch on the
     available types.

     This procedure opens and initializes the device, which remains
     valid until explicitly closed by the procedure `graphics-close'.
     Depending on the implementation of the graphics device, if this
     object is reclaimed by the garbage collector, the graphics device
     may remain open or it may be automatically closed.  While a
     graphics device remains open the resources associated with it are
     not released.

 - procedure: graphics-close graphics-device
     Closes GRAPHICS-DEVICE, releasing its resources.  Subsequently it
     is an error to use GRAPHICS-DEVICE.

Coordinates for Graphics
========================

   Each graphics device has two different coordinate systems associated
with it: "device coordinates" and "virtual coordinates".  Device
coordinates are generally defined by low-level characteristics of the
device itself, and often cannot be changed.  Most device coordinate
systems are defined in terms of pixels, and usually the upper-left-hand
corner is the origin of the coordinate system, with X coordinates
increasing to the right and Y coordinates increasing downwards.

   In contrast, virtual coordinates are more flexible in the units
employed, the position of the origin, and even the direction in which
the coordinates increase.  A virtual coordinate system is defined by
assigning coordinates to the edges of a device.  Because these edge
coordinates are arbitrary real numbers, any Cartesian coordinate system
can be defined.

   All graphics procedures that use coordinates are defined on virtual
coordinates.  For example, to draw a line at a particular place on a
device, the virtual coordinates for the endpoints of that line are
given.

   When a graphics device is initialized, its virtual coordinate system
is reset so that the left edge corresponds to an x-coordinate of `-1',
the right edge to x-coordinate `1', the bottom edge to y-coordinate
`-1', and the top edge to y-coordinate `1'.

 - procedure: graphics-device-coordinate-limits graphics-device
     Returns (as multiple values) the device coordinate limits for
     GRAPHICS-DEVICE.  The values, which are exact non-negative
     integers, are: X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP.

 - procedure: graphics-coordinate-limits graphics-device
     Returns (as multiple values) the virtual coordinate limits for
     GRAPHICS-DEVICE.  The values, which are real numbers, are: X-LEFT,
     Y-BOTTOM, X-RIGHT, and Y-TOP.

 - procedure: graphics-set-coordinate-limits graphics-device x-left
          y-bottom x-right y-top
     Changes the virtual coordinate limits of GRAPHICS-DEVICE to the
     given arguments.  X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP must be
     real numbers.  Subsequent calls to `graphics-coordinate-limits'
     will return the new limits.  This operation has no effect on the
     device's displayed contents.

     Note: This operation usually resets the clip rectangle, although
     it is not guaranteed to do so.  If a clip rectangle is in effect
     when this procedure is called, it is necessary to redefine the
     clip rectangle afterwards.

Drawing Graphics
================

   The procedures in this section provide the basic drawing
capabilities of Scheme's graphics system.

 - procedure: graphics-clear graphics-device
     Clears the display of GRAPHICS-DEVICE.  Unaffected by the current
     drawing mode.

 - procedure: graphics-draw-point graphics-device x y
     Draws a single point on GRAPHICS-DEVICE at the virtual coordinates
     given by X and Y, using the current drawing mode.

 - procedure: graphics-erase-point graphics-device x y
     Erases a single point on GRAPHICS-DEVICE at the virtual
     coordinates given by X and Y.  This procedure is unaffected by the
     current drawing mode.

This is equivalent to

     (lambda (device x y)
       (graphics-bind-drawing-mode device 0
         (lambda ()
           (graphics-draw-point device x y))))

 - procedure: graphics-draw-line graphics-device x-start y-start x-end
          y-end
     X-START, Y-START, X-END, and Y-END must be real numbers.  Draws a
     line on GRAPHICS-DEVICE that connects the points (X-START,
     Y-START) and (X-END, Y-END).  The line is drawn using the current
     drawing mode and line style.

 - procedure: graphics-draw-text graphics-device x y string
     Draws the characters of STRING at the point (X, Y) on
     GRAPHICS-DEVICE, using the current drawing mode.  The
     characteristics of the characters drawn are device-dependent, but
     all devices are initialized so that the characters are drawn
     upright, from left to right, with the leftmost edge of the
     leftmost character at X, and the baseline of the characters at Y.

   The following two procedures provide an alternate mechanism for
drawing lines, which is more akin to using a plotter.  They maintain a
"cursor", which can be positioned to a particular point and then
dragged to another point, producing a line.  Sequences of connected line
segments can be drawn by dragging the cursor from point to point.

   Many graphics operations have an unspecified effect on the cursor.
The following exceptions are guaranteed to leave the cursor unaffected:

     graphics-device-coordinate-limits
     graphics-coordinate-limits
     graphics-enable-buffering
     graphics-disable-buffering
     graphics-flush
     graphics-bind-drawing-mode
     graphics-set-drawing-mode
     graphics-bind-line-style
     graphics-set-line-style

   The initial state of the cursor is unspecified.

 - procedure: graphics-move-cursor graphics-device x y
     Moves the cursor for GRAPHICS-DEVICE to the point (X, Y).  The
     contents of the device's display are unchanged.

 - procedure: graphics-drag-cursor graphics-device x y
     Draws a line from GRAPHICS-DEVICE's cursor to the point (X, Y),
     simultaneously moving the cursor to that point.  The line is drawn
     using the current drawing mode and line style.

Characteristics of Graphics Output
==================================

   Two characteristics of graphics output are so useful that they are
supported uniformly by all graphics devices: "drawing mode" and "line
style".  A third characteristic, "color", is equally useful (if not
more so), but implementation restrictions prohibit a uniform interface.

   The "drawing mode", an exact integer in the range `0' to `15'
inclusive, determines how the figure being drawn is combined with the
background over which it is drawn to generate the final result.
Initially the drawing mode is set to "source", so that the new output
overwrites whatever appears in that place.  Useful alternative drawing
modes can, for example, erase what was already there, or invert it.

   Altogether 16 boolean operations are available for combining the
source (what is being drawn) and the destination (what is being drawn
over).  The source and destination are combined by the device on a
pixel-by-pixel basis as follows:

     Mode    Meaning
     ----    -------
     0       ZERO [erase; use background color]
     1       source AND destination
     2       source AND (NOT destination)
     3       source
     4       (NOT source) AND destination
     5       destination
     6       source XOR destination
     7       source OR destination
     8       NOT (source OR destination)
     9       NOT (source XOR destination)
     10      NOT destination
     11      source OR (NOT destination)
     12      NOT source
     13      (NOT source) OR destination
     14      (NOT source) OR (NOT destination)
     15      ONE [use foreground color]

   The "line style", an exact integer in the range `0' to `7'
inclusive, determines which parts of a line are drawn in the foreground
color, and which in the background color.  The default line style,
"solid", draws the entire line in the foreground color.  Alternatively,
the "dash" style alternates between foreground and background colors to
generate a dashed line.  This capability is useful for plotting several
things on the same graph.

   Here is a table showing the name and approximate pattern of the
different styles.  A `1' in the pattern represents a foreground pixel,
while a `-' represents a background pixel.  Note that the precise
output for each style will vary from device to device.  The only style
that is guaranteed to be the same for every device is "solid".

     Style   Name                    Pattern
     -----   -------                 -------
     0       solid                   1111111111111111
     1       dash                    11111111--------
     2       dot                     1-1-1-1-1-1-1-1-
     3       dash dot                1111111111111-1-
     4       dash dot dot            11111111111-1-1-
     5       long dash               11111111111-----
     6       center dash             111111111111-11-
     7       center dash dash        111111111-11-11-

 - procedure: graphics-bind-drawing-mode graphics-device drawing-mode
          thunk
 - procedure: graphics-bind-line-style graphics-device line-style thunk
     These procedures bind the drawing mode or line style,
     respectively, of GRAPHICS-DEVICE, invoke the procedure THUNK with
     no arguments, then undo the binding when THUNK returns.  The value
     of each procedure is the value returned by THUNK.  Graphics
     operations performed during THUNK's dynamic extent will see the
     newly bound mode or style as current.

 - procedure: graphics-set-drawing-mode graphics-device drawing-mode
 - procedure: graphics-set-line-style graphics-device line-style
     These procedures change the drawing mode or line style,
     respectively, of GRAPHICS-DEVICE.  The mode or style will remain
     in effect until subsequent changes or bindings.

Buffering of Graphics Output
============================

   To improve performance of graphics output, most graphics devices
provide some form of buffering.  By default, Scheme's graphics
procedures flush this buffer after every drawing operation.  The
procedures in this section allow the user to control the flushing of
the output buffer.

 - procedure: graphics-enable-buffering graphics-device
     Enables buffering for GRAPHICS-DEVICE.  In other words, after this
     procedure is called, graphics operations are permitted to buffer
     their drawing requests.  This usually means that the drawing is
     delayed until the buffer is flushed explicitly by the user, or
     until it fills up and is flushed by the system.

 - procedure: graphics-disable-buffering graphics-device
     Disables buffering for GRAPHICS-DEVICE.  By default, all graphics
     devices are initialized with buffering disabled.  After this
     procedure is called, all drawing operations perform their output
     immediately, before returning.

     Note: `graphics-disable-buffering' flushes the output buffer if
     necessary.

 - procedure: graphics-flush graphics-device
     Flushes the graphics output buffer for GRAPHICS-DEVICE.  This
     operation has no effect for devices that do not support buffering,
     or if buffering is disabled for the device.

Clipping of Graphics Output
===========================

   Scheme provides a rudimentary mechanism for restricting graphics
output to a given rectangular subsection of a graphics device.  By
default, graphics output that is drawn anywhere within the device's
virtual coordinate limits will appear on the device.  When a "clip
rectangle" is specified, however, output that would have appeared
outside the clip rectangle is not drawn.

   Note that changing the virtual coordinate limits for a device will
usually reset the clip rectangle for that device, as will any operation
that affects the size of the device (such as a window resizing
operation).  However, programs should not depend on this.

 - procedure: graphics-set-clip-rectangle graphics-device x-left
          y-bottom x-right y-top
     Specifies the clip rectangle for GRAPHICS-DEVICE in virtual
     coordinates.  X-LEFT, Y-BOTTOM, X-RIGHT, and Y-TOP must be real
     numbers.  Subsequent graphics output is clipped to the
     intersection of this rectangle and the device's virtual coordinate
     limits.

 - procedure: graphics-reset-clip-rectangle graphics-device
     Eliminates the clip rectangle for GRAPHICS-DEVICE.  Subsequent
     graphics output is clipped to the virtual coordinate limits of the
     device.

Custom Graphics Operations
==========================

   In addition to the standard operations, a graphics device may support
"custom operations".  For example, most devices have custom operations
to control color.  `graphics-operation' is used to invoke custom
operations.

 - procedure: graphics-operation graphics-device name object ...
     Invokes the graphics operation on GRAPHICS-DEVICE whose name is
     the symbol NAME, passing it the remaining arguments.  This
     procedure can be used to invoke the standard operations, as well as
     custom operations that are specific to a particular graphics device
     type.  The names of the standard graphics operations are formed by
     removing the `graphics-' prefix from the corresponding procedure.
     For example, the following are equivalent:

          (graphics-draw-point device x y)
          (graphics-operation device 'draw-point x y)

     For information on the custom operations for a particular device,
     see the documentation for its type.

Images
======

   Some graphics device types support images, which are rectangular
pieces of picture that may be drawn into a graphics device.  Images are
often called something else in the host graphics system, such as
bitmaps or pixmaps.  The operations supported vary between devices, so
look under the different device types to see what operations are
available.  All devices that support images support the following
operations.

 - operation on graphics-device: create-image width height
     Images are created using the `create-image' graphics operation,
     specifying the WIDTH and HEIGHT of the image in device coordinates
     (pixels).

          (graphics-operation device 'create-image 200 100)

     The initial contents of an image are unspecified.

     `create-image' is a graphics operation rather than a procedure
     because the kind of image returned depends on the kind of graphics
     device used and the options specified in its creation.  The image
     may be used freely with other graphics devices created with the
     same attributes, but the effects of using an image with a graphics
     device with different attributes (for example, different colors)
     is undefined.  Under X, the image is display dependent.

 - operation on graphics-device: draw-image x y image
     The image is copied into the graphics device at the specified
     position.

 - operation on graphics-device: draw-subimage x y image im-x im-y w h
     Part of the image is copied into the graphics device at the
     specified (X, Y) position.  The part of the image that is copied
     is the rectangular region at IM-X and IM-Y and of width W and
     height H.  These four numbers are given in device coordinates
     (pixels).

 - procedure: image? object
     Returns `#t' if OBJECT is an image, otherwise returns `#f'.

 - procedure: image/destroy image
     This procedure destroys IMAGE, returning storage to the system.
     Programs should destroy images after they have been used because
     even modest images may use large amounts of memory.  Images are
     reclaimed by the garbage collector, but they may be implemented
     using memory outside of Scheme's heap.  If an image is reclaimed
     before being destroyed, the implementation might not deallocate
     that non-heap memory, which can cause a subsequent call to
     `create-image' to fail because it is unable to allocate enough
     memory.

 - procedure: image/height image
     Returns the height of the image in device coordinates.

 - procedure: image/width image
     Returns the width of the image in device coordinates.

 - procedure: image/fill-from-byte-vector image bytes
     The contents of IMAGE are set in a device-dependent way, using one
     byte per pixel from BYTES (a string).  Pixels are filled row by
     row from the top of the image to the bottom, with each row being
     filled from left to right.  There must be at least `(*
     (image/height IMAGE) (image/width IMAGE))' bytes in BYTES.

X Graphics
==========

   MIT Scheme supports graphics in the X window system (version 11).
Arbitrary numbers of displays may be opened, and arbitrary numbers of
graphics windows may be created for each display.  A variety of
operations is available to manipulate various aspects of the windows, to
control their size, position, colors, and mapping.  The X graphics
device type supports images, which are implemented as Xlib `XImage'
objects.  X display, window, and image objects are automatically closed
if they are reclaimed by the garbage collector.

X Graphics Type
---------------

   A graphics device for X windows is created by passing the symbol `x'
as the graphics device type name to `make-graphics-device':

     (make-graphics-device 'x #!optional DISPLAY GEOMETRY SUPPRESS-MAP?)

where DISPLAY is either a display object, `#f', or a string; GEOMETRY
is either `#f' or a string; and SUPPRESS-MAP?  is a boolean or a vector
(see below).  A new window is created on the appropriate display, and a
graphics device representing that window is returned.

   DISPLAY specifies which X display the window is to be opened on; if
it is `#f' or a string, it is passed as an argument to
`x-open-display', and the value returned by that procedure is used in
place of the original argument.  GEOMETRY is an X geometry string, or
`#f' which means to use the default geometry (which is specified as a
resource).

   SUPPRESS-MAP?, if given, may take two forms.  First, it may be a
boolean: if `#f' (the default), the window is automatically mapped
after it is created; otherwise, `#t' means to suppress this automatic
mapping.  The second form is a vector of three elements.  The first
element is a boolean with the same meaning as the boolean form of
SUPPRESS-MAP?.  The second element is a string, which specifies an
alternative resource name to be used for looking up the window's
resources.  The third element is also a string, which specifies a class
name for looking up the window's resources.  The default value for
SUPPRESS-MAP? is `#f'.

   The default resource and class names are `"schemeGraphics"' and
`"SchemeGraphics"' respectively.

   The window is initialized using the resource and class names
specified by SUPPRESS-MAP?, and is sensitive to the following resource
properties:

     Property        Class           Default
     --------        -----           -------
     geometry        Geometry        512x384+0+0
     font            Font            fixed
     borderWidth     BorderWidth     2
     internalBorder  BorderWidth     [border width]
     background      Background      white
     foreground      Foreground      black
     borderColor     BorderColor     [foreground color]
     cursorColor     Foreground      [foreground color]
     pointerColor    Foreground      [foreground color]

   The window is created with a `backing_store' attribute of `Always'.
The window's name and icon name are initialized to `"scheme-graphics"'.

Utilities for X Graphics
------------------------

 - procedure: x-graphics/open-display display-name
     Opens a connection to the display whose name is DISPLAY-NAME,
     returning a display object.  If unable to open a connection, `#f'
     is returned.  DISPLAY-NAME is normally a string, which is an X
     display name in the usual form; however, `#f' is also allowed,
     meaning to use the value of the unix environment variable
     `DISPLAY'.

 - procedure: x-graphics/close-display display
     Closes DISPLAY; after calling this procedure, it is an error to
     use DISPLAY for any purpose.  Any windows that were previously
     opened on DISPLAY are destroyed and their resources returned to
     the operating system.

 - procedure: x-close-all-displays
     Closes all open connections to X displays.  Equivalent to calling
     `x-close-display' on all open displays.

 - procedure: x-geometry-string x y width height
     This procedure creates and returns a standard X geometry string
     from the given arguments.  X and Y must be either exact integers or
     `#f', while WIDTH and HEIGHT must be either exact non-negative
     integers or `#f'.  Usually either X and Y are both specified or
     both `#f'; similarly for WIDTH and HEIGHT.  If only one of the
     elements of such a pair is specified, it is ignored.

     Examples:

          (x-geometry-string #f #f 100 200) => "100x200"
          (x-geometry-string 2 -3 100 200) => "100x200+2-3"
          (x-geometry-string 2 -3 #f #f) => "+2-3"

     Note that the X and Y arguments cannot distinguish between `+0'
     and `-0', even though these have different meanings in X.  If
     either of those arguments is `0', it means `+0' in X terminology.
     If you need to distinguish these two cases you must create your
     own geometry string using Scheme's string and number primitives.