[Commit] papers/xr_ols2003 appendix.tex,NONE,1.1 api.tex,1.2,1.3 introduction.tex,1.3,1.4 xr_ols2003.tex,1.3,1.4

[Carl Worth]

Committed by: cworth

Update of /local/src/CVS/papers/xr_ols2003
In directory home.keithp.com:/tmp/cvs-serv16062

Modified Files:
	api.tex introduction.tex xr_ols2003.tex 
Added Files:
	appendix.tex 
Log Message:
Spewed some text on how to use the API

--- NEW FILE: appendix.tex ---
\appendix

\section{Example Source Code}

\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{Using XrMoveTo, XrRelLineTo, and XrStroke}
\label{fig:spiral_code}
\end{figure}

\begin{figure}[htbp]
\begin{scriptsize}
\begin{verbatim}
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);
}

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);
}
\end{verbatim}
\end{scriptsize}
\caption{Using XrSetLineCap, XrSetLineJoin, XrSave, and XrRestore}
\label{fig:caps_joins_code}
\end{figure}


Index: api.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/api.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- api.tex	15 May 2003 02:00:27 -0000	1.2
+++ api.tex	15 May 2003 17:34:17 -0000	1.3
@@ -1,13 +1,241 @@
-\section{API}
+\section{API and Examples}
 
-% Yes, I'm having too much fun drawing optical illusions
+This section provides a tour of the application programming interface
+(API) provided by Xr. Major features of the API are demonstrated in
+illustrations along with source code sufficient to produce each
+illustration.
+
+\subsection{Xr Initialization}
+
+\begin{figure}[htbp]
+\begin{scriptsize}
+\begin{verbatim}
+#include <Xr.h>
+
+#define WIDTH 600
+#define HEIGHT 600
+#define STRIDE (WIDTH * 4)
+
+char image[STRIDE*HEIGHT];
+
+int
+main (void)
+{
+    XrState *xrs;
+
+    xrs = XrCreate ();
+
+    XrSetTargetImage (xrs, image,
+                      XrFormatARGB32,
+                      WIDTH, HEIGHT, STRIDE);
+
+    /* draw things using xrs ... */
+
+    XrDestroy (xrs);
+
+    /* do something useful with image
+       (eg. write to a file) */
+
+    return 0;
+}
+\end{verbatim}
+\end{scriptsize}
+\caption{Minimal program using Xr}
+\label{fig:source_minimal}
+\end{figure}
+
+Figure~\ref{fig:source_minimal} shows a minimal program using Xr. This
+program does not actually do useful work---it never draws anything,
+but it demonstrates the initialization and cleanup procedures required
+for using Xr.
+
+After including the Xr header file, the first Xr function a program
+must call is XrCreate. This function returns a pointer to an XrState
+object, which is used by Xr to store its data. The XrState pointer is
+passed as the first argument to almost all other Xr functions.
+
+Before any drawing functions may be called, Xr must be provided with a
+target surface to receive the resulting graphics. Xr has the potential
+to support any of several different types of graphics targets as
+supported by the Xc backend. Currently, Xr/Xc have support for
+rendering to in-memory images as well as to any X Window System
+``drawable'', (eg. a window or a pixmap).
+
+Figure~\ref{fig:source_minimal} includes a call to XrSetTargetImage to
+direct graphics to an array of bytes arranged as 4-byte ARGB pixels
+(alpha, red, green, and blue). Xr provides a similar call,
+XrSetTargetDrawable, to direct graphics to an X drawable.
+
+With the XrState object created and initialized with a rendering
+target, Xr is ready to accept drawing commands.
+
+When the program is done using Xr, it signifies this by calling
+XrDestroy. At this point Xr frees any data remaining within the
+XrState object, and it becomes invalid for the program to use the
+value of the XrState pointer, (unless a new object is created by
+calling XrCreate). The results of any graphics operations are still
+available on the target surface, and the program can access that
+surface as appropriate, (eg. write the image to a file, display the
+graphics on the screen, etc.).
+
+Sections~\ref{sec:path_example}-\ref{sec:pattern_example} 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}.
+
+\subsection{Transformations}
+
+All coordinates passed from user code to Xr are in a coordinate system
+known as ``user space''. These coordinates must be transformed to
+``device space'' which corresponds to the device grid of the target
+surface. This transformation is controlled by the current
+transformation matrix (CTM) within Xr.
+
+Initially, the CTM in Xr is an identity matrix, so user space will
+initially align with device space, (with the origin at the upper-left
+corner of the surface, the X axis increasing to the right, and the Y
+axis increasing down).
+
+The CTM can be modified by the user to position, scale, or rotate
+subsequent objects to be drawn. These operations are performed by the
+functions XrTranslate, XrScale, and XrRotate. XrConcatMatrix will
+compose a given matrix into the current CTM and XrSetMatrix will
+directly set the CTM to a given matrix. The XrDefaultMatrix function
+can be used to restore the CTM to its original state.
+
+\subsection{Save/Restore of Graphics State}
+
+Programs using a structured approach to drawing will modify graphics
+state parameters in a hierarchical fashion. For example, a program may
+traverse a tree of objects to be drawn, modifying the CTM, current
+color, line width, etc. at each level of the hierarchy.
+
+Xr supports this hierarchical approach to graphics by maintaing a
+stack of graphics state objects within the XrState object. The XrSave
+function pushes a copy of the current graphics state onto the top of
+the stack. Modifications to the graphics state are made only to the
+object on the top of the stack. The XrRestore function pops a graphics
+state object off of the stack restoring the graphics state to its
+state before the last XrSave operation.
+
+This model has proven effective within structured C programs. Most
+drawing functions can be written with the following style:
+\begin{verbatim}
+void draw_something (XrState *xrs)
+{
+    XrSave (xrs);
+
+    /* draw something here */
+
+    XrRestore (xrs);
+}
+\end{verbatim}
+This approach has the benefit that modifications to the graphics state
+within the function will not be visible outside the function, leading
+to more readily reusable code. Sometimes a single function will
+contain multiple sections of code framed by XrSave/XrRestore calls.
+Some find it more readable to include a new indented block between the
+XrSave/XrRestore calls in this case. Figure~\ref{fig:caps_joins_code}
+contains an example of this style.
+
+\subsection{Path Construction}
+\label{sec:path_example}
+
+One of the primary elements of the Xr graphics state is the current
+path. A path consists of one or more independent subpaths, each of
+which is an ordered set of straight or curved segments. Any non-empty
+path has a ``current point'', the final coordinate in the final
+segment of the current subpath. All path construction functions both
+read and update the current point.
+
+Xr provides several functions for constructing paths. XrNewPath clears
+the current path, discarding any previously defined path. The first
+path construction called after XrNewPath should be XrMoveTo which
+simply moves the current point to the point specified. It is also
+valid to call XrMoveTo when the current path is non-empty in order to
+begin a new subpath.
+
+XrLineTo adds a straight line segment to the current path, from the
+current point to the point specified. XrCurveTo adds a cubic bezier
+spline with a control polygon defined by the current point as well as
+the three points specified.
+
+It is often convenient to specify path coordinates as relative offsets
+from the current point rather than as aboslute coordinates. To allow
+this, Xr provides XrRelMoveTo, XrRelLineTo, and XrRelCurveTo.
+
+Finally, XrClosePath closes the current subpath. This operations
+involves adding a straight line segment from the current point to the
+initial point of the current subpath, (ie. point specified by the most
+recent call to XrMoveTo or XrRelMoveTo). Calling XrClosePath is not
+equivalent to adding the corresponding line segment with XrLineTo or
+XrRelLineTo. The distinction is that a closed subpath will have a join
+at the junction of the final coincident point while an unclosed path
+will have caps on either end of the path, (even if the two ends happen
+to be coincident). See Section~\ref{sec:caps_joins_example} for more
+discussion of caps and joins.
+
+As rectangular paths are commonly used, Xr provides a convenience
+function for adding a rectangular subpath to the current path. A call
+to \texttt{XrRectangle(xrs, x, y, width, height)} is equivalent to the
+following sequence of calls:
+\begin{verbatim}
+XrMoveTo    (xrs,      x, y);
+XrRelLineTo (xrs,  width, 0);
+XrRelLineTo (xrs, 0, height);
+XrRelLineTo (xrs, -width, 0);
+XrClosePath (xrs);
+\end{verbatim}
+
+\subsection{Path Drawing}
+
+After a path is constructed, it can be drawn in one of two ways:
+stroking its outline (XrStroke) or filling its interior (XrFill).
+
+XrStroke draws the outline formed by stroking the path with a pen of
+the current line width.  The line width is set with the XrSetLineWidth
+function. As subsequent segments within a subpath are drawn, they are
+connected according to one of three different join styles, (bevel,
+miter, or round), as set by the XrSetLineJoin. Closed subpaths are
+also joined at the closure point. Unclosed subpaths have one of three
+different cap styles, (butt, square, or round), applied at either end
+of the path. The cap style is set with the XrSetLineCap function.
+
+XrFill fills the area on the ``inside'' of the current path. Xr allows
+either the winding rule or the even-odd rule to be used to determine
+the area inside the path. This behavior is controlled by calling
+XrSetFillRule with a value of XrFillRuleWinding or XrFillRuleEvenOdd.
+
+Figure~\ref{fig:spiral_code} shows an example of code using XrMoveTo
+and XrRelLineTo to construct a spiral-shaped path. XrStroke is used to
+draw the outline of this path. Figure~\ref{fig:spiral_result} shows
+the result of this code, (a figure that appears to be several nested
+squares but is in fact a single continuous path).
+
+% And yes, I'm having too much fun drawing optical illusions.
 
 \begin{figure}[htbp]
   \begin{center}
   \epsfxsize=2in
   \epsfbox{examples/spiral}
   \caption{Example showing XrStroke}
-  \label{fig:stroke_example}
+  \label{fig:spiral_result}
+  \end{center}
+\end{figure}
+
+% XXX: How do we want to attribute the illusions?
+%  I found the spiral in Al Seckel's ``The Great Book of Optical Illusions'' (Firefly Books Ltd., 2002, Buffalo, New York) page 29.
+% The Hering illusion is due to Ewald Hering (1861) also in Seckel page 134.
+% The shape-from-shading illusion is Isao Watanabe, (he calls it ``3-D Shape and Outline'').
+% It's in Seckel page 286 and on Watanabe's web site:
+% http://www.let.kumamoto-u.ac.jp/watanabe/Watanabe-E/Illus-E/3D-E/index.html
+
+\begin{figure}[htbp]
+  \begin{center}
+    \epsfxsize=2in \epsfbox{examples/caps_joins}
+  \caption{Example showing cap and join styles}
+  \label{fig:caps_joins_result}
   \end{center}
 \end{figure}
 
@@ -15,10 +243,13 @@
   \begin{center}
   \epsfxsize=1in
   \epsfbox{examples/hering}
-  \caption{Example showing XrSetLineWidth and XrStroke}
+  \caption{Example showing XrTranslate, XrRotate and XrSetLineWidth}
   \label{fig:line_width_example}
   \end{center}
 \end{figure}
+
+\subsection{Using Patterns}
+\label{sec:pattern_example}
 
 \begin{figure}[htbp]
   \begin{center}

Index: introduction.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/introduction.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- introduction.tex	14 May 2003 21:04:22 -0000	1.3
+++ introduction.tex	15 May 2003 17:34:17 -0000	1.4
@@ -36,7 +36,7 @@
   \end{center}
 \end{figure}
 
-Attribution: Original raster image by Larry Ewing,
-(http://www.isc.tamu.edu/~lewing/linux/). Vectorized version by Larry
-Budig (http://www.home.unix-ag.org/simon/penguin/).
+% XXX: Attribution: Original raster image by Larry Ewing,
+% (http://www.isc.tamu.edu/~lewing/linux/). Vectorized version by Larry
+% Budig (http://www.home.unix-ag.org/simon/penguin/).
 

Index: xr_ols2003.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/xr_ols2003.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- xr_ols2003.tex	14 May 2003 21:04:22 -0000	1.3
+++ xr_ols2003.tex	15 May 2003 17:34:17 -0000	1.4
@@ -34,8 +34,6 @@
 \input{introduction}
 \input{api}
 
-\end{document}
-
-
-
+\input{appendix}
 
+\end{document}