diff --git a/cpdfmanual.pdf b/cpdfmanual.pdf index f4bd868..b65bec5 100644 Binary files a/cpdfmanual.pdf and b/cpdfmanual.pdf differ diff --git a/cpdfmanual.tex b/cpdfmanual.tex index 011c633..218d10b 100644 --- a/cpdfmanual.tex +++ b/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?\\ diff --git a/manualimages/clip.pdf b/manualimages/clip.pdf new file mode 100644 index 0000000..f58053d --- /dev/null +++ b/manualimages/clip.pdf @@ -0,0 +1,29 @@ +%PDF-2.0 +% +1 0 obj +<> +endobj +2 0 obj +<> +endobj +3 0 obj +<>/MediaBox[0 0 595.2765 841.89105]/Contents[4 0 R]>> +endobj +4 0 obj +<> +stream +x} DWaS]I?S!DJ ݵ"a{P*rQ`JVGיRڧѲpdBAbEPXr@AHuL# +endstream +endobj +xref +0 5 +0000000000 65535 f +0000000015 00000 n +0000000060 00000 n +0000000111 00000 n +0000000217 00000 n +trailer +<<563e1a46cebcb6dc4d48ffb3eda578bf>]>> +startxref +404 +%%EOF diff --git a/manualimages/matrix.pdf b/manualimages/matrix.pdf new file mode 100644 index 0000000..8849d08 --- /dev/null +++ b/manualimages/matrix.pdf @@ -0,0 +1,29 @@ +%PDF-2.0 +% +1 0 obj +<> +endobj +2 0 obj +<> +endobj +3 0 obj +<>/MediaBox[0 0 595.2765 841.89105]/Contents[4 0 R]>> +endobj +4 0 obj +<> +stream +xP \ c2F"/"BȾdD qޙH+^ҡu.Ĉ=9^<{vwDŽ05F1 TkiK!$TkeXMMq-[9 y#;q\D#Af4d.ͼlg7DŽ3G+r| +endstream +endobj +xref +0 5 +0000000000 65535 f +0000000015 00000 n +0000000060 00000 n +0000000111 00000 n +0000000217 00000 n +trailer +<<22e0ff924dd64953b12cdba4345538a9>]>> +startxref +459 +%%EOF diff --git a/manualimages/pop.pdf b/manualimages/pop.pdf new file mode 100644 index 0000000..0da63bc Binary files /dev/null and b/manualimages/pop.pdf differ diff --git a/manualimages/xobj.pdf b/manualimages/xobj.pdf new file mode 100644 index 0000000..483d496 Binary files /dev/null and b/manualimages/xobj.pdf differ