% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
\clearpage
\section{Using Images as a Pattern}
\label{library:patterns.images}

\begin{tikzlibrary}{ext.patterns.images}
  This library allows to use an image to be used as a repeating pattern for a path.
  
  \inspiration{Pattern-Q}{Pattern-A}
\end{tikzlibrary}

With this library arbitrary images (or indeed PDF documents) can be used as
a repeating pattern for the background of a path.

This is a two-step process:
\begin{enumerate}
\item Declaring an image as an ``image-pattern''.
\item Using the ``image-pattern''.
\end{enumerate}

\begin{command}{\tikzextsetupimageaspattern\oarg{options}\marg{name}\marg{image}}\cmdcompat{\pgfsetupimageaspattern}
\end{command}

\begin{key}{/\tikzext/image as pattern=\meta{options} (default \{\})}\keycompat{tikz}

\begin{codeexample}[preamble=\usetikzlibrary{ext.patterns.images,shapes.geometric}]
\tikzextsetupimageaspattern[width=.5cm]{grid}{example-image-1x1}
\tikz \node[star, minimum size=3cm, draw,
  ext/image as pattern={name=grid, options={left, bottom, y=-.5cm, rotate=45}}] {};
\end{codeexample}
\end{key}

\begin{key}{/\tikzext/image as pattern/name=\meta{name}}\keycompat{tikz/image as pattern}
Specifies the name of the ``image-pattern'' to be used.
\end{key}

\begin{stylekey}{/\tikzext/image as pattern/option}\keycompat{tikz/image as pattern}
Options that will be used by the internal |\pgftext|,\indexCommandO{\pgftext}
only keys from |/pgf/text| should be used.\indexKeyO[/pgf/]{text}
\end{stylekey}

\begin{key}{/\tikzext/image as pattern/options=\meta{style}}\keycompat{tikz/image as pattern}
Appends to style |/tikz/ext/image as pattern/option|.
\end{key}