Initial revision

diff --git a/v7/doc/ref-manual/pictures.texinfo b/v7/doc/ref-manual/pictures.texinfo
new file mode 100644 (file)
index 0000000..64033fa
--- /dev/null
+++ b/v7/doc/ref-manual/pictures.texinfo
@@ -0,0 +1,146 @@
+@node Pictures,  , Starbase Graphics, Graphics
+@section Pictures (MIT 6.001 implementation only)
+
+@cindex pictures
+A @dfn{picture} data object is a two-dimensional array of real numbers
+that represents a grey-scale image on the screen.  The grey level that
+the value of each element represents is determined relative to the range
+of values of the array.
+
+The width of a picture is the number of elements in each row and the
+height is the number of elements in each column.  The elements are
+referenced by giving the horizontal component first and the vertical one
+second, with the origin at the bottom left corner of the displayed
+picture.
+
+Coordinates (@var{i}, @var{j}) are @dfn{valid coordinates} of picture
+@var{p} if and only if:
+
+@example
+@group
+(and (exact-nonnegative-integer? @var{i})
+     (exact-nonnegative-integer? @var{j})
+     (< @var{i} (picture-width @var{p}))
+     (< @var{j} (picture-height @var{p})))
+@end group
+@end example
+
+@menu
+* Construction of Pictures::    
+* Manipulating Pictures::       
+* Displaying Pictures::         
+* Saving and Restoring Pictures::  
+@end menu
+
+@node Construction of Pictures, Manipulating Pictures,  , Pictures
+@subsection Construction of Pictures
+
+@code{make-picture} and @code{procedure->picture} are simple ways to
+make pictures.  @code{picture-map} is a way to create a new picture by
+applying a procedure to one or more pictures.  Pictures can also be made
+by reading files: see @code{pgm-file->picture}.
+
+@deffn {procedure+} make-picture x y [k]
+@var{X} and @var{y} must be exact positive integers and @var{k}, if
+specified, must be a real number.  Returns a picture of width @var{x}
+and height @var{y}.  If @var{k} is specified then each picture element
+is initialized to @var{k}, otherwise the elements are unspecified.
+@end deffn
+
+@deffn {procedure+} procedure->picture x y f
+@var{X} and @var{y} must be exact positive integers, and @var{f} must be
+a real-valued procedure of two variables.  Returns a picture of width
+@var{x} and height @var{y}, where the value of each element is the
+result of applying @var{f} to the element's coordinates.
+@end deffn
+
+@deffn {procedure+} picture-map f picture @dots{}
+@var{F} must be a procedure, and all of the @var{picture} arguments must
+have the same dimensions.  Returns a newly allocated picture, each
+element of which is obtained by calling @var{f}, passing it as arguments
+the corresponding element of each @var{picture} argument.  (Thus @var{f}
+must accept the same number of arguments as there are @var{picture}
+arguments to @code{picture-map}.)
+
+In other words, each element could have been initialized as follows:
+
+@example
+@group
+(picture-set! @var{result} @var{i} @var{j}
+              (@var{f} (picture-ref @var{picture} @var{i} @var{j}) @dots{}))
+@end group
+@end example
+@end deffn
+
+@node Manipulating Pictures, Displaying Pictures, Construction of Pictures, Pictures
+@subsection Manipulating Pictures
+
+@deffn {procedure+} picture? object
+Returns @code{#t} if @var{object} is a picture, otherwise returns
+@code{#f}.
+@end deffn
+
+@deffn {procedure+} picture-width picture
+@deffnx {procedure+} picture-height picture
+These procedures return the width and height, respectively, of
+@var{picture}.
+@end deffn
+
+@deffn {procedure+} picture-min picture
+@deffnx {procedure+} picture-max picture
+These procedures return, respectively, the least and the greatest values
+stored in @var{picture}.
+@end deffn
+
+@deffn {procedure+} picture-ref picture i j
+Returns the value of element (@var{i},@var{j}) of @var{picture} (always
+a real number).  @var{I} and @var{j} must be valid coordinates for
+@var{picture}.
+@end deffn
+
+@deffn {procedure+} picture-set! picture i j k
+Stores @var{k} at element (@var{i},@var{j}) in @var{picture} and returns
+an unspecified value.  @var{K} must be a real number and @var{I} and
+@var{j} must be valid coordinates for @var{picture}.
+@end deffn
+
+@node Displaying Pictures, Saving and Restoring Pictures, Manipulating Pictures, Pictures
+@subsection Displaying Pictures
+
+To display pictures, an X graphics window must first be created.
+Although any window may be used, the colormap will not be guaranteed to
+be correct for grey-scale pictures, therefore the recommended way of
+creating windows for displaying pictures is to use the
+@code{make-window} procedure.
+
+@deffn {procedure+} picture-display w picture [min [max]]
+Displays, in the graphics device @var{w}, the largest integer scaling of
+@var{picture} that can be contained in @var{w}.  If @var{min} and
+@var{max} are specified then the grey levels will be computed using
+these values as @var{picture}'s minimum and maximum values, otherwise
+the actual least and greatest values of @var{picture} will be used.  The
+value returned by this procedure is unspecified.
+@end deffn
+
+@deffn {procedure+} make-window w h x y
+Returns a graphics device of width @var{w}, height @var{h} and screen
+position @var{x},@var{y} (as would be given in an X geometry string)
+with a grey-scale colormap attached.
+@end deffn
+
+@node Saving and Restoring Pictures,  , Displaying Pictures, Pictures
+@subsection Saving and Restoring Pictures
+
+Pictures can be read from or written to files in @sc{pgm} format using
+the following procedures.
+
+@deffn {procedure+} pgm-file->picture pathname
+Reads a grey-scale image stored in @sc{pgm} format from the file
+@var{pathname}, returning a picture whose graphical representation will
+closely resemble that of the saved image.
+@end deffn
+
+@deffn {procedure+} picture->pgm-file picture pathname
+Saves @var{picture} in @sc{pgm} format in the file @var{pathname}.
+Overwrites any previously existing file of that name.
+@end deffn