head	1.12;
access;
symbols;
locks; strict;
comment	@% @;


1.12
date	2003.05.17.01.41.53;	author cworth;	state Exp;
branches;
next	1.11;

1.11
date	2003.05.16.20.21.46;	author cworth;	state Exp;
branches;
next	1.10;

1.10
date	2003.05.16.20.13.11;	author keithp;	state Exp;
branches;
next	1.9;

1.9
date	2003.05.16.19.55.44;	author cworth;	state Exp;
branches;
next	1.8;

1.8
date	2003.05.16.19.21.12;	author cworth;	state Exp;
branches;
next	1.7;

1.7
date	2003.05.16.15.39.14;	author cworth;	state Exp;
branches;
next	1.6;

1.6
date	2003.05.16.13.29.16;	author cworth;	state Exp;
branches;
next	1.5;

1.5
date	2003.05.16.06.38.37;	author cworth;	state Exp;
branches;
next	1.4;

1.4
date	2003.05.16.05.37.30;	author cworth;	state Exp;
branches;
next	1.3;

1.3
date	2003.05.15.20.20.22;	author cworth;	state Exp;
branches;
next	1.2;

1.2
date	2003.05.15.20.04.48;	author cworth;	state Exp;
branches;
next	1.1;

1.1
date	2003.05.15.17.34.17;	author cworth;	state Exp;
branches;
next	;


desc
@@


1.12
log
@Final batch of minor corrections. Should be ready to ship now.
@
text
@\appendix

\section{Example Source Code}
\label{sec:source_code}

This appendix contains the source code that was used to draw each
figure in Section~\ref{sec:api}. Each example contains a top-level
``draw'' function that accepts an XrState pointer, a width, and a
height. The examples here can be made into complete programs by adding the
code from the example program of Figure~\ref{fig:source_minimal} and
inserting a call to the appropriate ``draw'' function.

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
draw_hering (XrState *xrs,
             int width, int height)
{
#define LINES 32.0
#define MAX_THETA (.80 * M_PI_2)
#define THETA (2 * MAX_THETA / (LINES-1))

  int i;

  XrSetRGBColor (xrs, 0, 0, 0);
  XrSetLineWidth (xrs, 2.0);

  XrSave (xrs);
  {
    XrTranslate (xrs, width / 2, height / 2);
    XrRotate (xrs, MAX_THETA);
       
    for (i=0; i < LINES; i++) {
      XrMoveTo (xrs, -2 * width, 0);
      XrLineTo (xrs, 2 * width, 0);
      XrStroke (xrs);
            
      XrRotate (xrs, - THETA);
    }
  }
  XrRestore (xrs);

  XrSetLineWidth (xrs, 6);
  XrSetRGBColor (xrs, 1, 0, 0);

  XrMoveTo (xrs, width / 4, 0);
  XrRelLineTo (xrs, 0, height);
  XrStroke (xrs);

  XrMoveTo (xrs, 3 * width / 4, 0);
  XrRelLineTo (xrs, 0, height);
  XrStroke (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for Hering illusion of Figure~\ref{fig:hering}}
\label{fig:hering_source}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
draw_caps_joins (XrState *xrs,
                 int width, int height)
{
    static double dashes[2] = {10, 20};
    int line_width = height / 12 & (~1);

    XrSetLineWidth (xrs, line_width);
    XrSetRGBColor (xrs, 0, 0, 0);

    XrTranslate (xrs, line_width, line_width);
    width -= 2 *line_width;

    XrSetLineJoin (xrs, XrLineJoinBevel);
    XrSetLineCap (xrs, XrLineCapButt);
    stroke_v_twice (xrs, width, height);

    XrTranslate (xrs, 0, height/4-line_width);
    XrSetLineJoin (xrs, XrLineJoinMiter);
    XrSetLineCap (xrs, XrLineCapSquare);
    stroke_v_twice (xrs, width, height);

    XrTranslate (xrs, 0, height/4-line_width);
    XrSetLineJoin (xrs, XrLineJoinRound);
    XrSetLineCap (xrs, XrLineCapRound);
    stroke_v_twice (xrs, width, height);
}

void
stroke_v_twice (XrState *xrs,
                int width, int height)
{
    XrMoveTo (xrs, 0, 0);
    XrRelLineTo (xrs, width/2,  height/2);
    XrRelLineTo (xrs, width/2, -height/2);

    XrSave (xrs);
    XrStroke (xrs);
    XrRestore (xrs);

    XrSave (xrs);
    {
        XrSetLineWidth (xrs, 2.0);
        XrSetLineCap (xrs, XrLineCapButt);
        XrSetRGBColor (xrs, 1, 1, 1);
        XrStroke (xrs);
    }
    XrRestore (xrs);

    XrNewPath (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for cap and join demonstration of Figure~\ref{fig:caps_joins}}
\label{fig:caps_joins_source}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
draw_spiral (XrState *xrs,
             int width, int height)
{
  int wd = .02 * width;
  int hd = .02 * height;
  int i;

  width -= 2;
  height -= 2;

  XrMoveTo (xrs, width - 1, -hd - 1);
  for (i=0; i < 9; i++) {
    XrRelLineTo (xrs, 0, height-hd*(2*i-1));
    XrRelLineTo (xrs, -(width-wd*(2*i)), 0);
    XrRelLineTo (xrs, 0,-(height-hd*(2*i)));
    XrRelLineTo (xrs,  width-wd*(2*i+1), 0);
  }

  XrSetRGBColor (xrs, 0, 0, 1);
  XrStroke (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for nested box illusion of Figure~\ref{fig:spiral}}
\label{fig:spiral_source}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
draw_splines (XrState *xrs,
              int width, int height)
{
    int i;
    double tolerance[5] = {.1,.5,1,5,10};
    double line_width = .08 * width;
    double gap = width / 6;

    XrSetRGBColor (xrs, 0, 0, 0);
    XrSetLineWidth (xrs, line_width);

    XrTranslate (xrs, gap, 0);
    for (i=0; i < 5; i++) {
        XrSetTolerance (xrs, tolerance[i]);
        draw_spline (xrs, height);
        XrTranslate (xrs, gap, 0);
    }
}

void
draw_spline (XrState *xrs, double height)
{
    XrMoveTo (xrs, 0, .1 * height);
    height = .8 * height;
    XrRelCurveTo (xrs,
                  -height/2, height/2,
                  height/2, height/2,
                  0, height);
    XrStroke (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for splines drawn with varying tolerance as in Figure~\ref{fig:splines_tolerance}}
\label{fig:splines_tolerance_source}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
draw_stars (XrState *xrs,
            int width, int height)
{
  XrSetRGBColor (xrs, 0, 0, 0);

  XrSave (xrs);
  {
    XrTranslate (xrs, 5, height/2.6);
    XrScale (xrs, height, height);
    star_path (xrs);
    XrSetFillRule (xrs, XrFillRuleWinding);
    XrFill (xrs);
  }
  XrRestore (xrs);

  XrSave (xrs);
  {
    XrTranslate (xrs,
                 width-height-5, height/2.6);
    XrScale (xrs, height, height);
    star_path (xrs);
    XrSetFillRule (xrs, XrFillRuleEvenOdd);
    XrFill (xrs);
  }
  XrRestore (xrs);
}

void
star_path (XrState *xrs)
{
    int i;
    double theta = 4 * M_PI / 5.0;

    XrMoveTo (xrs, 0, 0);
    for (i=0; i < 4; i++) {
        XrRelLineTo (xrs, 1.0, 0);
        XrRotate (xrs, theta);
    }
    XrClosePath (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for stars to demonstrate fill rule as in Figure~\ref{fig:stars}}
\label{fig:stars_source}
\end{figure}

\begin{figure*}[t]
\begin{scriptsize}
\begin{minipage}{.5\linewidth}
\begin{verbatim}
void
draw_gradients (XrState *xrs,
                int img_width, int img_height)
{
    XrSurface *gradient;
    double width, height, pad;

    width = img_width / 4.0;
    pad = (img_width - (3 * width)) / 2.0;
    height = img_height;

    gradient=make_gradient(xrs,width,height);

    XrSetPattern (xrs, gradient);
    draw_flat (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_tent (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_cylinder (xrs, width, height);

    XrRestore (xrs);

    XrSurfaceDestroy (gradient);
}

XrSurface *
make_gradient (XrState *xrs,
               double width, double height)
{
    XrSurface *g;
    XrMatrix *matrix;

    XrSave (xrs);

    g = XrSurfaceCreateNextTo (
                 XrGetTargetSurface (xrs),
                 XrFormatARGB32, 3, 2);
    XrSetTargetSurface (xrs, g);

    XrSetRGBColor (xrs, 0, 0, 0);
    XrRectangle (xrs, 0, 0, 1, 2);
    XrFill (xrs);

    XrSetRGBColor (xrs, 1, 1, 1);
    XrRectangle (xrs, 1, 0, 1, 2);
    XrFill (xrs);

    XrSetRGBColor (xrs, 0, 0, 0);
    XrRectangle (xrs, 2, 0, 1, 2);
    XrFill (xrs);

    XrRestore (xrs);

    matrix = XrMatrixCreate ();
    XrMatrixScale (matrix,
                   2.0/width, 1.0/height);
    XrSurfaceSetMatrix (g, matrix);
    XrSurfaceSetFilter (g, XrFilterBilinear);
    XrMatrixDestroy (matrix);

    return g;
}
\end{verbatim}
\end{minipage}
\begin{minipage}{.5\linewidth}
\begin{verbatim}
void
draw_flat (XrState *xrs, double w, double h)
{
    double hw = w / 2.0;

    XrRectangle (xrs, 0, hw, w, h - hw);

    XrFill (xrs);
}

void
draw_tent (XrState *xrs, double w, double h)
{
    double hw = w / 2.0;

    XrMoveTo    (xrs,   0,  hw);
    XrRelLineTo (xrs,  hw, -hw);
    XrRelLineTo (xrs,  hw,  hw);
    XrRelLineTo (xrs,   0,  h - hw);
    XrRelLineTo (xrs, -hw, -hw);
    XrRelLineTo (xrs, -hw,  hw);
    XrClosePath (xrs);

    XrFill (xrs);
}

void
draw_cylinder (XrState *xrs, double w, double h)
{
    double hw = w / 2.0;

    XrMoveTo (xrs, 0, hw);
    XrRelCurveTo (xrs,   0, -hw,
                  w, -hw,   w, 0);
    XrRelLineTo (xrs, 0, h - hw);
    XrRelCurveTo (xrs,   0, -hw,
                  -w, -hw,  -w, 0);
    XrClosePath (xrs);

    XrFill (xrs);
}
\end{verbatim}
\end{minipage}
\end{scriptsize}
\caption{Source for 3 gradient-filled shapes of Figure~\ref{fig:outline}}
\label{fig:outline_source}
\end{figure*}
@


1.11
log
@Reordered code in appendix so draw function is always first
@
text
@d4 1
d8 2
a9 2
``draw'' function that accepts and XrState pointer, a width, and a
height. The examples here can be made complete programs by adding the
d11 1
a11 1
inserting a call to the ``draw'' function.
d57 1
a57 1
\caption{Source for Hering illusion}
d117 1
a117 1
\caption{Source for cap and join demonstration}
d148 1
a148 1
\caption{Source for nested box illusion}
d188 1
a188 1
\caption{Source for splines drawn with varying tolerance}
d238 1
a238 1
\caption{Source for stars to demonstrate fill rule}
d358 1
a358 1
\caption{Source for 3 gradient-filled shapes}
@


1.10
log
@reorder and reformat examples
@
text
@a63 24
stroke_v_twice (XrState *xrs,
                int width, int height)
{
    XrMoveTo (xrs, 0, 0);
    XrRelLineTo (xrs, width/2,  height/2);
    XrRelLineTo (xrs, width/2, -height/2);

    XrSave (xrs);
    XrStroke (xrs);
    XrRestore (xrs);

    XrSave (xrs);
    {
        XrSetLineWidth (xrs, 2.0);
        XrSetLineCap (xrs, XrLineCapButt);
        XrSetRGBColor (xrs, 1, 1, 1);
        XrStroke (xrs);
    }
    XrRestore (xrs);

    XrNewPath (xrs);
}

void
d90 24
a154 12
draw_spline (XrState *xrs, double height)
{
    XrMoveTo (xrs, 0, .1 * height);
    height = .8 * height;
    XrRelCurveTo (xrs,
                  -height/2, height/2,
                  height/2, height/2,
                  0, height);
    XrStroke (xrs);
}

void
d173 12
a194 14
star_path (XrState *xrs)
{
    int i;
    double theta = 4 * M_PI / 5.0;

    XrMoveTo (xrs, 0, 0);
    for (i=0; i < 4; i++) {
        XrRelLineTo (xrs, 1.0, 0);
        XrRotate (xrs, theta);
    }
    XrClosePath (xrs);
}

void
d221 14
d245 27
a308 27

void
draw_gradients (XrState *xrs,
                int img_width, int img_height)
{
    XrSurface *gradient;
    double width, height, pad;

    width = img_width / 4.0;
    pad = (img_width - (3 * width)) / 2.0;
    height = img_height;

    gradient=make_gradient(xrs,width,height);

    XrSetPattern (xrs, gradient);
    draw_flat (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_tent (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_cylinder (xrs, width, height);

    XrRestore (xrs);

    XrSurfaceDestroy (gradient);
}
d346 1
a346 1
		    w, -hw,   w, 0);
d349 1
a349 1
		   -w, -hw,  -w, 0);
@


1.9
log
@Fixed introduction to appendix
@
text
@a63 31
draw_spiral (XrState *xrs,
             int width, int height)
{
  int wd = .02 * width;
  int hd = .02 * height;
  int i;

  width -= 2;
  height -= 2;

  XrMoveTo (xrs, width - 1, -hd - 1);
  for (i=0; i < 9; i++) {
    XrRelLineTo (xrs, 0, height-hd*(2*i-1));
    XrRelLineTo (xrs, -(width-wd*(2*i)), 0);
    XrRelLineTo (xrs, 0,-(height-hd*(2*i)));
    XrRelLineTo (xrs,  width-wd*(2*i+1), 0);
  }

  XrSetRGBColor (xrs, 0, 0, 1);
  XrStroke (xrs);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for nested box illusion}
\label{fig:spiral_source}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
void
d124 71
d241 1
a241 1
\begin{figure}[htbp]
d243 69
d314 11
a324 1
draw_spline (XrState *xrs, double height)
d326 11
a336 7
    XrMoveTo (xrs, 0, .1 * height);
    height = .8 * height;
    XrRelCurveTo (xrs,
                  -height/2, height/2,
                  height/2, height/2,
                  0, height);
    XrStroke (xrs);
d340 1
a340 2
draw_splines (XrState *xrs,
              int width, int height)
d342 1
a342 4
    int i;
    double tolerance[5] = {.1,.5,1,5,10};
    double line_width = .08 * width;
    double gap = width / 6;
d344 7
a350 2
    XrSetRGBColor (xrs, 0, 0, 0);
    XrSetLineWidth (xrs, line_width);
d352 1
a352 6
    XrTranslate (xrs, gap, 0);
    for (i=0; i < 5; i++) {
        XrSetTolerance (xrs, tolerance[i]);
        draw_spline (xrs, height);
        XrTranslate (xrs, gap, 0);
    }
d355 1
d357 3
a359 78
\caption{Source for splines drawn with varying tolerance}
\label{fig:splines_tolerance_source}
\end{figure}

% This one may be a bit long, (and it's already incomplete).
% I think we alrady have too many examples, let's drop this.
% \begin{figure}[htbp]
% \begin{scriptsize}
% \begin{verbatim}
% XrSurface *
% make_gradient (XrState *xrs,
%                double width, double height)
% {
%     XrSurface *g;
%     XrMatrix *matrix;
% 
%     XrSave (xrs);
% 
%     g = XrSurfaceCreateNextTo (
%                  XrGetTargetSurface (xrs),
%                  XrFormatARGB32, 3, 2);
%     XrSetTargetSurface (xrs, g);
% 
%     XrSetRGBColor (xrs, 0, 0, 0);
%     XrRectangle (xrs, 0, 0, 1, 2);
%     XrFill (xrs);
% 
%     XrSetRGBColor (xrs, 1, 1, 1);
%     XrRectangle (xrs, 1, 0, 1, 2);
%     XrFill (xrs);
% 
%     XrSetRGBColor (xrs, 0, 0, 0);
%     XrRectangle (xrs, 2, 0, 1, 2);
%     XrFill (xrs);
% 
%     XrRestore (xrs);
% 
%     matrix = XrMatrixCreate ();
%     XrMatrixScale (matrix,
%                    2.0/width, 1.0/height);
%     XrSurfaceSetMatrix (g, matrix);
%     XrSurfaceSetFilter (g, XrFilterBilinear);
%     XrMatrixDestroy (matrix);
% 
%     return g;
% }
% 
% void
% draw_gradients (XrState *xrs,
%                 int img_width, int img_height)
% {
%     XrSurface *gradient;
%     double width, height, pad;
% 
%     width = img_width / 4.0;
%     pad = (img_width - (3 * width)) / 2.0;
%     height = img_height;
% 
%     gradient=make_gradient(xrs,width,height);
% 
%     XrSetPattern (xrs, gradient);
%     draw_flat (xrs, width, height);
%     XrTranslate (xrs, width + pad, 0);
%     XrSetPattern (xrs, gradient);
%     draw_tent (xrs, width, height);
%     XrTranslate (xrs, width + pad, 0);
%     XrSetPattern (xrs, gradient);
%     draw_cylinder (xrs, width, height);
% 
%     XrRestore (xrs);
% 
%     XrSurfaceDestroy (gradient);
% }
% \end{verbatim}
% \end{scriptsize}
% \caption{Source for 3 gradient-filled shapes}
% \label{fig:outline_source}
% \end{figure}
@


1.8
log
@Fixed placement of Hering figure
@
text
@d3 1
a3 6
XXX: Fix this paragraph
Sections~\ref{sec:transformations}-\ref{sec:images} provide examples
that build on this initial program. Each example consists of a single
function that accepts an XrState pointer and performs drawing
operations. Each example can be made into a complete program by simply
adding the new function call to the program of Figure~\ref{fig:source_minimal}.
d5 6
a10 1
\section{Example Source Code}
@


1.7
log
@Added reference to convolution.
Added prose around the penguin figures.
Added references for artwork by Larry Ewing and Simon Budig and the GIMP.
Removed long (and incomplete) source code for gradient example.
@
text
@d3 7
@


1.6
log
@Added reference to Hering figure with source code.
(Had to implement this twice as I screwed up and let cvsup blow away my change the first time)
@
text
@d234 74
a307 72
\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
XrSurface *
make_gradient (XrState *xrs,
               double width, double height)
{
    XrSurface *g;
    XrMatrix *matrix;

    XrSave (xrs);

    g = XrSurfaceCreateNextTo (
                 XrGetTargetSurface (xrs),
                 XrFormatARGB32, 3, 2);
    XrSetTargetSurface (xrs, g);

    XrSetRGBColor (xrs, 0, 0, 0);
    XrRectangle (xrs, 0, 0, 1, 2);
    XrFill (xrs);

    XrSetRGBColor (xrs, 1, 1, 1);
    XrRectangle (xrs, 1, 0, 1, 2);
    XrFill (xrs);

    XrSetRGBColor (xrs, 0, 0, 0);
    XrRectangle (xrs, 2, 0, 1, 2);
    XrFill (xrs);

    XrRestore (xrs);

    matrix = XrMatrixCreate ();
    XrMatrixScale (matrix,
                   2.0/width, 1.0/height);
    XrSurfaceSetMatrix (g, matrix);
    XrSurfaceSetFilter (g, XrFilterBilinear);
    XrMatrixDestroy (matrix);

    return g;
}

void
draw_gradients (XrState *xrs,
                int img_width, int img_height)
{
    XrSurface *gradient;
    double width, height, pad;

    width = img_width / 4.0;
    pad = (img_width - (3 * width)) / 2.0;
    height = img_height;

    gradient=make_gradient(xrs,width,height);

    XrSetPattern (xrs, gradient);
    draw_flat (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_tent (xrs, width, height);
    XrTranslate (xrs, width + pad, 0);
    XrSetPattern (xrs, gradient);
    draw_cylinder (xrs, width, height);

    XrRestore (xrs);

    XrSurfaceDestroy (gradient);
}
\end{verbatim}
\end{scriptsize}
\caption{Source for 3 gradient-filled shapes}
\label{fig:outline_source}
\end{figure}
@


1.5
log
@Added paint and images sections.
Added source for gradient example.
@
text
@d9 48
d238 2
a239 2
create_gradient (XrState *xrs,
                 double width, double height)
d277 1
a277 1
                  int img_width, int img_height)
d286 1
a286 1
    gradient = create_gradient (xrs, width, height);
@


1.4
log
@Added source code for splines figure.
Removed \texttt from function names.
@
text
@d185 73
@


1.3
log
@Fixed stars.c
@
text
@d145 40
@


1.2
log
@Added some figure references. Added stars example
@
text
@a109 3
    XrRotate (xrs, theta);
    XrRotate (xrs, theta);
    XrRotate (xrs, theta);
@


1.1
log
@Spewed some text on how to use the API
@
text
@d32 2
a33 2
\caption{Using XrMoveTo, XrRelLineTo, and XrStroke}
\label{fig:spiral_code}
d92 2
a93 2
\caption{Using XrSetLineCap, XrSetLineJoin, XrSave, and XrRestore}
\label{fig:caps_joins_code}
d96 52
@