[Commit] papers/xr_ols2003 api.tex,1.4,1.5

[Carl Worth]

Committed by: cworth

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

Modified Files:
	api.tex 
Log Message:
Several minor edits to API section

Index: api.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/api.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- api.tex	15 May 2003 20:04:48 -0000	1.4
+++ api.tex	16 May 2003 00:32:34 -0000	1.5
@@ -61,22 +61,20 @@
 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.
+The program calls XrSetTargetImage to direct graphics to an array of
+bytes arranged as 4-byte ARGB pixels. A similar call,
+XrSetTargetDrawable, is available 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.).
+XrDestroy. During XrDestroy, all data is released from the XrState
+object. It is then invalid for the program to use the value of the
+XrState pointer until 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:transformations}-\ref{sec:patterns} provide examples
 that build on this initial program. Each example consists of a single
@@ -100,28 +98,31 @@
 
 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.
+functions XrTranslate, XrScale, and XrRotate. Additionally,
+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.
+state parameters in a hierarchical fashion. For example, while
+traversing a tree of objects to be drawn a program may modify the CTM,
+current color, line width, etc. at each level of the hierarchy.
 
-Xr supports this hierarchical approach to graphics by maintaing a
+Xr supports this hierarchical approach to graphics by maintaining 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.
+state object off of the stack, restoring all graphics parameters to
+their 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:
+drawing functions can be written with the following style, wrapping
+the body of the function with calls to XrSave and XrRestore:
+\begin{small}
 \begin{verbatim}
 void
 draw_something (XrState *xrs)
@@ -133,6 +134,7 @@
     XrRestore (xrs);
 }
 \end{verbatim}
+\end{small}
 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
@@ -151,20 +153,20 @@
 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.
+Xr provides several functions for constructing paths. XrNewPath
+installs an empty 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
+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
+from the current point rather than as absolute coordinates. To allow
 this, Xr provides XrRelMoveTo, XrRelLineTo, and XrRelCurveTo.
 Figure~\ref{fig:spiral} shows a rendering of a path constructed with
 one call to XrMoveTo and four calls to XrRelLineTo in a loop. The
@@ -179,9 +181,9 @@
   \end{center}
 \end{figure}
 
-Finally, XrClosePath closes the current subpath. This operations
+Finally, XrClosePath closes the current subpath. This operation
 involves adding a straight line segment from the current point to the
-initial point of the current subpath, (ie. point specified by the most
+initial point of the current subpath, (ie. the 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
@@ -192,8 +194,9 @@
 
 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
+to \texttt{\small XrRectangle(xrs, x, y, width, height)} is equivalent to the
 following sequence of calls:
+\begin{small}
 \begin{verbatim}
 XrMoveTo    (xrs,      x, y);
 XrRelLineTo (xrs,  width, 0);
@@ -201,6 +204,7 @@
 XrRelLineTo (xrs, -width, 0);
 XrClosePath (xrs);
 \end{verbatim}
+\end{small}
 
 \subsection{Path Drawing}
 \label{sec:path_drawing}
@@ -212,14 +216,14 @@
 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
+miter, or round), as set by 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.
 
 Figure~\ref{fig:caps_joins} demonstrates the three possible cap and
-join styles. The source code for this figure (see
-Figure~\ref{fig:caps_joins_source}) demonstrates the use of
+join styles. The source code for this figure
+(Figure~\ref{fig:caps_joins_source}) demonstrates the use of
 XrSetLineJoin and XrSetLineCap as well as XrTranslate, XrSave, and
 XrRestore.
 \begin{figure}[htbp]
@@ -230,10 +234,11 @@
   \end{center}
 \end{figure}
 
-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.
+XrFill fills the area on the ``inside'' of the current path. Xr can
+apply either the winding rule or the even-odd rule to determine the
+meaning of ``inside''. This behavior is controlled by calling
+XrSetFillRule with a value of either XrFillRuleWinding or
+XrFillRuleEvenOdd.
 
 Figure~\ref{fig:stars} demonstrates the effect of the fill rule given
 a star-shaped path. With the winding rule the entire star is filled