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

Carl Worth commit@keithp.com
Thu, 15 May 2003 23:38:39 -0700


Committed by: cworth

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

Modified Files:
	api.tex appendix.tex 
Log Message:
Added paint and images sections.
Added source for gradient example.

Index: api.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/api.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- api.tex	16 May 2003 05:37:30 -0000	1.7
+++ api.tex	16 May 2003 06:38:37 -0000	1.8
@@ -79,7 +79,7 @@
 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:paint} provide examples
+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
@@ -302,14 +302,89 @@
   \end{center}
 \end{figure}
 
+\subsection{Paint}
+\label{sec:paint}
+
+The exampless shown so far have all used opaque ``paint'' as the
+source for all drawing operations. The color of this paint is selected
+with the XrSetRGBColor function.
+
+Xr supports more interesting possibilities for the paint used in
+graphics operations. First, the source color need not be opaque; the
+XrSetAlpha function establishes an opacity level for the source paint.
+The alpha value ranges from 0 (transparent) to 1 (opaque).
+
+When Xr graphics operations combine translucent surfaces, there are a
+number of different ways in which the source and destination colors
+can be combined. Xr provides support for all of the Porter/Duff
+compositing operators as well as the extended operators defined in the
+X Render extension. The desired operator is selected by calling
+XrSetOperator before compositing. The default operator value is
+XrOperatorOver corresponding to the Porter/Duff OVER operator.
+
+Finally, the XrSetPattern function allows any XrSurface to be
+installed as a static or repeating pattern to be used as the ``paint''
+for subsequent graphics operations. The pattern surface may have been
+initialized from an external image source or may have been the result
+of previous Xr graphics operations.
+
+Figure~\ref{fig:outline} was created by first drawing small, vertical
+black and white rectangles onto a 3X2 surface. This surface was then
+scaled, filtered, and used as the pattern for 3 XrFill operations.
+This demonstrates an efficient means of generating linear gradients
+within Xr. The source for this image can be seen in
+Figure~\ref{fig:outline_source}.
+\begin{figure}[htbp]
+  \begin{center}
+  \epsfxsize=2.5in
+  \epsfbox{examples/outline}
+  \caption{An example showing XrFill with XrSetPattern used to create a gradient}
+  \label{fig:outline}
+  \end{center}
+\end{figure}
+
 \subsection{Images}
+\label{sec:images}
 
-XXX: Discuss XrShowSurface
+In addition to the vector path support, Xr also supports bitmapped
+images as a primitive object. Images are transformed, (and optionally
+filtered), by the CTM in the same manner as all othere primitives. In
+order to display an image, an XrSurface object must first be created
+for the image, then the image can be displayed with the XrShowSurface
+function. XrShowSurface places an image of the given width and height
+at the origin in user space, so XrTranslate can be used to position
+the surface.
 
-\subsection{Paint}
-\label{sec:paint}
+In addition to the CTM, each surface also has its own matrix providing
+a transformation from user space to image space. This matrix can be
+used to transform a surface independently from the CTM.
 
-XXX: Discuss XrSetRGBColor, XrSetAlpha, XrSetOperator, XrSetPattern
+The XrShowSurface function has another important use besides allowing
+the display of external images. When using the Porter/Duff compositing
+operators, it is often desirable to combine several graphics
+primitives on an intermediate surface before compositing the result
+onto the target surface. This functionality is similar to the notion
+of transparency groups in PDF 1.4 and can be achieved with the
+following idiom:
+\begin{small}
+\begin{verbatim}
+XrSave (xrs);
+XrSetTargetSurface (xrs, intermediate);
+/* draw to intermediate surface with 
+   any Xr operations */
+XrRestore (xrs);
+XrShowSurface (xrs, surface);
+\end{verbatim}
+\end{small}
+In this example an intermediate surface is installed as the target
+surface, and then graphics are drawn on the intermediate surface. When
+XrRestore is called, the original target surface is restored and the
+resulting graphics from the intermediate surface are composited onto
+the original target.
+
+This technique can be applied recursively with any number of levels of
+intermediate surfaces each receiving the results of its ``child''
+surfaces before being composited into its ``parent'' surface.
 
 \begin{figure}[htbp]
   \begin{center}
@@ -320,12 +395,4 @@
   \end{center}
 \end{figure}
 
-\begin{figure}[htbp]
-  \begin{center}
-  \epsfxsize=2.5in
-  \epsfbox{examples/outline}
-  \caption{Example showing XrSetPattern and XrFill}
-  \label{fig:fill_example}
-  \end{center}
-\end{figure}
 

Index: appendix.tex
===================================================================
RCS file: /local/src/CVS/papers/xr_ols2003/appendix.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- appendix.tex	16 May 2003 05:37:30 -0000	1.4
+++ appendix.tex	16 May 2003 06:38:37 -0000	1.5
@@ -182,3 +182,76 @@
 \caption{Source for splines drawn with varying tolerance}
 \label{fig:splines_tolerance_source}
 \end{figure}
+
+\begin{figure}[htbp]
+\begin{scriptsize}
+\begin{verbatim}
+XrSurface *
+create_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 = create_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}