%% $Id: xytile.doc,v 3.4 1997/05/18 01:13:24 ross Exp $
%%
%% Xy-pic ``Pattern and Tile extension'' option.
%% Copyright (c) 1993-1997	Ross Moore	<ross@mpce.mq.edu.au>
%%
%% This file is part of the Xy-pic package for graphs and diagrams in TeX.
%% See the companion README and INSTALL files for further information.
%% Copyright (c) 1991-1997	Kristoffer H. Rose	<krisrose@brics.dk>
%%
%% The Xy-pic package is free software; you can redistribute it and/or modify
%% it under the terms of the GNU General Public License as published by the
%% Free Software Foundation; either version 2 of the License, or (at your
%% option) any later version.
%%
%% The Xy-pic package is distributed in the hope that it will be useful, but
%% WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
%% or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
%% for more details.
%%
%% You should have received a copy of the GNU General Public License along
%% with this package; if not, write to the Free Software Foundation, Inc.,
%% 675 Mass Ave, Cambridge, MA 02139, USA.
%%
\ifx\xyloaded\undefined \input xy \fi

\xyprovide{tile}{Pattern and Tile extension}{\stripRCS$Revision: 3.4 $}%
 {Ross Moore}{ross@mpce.mq.edu.au}%
 {Mathematics Department, Macquarie University, NSW~2109, Australia}

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This extension provides the ability to request that a filled region be 
tiled using a particular pattern. 

This is an effect not normally available within \TeX.
Instead it requires a suitable <driver> option to provide the necessary
|\special| commands, together with any extra commands needed to implement 
the effects. Thus
$$
\xy
 *+\txt<.8\hsize>{Using this extension will have no effect on the output
	unless used with a dvi-driver that explicitly supports it.}
 *\frm{-}
\endxy
$$
All effects defined in the |tile| extension can be implemented using most 
\PS\ <driver>s, loaded as |\xyoption{|<driver>|}|.  

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{Header:}\leavevmode
\DOCHEADER

Like using color, tiling with patterns is an instance of a special style, 
since use of a pattern has no effect on the size or shape of the <object> 
being typeset. It only affects how the <object> will appear on the printed
page or on-screen.

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\LoadAllPatterns{xymacpat}
\def\MacPatterns{\begin{figure*}[ht]
$$
%
 \newcount\R \newcount\C
 \def\n{\advance\R1 \C0 \POS(\R,\C)}
 \def\F##1{\advance\C1 %
 \POS(\R,\C)*+\txt\small{\phantom{filled}\\{\phantom{pattern}}}*[thicker]\frm{-},*[##1]\frm{**},
	+D*+!U\txt\small{##1}}
%
\R-1 \C0 \xy
 0;<0cm,-1.5cm>:<1.5cm,0cm>:: \relax
% \n,{\C1\POS(\R,\C)}
 \n\F{mac01}\F{mac02}\F{mac03}\F{mac04}\F{mac05}\F{mac06}\F{mac07}\F{mac08}
 \n\F{mac09}\F{mac10}\F{mac11}\F{mac12}\F{mac13}\F{mac14}\F{mac15}\F{mac16}
 \n\F{mac17}\F{mac18}\F{mac19}\F{mac20}\F{mac21}\F{mac22}\F{mac23}\F{mac24}
 \n\F{mac25}\F{mac26}\F{mac27}\F{mac28}\F{mac29}\F{mac30}\F{mac31}\F{mac32}
 \n\F{mac33}\F{mac34}\F{mac35}\F{mac36}\F{mac37}\F{mac38}
%
\endxy
$$
\caption{The 38 standard Macintosh patterns.}
??=[f.macpats]
\end{figure*}\let\MacPatterns=\relax}
\MacPatterns

\paragraph*{Patterns}
Patterns are specified as a <shape> modifier, similar to the way colours
are specified by name.  
The pattern is applied to the whole of the current <object> whether this be 
text, an \Xy-pic line, curve or arrow-tip, or a composite object such as 
a matrix or the complete picture. However some DVI-drivers may not support 
use of patterns in all cases.

If the current DVI-driver cannot support patterns then a request for one
simply produces a warning message in the log file. After two such
messages subsequent requests are ignored completely.
%
\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DOCMODE(
\xydef@\xypatternwarning@@{\xypatternmessage@
 \gdef\xypatternwarning@{\xypatternmessage@
  \xywarning@{...no further pattern warnings will be given.}%
 \global\let\xypatternwarning@=\relax }}
\xylet@\xypatternwarning@=\xypatternwarning@@

\xydef@\xypatternmessage@{%
  \xywarning@{Current driver does not support patterns.}}%
\DOCMODE)

This allows new patterns to be specified from raw data.
Make sure the usual catcodes are in place before the data is tokenised.

\DOCMODE(
\xydef@\newxypattern{\begingroup\xycatcodes\newxypattern@i}
\xydef@\newxypattern@i#1#2{\edef\next@{\endgroup
 \noexpand\newxyPattern{#1}{}{#2}{}}\next@}
\xydef@\newxyPattern#1#2#3#4{\newxypattern@{#1}{#2}{#3}{#4}{}}
\DOCMODE)

Existing pattern names can be overridden using |\newxypattern@#1#2\relax|.

\DOCMODE(
\xydef@\newxypattern@#1#2#3#4#5{%
 \expandafter\let\expandafter\next@\csname shape [#1]\endcsname
 \ifx\next@\relax
  \DN@{#4}\ifx\next@\empty
   \DN@{#2}\ifx\next@\empty
    \DN@{\newxystyle{#1}{\xylocalpattern@{}{#3}\xypattern@{#3}}}%
   \else
    \DN@{\newxystyle{#1}{\xylocalpattern@{#2}{#3}\xypattern@{#2 #3}}}%
   \fi
  \else\DN@{#2#3}\ifx\next@\empty
    \DN@{\newxystyle{#1}{\xylocalpattern@{#4}{}\xypattern@{#4}}}%
   \else
    \DN@{\newxystyle{#1}{\xylocalpattern@{#2}{#3}\xypattern@{#4}}}%
  \fi\fi 
 \else \def\tmp@{\relax}\DNii@{#5}%
 \ifx\nextii@\tmp@
  \DN@{#4}\ifx\next@\empty
   \DN@{#2}\ifx\next@\empty
    \DN@{\newxystyle{#1}{\xylocalpattern@{}{#3}\xypattern@{#3}}}%
   \else
    \DN@{\newxystyle{#1}{\xylocalpattern@{#2}{#3}\xypattern@{#2 #3}}}%
   \fi
  \else
   \DN@{#2#3}\ifx\next@\empty
    \DN@{\newxystyle{#1}{\xylocalpattern@{#4}{}\xypattern@{#4}}}%
   \else
    \DN@{\newxystyle{#1}{\xylocalpattern@{#2}{#3}\xypattern@{#4}}}%
  \fi\fi 
 \else\DN@{}\fi\fi \next@\relax }
\DOCMODE)

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
\begin{defs}
|[|<name>|]| & use named pattern \hfill \cr
\noalign{\smallskip}
\multispan2{??c![\newxypattern]|{|<name>|}{|<data>|}|}\cr 
&\omit specify new pattern using <data>\hfil\cr
\noalign{\smallskip}
\multispan2{|\UsePatternFile{|<file>|}|}\cr
&\omit sets default file for patterns\hfil \cr
\noalign{\smallskip}
\multispan2{|\LoadAllPatterns{|<file>|}|}\cr
&\omit load all patterns in <file>\hfil \cr
\noalign{\smallskip}
\multispan2{|\LoadPattern{|<name>|}{|<file>|}|}\cr
&\omit load named pattern from <file> \hfil\cr
\noalign{\smallskip}
\multispan2{|\AliasPattern{|<alias>|}{|<name>|}{|<file>|}|}\cr
&\omit let <alias> denote pattern from <file>.\hfil
\end{defs}
%
Although pattern data may be specified directly using |\newxypattern|, it is
more usual to load it from a <file> in which many patterns are defined by
name, each on a separate line.  By convention such files always end in |.xyp|
(\Xy-pattern) so no extension should be specified. The pattern is then
requested using either the name supplied in the file or by an alias.  Once
|\UsePatternFile| has been used, then a null <file> argument to the other
commands will still find patterns in the default file. The default remains in
effect for the current level of \TeX\ grouping.

For example, the following picture  
\begin{code}
\AliasPattern{bricks}{mac12}{xymacpat}
\AliasPattern{bars}{mac08}{xymacpat}
\xy *+<5pc,3.1pc>{},{*[bricks]\frm{**}}
 ,*+<2.5pc>[o]{},*[bars]\frm{**}
\endxy
\end{code}
$$\docode$$
uses `filled' frames from the |frame| feature:
\displaycode

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

There are two methods, perhaps used simultaneously, for handling requests 
for a pattern. The |\xylocalpattern@| is the normal method, patterning 
whatever objects \TeX\ typesets from fonts or rules. 
The more specialized |\xypattern@| is used with a \PS\ <driver>. 

Thus a <driver> which supports both pattern and \PS\ must define a method to 
handle |\xylocalpattern@| but should leave alone |\xypattern@|. The latter
method will be adjusted appropriately when a \PS\ <driver> is installed.

\DOCMODE(
\xydef@\xyNopattern@#1{}
\xylet@\xypattern@@=\xyNopattern@
\xydef@\xyNopattern@@#1#2{\xypatternwarning@}

\xylet@\xypattern@=\xypattern@@
\xylet@\xylocalpattern@=\xyNopattern@@
\DOCMODE)

This is to facilitate unloading patterns when the <driver> is changed
to one that does not support this feature. This is the default state, 
until an appropriate <driver> is loaded.

\DOCMODE(
\xydef@\Unloadpattern@{%
 \let\xylocalpattern@=\xyNopattern@@
 \let\xypattern@=\xyNopattern@
 \let\xypatternwarning@=\xypatternwarning@@ }

\Unloadpattern@
\DOCMODE)

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\paragraph*{Pattern data}
A region is tiled using copies of a single `cell' regularly placed so as to
seamlessly tile the entire region. The <data> appearing as an argument to
|\newxypattern| is ultimately passed to the dvi-driver.

The simplest form of pattern data is: <num> <Hex-data>, where the data 
is a 16-character string of Hexadecimal digits; i.e. 0--9, $A$--$F$. 
Each Hex-digit equates to 4 binary bits, so this data contains 64 bits 
representing pixels in an $8\times8$ array.
The <num> is an integer counting the number of `0's among the 64 bits. 
Taken as a fraction of 64, this number or its complement, represents the 
average density of `on' pixels within a single cell of the pattern. 
Drivers unable to provide the fine detail of a pattern may simply use this 
number, or its complement, as a gray-level or part of a colour specification 
for the whole region to be tiled.

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

A desirable set of standard patterns could be specified to be always loaded.
If such a set emerges indeed as being frequently desirable then it will be 
included here.

\DOCMODE(
\xydef@\xystandardpatterns@{}%
\DOCMODE)

\NOTE: The driver file must call |\xystandardpatterns@| before these 
patterns become accessible. This is to allow any <driver>-specific 
definitions to be active when these patterns are defined.

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DOCMODE(
\xynew@{read}{\xypatread@}
\xydef@\defaultpattfile@{}

\xydef@\xygetfilepatterns@#1{\DN@{#1}%
 \ifx\next@\empty
  \ifx\defaultpattfile@\empty \xywarning@{No pattern file specified.}%
  \else \DN@{\expandafter\openpattfile@\expandafter{\defaultpattfile@}}\fi
 \else \DN@{\openpattfile@{#1}}\fi \next@ }

\xydef@\openpattfile@#1{\openin\xypatread@=#1.xyp %
 \ifeof\xypatread@\xywarning@{No patterns in file: #1.xyp}%
  \closein\xypatread@
 \else \expandafter \xyreadpatfile@ \fi }%

\xydef@\UsePatternFile#1{\def\defaultpattfile@{#1}}

\xydef@\LoadAllPatterns{\let\parsepattern@=\parsepattern@@
  \xygetfilepatterns@ }

\xydef@\LoadPattern#1{\let\parsepattern@=\filepattern@@
  \def\pattname@{#1}\xygetfilepatterns@}

\xydef@\AliasPattern#1#2{\let\parsepattern@=\aliaspattern@@
  \def\aliasname@{#1}\def\pattname@{#2}\xygetfilepatterns@}
\DOCMODE)

The character |!| is used to delimit comments within pattern-data
files.

\DOCMODE(
\xydef@\xyreadpatfile@{%
 \loop@ \bgroup\xycatcodes
  \global\read\xypatread@ to\xypatline@
  \ifeof\xypatread@ \aftergroup\endpatread@
   \else\aftergroup\morepatread@\fi \edef\next@{%
  \egroup\noexpand\getxypattern@{\xypatline@!!!}\relax}\next@
 \repeat@ }
\xydef@\endpatread@{\closein\xypatread@\iffalse}
\xydef@\morepatread@{\iftrue}

%\xydef@\getxypattern@{\futurelet\next\getxypattern@@}
\xydef@\getxypattern@#1{\def\next{#1}\getxypattern@@}
\xydef@\getxypattern@@{\DN@{!!!}\ifx\next\next@\DN@{}%
 \else\DN@{\expandafter\parsepattern@\next}\fi \next@ }

\xydef@\parsepattern@@#1 #2!#3\relax{\newxypattern{#1}{#2}}
\xydef@\filepattern@@#1 #2!#3\relax{\DN@{#1}%
 \ifx\next@\pattname@
  \DN@{\expandafter\foundpattern@\expandafter{\pattname@}{#2}}%
 \else\DN@{}\fi \next@ }
\xydef@\foundpattern@#1#2{\newxypattern{#1}{#2}\endpatread@\fi
 \expandafter\eat@}
\xydef@\aliaspattern@@#1 #2!#3\relax{\DN@{#1}%
 \ifx\next@\pattname@
  \DN@{\expandafter\foundpattern@\expandafter{\aliasname@}{#2}}%
 \else\DN@{}\fi \next@ }

%\xydef@\parsepattern@#1 #2!#3\relax{\message{#1:#2}}
\DOCMODE)

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\medskip
\noindent
The file |xymacpat.xyp| contains defining data for the 38 standard
patterns available with the Macintosh Operating system. 
Figure~??[f.macpats] displays all these patterns.

% Comment this line an uncomment one below, to move the patterns to a 
% later page.

%\MacPatterns

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage
\paragraph*{Rotating and Resizing Patterns}
%
Some implementations of patterns are sufficiently versatile to allow extra
parameters to affect the way the pattern data is interpreted. \PS\ is one
such implementation in which it is possible to rotate the whole pattern and
even to expand or contract the sizes of the basic cell. 

Due to the raster nature of output devices, not all such requests can be
guaranteed to produce aesthetic  results on all devices. In practice only
rotations through specific angles (e.g 30$^\circ$, 45$^\circ$, 60$^\circ$)
and particular scaling ratios can be reliably used. 
Thus there is no sophisticated interface provided by \Xy-pic to access these 
features. However the `\PS\ escape' mechanism does allow a form of access,
when a \PS\ <driver> is handling pattern requests. 

Special \PS\ operators |pa| and |pf| set the pattern angle (normally 0) 
and `frequency' measured in {\em cells per inch}. Hence, when used as an
<object>-modifier, |[! 30 pa 18.75 pq]| rotates the pattern by 30$^\circ$ 
clockwise and uses a smaller pattern cell (larger frequency). 
The default frequency of $12.5=300/(8\times3)$ means that 
each pixel in a pattern cell corresponds, on a device of resolution 
300{\small dpi}, to a $3\times3$ square of device pixels; 
on such a device $18.75$ uses $2\times2$ squares.

At 300{\small dpi} a frequency of $9.375=300/(8\times4)$ uses $4\times4$ 
squares. These match the natural size for pixels on a 75{\small dpi} screen 
and are pretty close for 72{\small dpi} screens. 
Though appropriate for screen displays, these are `too chunky' for high
quality printed work. Doubling the frequency is too fine for some patterns,
hence the intermediate choice of $12.5$ as default. 
In order for printed output to match the screen view, a \PS\ operator |macfreq| 
has been defined to facilitate requests for $9.375$, via |[!macfreq]|.

The next diagram displays changes to the frequency. 
%  
$$
 \newcount\R \newcount\C
 \def\n{\advance\R1 \C0 \POS(\R,\C)}
 \def\F#1#2{\advance\C1 %
 \POS(\R,\C)*+\txt\small{filled\\pattern}*[thicker]\frm{-}
 ,*[! #2 pq][#1]\frm{**},
	+D*+!U\txt\small{#2}}
%
\R-1 \C0 \xy
 0;<0cm,-1.5cm>:<2.0cm,0cm>:: \relax
% \n,{\C1\POS(\R,\C)}
 \n\F{mac38}{9.375}\F{mac38}{12.5}\F{mac38}{18.75}\F{mac38}{37.5}
 \n\F{mac16}{9.375}\F{mac16}{12.5}\F{mac16}{18.75}\F{mac16}{37.5}
%
\endxy
$$

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
\paragraph*{Saving patterns: \ }
%
When styles are saved using ??c[[=]<word>|]|, see note~??g[xy.doc:define
<shape>] of \S??g[xy.doc:object], then the current pattern (if any) is also
saved.  Subsequent use of |[|<word>|]| recovers the pattern as well as colour
and line-style settings.  This includes any explicit variations applied using
the ``Style Escape'' mechanism.
 
Here is a variation of an earlier example, with extra effects.
\begin{code}
\UsePatternFile{xymacpat}
\AliasPattern{bricks}{mac12}{}
\LoadPattern{mac28}{}\LoadPattern{mac05}{}
\xy *=0[! macfreq -45 pa][mac28][|=Bars]{}
,*+<12pc,4pc>{}*[bricks]\frm{**}
,-<3.5pc,0pt>,*+<2.65pc>[o]{},*[Bars]\frm{**}
,*[thicker]\frm{o},+<6pc,0pt>
,*+<5pc, 2.7pc>{},*[mac05]\frm{**},*\frm{-,}
,*[white]\txt\Large\bf\sf{Kilroy\\was here}
\endxy
\end{code}
$$\docode$$
\displaycode

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Add this extension to the driver-tables as ``unload'',
unless an already-loaded driver can support it:

\DOCMODE(
\DN@{\xyaddunsupport{tile}\Unloadpattern@}%
\ifx\xyeverywithoption@tile@\undefined
\else\ifx\xyeverywithoption@tile@\empty
\else
 \DN@{\xysetup@@{\xywithoption{tile}{\xyeverywithoption@tile@\xydriversloaded@@}}}%
\fi\fi \next@
\DOCMODE)

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Uncomment this to move the patterns to a later page.

%\MacPatterns

\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{The end \& Log}\leavevmode

\DOCMODE(
\xyendinput

% $Log: xytile.doc,v $
% Revision 3.4  1997/05/18 01:13:24  ross
% Essential bugfixes.
%
% Revision 3.3  1996/12/18  09:43:06  ross
% documentation change
%
% Revision 3.2  1995/09/19  18:21:41  ross
% Bug fix release.
%
% Revision 3.1  1995/09/05  20:36:33  ross
% Release!
%
% Revision 3.0  1995/07/07  20:13:19  ross
% Major release w/new User's Guide!
%
% Revision 2.13  1995/07/04  15:04:51  ross
% Ready for release of v3.
%
%
% NEW for version 3.0 by by Ross Moore.
\DOCMODE)

\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Tell Emacs that this is a LaTeX document and how it is formatted:
% Local Variables:
% mode:latex
% fill-column:77
% fill-prefix:""
% End: