diff options
author | Karl Berry <karl@freefriends.org> | 2018-02-23 21:54:14 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-02-23 21:54:14 +0000 |
commit | 87d871a3d83784d48b71fa3712b9f525bfc710d2 (patch) | |
tree | f12f9ffdc697b5af9ee14c06874ec0e2f72c9f94 /Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx | |
parent | ccc63194ce7813106830c8a8755c54d89de831b4 (diff) |
l3 (22feb18)
git-svn-id: svn://tug.org/texlive/trunk@46720 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx | 575 |
1 files changed, 575 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx new file mode 100644 index 00000000000..9b7c04d5e54 --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx @@ -0,0 +1,575 @@ +% \iffalse meta-comment +% +%% File: l3draw.dtx Copyright(C) 2018 The LaTeX3 Project +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% http://www.latex-project.org/lppl.txt +% +% This file is part of the "l3experimental bundle" (The Work in LPPL) +% and all files in that bundle must be distributed together. +% +% ----------------------------------------------------------------------- +% +% The development version of the bundle can be found at +% +% https://github.com/latex3/latex3 +% +% for those people who are interested. +% +%<*driver|package> +\RequirePackage{expl3} +%</driver|package> +%<*driver> +\documentclass[full]{l3doc} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \title{^^A +% The \pkg{l3draw} package\\ Core drawing support^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released 2018/02/21} +% +% \maketitle +% +% \begin{documentation} +% +% \section{\pkg{l3draw} documentation} +% +% The \pkg{l3draw} package provides a set of tools for creating (vector) +% drawings in \pkg{expl3}. It is heavily inspired by the \pkg{pgf} layer of +% the Ti\textit{k}Z system, with many of the interfaces having the same form. +% However, the code provided here is build entirely on core \pkg{expl3} ideas +% and uses the \LaTeX3 FPU for numerical support. +% +% Numerical expressions in \pkg{l3draw} are handled as floating point +% expressions, unless otherwise noted. This means that they may contain or +% omit explicit units. Where units are omitted, they will automatically be +% taken as given in (\TeX{}) points. +% +% The code here is \emph{highly} experimental. +% +% \subsection{Drawings} +% +% \begin{function}{\draw_begin:, \draw_end:} +% \begin{syntax} +% \cs{draw_begin:} +% ... +% \cs{draw_end:} +% \end{syntax} +% Each drawing should be created within a \cs{draw_begin:}/\cs{draw_end:} +% function pair. The \texttt{begin} function sets up a number of key +% data structures for the rest of the functions here: unless otherwise +% specified, use of |\draw_...| functions outside of this +% \enquote{environment} is \emph{not supported}. +% +% The drawing created within the environment will be inserted into +% the typesetting stream by the \cs{draw_end:} function, which will +% switch out of vertical mode if required. +% \end{function} +% +% \subsection{Graphics state} +% +% Within the drawing environment, a number of functions control how drawings +% will appear. Note that these all apply \emph{globally}, though some are +% rest at the start of each drawing (\cs{draw_begin:}). +% +% \begin{function}{\g_draw_linewidth_default_dim} +% The default value of the linewidth for stokes, set at the start +% of every drawing (\cs{draw_begin:}). +% \end{function} +% +% \begin{function}{\draw_linewidth:n, \draw_inner_linewidth:n} +% \begin{syntax} +% \cs{draw_linewidth:n} \Arg{width} +% \end{syntax} +% Sets the width to be used for stroking to the \meta{width} (an +% \meta{fp expr}). +% \end{function} +% +% \begin{function}{\draw_nonzero_rule:, \draw_evenodd_rule:} +% \begin{syntax} +% \cs{draw_nonzero_rule:} +% \end{syntax} +% Active either the non-zero winding number or the even-odd rule, +% respectively, for determining what is inside a fill or clip area. +% For technical reasons, these command are not influenced by scoping +% and apply on an ongoing basis. +% \end{function} +% +% \begin{function} +% { +% \draw_cap_butt: , +% \draw_cap_rectangle: , +% \draw_cap_round: +% } +% \begin{syntax} +% \cs{draw_cap_butt:} +% \end{syntax} +% Sets the style of terminal stroke position to one of butt, rectangle or +% round. +% \end{function} +% +% \begin{function} +% { +% \draw_join_bevel: , +% \draw_join_miter: , +% \draw_join_round: +% } +% \begin{syntax} +% \cs{draw_cap_butt:} +% \end{syntax} +% Sets the style of stroke joins to one of bevel, miter or round. +% \end{function} +% +% \begin{function}{\draw_miterlimit:n} +% \begin{syntax} +% \cs{draw_miterlimit:n} \Arg{limit} +% \end{syntax} +% Sets the miter \meta{limit} of lines joined as a miter, as described in the +% PDF and PostScript manuals. The \meta{limit} is an \meta{fp expr}. +% \end{function} +% +% \subsection{Points} +% +% Functions supporting the calculation of points (co-ordinates) are expandable +% and may be used outside of the drawing environment. When used in this +% way, they all yield a co-ordinate tuple, for example +% \begin{verbatim} +% \tl_set:Nx \l_tmpa_tl { \draw_point:nn { 1 } { 2 } } +% \tl_show:N \l_tmpa_tl +% \end{verbatim} +% gives +% \begin{verbatim} +% > \l_tmpa_tl=1pt,2pt. +% <recently read> } +% \end{verbatim} +% +% This output form is then suitable as \emph{input} for subsequent point +% calculations, \emph{i.e.}~where a \meta{point} is required it may be +% given as a tuple. This \emph{may} include units and surrounding +% parentheses, for example +% \begin{verbatim} +% 1,2 +% (1,2) +% 1cm,3pt +% (1pt,2cm) +% 2 * sind(30), 2^4in +% \end{verbatim} +% are all valid input forms. Notice that each part of the tuple may itself +% be a float point expression. +% +% Point co-ordinates are relative to the canvas axes, but can be transformed +% by \cs{draw_point_transform:n}. These manipulation is applied by many +% higher-level functions, for example path construction, and allows parts of +% a drawing to be rotated, scaled or skewed. This occurs before writing any +% data to the driver, and so such manipulations are tracked by the drawing +% mechanisms. See \cs{driver_draw_transformcm:nnnnnn} for driver-level +% manipulation of the canvas axes themselves. +% +% Notice that in contrast to \pkg{pgf} it is possible to give the positions +% of points \emph{directly}. +% +% \subsubsection{Basic point functions} +% +% \begin{function}[EXP]{\draw_point:nn} +% \begin{syntax} +% \cs{draw_point:nn} \Arg{x} \Arg{y} +% \end{syntax} +% Gives the co-ordinates of the point at \meta{x} and \meta{y}, both of +% which are \meta{fp expr}. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_polar:nn, \draw_point_polar:nnn} +% \begin{syntax} +% \cs{draw_point_polar:nn} \Arg{angle} \Arg{radius} +% \cs{draw_point_polar:nnn} \Arg{angle} \Arg{radius-a} \Arg{radius-b} +% \end{syntax} +% Gives the co-ordinates of the point at \meta{angle} (an \meta{fp expr} in +% \emph{degrees}) and \meta{radius}. The three-argument version accepts +% two radii of different lengths. +% +% Note the interface here is somewhat different from that in \pkg{pgf}: +% the one- and two-radii versions in \pkg{l3draw} use separate functions, +% whilst in \pkg{pgf} they use the same function and a keyword. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_add:nn} +% \begin{syntax} +% \cs{draw_point_add:nn} \Arg{point1} \Arg{point2} +% \end{syntax} +% Adds \meta{point1} to \meta{point2}. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_diff:nn} +% \begin{syntax} +% \cs{draw_point_diff:nn} \Arg{point1} \Arg{point2} +% \end{syntax} +% Subtracts \meta{point1} from \meta{point2}. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_scale:nn} +% \begin{syntax} +% \cs{draw_point_scale:nn} \Arg{scale} \Arg{point} +% \end{syntax} +% Scales the \meta{point} by the \meta{scale} (an \meta{fp expr}). +% \end{function} +% +% \begin{function}[EXP]{\draw_point_unit_vector:n} +% \begin{syntax} +% \cs{draw_point_unit_vector:n} \Arg{point} +% \end{syntax} +% Expands to the co-ordinates of a unit vector joining the \meta{point} +% with the origin. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_transform:n} +% \begin{syntax} +% \cs{draw_point_transform:n} \Arg{point} +% \end{syntax} +% Evaluates the position of the \meta{point} subject to the current +% transformation matrix. This operation is applied automatically by +% most higher-level functions (\emph{e.g.}~path manipulations). +% \end{function} +% +% \subsubsection{Points on a vector basis} +% +% As well as giving explicit values, it is possible to describe points +% in terms of underlying direction vectors. The latter are initially +% co-incident with the standard Cartesian axes, but may be altered by +% the user. +% +% \begin{function}{\draw_xvec_set:n, \draw_yvec_set:n, \draw_zvec_set:n} +% \begin{syntax} +% \cs{draw_xvec_set:n} \Arg{point} +% \end{syntax} +% Defines the appropriate base vector to point toward the \meta{point} +% on the canvas. The standard settings for the $x$- and $y$-vectors are +% $1\,\mathrm{cm}$ along the relevant canvas axis, whilst for the +% $z$-vector an appropriate direction is taken. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_vec:nn, \draw_point_vec:nnn} +% \begin{syntax} +% \cs{draw_point_vec:nn} \Arg{xscale} \Arg{yscale} +% \cs{draw_point_vec:nnn} \Arg{xscale} \Arg{yscale} \Arg{zscale} +% \end{syntax} +% Expands to the co-ordinate of the point at \meta{xscale} times the +% $x$-vector and \meta{yscale} times the $y$-vector. The three-argument +% version extends this to include the $z$-vector. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_vec_polar:nn, \draw_point_vec_polar:nnn} +% \begin{syntax} +% \cs{draw_point_vec_polar:nn} \Arg{angle} \Arg{radius} +% \cs{draw_point_vec_polar:nnn} \Arg{angle} \Arg{radius-a} \Arg{radius-b} +% \end{syntax} +% Gives the co-ordinates of the point at \meta{angle} (an \meta{fp expr} in +% \emph{degrees}) and \meta{radius}, relative to the prevailing +% $x$- and $y$-vectors. The three-argument version accepts two radii of +% different lengths. +% +% Note the interface here is somewhat different from that in \pkg{pgf}: +% the one- and two-radii versions in \pkg{l3draw} use separate functions, +% whilst in \pkg{pgf} they use the same function and a keyword. +% \end{function} +% +% \subsubsection{Intersections} +% +% \begin{function}[EXP]{\draw_point_intersect_lines:nnnn} +% \begin{syntax} +% \cs{draw_point_intersect_lines:nnnn} \Arg{point1} \Arg{point2} \Arg{point3} \Arg{point4} +% \end{syntax} +% Evaluates the point at the intersection of one line, joining +% \meta{point1} and \meta{point2}, and a second line joining \meta{point3} +% and \meta{point4}. If the lines do not intersect, or are coincident, and +% error will occur. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_intersect_circles:nnnn} +% \begin{syntax} +% \cs{draw_point_intersect_circles:nnnnn} +% \Arg{center1} \Arg{radius1} \Arg{center2} \Arg{radius2} \Arg{root} +% \end{syntax} +% Evaluates the point at the intersection of one circle with +% \meta{center1} and \meta{radius1}, and a second circle with \meta{center2} +% and \meta{radius2}. If the circles do not intersect, or are coincident, and +% error will occur. +% +% Note the interface here has a different argument ordering from that in +% \pkg{pgf}, which has the two centers then the two radii. +% \end{function} +% +% \subsubsection{Interpolations} +% +% \begin{function}[EXP]{\draw_point_interpolate_line:nnn} +% \begin{syntax} +% \cs{draw_point_interpolate_line:nnn} \Arg{part} \Arg{point1} \Arg{point2} +% \end{syntax} +% Expands to the point which is \meta{part} way along the line joining +% \meta{point1} and \meta{point2}. The \meta{part} may be an interpolation or +% an extrapolation, and is a floating point value expressing a percentage +% along the line, \emph{e.g.}~a value of \texttt{0.5} would be half-way +% between the two points. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_interpolate_distance:nnn} +% \begin{syntax} +% \cs{draw_point_interpolate_distance:nnn} \Arg{distance} \Arg{point expr1} \Arg{point expr2} +% \end{syntax} +% Expands to the point which is \meta{distance} way along the line joining +% \meta{point1} and \meta{point2}. The \meta{distance} may be an interpolation +% or an extrapolation. +% \end{function} +% +% \begin{function}[EXP]{\draw_point_interpolate_curve:nnnnnn} +% \begin{syntax} +% \cs{draw_point_interpolate_curve:nnnnnn} \Arg{part} +% \Arg{start} \Arg{control1} \Arg{control2} \Arg{end} +% \end{syntax} +% Expands to the point which is \meta{part} way along the curve between +% \meta{start} and \meta{end} and defined by \meta{control1} and +% \meta{control2}. The \meta{part} may be an interpolation or +% an extrapolation, and is a floating point value expressing a percentage +% along the curve, \emph{e.g.}~a value of \texttt{0.5} would be half-way +% along the curve. +% \end{function} +% +% \subsection{Paths} +% +% Paths are constructed by combining one or more operations before applying +% one or more actions. Thus until a path is \enquote{used}, it may be +% manipulated or indeed discarded entirely. Only one path is active at +% any one time, and the path is \emph{not} affected by \TeX{} grouping. +% +% \begin{function}{\draw_path_corner_arc:n} +% \begin{syntax} +% \cs{draw_path_corner_arc:n} \Arg{length} +% \end{syntax} +% Sets the degree of rounding applied to corners in a path: if the +% \meta{length} is \texttt{0pt} then no rounding applies. The value of the +% \meta{length} is local to the current \TeX{} group. \emph{At present, +% corner arcs are not activated in the code.} +% \end{function} +% +% \begin{function}{\draw_path_moveto:n} +% \begin{syntax} +% \cs{draw_path_moveto:n} \Arg{point} +% \end{syntax} +% Moves the reference point of the path to the \meta{point}, but will +% not join this to any previous point. +% \end{function} +% +% \begin{function}{\draw_path_lineto:n} +% \begin{syntax} +% \cs{draw_path_lineto:n} \Arg{point} +% \end{syntax} +% Joins the current path to the \meta{point} with a straight line. +% \end{function} +% +% \begin{function}{\draw_path_curveto:nnn} +% \begin{syntax} +% \cs{draw_path_curveto:nnn} \Arg{control1} \Arg{control2} \Arg{end} +% \end{syntax} +% Joins the current path to the \meta{end} with a curved line defined by +% cubic Bézier points \meta{control1} and \meta{control2}. +% \end{function} +% +% \begin{function}{\draw_path_curveto:nn} +% \begin{syntax} +% \cs{draw_path_curveto:nn} \Arg{control} \Arg{end} +% \end{syntax} +% Joins the current path to the \meta{end} with a curved line defined by +% quadratic Bézier point \meta{control}. +% \end{function} +% +% \begin{function}{\draw_path_arc:nnn, \draw_path_arc:nnnn} +% \begin{syntax} +% \cs{draw_path_arc:nnn} \Arg{angle1} \Arg{angle2} \Arg{radius} +% \cs{draw_path_arc:nnnn} \Arg{angle1} \Arg{angle2} \Arg{radius-a} \Arg{radius-b} +% \end{syntax} +% Joins the current path with an arc between \meta{angle1} and \meta{angle2} +% and of \meta{radius}. The four-argument version accepts two radii of +% different lengths. +% +% Note the interface here has a different argument ordering from that in +% \pkg{pgf}, which has the two centers then the two radii. +% \end{function} +% +% \begin{function}{\draw_path_arc_axes:nnnn} +% \begin{syntax} +% \cs{draw_path_arc_axes:nnn} \Arg{angle1} \Arg{angle2} \Arg{vector1} \Arg{vector2} +% \end{syntax} +% Appends the portion of an ellipse from \meta{angle1} to \meta{angle2} of an +% ellipse with axes along \meta{vector1} and \meta{vector2} to the current path. +% \end{function} +% +% \begin{function}{\draw_path_ellipse:nnnn} +% \begin{syntax} +% \cs{draw_path_ellipse:nnn} \Arg{center} \Arg{vector1} \Arg{vector2} +% \end{syntax} +% Appends an ellipse at \meta{center} with axes along \meta{vector1} and +% \meta{vector2} to the current path. +% \end{function} +% +% \begin{function}{\draw_path_circle:nn} +% \begin{syntax} +% \cs{draw_path_circle:nn} \Arg{center} \Arg{radius} +% \end{syntax} +% Appends a circle of \meta{radius} at \meta{center} to the current path. +% \end{function} +% +% \begin{function}{\draw_path_rectangle:nn, \draw_path_rectangle_corners:nn} +% \begin{syntax} +% \cs{draw_path_rectangle:nn} \Arg{lower-left} \Arg{displacement} +% \cs{draw_path_rectangle_corners:nn} \Arg{lower-left} \Arg{top-right} +% \end{syntax} +% Appends a rectangle starting at \meta{lower-left} to the current path, +% with the size of the rectangle determined either by a \meta{displacement} +% or the position of the \meta{top-right}. +% \end{function} +% +% \begin{function}{\draw_path_grid:nnnn} +% \begin{syntax} +% \cs{draw_path_grid:nnnn} \Arg{xspace} \Arg{yspace} \Arg{lower-left} \Arg{upper-right} +% \end{syntax} +% Constructs a grid of \meta{xspace} and \meta{yspace} from the +% \meta{lower-left} to the \meta{upper-right}, and appends this to the +% current path. +% \end{function} +% +% \begin{function}{\draw_path_close:} +% \begin{syntax} +% \cs{draw_path_close:} +% \end{syntax} +% Closes the current part of the path by appending a straight line from +% the current point to the starting point of the path. +% \end{function} +% +% \begin{function}{\draw_path_use:n, \draw_path_use_clear:n} +% \begin{syntax} +% \cs{draw_path_use:n} \Arg{action(s)} +% \end{syntax} +% Inserts the current path, carrying out one ore more possible \meta{actions} +% (a comma list): +% \begin{itemize} +% \item \texttt{clear} Resets the path to empty +% \item \texttt{clip} Clips any content outside of the path +% \item \texttt{draw} +% \item \texttt{fill} Fills the interior of the path with the current +% file color +% \item \texttt{stroke} Draws a line along the current path +% \end{itemize} +% \end{function} +% +% \subsection{Color} +% +% \begin{function}{\draw_color:n, \draw_fill:n, \draw_stroke:n} +% \begin{syntax} +% \cs{draw_color:n} \Arg{color expression} +% \end{syntax} +% Evaluates the \meta{color expression} as described for \pkg{l3color}. +% \end{function} +% +% \subsection{Transformations} +% +% Points are normally used unchanged relative to the canvas axes. This can +% be modified by applying a transformation matrix. The canvas axes themselves +% may be adjusted using \cs{driver_draw_transformcm:nnnnnn}: note that this +% is transparent to the drawing code so is not tracked. +% +% \begin{function}{\draw_transform_reset:} +% \begin{syntax} +% \cs{draw_transform_reset:} +% \end{syntax} +% Resets the matrix to the identity. +% \end{function} +% +% \begin{function}{\draw_transform_concat:nnnnn} +% \begin{syntax} +% \cs{draw_transform_concat:nnnnn} +% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector} +% \end{syntax} +% Appends the given transformation to the currently-active one. The +% transformation is made up of a matrix \meta{a}, \meta{b}, \meta{c} and +% \meta{d}, and a shift by the \meta{vector}. +% \end{function} +% +% \begin{function}{\draw_transform:nnnnn} +% \begin{syntax} +% \cs{draw_transform:nnnnn} +% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector} +% \end{syntax} +% Applies the transformation matrix specified, over-writing any existing +% matrix. The transformation is made up of a matrix \meta{a}, \meta{b}, +% \meta{c} and \meta{d}, and a shift by the \meta{vector}. +% \end{function} +% +% \begin{function}{\draw_transform_triangle:nnn} +% \begin{syntax} +% \cs{draw_transform_triangle:nnn} +% \Arg{origin} \Arg{point1} \Arg{point2} +% \end{syntax} +% Applies a transformation such that the co-ordinates $(0, 0)$, $(1, 0)$ +% and $(0, 1)$ are given by the \meta{origin}, \meta{point1} and +% \meta{point2}, respectively. +% \end{function} +% +% \begin{function}{\draw_transform_invert:} +% \begin{syntax} +% \cs{draw_transform_invert:} +% \end{syntax} +% Inverts the current transformation matrix and reverses the current +% shift vector. +% \end{function} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3draw} implementation} +% +% \begin{macrocode} +%<*initex|package> +% \end{macrocode} +% +% \begin{macrocode} +%<@@=draw> +% \end{macrocode} +% +% \begin{macrocode} +%<*package> +\ProvidesExplPackage{l3draw}{2018/02/21}{} + {L3 Experimental core drawing support} +%</package> +% \end{macrocode} +% +% \begin{macrocode} +\RequirePackage { l3color } +% \end{macrocode} +% +% Everything else is in the sub-files! +% +% \begin{macrocode} +%</initex|package> +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex |