Continue with documenting -draw

cpdfmanual.tex

@@ -4292,6 +4292,19 @@ To avoid calculating the Bezier curves for a circle manually, \texttt{cpdf} can
    \noindent\verb!-clipeo! Clip, even odd
   \end{framed}}
 
+\noindent We can use a path to form a clipping region for subsequent content using \texttt{-clip} or \texttt{-clipeo}. For example: 
+
+\begin{framed}
+ \noindent\small\verb?cpdf -create-pdf AND -draw -circle "300 300 100" -clip?\\
+ \noindent\small\verb?     -circle "300 350 100" -fill -o out.pdf?\\
+\end{framed}
+
+\noindent Here is the result:
+
+\bigskip
+\fbox{\includegraphics[width=0.3\textwidth]{manualimages/clip.pdf}}
+\bigskip
+
 \section{Path parameters}
   {\small\begin{framed}
    \noindent\verb!-strokecol "g" | "r g b" | "c y m k"! Set stroke colour\\
@@ -4347,18 +4360,47 @@ Lines may have dash patterns. A dash pattern consists of one or more numbers. Al
 \fbox{\includegraphics[width=0.3\textwidth]{manualimages/dash.pdf}}
 \bigskip
 
+%FIXME specify the angles etc. properly - what units?
 \section{The graphics stack and matrices}
   {\small\begin{framed}
    \noindent\verb!-push! Push graphics stack\\
    \noindent\verb!-pop! Pop graphics stack\\
-   \noindent\verb!-matrix! Append to graphics matrix\\
-   \noindent\verb!-mtrans! Translate the graphics matrix\\
-   \noindent\verb!-mrot! Rotate the graphics matrix\\
-   \noindent\verb!-mscale! Scale the graphics matrix\\
-   \noindent\verb!-mshearx! Shear the graphics matrix in X\\
-   \noindent\verb!-msheary! Shear the graphics matrix in Y
+   \noindent\verb!-matrix "a b c d e f"! Append to graphics matrix\\
+   \noindent\verb!-mtrans "tx ty"! Translate the graphics matrix\\
+   \noindent\verb!-mrot "x y a"! Rotate the graphics matrix\\
+   \noindent\verb!-mscale "sx sy"! Scale the graphics matrix\\
+   \noindent\verb!-mshearx "x y a"! Shear the graphics matrix in X\\
+   \noindent\verb!-msheary "x y a"! Shear the graphics matrix in Y
   \end{framed}}
 
+PDF maintains a stack of graphics state, which we can manipulate with \texttt{-push} which stores the current state, then modify the state for our own purposes, and then use \texttt{-pop} to restore the previous state. Such invocations may be nested. Here is a simple example:
+ 
+\begin{framed}
+ \noindent\small\verb?cpdf -create-pdf AND -draw -circle "200 200 100" -fillcol red -fill?\\
+ \noindent\small\verb?     -push -fillcol blue -circle "300 300 100" -fill?\\
+ \noindent\small\verb?     -pop -circle "400 400 100" -fill  -o out.pdf?
+\end{framed}
+
+\noindent When we use \texttt{-pop} the colour returns to the saved one:
+
+\bigskip
+\fbox{\includegraphics[width=0.3\textwidth]{manualimages/pop.pdf}}
+\bigskip
+
+\noindent One very common use for a \texttt{-push}/\texttt{-pop} pair is to isolate the effects of an operation which modifies the current transformation matrix. These operations are used to translate, rotate, scale and so on. For example: 
+
+\begin{framed}
+ \noindent\small\verb?cpdf -create-pdf AND -draw -circle "200 200 100" -stroke -push?\\
+ \noindent\small\verb?     -mrot "0 0 -0.3" -mscale "0 0 1.5 2" -circle "200 200 100" -stroke?\\
+ \noindent\small\verb?      -pop -circle "200 200 50" -fill -o out.pdf?
+\end{framed}
+
+This is the result. See how the graphics transformation is undone when \texttt{-push} is invoked:
+
+\bigskip
+\fbox{\includegraphics[width=0.3\textwidth]{manualimages/matrix.pdf}}
+\bigskip
+
 \section{Re-use with XObjects}
   {\small\begin{framed}
    \vspace{1.5mm}
@@ -4368,6 +4410,22 @@ Lines may have dash patterns. A dash pattern consists of one or more numbers. Al
    \noindent\verb!-use! Use a saved sequence of graphics operators
   \end{framed}}
 
+In our examples, we have sometimes had to write the same operations multiple times. To avoid this, PDF has a mechanism called an XObject. This allows us to save a set of operations for re-use in different contexts, or on different pages. For example, here we store an XObject which just strokes a circle. We then \texttt{-use} it once, and alter the colour and transformation matrix and \texttt{-use} it again.
+
+\begin{framed}
+ \noindent\small\verb?cpdf -create-pdf AND -draw -xobj-bbox "0 0 200 200" -xobj A?\\
+ \noindent\small\verb?     -circle "100 100 50" -stroke -end-xobj?\\
+ \noindent\small\verb?     -use A -strokecol red -mtrans "20 20" -use A -o out.pdf?
+\end{framed}
+
+\noindent Note that we must specify a bounding box for the XObject with \texttt{-xobj-bbox}. Here is the result:
+
+\bigskip
+\fbox{\includegraphics[width=0.3\textwidth]{manualimages/xobj.pdf}}
+\bigskip
+
+\noindent XObjects may be nested.
+
 \section{Images}
   {\small\begin{framed}
    \noindent\verb!-draw-jpeg! Load a JPEG from file and name it\\
@@ -4424,6 +4482,8 @@ URLs don't work in special text.
 
 The drawing operation \texttt{-newpage} creates a fresh page of the same dimensions as the last page of the document, and sets the drawing range to just that page. For example:
 
+%FIXME: Re-use an xobject across pages
+
 \begin{framed}
  \noindent\small\verb?cpdf -create-pdf AND -draw -bt -text "Page 1" -et?\\
  \noindent\small\verb?     -newpage -bt -text "Page 2" -et?\\

manualimages/clip.pdf

@@ -0,0 +1,29 @@
+%PDF-2.0
+%<25><><EFBFBD><EFBFBD>
+1 0 obj
+<</Type/Catalog/Pages 2 0 R>>
+endobj
+2 0 obj
+<</Type/Pages/Kids[3 0 R]/Count 1>>
+endobj
+3 0 obj
+<</Type/Page/Parent 2 0 R/Resources<<>>/MediaBox[0 0 595.2765 841.89105]/Contents[4 0 R]>>
+endobj
+4 0 obj
+<</Length 119/Filter/FlateDecode>>
+stream
+x
}<7D><>
+<EFBFBD> DWaS<>]<5D>I<1C><>?<3F><>S!<21>DJ<44> <20><>ݵ"a{<7B>P*rQ<72><11><><EFBFBD><EFBFBD>`<60><><EFBFBD><EFBFBD><EFBFBD><12>J<EFBFBD><4A><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><1C>VGיR<D799>ڧ<EFBFBD><DAA7>Ѳ<EFBFBD>p<EFBFBD><70>dBA<42><41><EFBFBD><EFBFBD>b<EFBFBD>E<>PX<50>r@A<>H<EFBFBD><48><EFBFBD><EFBFBD>u<>L#
+endstream
+endobj
+xref
+0 5 
+0000000000 65535 f 
+0000000015 00000 n 
+0000000060 00000 n 
+0000000111 00000 n 
+0000000217 00000 n 
+trailer
+<</Size 5/Root 1 0 R/ID[<563e1a46cebcb6dc4d48ffb3eda578bf><563e1a46cebcb6dc4d48ffb3eda578bf>]>>
+startxref
+404

manualimages/matrix.pdf

@@ -0,0 +1,29 @@
+%PDF-2.0
+%<25><><EFBFBD><EFBFBD>
+1 0 obj
+<</Type/Catalog/Pages 2 0 R>>
+endobj
+2 0 obj
+<</Type/Pages/Kids[3 0 R]/Count 1>>
+endobj
+3 0 obj
+<</Type/Page/Parent 2 0 R/Resources<<>>/MediaBox[0 0 595.2765 841.89105]/Contents[4 0 R]>>
+endobj
+4 0 obj
+<</Length 174/Filter/FlateDecode>>
+stream
+x
<01>P<EFBFBD>
+<EFBFBD> \<5C><0B><>c2F<32>"<22>/<1F><><EFBFBD><EFBFBD>"<22><02><>BȾ<42><C8BE>d<EFBFBD>D q<0F>ޙ<EFBFBD>H+^<5E><>ҡ<>u.<05><>Ĉ=9^<5E><{vwDŽ<77>0<EFBFBD><30><EFBFBD>5F<35><46>1<0E><> <20><>TkiK<><07>!$TkeX<65>MMq<4D>-[9	<09><><EFBFBD>y<EFBFBD><79><EFBFBD>#;q<>\D#Af4<66><34><EFBFBD>d.<2E>ͼl<><6C><EFBFBD>g<EFBFBD><67><EFBFBD><EFBFBD>7DŽ<37><C784>3<EFBFBD>G<EFBFBD><47><EFBFBD>+<2B><><05>r<EFBFBD>|
+endstream
+endobj
+xref
+0 5 
+0000000000 65535 f 
+0000000015 00000 n 
+0000000060 00000 n 
+0000000111 00000 n 
+0000000217 00000 n 
+trailer
+<</Size 5/Root 1 0 R/ID[<22e0ff924dd64953b12cdba4345538a9><22e0ff924dd64953b12cdba4345538a9>]>>
+startxref
+459