File: Graphics.tex

package info (click to toggle)
hugs 1.4.199801-1
links: PTS
area: non-free
in suites: slink
size: 7,220 kB
ctags: 5,609
sloc: ansic: 32,083; haskell: 12,143; yacc: 949; perl: 823; sh: 602; makefile: 236
file content (1480 lines) | stat: -rw-r--r-- 44,122 bytes
%**<title> The Hugs Graphics Library </title>
%**<body bgcolor="#ffffff">
%**<h2>The Hugs Graphics Library (Draft)</h2>
%**<font size=4> <blockquote>
%**Alastair Reid<br>
%**Department of Computer Science<br>
%**New Haven, CT 06520<br>
%**reid-alastair@cs.yale.edu<br>
%**</blockquote></font>
%*ignore
\documentstyle[11pt]{article}

% copied from the Haskore tutorial
\textheight=8.5in
\textwidth=6.5in
\topmargin=-.3in
\oddsidemargin=0in
\evensidemargin=0in
\parskip=6pt plus2pt minus2pt

% and some of my own personal preferences
\parindent=0in

\newcommand{\var}[1]{{\tt #1\/}}    % variables
\newcommand{\fun}[1]{{\tt #1\/}}    % functions
\newcommand{\expr}[1]{{\tt #1\/}}   % expressions
\newcommand{\type}[1]{{\tt #1\/}}   % types
\newcommand{\module}[1]{{\tt #1\/}} % modules
%\newcommand{\modName}[1]{\item[module #1]:}
\newcommand{\modName}[1]{\subsection{Module {#1}}}

\newcommand{\tva}{$\alpha$} % type variables
\newcommand{\tvb}{$\beta $}
\newcommand{\tvc}{$\gamma$}

\newcommand{\arrow}{$\enspace\to\enspace$} % type constructors

\newcommand{\Hugs}{{\bf Hugs\/}}
\newcommand{\GHC}{{\bf GHC\/}}
\newcommand{\Haskell}{{\bf Haskell\/}}

\newenvironment{aside}{%
  \medbreak
  \noindent
  {\bf Aside: }
  \begingroup
    \sl
    \begin{indent}  % why doesn't this do what I expect?
}{%
    \end{indent}
  \endgroup
  \par
  {\bf End aside.}
  \medbreak
}

\newenvironment{note}{%
  \medbreak
  \noindent
  {\bf Note: }
  \begingroup
    \sl
    \begin{indent}  % why doesn't this do what I expect?
}{%
    \end{indent}
  \endgroup
  \par
  {\bf End note.}
  \medbreak
}

\newcommand{\Portability}[1]{\par{{\bf Portability Note:} \sl #1}\par}

% These are used for reminders, communication between authors, etc.
% There should be no calls to these guys in the final document.

\newcommand{\HeyPaul}[1]{\par{{\bf Hey Paul:} \sl #1}\par}
\newcommand{\ToDo}[1]{\par{{\bf ToDo:} \sl #1}\par}

\newenvironment{outline}{%
  \medbreak
  \noindent
  {\bf Outline: }
  \begingroup
    \nobreak
    \sl
}{%
  \endgroup
  \nobreak
  {\bf End outline.}
  \medbreak
}

% Here's how you create figures
%
% \begin{figure*}
% \centerline{
% Foo
% }
% \caption{...}
% \label{...}
% \end{figure*}

\begin{document}

\title{%
  The Hugs Graphics Library\\
  (Draft)%
}

\author{Alastair Reid\\
Yale University\\
Department of Computer Science\\
New Haven, CT 06520\\
{\tt reid-alastair@cs.yale.edu}}

\date{1 April, 1997}

\maketitle

%*endignore

\section{Introduction}\label{introduction}

The Hugs Graphics Library is designed to give the programmer access to
most interesting parts of the Win32 Graphics Device Interface without
exposing the programmer to the pain and anguish usually associated
with using this interface.

To give you a taste of what the library looks like, here is the 
obligatory ``Hello World'' program:

\begin{verbatim}
> module Hello where
>
> import Graphics
>
> helloWorld :: IO ()
> helloWorld = runGraphics (do
>         w <- openWindow "Hello World Window" (300, 300)
>         draw w (text (100, 100) "Hello")
>         draw w (text (100, 200) "World")
>         getKey w
>         closeWindow w
>         )
\end{verbatim}

Here's what each function does:
\begin{itemize}
\item
  \expr{runGraphics :: IO () -> IO ()} get \Hugs{} ready to do graphics,
  runs an action (here, the action is a sequence of 4 subactions) and
  cleans everything up at the end.%
  %
  \footnote{%
    The description of
    \fun{runGraphics} is rather vague because of our promise to protect
    you from the full horror of Win32 programming.  If you really want to
    know, we highly recommend Charles Petzold's book ``Programming Windows
    95'' which does an excellent job with a difficult subject.%
  }
  %

\item
  \expr{openWindow :: String -> Point -> IO Window} opens a window 
  specifying the window title ``Hello World Window'' and the size
  of the window (300 pixels $\times$ 300 pixels).

\item
  \expr{draw :: Window -> Picture -> IO ()} draws a \type{Picture}
  on a \type{Window}.

\item
  \expr{text :: Point -> String -> Picture} creates a \type{Picture}
  consisting of a \type{String} at a given screen location. 

\item
  \expr{getKey :: Window -> IO ()} waits for the user to press
  (and release) a key.  This is necessary to prevent the window
  from closing before you have a chance to read what's on the screen.

\item
  \expr{closeWindow :: Window -> IO ()} closes the window.

\end{itemize}

The rest of this document is organised as follows:
\begin{itemize}
\item Section~\ref{pictures} describes \type{Picture}s.
\item Section~\ref{windows} describes \type{Window}s.
\item Section~\ref{events} describes \type{Event}s.
\item Section~\ref{concurrency} describes the Concurrent Haskell
      primitives which you need to create complex interfaces.
\end{itemize}

% \begin{note}
% This document is just a draft --- it contains British spelling (which
% conflicts horribly with the US spelling used within the library); it
% is incomplete; and it probably contains the occasional error as well.
% \end{note}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Pictures}\label{pictures}

In section~\ref{introduction}, we used these two functions to draw 
to a window

\begin{verbatim}
> draw :: Window -> Picture -> IO ()
> text :: Point  -> String  -> Picture
\end{verbatim}

This section describes other ways of creating pictures that can be
drawn to the screen.

\subsection{Primitive Pictures}\label{primitives}

Here's a list of the primitive operations

\begin{verbatim}
> empty        :: Picture
> ellipse      :: Point -> Point          -> Picture
> shearEllipse :: Point -> Point -> Point -> Picture
> line         :: Point -> Point          -> Picture
> polyline     :: [Point] -> Picture
> polygon      :: [Point] -> Picture
> polyBezier   :: [Point] -> Picture
> text         :: Point -> String -> Picture
\end{verbatim}

\fun{empty} is a blank \type{Picture}.

\fun{ellipse} is a filled ellipse which fits inside a rectangle defined by two
\type{Point}s on the window. \fun{shearEllipse} is a filled ellipse
inside a parallelogram defined by three \type{Point}s on the window.
\ToDo{Is there a way to draw unfilled ellipses?}

\fun{line} is a line between two \type{Point}s.  \fun{polyline}
is a series of lines through a list of \type{Point}s.
\fun{polyBezier} is a series of (unfilled) bezier curves defined by
a list of $3n+1$ control \type{Point}s.
\fun{polygon} is a filled polygon defined by a list of \type{Point}s.

\fun{text} is a rendered \type{String}.

\subsection{Picture Modifiers}\label{modifiers}

One of the most useful properties of \type{Picture}s is that they can
be modified in various ways.  Here is a selection of the modifiers
available

\begin{verbatim}
> withFont          :: Font      -> Picture -> Picture
> withTextColor     :: RGB       -> Picture -> Picture
> withTextAlignment :: Alignment -> Picture -> Picture
> withBkColor       :: RGB       -> Picture -> Picture
> withBkMode        :: BkMode    -> Picture -> Picture
> withPen           :: Pen       -> Picture -> Picture
> withColor         :: RGB       -> Picture -> Picture
> withBrush         :: Brush     -> Picture -> Picture
\end{verbatim}

The effect of these ``modifiers'' is to modify the way in which a
picture will be drawn.  For example, if \var{courier :: Font} is a 10
point Courier font, then drawing \expr{withFont courier (text (100,100)
"Hello")} will draw the string \expr{"Hello"} on the window using the
10 point Courier font.

Modifiers are cumulative: a series of modifiers can be applied to a
single picture.  For example, the picture
  
\begin{verbatim}
> withFont courier (
>   withTextColor red (
>     withTextAlignment (Center, Top) (
>       text (100,100) "Hello World"
>     )
>   )
> )
\end{verbatim}

will be 

\begin{itemize}
\item horizontally aligned
  so that the centre of the text is at \expr{(100, 100)};

\item vertically aligned
  so that the top of the text is at \expr{(100, 100)};

\item coloured red

\item displayed in 10 point Courier font

\end{itemize}

Modifiers nest in the obvious way --- so 
%
\begin{verbatim}
> withTextColor red (
>   withTextColor green (
>     text (100,100) "What Colour Am I?"
>   )
> )
\end{verbatim}
%
will produce green text, as expected.

\begin{aside}

As you write more and more complex pictures, you'll quickly realise
that it's very tedious to insert all those parentheses and to keep
everything indented in a way that reveals its structure.

Fortunately, the Haskell Prelude provides a right associative 
application operator
%
\begin{verbatim}
> ($) :: (a -> b) -> a -> b
\end{verbatim}
%
which eliminates the need for almost all parentheses when defining
pictures.  Using the \fun{(\$)} operator, the above example can
be rewritten like this
%
\begin{verbatim}
> withTextColor red   $
> withTextColor green $
> text (100,100) "What Colour Am I?"
\end{verbatim}
%

\end{aside}

\subsection{Combining Pictures}

The other useful property of \type{Picture}s is that they can be
combined using the \fun{over} combinator

\begin{verbatim}
> over :: Picture -> Picture -> Picture
\end{verbatim}

For example, drawing this picture produces a red triangle ``on top of''
(or ``in front of'') a blue square
%
\begin{verbatim}
> over
>   (withBrush red  $ polygon [(200,200),(400,200),(300,400)])
>   (withBrush blue $ polygon [(100,100),(500,100),(500,500),(100,500)])
\end{verbatim}

Notice that modifiers respect the structure of a picture --- modifiers
applied to one part of a picture have no effect on other parts of
the picture.  For example the above picture could be rewritten like
this.
%
\begin{verbatim}
> withBrush blue $ 
> over
>   (withBrush red  $ polygon [(200,200),(400,200),(300,400)])
>   (polygon [(100,100),(500,100),(500,500),(100,500)])
\end{verbatim}

The \fun{overMany} function is useful if you want to draw a list of
pictures.  It's type and definition are

\begin{verbatim}
> overMany :: [Picture] -> Picture
> overMany = foldr over empty
\end{verbatim}

Notice that pictures at the head of the list are drawn ``in front of'' 
pictures at the tail of the list.


\subsection{Attribute Generators}\label{generators}

The picture modifiers listed at the start of Section~\ref{modifiers}
use attributes with types like \type{Font}, \type{RGB} and
\type{Brush}, but so far we have no way of generating any of these attributes.

Some of these types are {\em concrete\/} (you can create them using
normal data constructors) and some are {\em abstract\/} (you can only create
them with special ``attribute generators'').  Here's the definitions
of the concrete types.

\begin{verbatim}
> type Angle     = Double
> type Dimension = Int
> type Point     = (Dimension,Dimension)
> data RGB       = RGB Int Int Int
> 
> -- Text alignments
> type Alignment = (HAlign, VAlign)
> -- names have a tick to distinguish them from Prelude names (blech!)
> data HAlign = Left' | Center   | Right'
> data VAlign = Top   | Baseline | Bottom
> 
> -- Text background modes
> data BkMode = Opaque | Transparent
\end{verbatim}

The attributes \type{Font}, \type{Brush} and \type{Pen} are
{\em abstract,\/} and are a little more complex because we want to 
delete the font, brush, or pen once we've finished using it.  This
gives the attribute generators a similar flavour to the modifiers seen
in section~\ref{modifiers} --- these functions are applied to an
argument of type \type{\tva \arrow Picture} and return a
\type{Picture}.

%
\begin{verbatim}
> mkFont  :: Point -> Angle -> Bool -> Bool -> String -> 
>                                   (Font  -> Picture) -> Picture
> mkBrush ::                 RGB -> (Brush -> Picture) -> Picture
> mkPen   :: Style -> Int -> RGB -> (Pen   -> Picture) -> Picture
\end{verbatim}

For example, the following program uses a $50 \times 50$ pixel, non-bold,
italic, Arial font to draw red text on a green background at an angle
of 45 degrees across the screen.

\begin{verbatim}
> fontDemo = runGraphics $ do
>   w <- openWindow "Font Demo Window" (5,5)
>   draw w $
>     withTextColor (RGB 255 0 0)               $
>     mkFont (50,100) (pi/4) False True "Arial" $ \ font ->
>     withFont font                             $
>     withBkColor (RGB 0 255 0)                 $
>     withBkMode  Opaque                        $
>     text (0.5,4.5) "Font Demo"
>   getKey w
>   closeWindow w
\end{verbatim}

A default font is substituted if the requested font does not exist.
The rotation angle is ignored if the font is not a ``TrueType'' font
(eg for {\tt System} font).



\subsection{Brushes, Pens and Text Colors}

If you were counting, you'll have noticed that there are five separate
ways of specifying colors

\begin{verbatim}
> mkBrush       ::                 RGB -> (Brush -> Picture) -> Picture
> mkPen         :: Style -> Int -> RGB -> (Pen   -> Picture) -> Picture
> withTextColor ::                 RGB -> Picture            -> Picture
> withBkColor   ::                 RGB -> Picture            -> Picture
> withRGB       ::                 RGB -> Picture            -> Picture
\end{verbatim}

What do these different modifiers and attributes control?

\begin{description}
\item[Brushes] 
  are used when filling shapes --- so the brush colour is
  used when drawing polygons, ellipses and regions.

\item[Pens]
  are used when drawing lines --- so the pen colour is used
  when drawing lines, polylines and polyBeziers.
  Surprisingly, the pen is also used to draw a line round all
  the filled shapes --- so the pen colour also affects how
  polygons, ellipses and regions are drawn.

  Pens also have a ``style'' and a ``width''.  The \type{Style}
  argument is used to select solid lines or various styles of
  dotted and dashed lines.

\begin{verbatim}
> data Style
>   = Solid 
>   | Dash        -- "-------"
>   | Dot         -- "......."  
>   | DashDot     -- "_._._._"  
>   | DashDotDot  -- "_.._.._"  
>   | Null
>   | InsideFrame
\end{verbatim}

  One of the Win32 ``gotchas'' is that the choice of \type{Style}
  only applies if the width is 1 or less.  With greater widths,
  the pen style will always be \fun{Solid} no matter what you try to
  select.

\ToDo{%
  Should I split \fun{mkPen} into two separate functions?
  One to do wide pens and one to do patterned pens?%
}


\item[TextColor]
  is used as the foreground colour when drawing text.

\item[BkColor]
  is used as the background colour when drawing text with
  background mode \fun{Opaque}.  The background colour is
  ignored when the mode is \fun{Transparent}.
  
  \ToDo{Should I expand the name \type{BkColor} to \type{BackgroundColor}?}

\end{description}

Finally, \fun{withRGB} is a convenience function which sets the brush,
pen and text colors to the same value.  Here is its definition

\begin{verbatim}
> withRGB :: RGB -> Picture -> Picture
> withRGB c p = 
>   mkBrush c       $ \ brush ->
>   withBrush brush $
>   mkPen Solid 2 c $ \ pen ->
>   withPen pen     $
>   withTextColor c $
>   p
\end{verbatim}

\subsection{Named Colours}

Working with RGB triples is a pain in the neck so the
\module{GraphicsColor} module provides these built in colours as
convenient ``abbreviations.''

\begin{verbatim}
> data Color 
>   = Black
>   | Blue
>   | Green 
>   | Cyan
>   | Red 
>   | Magenta
>   | Yellow
>   | White
>  deriving (Eq, Ord, Bounded, Enum, Ix, Show, Read)
\end{verbatim}

This type is useful because it may be used to index an array of
RGB triples.

\begin{verbatim}
> colorTable :: Array Color RGB
\end{verbatim}

For example, we provide this function which looks up a colour in the
\var{colorTable} and uses that colour for the brush, pen and text colour.

\begin{verbatim}
> withColor :: Color -> Picture -> Picture
\end{verbatim}

It's worth pointing out that there's nothing ``magical'' about the
\type{Color} type or our choice of colours.  If you don't like our
choice of colours, our names, or the way we mapped them onto RGB
triples, you can write your own!  To get you started, here's our
implementation of \fun{withColor} and \var{colorTable}.

\begin{verbatim}
> withColor c = withRGB (colorTable ! c)
> 
> colorTable = array (minBound, maxBound) colorList
> 
> colorList  :: [(Color, RGB)]
> colorList =
>   [ (Black   , RGB   0   0   0)
>   , (Blue    , RGB   0   0 255)
>   , (Green   , RGB   0 255   0)
>   , (Cyan    , RGB   0 255 255)
>   , (Red     , RGB 255   0   0)
>   , (Magenta , RGB 255   0 255)
>   , (Yellow  , RGB 255 255   0)
>   , (White   , RGB 255 255 255)
>   ]
\end{verbatim}


\subsection{Bitmaps}

\type{Bitmap}s can be displayed in three ways:

\begin{enumerate}
\item with no transformation at  a point
\item stretched to fit           a rectangle
\item rotated and sheared to fit a parallelogram
\end{enumerate}

Rectangles are specified by a pair of points: the top-left, and
bottom-right corners of the rectangle.

\begin{verbatim}
> bitmap        :: Point                      -> Bitmap -> Picture
> stretchBitmap :: Point  -> Point            -> Bitmap -> Picture
> shearBitmap   :: Point  -> Point  -> Point  -> Bitmap -> Picture
\end{verbatim}

\Portability{\fun{shearBitmap} is not supported on Win'95.}

\type{Bitmap}s are read in from files and disposed of using 
\begin{verbatim}
> readBitmap    :: String -> IO Bitmap
> deleteBitmap  :: Bitmap -> IO ()
\end{verbatim}
(but be sure that the current \type{Picture} on a \type{Window}
doesn't contain a reference to a \type{Bitmap} before you delete the
\type{Bitmap}!)

This operation gets the size of a bitmap.
\begin{verbatim}
> getBitmapSize :: Bitmap -> IO (Int, Int)
\end{verbatim}

\ToDo{%
  Describe the other bitmap operations 
  --- clean them up a bit first though!%
}

\subsection{Regions}


The most complicated graphics objects are \type{Region}s.
\type{Regions} can be viewed as sets of pixels on the screen.
They are created from rectangles, ellipses, polygons and combined
using set operations (union, intersection, difference and xor).

The main difficulty is that, in order to make sure that \type{Region}s
are allocated and deallocated correctly, all \type{Region} operations
have a type of the form 

\type{\tva \arrow (Region \arrow Picture) \arrow Picture}

That is, all \type{Region} operations are applied to a
``continuation'' which will use the \type{Region} to generate a
\type{Picture}.

These are the operations available

\begin{verbatim}
> mkEmpty     ::                     (Region -> Picture) -> Picture
> mkRectangle :: Point -> Point   -> (Region -> Picture) -> Picture
> mkEllipse   :: Point -> Point   -> (Region -> Picture) -> Picture
> mkPolygon   :: [Point]          -> (Region -> Picture) -> Picture
> 
> andRegion   :: Region -> Region -> (Region -> Picture) -> Picture
> orRegion    :: Region -> Region -> (Region -> Picture) -> Picture
> xorRegion   :: Region -> Region -> (Region -> Picture) -> Picture
> diffRegion  :: Region -> Region -> (Region -> Picture) -> Picture
> 
> region      :: Region -> Picture
\end{verbatim}

\ToDo{Should the combining operations have more setlike names?}

\Portability{%
  We'd like to port most of this library over to X11; however, we 
  suspect that the \type{Region} operations will be hard to port.%
}


\subsection{The \type{Picture} Algebra}

The Picture modifiers satisfy a large number of useful identities.
For example, 

\begin{itemize}
\item
  The triple $\langle \type{Picture}, \fun{over}, \fun{empty} \rangle$
  forms a ``monoid.'' If this wasn't true, we wouldn't find the
  \fun{overMany} function very useful.

\item
  Modifiers and generators all distribute over \fun{over}.
  That is,
\begin{verbatim}
> mkFoo <args> (p1 `over` p2) = (mkFoo <args> p1) `over` (mkFoo <args> p2)
> withFoo foo  (p1 `over` p2) = (withFoo foo  p1) `over` (withFoo foo  p2)
\end{verbatim}

(These laws are especially useful when trying to make programs more efficient
--- see section~\ref{efficiency}.)

\item
  ``Independent'' modifiers commute with each other.
  For example,
\begin{verbatim}
> withTextColor c (withTextAlignment a p) = withTextAlignment a (withTextColor c p)
\end{verbatim}

\item
  Generators commute with modifiers.
  For example,
\begin{verbatim}
> mkBrush c (\ b -> withBrush b' p) = withBrush b' mkBrush c (\ b -> p)
\end{verbatim}
  if \var{b} and \var{b'} are distinct.

\item
  Generators commute with other generators.  For example

\begin{verbatim}
> mkBrush c (\ b -> mkBrush c' (\ b' -> p)) = mkBrush c' (\ b' -> mkBrush c (\ b -> p))
\end{verbatim}
  if \var{b} and \var{b'} are distinct.

\item
  ``Irrelevant'' modifiers and generators can be added or removed at will.
  For example, the text colour has no effect on line drawing
\begin{verbatim}
> withTextColor c (line p0 p1) = line p0 p1
\end{verbatim}
  and there's no need to create a brush if you don't use it
\begin{verbatim}
> mkBrush c (\ b -> p) = p, if b does not occur in p
\end{verbatim}

(This last law can also be stated in the form
\begin{verbatim}
> mkBrush c (\ b -> prim) = prim
\end{verbatim}
for any primitive operation.)

\end{itemize}

\ToDo{%
  Add tables describing which modifiers are relevant and which
  ones are independent.  Or just list all the identities.%
}

The practical upshot of all this is that there are many ways to
rearrange a picture so that it will be drawn more (or less)
efficiently.  We explore this topic in the next section.


\subsection{Efficiency Considerations}\label{efficiency}

The other sections provide a very simple set of functions for creating
pictures --- but at the cost of ignoring efficiency.  For example, this
innocent looking picture

\begin{verbatim}
> overMany
>   [ withColor Red $ ellipse (000,000) (100,100)
>   , withColor Red $ ellipse (100,100) (200,200)
>   , withColor Red $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

will take about 10 times as long to draw as this equivalent picture

\begin{verbatim}
> mkBrush (colorTable ! Red) $ \ redBrush  ->
> overMany
>   [ withBrush redBrush $ ellipse (000,000) (100,100)
>   , withBrush redBrush $ ellipse (100,100) (200,200)
>   , withBrush redBrush $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

Briefly, the problems are that \fun{withColor} sets the colour of the
brush, the pen and the text but ellipses only use the brush colour;
and we're calling \fun{withColor} $3$ times more than we have to.
This wouldn't matter if brush creation was cheap and easy.  However,
most typical workstations can only display at most $256$ or $65536$
different colours on the screen at once but allow you to specify any
one of $16777216$ different colours when selecting a drawing colour
--- finding a close match to the requested colour can be as
expensive as drawing the primitive object itself.

\ToDo{%
  Time both pictures --- check that my estimate is about right.%
}

This doesn't matter much for a picture of this size --- but if you're
drawing several thousand picture elements onto the screen as part of
an animation, it can make the difference between a quite respectable
frame rate of 20--30 frames per second and an absolutely unusable
frame rate of 2--3 frames per second.

\begin{aside}

The (lazy) functional programming community has a bad habit of
ignoring these kinds of considerations; with the result that C
programmers have acquired the notion that functional programs will
{\em necessarily\/} run {\em several orders of magnitude\/} more
slowly than equivalent C programs.  On the basis of this notion, 
they {\em quite rightly\/} regard functional languages as toys which
have no relevance to Real Programming.

We'd like to dispel that belief and so, in designing the graphics
library, we have made a serious attempt to expose enough of the
underlying machinery that we can tackle this sort of efficiency
consideration.

That said, it's worth emphasising that \Hugs{} is an interpreter which
makes it run 10--100 times more slowly than compiled implementations
of \Haskell{} such as \GHC{}.  If you really are wanting to animate
thousands of objects, you probably shouldn't be relying on \Hugs{}.

\end{aside}


\subsection{Eliminate calls to \fun{withRGB} and \fun{withColor}}

At the risk of pointing out the obvious, the first step in optimising
a program in this way is to expand all uses of the \fun{withRGB} and
\fun{withColor} functions and eliminating unnecessary calls to
\fun{mkBrush}, \fun{mkPen} and \fun{withTextColor}.  Applying this
optimisation to the above \type{Picture}, we obtain this (which should run
about 3 times faster).

\begin{verbatim}
> overMany
>   [ mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (000,000) (100,100)
>   , mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (100,100) (200,200)
>   , mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

\subsection{Lifting generators to the top of \type{Pictures}}


Another important optimisation is to avoid creating many identical
brushes, pens or fonts when one will do.  We do this by ``lifting''
brush creation out to the top of a picture.  For example, this picture

\begin{verbatim}
> overMany
>   [ mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (000,000) (100,100)
>   , mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (100,100) (200,200)
>   , mkBrush red $ \ redBrush -> withBrush redBrush $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

creates three red brushes.  It would be more efficient to rewrite it 
like this

\begin{verbatim}
> mkBrush red  $ \ redBrush  ->
> overMany
>   [ withBrush redBrush $ ellipse (000,000) (100,100)
>   , withBrush redBrush $ ellipse (100,100) (200,200)
>   , withBrush redBrush $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

If your program uses a lot of brushes, it may be more convenient to
store the brushes in a ``palette'' (ie an array of brushes)

\begin{verbatim}
> mkBrush red  $ \ redBrush  ->
> mkBrush blue $ \ blueBrush ->
> let palette = array (minBound, maxBound) 
>                     [(Red, redBrush), (Blue, blueBrush)]
> in
> overMany
>   [ withBrush (palette ! Red)  $ ellipse (000,000) (100,100)
>   , withBrush (palette ! Blue) $ ellipse (100,100) (200,200)
>   , withBrush (palette ! Red)  $ ellipse (200,200) (300,300)
>   ]
\end{verbatim}

\ToDo{%
  Write the obvious function with type
  \type{[RGB] -> ([Brush] -> Picture) -> Picture} 
  (and similarily, for Pens, Fonts, etc).%
}

\subsection{Lifting generators out of pictures}

Even this program has room for improvement: every time the picture is
redrawn (eg whenever the window is resized), it will create fresh
brushes with which to draw the picture.  The graphics library provides
a way round this --- but it's more difficult and fraught with danger.

\begin{outline}
This section will talk about using explicit creation and deletion
functions to create brushes, fonts, etc.

The situation isn't very happy at the moment because it's easy to
forget to deallocate brushes before you quit or to deallocate them
before you change the picture.  

Maybe things will be better by the time we do an official release...

\end{outline}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Windows}\label{windows}

In section~\ref{introduction} we saw the function \fun{draw} for
drawing a \type{Picture} on a \type{Window}.  It turns out that
\fun{draw} is not a primitive function but, rather, it is defined
using these two primitive functions which read the current
\type{Picture} and set a new \type{Picture}.

\begin{verbatim}
> getPicture   :: Window -> IO Picture
> setPicture   :: Window -> Picture -> IO ()
\end{verbatim}

Here's how these functions are used to define the function \fun{draw}
(which we used in section~\ref{introduction}) and another useful
function \fun{clearWindow}.

\begin{verbatim}
> draw         :: Window -> Picture -> IO ()
> draw w p = do
>         oldPicture <- getPicture w
>         setPicture w (p `over` oldPicture)
>
> clearWindow :: Window -> IO ()
> clearWindow w = setPicture w empty
\end{verbatim}


\section{Events}\label{events}

The graphics library supports several different input devices (the
mouse, the keyboard, etc) each of which can generate several different
kinds of event (mouse movement, mouse button clicks, key presses, key
releases, window resizing, etc.)


\subsection{Keyboard events}

In section~\ref{introduction} we saw the function \fun{getKey} being
used to wait until a key was pressed and released.  The function
\fun{getKey} is defined in terms of a more general function \fun{getKeyEx}

\begin{verbatim}
> getKeyEx     :: Window -> Bool -> IO Char
\end{verbatim}

which can be used to wait until a key is pressed (\expr{getKeyEx w True})
or until it is released (\expr{getKeyEx w False}).  The definition of
\fun{getKey} using this function is trivial:

\begin{verbatim}
> getKey       :: Window -> IO Char
> getKey w = do { getKeyEx w True; getKeyEx w False }
\end{verbatim}


\subsection{Mouse events}

As well as waiting for keyboard events, we can wait for mouse button
events.  We provide three functions for getting these events.
\fun{getLBP} and \fun{getRBP} are used to wait for left and right
button presses.  Both functions are defined using \fun{getButton}
which can be used to wait for either the left button or the right
button being either pressed or released.

\begin{verbatim}
> getLBP       :: Window -> IO Point
> getRBP       :: Window -> IO Point
> getButton    :: Window -> Bool -> Bool -> IO Point
>
> getLBP w = getButton w True  True
> getRBP w = getButton w False True
\end{verbatim}


\subsection{General events}

The functions \fun{getKeyEx} and \fun{getButton} described in the
previous sections are not primitive functions.  Rather they are
defined using the primitive function \fun{getEvent}

\begin{verbatim}
> getEvent     :: Window -> IO Event
\end{verbatim}

which waits for the next ``event'' on a given \type{Window}.
\type{Event}s are defined by the following data type.

\begin{verbatim}
> data Event 
>   = Key       { char :: Char, isDown :: Bool }
>   | Button    { pt :: Point, isLeft, isDown :: Bool }
>   | MouseMove { pt :: Point }
>   | Resize
>   | Closed
>  deriving Show 
\end{verbatim}

These events are:

\begin{itemize}
\item
  \expr{Key\{char, isDown\}} occurs when a key is pressed 
  (\expr{isDown==True})
  or released (\expr{isDown==False}).  \expr{char} is the ``keycode'' for the
  corresponding key.  This keycode can be a letter, a number or some other 
  value corresponding to the shift key, control key, etc.  

  \ToDo{%
    Say more about what the keycode is --- in the meantime, users will
    just have to try a few experiments to find out which code each key
    produces.%
  }

\item
  \expr{Button\{pt, isLeft, isDown\}} occurs when a mouse button is
  pressed (\expr{isDown==True}) or released (\expr{isDown==False}).
  \expr{pt} is the mouse position when the button was pressed and
  \expr{isLeft} indicates whether it was the left or the right button.

  \Portability{%
    When we support X11 as well, we'll have to change this
    datatype to support up to 5 buttons (with 3 being the usual number).%
  }

\item
  \expr{MouseMove\{pt\}} occurs when the mouse is moved inside the window.
  \expr{pt} is the position of the mouse after the movement.

\item
  \expr{Resize} occurs when the window is resized.
  The new window size can be discovered using these functions.

\begin{verbatim}
> windowRect   :: Window -> IO (Point, Point)
> windowSize   :: Window -> IO Point
\end{verbatim}

\item
  \expr{Resize} occurs when the window is closed.

\end{itemize}

\Portability{%
  Programmers should assume that this datatype will be extended in the
  not-too-distant future and that individual events may change slightly.
  As a minimum, you should add a ``match anything'' alternative to
  any function which pattern matches against \type{Event}s.%
}

As examples of how \fun{getEvent} might be used in a program, here are
the definitions of \fun{getKeyEx} and \fun{getButton}.

\begin{verbatim}
> getKeyEx     :: Window -> Bool -> IO Char
> getKeyEx w down = loop
>  where
>   loop = do
>         e <- getEvent w
>         case e of 
>         Key { char = c, isDown } 
>           |  isDown == down 
>           -> return c
>         _ -> loop
\end{verbatim}

\begin{verbatim}
> getButton    :: Window -> Bool -> Bool -> IO Point
> getButton w left down = loop
>  where
>   loop = do
>         e <- getEvent w
>         case e of 
>         Button {pt,isLeft,isDown} 
>           | isLeft == left && isDown == down
>           -> return pt
>         _ -> loop
\end{verbatim}

\subsection{Using Timers}

\Portability{%
  Timers are not very well integrated with the rest of the library at
  the moment.  We plan to improve this situation in future versions.%
}

If you want to use a timer, you have to open the window using
\fun{openWindowEx} instead of \fun{openWindow}

\begin{verbatim}
> openWindowEx :: String -> Maybe Point -> Maybe Point ->
>                 (Picture -> DrawFun) -> Maybe Int -> 
>                 IO Window
\end{verbatim}

This {\em extended\/} version of \fun{openWindow} takes extra parameters
which specify
\begin{itemize}
\item the initial position of a window;
\item how to display a picture on a window; and
\item the time between ticks (in milliseconds).
\end{itemize}

The drawing function can be either \fun{drawBufferedPicture} which
uses a ``double buffer'' to reduce flicker or \fun{drawPicture} which
draws directly to the window and runs slightly faster.  You should
probably use \fun{drawBufferedPicture} for animations.

The timer generates ``tick events'' at regular intervals.  The
function \fun{getTick} waits for the next ``tick event'' to occur.

\begin{verbatim}
> getTick      :: Window -> IO ()
\end{verbatim}

\begin{aside}
With normal events, like button presses, we store every event that
happens until you remove that event from the queue.  If we did this
with tick events, and your program takes a little too long to draw
each frame of an animation, the event queue could become so swamped
with ``ticks'' that you'd never respond to user input.  To avoid this
problem, we only insert a tick into the queue if there's no tick there 
already.
\end{aside}

Here's a simple example of how to use timers

\begin{verbatim}
timerDemo = do
  w <- openWindowEx 
         "Timer demo"         -- title
         (Just (500,500))     -- initial position of window
         (Just (100,100))     -- initial size of window
         drawBufferedPicture  -- draw function - see above
         (Just 50)            -- tick rate
  let
    loop x = do
      setPicture w $ text (0,50) $ show x
      getTick w            -- wait for next tick on window
      loop (x+1)
  loop 0
\end{verbatim}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Concurrent Haskell}\label{concurrency}

If you want to use multiple windows or each window contains a
number of essentially independent components, it is convenient
to use separate threads for handling each window.  \Hugs{}
provides a simple mechanism for doing that. 

The simplest concurrency primitives are \fun{par} and \fun{par\_}

\begin{verbatim}
> par  :: IO a -> IO b -> IO (a,b)
> par_ :: IO a -> IO b -> IO ()
\end{verbatim}

(These are both exported from the \module{MVar} module.)

These run two \type{IO} actions in parallel and terminate when both
actions terminate.  The function \fun{par\_} discards the results of
the actions.

\begin{aside}
The underscore in the name \fun{par\_} is derived from the use of
the underscore in the definition of \fun{par\_}.
 
\begin{verbatim}
> par_ p q = (p `par` q) >>= \ _ -> return ()
\end{verbatim}

This naming convention is also used in the Haskell Prelude and
standard libraries (\fun{mapM\_}, \fun{zipWithM\_}, etc.).
\end{aside}

The function \fun{parMany} generalises \fun{par\_} to lists.

\begin{verbatim}
> parMany :: [ IO () ] -> IO ()
> parMany = foldr par_ (return ())
\end{verbatim}

Of course, you'll quickly realise that there's not much point in being
able to create concurrent threads if threads can't communicate with
each other.  \Hugs{} provides an implementation of the ``Concurrent
Haskell'' primitives described in this paper

\begin{verbatim}
   "Concurrent Haskell"
   Simon Peyton Jones, Andrew Gordon and Sigbjorn Finne.
   In Proceedings of the ACM Symposium on Principles of Programming
   Languages,St Petersburg Beach, Florida, January 1996. 
   http://www.dcs.gla.ac.uk/fp/authors/Simon_Peyton_Jones/
     concurrent-haskell.ps
\end{verbatim}

to which we refer the enthusiastic reader.

\begin{aside}
Programmers should be aware that there is one significant difference
between \Hugs{} implementation of concurrency and \GHC{}s.

\begin{description}
\item[GHC]
  uses preemptive multitasking.

  Context switches can occur at any time (except if you call a C
  function (like "getchar") which blocks the entire process while
  waiting for input.

\item[Hugs]
  uses cooperative multitasking.  

  Context switches only occur when you use one of the primitives
  defined in this module.  This means that programs such as:

\begin{verbatim}
> main = forkIO (write 'a') >> write 'b'
>  where
>   write c = putChar c >> write c
\end{verbatim}

  will print either "aaaaaaaaaaaaaa..." or "bbbbbbbbbbbb..."
  instead of some random interleaving of 'a's and 'b's.

\end{description}

Cooperative multitasking is sufficient for writing coroutines and simple
graphical user interfaces. 
\end{aside}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Quick Reference}

This section consists of a quick summary of every module.

\ToDo{%
  It would be very cool to turn this appendix into an index
  containing the type of each function, the definition of 
  each transparent type and the page numbers on which it is
  discussed.  Sadly, I have no idea how to do it.%
}



% \begin{description}

\modName{GraphicsPicture}

\begin{verbatim}
> -- Reexports everything exported by the following modules:
> --
> --    GraphicsTypes
> --    GraphicsText
> --    GraphicsRGN
> --    GraphicsFont
> --    GraphicsBrush
> --    GraphicsPen
> --    GraphicsBitmap
> 
> empty        :: Picture
> over         :: Picture -> Picture -> Picture
> overMany     :: [Picture] -> Picture
> 
> ellipse      :: Point -> Point          -> Picture
> shearEllipse :: Point -> Point -> Point -> Picture
> line         :: Point -> Point          -> Picture
> 
> polyline     :: [Point] -> Picture
> polygon      :: [Point] -> Picture
> polyBezier   :: [Point] -> Picture
> 
> withRGB      :: RGB -> Picture -> Picture
\end{verbatim}

\modName{GraphicsTypes}

\begin{verbatim}
> type Angle     = Double
> type Dimension = Int
> type Point     = (Dimension,Dimension)
> 
> data RGB = RGB Int Int Int
> 
> type Picture = ...
\end{verbatim}

\modName{GraphicsText}

\begin{verbatim}
> type Alignment = (HAlign, VAlign)
> 
> -- names have a tick to distinguish them from Prelude names (blech!)
> data HAlign = Left' | Center   | Right'
> data VAlign = Top   | Baseline | Bottom
> 
> data BkMode = Opaque | Transparent
> 
> text              :: Point     -> String  -> Picture
> withTextColor     :: RGB       -> Picture -> Picture
> withTextAlignment :: Alignment -> Picture -> Picture
> withBkColor       :: RGB       -> Picture -> Picture
> withBkMode        :: BkMode    -> Picture -> Picture
\end{verbatim}

\modName{GraphicsFont}

\begin{verbatim}
> newtype Font = ...
> 
> mkFont     :: Point -> Angle -> Bool -> Bool -> String -> 
>               (Font -> Picture) -> Picture
> withFont   :: Font -> Picture -> Picture
> 
> createFont :: Point -> Angle -> Bool -> Bool -> String -> IO Font
> deleteFont :: Font -> IO ()
\end{verbatim}

\modName{GraphicsBrush}

\begin{verbatim}
> newtype Brush = ...
> 
> mkBrush     :: RGB   -> (Brush -> Picture) -> Picture
> withBrush   :: Brush -> Picture -> Picture
> 
> createBrush :: RGB   -> IO Brush
> deleteBrush :: Brush -> IO ()
\end{verbatim}

\modName{GraphicsPen}

\begin{verbatim}
> newtype Pen = ...
> 
> data Style
>   = Solid 
>   | Dash        -- "-------"
>   | Dot         -- "......."  
>   | DashDot     -- "_._._._"  
>   | DashDotDot  -- "_.._.._"  
>   | Null
>   | InsideFrame
> 
> withPen   :: Pen -> Picture -> Picture
> mkPen     :: Style -> Int -> RGB -> (Pen -> Picture) -> Picture
> createPen :: Style -> Int -> RGB -> IO Pen
> deletePen :: Pen -> IO ()
\end{verbatim}

\modName{GraphicsBitmap}

\begin{verbatim}
> newtype Bitmap = ...
> 
> loadBitmap    :: String -> IO (Bitmap, (Int, Int))
> readBitmap    :: String -> IO Bitmap
> deleteBitmap  :: Bitmap -> IO ()
> 
> getBitmapSize :: Bitmap -> IO (Int, Int)
> 
> -- Bitmaps can be drawn in three ways:
> -- a) with no transformation at  a point
> -- b) stretched to fit           a rectangle
> -- c) rotated and sheared to fit a parallelogram
> --
> -- Sadly, the latter isn't supported in Win'95
> 
> bitmap        :: Point                      -> Bitmap -> Picture
> stretchBitmap :: Point  -> Point            -> Bitmap -> Picture
> shearBitmap   :: Point  -> Point  -> Point  -> Bitmap -> Picture
> 
> withBitmap             :: Bitmap -> Picture -> Picture
> createCompatibleBitmap :: Win32.HDC -> Int -> Int -> IO Bitmap
> withCompatibleBitmap   :: Int -> Int -> (Bitmap -> Picture) -> Picture
> withCompatibleDC       :: (Win32.HDC -> Picture) -> Picture
\end{verbatim}

\modName{GraphicsRGN}

\begin{verbatim}
> newtype Region = MkRegion Win32.HRGN
> 
> mkEmpty     ::                     (Region -> Picture) -> Picture
> mkRectangle :: Point -> Point   -> (Region -> Picture) -> Picture
> mkEllipse   :: Point -> Point   -> (Region -> Picture) -> Picture
> mkPolygon   :: [Point]          -> (Region -> Picture) -> Picture
> 
> andRegion   :: Region -> Region -> (Region -> Picture) -> Picture
> orRegion    :: Region -> Region -> (Region -> Picture) -> Picture
> xorRegion   :: Region -> Region -> (Region -> Picture) -> Picture
> diffRegion  :: Region -> Region -> (Region -> Picture) -> Picture
> 
> region      :: Region -> Picture
\end{verbatim}

\modName{GraphicsColor}

\begin{verbatim}
> data Color 
>   = Black
>   | Blue
>   | Green 
>   | Cyan
>   | Red 
>   | Magenta
>   | Yellow
>   | White
>  deriving (Eq, Ord, Bounded, Enum, Ix, Show, Read)
> 
> colorList  :: [(Color, RGB)]
> colorTable :: Array Color RGB
> withColor  :: Color -> Picture -> Picture
\end{verbatim}

\modName{GraphicsPicture (again)}

\begin{verbatim}
> -- These are defined in GraphicsPicture, but don't seem to belong there
> type DrawFun = Win32.HWND -> Win32.HDC -> IO ()
> drawPicture         :: Picture -> DrawFun
> drawBufferedPicture :: Picture -> DrawFun
\end{verbatim}

\modName{Graphics}

\begin{verbatim}
> -- Reexports everything exported by the following modules:
> --
> --   GraphicsPicture
> --   GraphicsWindows
> --   GraphicsUtils
\end{verbatim}

\modName{GraphicsWindows}

\begin{verbatim}
> data Window = ...
> 
> data Event 
>   = Key       { char :: Char, isDown :: Bool }
>   | Button    { pt :: Point, isLeft, isDown :: Bool }
>   | MouseMove { pt :: Point }
>   | Resize
>   | Closed
>  deriving Show 
> 
> runGraphics  :: IO () -> IO ()
> openWindow   :: String -> Point -> IO Window
> openWindowEx :: String -> Maybe Point -> Maybe Point -> 
>                 (Picture -> DrawFun) -> Maybe Int -> 
>                 IO Window
> closeWindow  :: Window -> IO ()
> redraw       :: Window -> IO ()
> windowRect   :: Window -> IO (Point, Point)
> getPicture   :: Window -> IO Picture
> setPicture   :: Window -> Picture -> IO ()
> getEvent     :: Window -> IO Event
> getTick      :: Window -> IO ()
\end{verbatim}

\modName{GraphicsUtils}

\begin{verbatim}
> clearWindow  :: Window -> IO ()
> draw         :: Window -> Picture -> IO ()
> windowSize   :: Window -> IO Point
> getLBP       :: Window -> IO Point
> getRBP       :: Window -> IO Point
> getButton    :: Window -> Bool -> Bool -> IO Point
> getKey       :: Window -> IO Char
> getKeyEx     :: Window -> Bool -> IO Char
\end{verbatim}

% \end{description}

%*ignore
\end{document}
%*endignore