diff options
author | Karl Berry <karl@freefriends.org> | 2018-03-07 21:50:56 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-03-07 21:50:56 +0000 |
commit | f11f49763fc33ac8427d8c175d98a8d1275e4c5c (patch) | |
tree | 79aacd4b6ab168db69112977f42c2c99204e1621 /Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx | |
parent | fb72b3560bdc8a98d78bf919da56c3316fa7723d (diff) |
l3 (6mar18)
git-svn-id: svn://tug.org/texlive/trunk@46875 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 | 670 |
1 files changed, 602 insertions, 68 deletions
diff --git a/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx index 9b7c04d5e54..7cefc6d837d 100644 --- a/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx +++ b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx @@ -25,6 +25,71 @@ %</driver|package> %<*driver> \documentclass[full]{l3doc} +\usepackage[utf8]{inputenc} +\usepackage{l3draw} +% For creating code demonstrations +% This needs access to some code-level interfaces in listings +\usepackage{listings} +\makeatletter +\lst@RequireAspects{writefile} +\newsavebox\demo@box +\lstnewenvironment{demo}[1][code and example] + {% + \global\let\lst@intname\@empty + \edef\demo@end{% + \expandafter\noexpand\csname demo@@#1@end\endcsname + }% + \@nameuse{demo@@#1}% + } + {\demo@end} +\newcommand\demo@new[3]{% + \@namedef{demo@@#1}{#2}% + \@namedef{demo@@#1@end}{#3}% +} +\newcommand*\demo@common{% + \setkeys{lst} + {% + basicstyle = \small\ttfamily, + basewidth = 0.51em, + gobble = 5, + language = [LaTeX]{TeX}, + }% +} +\newcommand*\demo@input{% + \ExplSyntaxOn + \catcode`\^^M = 10\relax + \catcode`\% = 14\relax + \input{\jobname.tmp}% + \ExplSyntaxOff +} +\demo@new{code and example}{% + \setbox\demo@box=\hbox\bgroup + \lst@BeginAlsoWriteFile{\jobname.tmp}% + \demo@common +}{% + \lst@EndWriteFile + \egroup + \begin{center} + \ifdim\wd\demo@box > 0.75\linewidth + \begin{minipage}{\linewidth} + \usebox\demo@box + \end{minipage}% + \par + \begin{minipage}{\linewidth} + \demo@input + \end{minipage} + \else + \begin{minipage}{0.25\linewidth} + \demo@input + \end{minipage}% + \hfil + \begin{minipage}{0.75\linewidth} + \usebox\demo@box + \end{minipage}% + \fi + \end{center} +} +\makeatother \begin{document} \DocInput{\jobname.dtx} \end{document} @@ -44,7 +109,7 @@ % }^^A % } % -% \date{Released 2018/02/21} +% \date{Released 2018/03/05} % % \maketitle % @@ -82,6 +147,64 @@ % 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. +% \begin{demo} +% \dim_new:N \l_mypos_dim +% \draw_begin: +% \draw_path_moveto:n { 0cm , \l_mypos_dim } +% \draw_path_lineto:n { 1cm , \l_mypos_dim } +% \dim_set:Nn \l_mypos_dim { 1cm } +% \draw_path_lineto:n { 1cm , \l_mypos_dim } +% \draw_path_close: +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% +% Within a drawing, the only commands that should appear are those directly +% aimed at drawing (from \pkg{l3draw}) and those which produce \emph{no} +% typeset output. For example, it is possible to include loops inside a +% drawing using |\int_step_function:nnnn| or similar. On the other hand, +% text should not be included directly in drawings, but should rather be +% inserted using the appropriate \pkg{l3draw} command. +% \end{function} +% +% Within a drawing, there are different ways of referring to a position. +% The co-ordinates of a point are given relative to the current +% \emph{drawing axes}. These can be manipulated and tracked at the code +% level. Underlying this is the \meta{canvas}, which is at the \pkg{draw} +% level essentially fixed and in line with the paper. Initially, the two +% sets of axes are coincident. (It is possible to manipulate the canvas +% axes at the driver level: this is then \enquote{transparent} to the +% \pkg{draw} level, and so should be used only when strictly required.) +% +% \begin{function}{\draw_suspend_begin:, \draw_suspend_end:} +% \begin{syntax} +% \cs{draw_suspend_begin:} +% ... +% \cs{draw_suspend_end:} +% \end{syntax} +% Suspends all of the drawing mechanisms to allow \enquote{normal} +% material to be created. Typically, this environment will be applied +% inside a box which may contain nested pictures. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \hbox_set:Nn \l_tmpa_box +% { +% \draw_suspend_begin: +% This~is~normal~text. +% \draw_begin: % A subpicture +% \draw_path_moveto:n { 1cm , 0cm } +% \draw_path_lineto:n { 1cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% More~text. +% \draw_suspend_end: +% } +% \draw_box_use:N \l_tmpa_box +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} % \end{function} % % \subsection{Graphics state} @@ -90,10 +213,10 @@ % 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} +% \begin{variable}{\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} +% \end{variable} % % \begin{function}{\draw_linewidth:n, \draw_inner_linewidth:n} % \begin{syntax} @@ -140,10 +263,54 @@ % % \begin{function}{\draw_miterlimit:n} % \begin{syntax} -% \cs{draw_miterlimit:n} \Arg{limit} +% \cs{draw_miterlimit:n} \Arg{factor} % \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}. +% Sets the miter \meta{factor} of lines joined as a miter, as described in the +% PDF and PostScript manuals. The \meta{factor} is an \meta{fp expr}. +% \end{function} +% +% \subsection{Scoping drawing elements} +% +% Scoping drawing elements is necessary to allowing nesting of subparts. +% These features have specific use requirements: the preconditions must be +% met. In particular, each type of drawing scope also constitutes a +% group (\cs{groupd_being:}/\cs{group_end:} pair): as such, they must be +% nested correctly. +% +% \begin{function}{\draw_scope_begin:, \draw_scope_end:} +% \begin{syntax} +% \cs{draw_scope_begin:} +% ... +% \cs{draw_scope_end:} +% \end{syntax} +% Creates a scope for localisation of state settings within a drawing. +% A scope forms a \TeX{} group but will also localise global state +% variables (such as \cs{g_draw_linewidth_default_dim}), and driver-level +% concepts such as the termination of lines. +% \begin{demo} +% \draw_begin: +% \draw_scope_begin: +% \group_begin: +% \draw_linewidth:n { 2pt } +% \draw_path_rectangle:nn { 0 , 0 } { 2ex , 2ex } +% \draw_path_use:n { stroke } +% \group_end: +% \draw_path_rectangle:nn { 3ex , 0ex } { 2ex , 2ex } +% \draw_path_use:n { stroke } +% \draw_scope_end: +% \draw_path_rectangle:nn { 6ex , 0ex } { 2ex , 2ex } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% Global graphical concepts restricted by scope are +% \begin{itemize} +% \item Line width +% \item Stroke and fill color +% \item Dash pattern +% \item Line joining and capping, including the miter limit +% \item Clipping paths +% \item Canvas (driver) transformations +% \end{itemize} % \end{function} % % \subsection{Points} @@ -180,7 +347,7 @@ % 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 +% mechanisms. See \cs{driver_draw_cm:nnnn} for driver-level % manipulation of the canvas axes themselves. % % Notice that in contrast to \pkg{pgf} it is possible to give the positions @@ -235,8 +402,8 @@ % \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. +% Expands to the co-ordinates of a unit vector in the direction of the +% \meta{point} from the origin. % \end{function} % % \begin{function}[EXP]{\draw_point_transform:n} @@ -255,9 +422,9 @@ % 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{function}{\draw_xvec:n, \draw_yvec:n, \draw_zvec:n} % \begin{syntax} -% \cs{draw_xvec_set:n} \Arg{point} +% \cs{draw_xvec: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 @@ -358,16 +525,86 @@ % 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{function}{\draw_path_corner_arc:nn} +% \begin{syntax} +% \cs{draw_path_corner_arc:n} \Arg{length1} \Arg{length2} +% \end{syntax} +% Sets the degree of rounding applied to corners in a path: the two +% \meta{length} values are the distances from the corner at which the curving +% should start. The first \meta{length} applies to the part of the path +% \enquote{leading in} to the corner (\emph{i.e.}~from the previous path +% operation), and the second to that \enquote{leading out}. If both +% values are \texttt{0pt} then corners will not be rounded. The values +% apply within the scope of the current \TeX{} group. +% \begin{demo} +% \draw_begin: +% \draw_path_corner_arc:nn { 5mm } { 5mm } +% \draw_path_rectangle_corners:nn +% { 0cm , 0cm } { 3cm , 2cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% \begin{demo} +% \draw_begin: +% \draw_path_corner_arc:nn { 10mm } { 5mm } +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 2cm } +% \draw_path_lineto:n { 3cm , 2cm } +% \draw_path_curveto:nnn +% { 3cm , 0cm } { 2cm , 0cm } { 1cm , 0 cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% The corners created are quarter-circles for exact right-angles and +% close approximations otherwise. Closing a path will result in rounding +% correctly. +% \begin{demo} +% \draw_begin: +% \draw_path_corner_arc:nn { 4pt } { 4pt } +% \draw_path_moveto:n +% { \draw_point_polar:nn { 0 } { 1cm } } +% \int_step_inline:nnnn { 72 } { 72 } { 359 } +% { +% \draw_path_lineto:n +% { \draw_point_polar:nn { #1 } { 1cm } } +% } +% \draw_path_close: +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% \end{function} +% +% \begin{function}{\draw_path_close:} % \begin{syntax} -% \cs{draw_path_corner_arc:n} \Arg{length} +% \cs{draw_path_close:} % \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.} +% Closes the current part of the path by appending a straight line from +% the current point to the starting point of the path. In general, any +% path to be \emph{filled} should include a close instructions. % \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} +% +% \subsubsection{Path operations on drawing axes} +% +% The standard path functions are all influenced by the active transformation +% matrix, \emph{i.e.}~the work relative to the drawing axes rather than +% the canvas. +% % \begin{function}{\draw_path_moveto:n} % \begin{syntax} % \cs{draw_path_moveto:n} \Arg{point} @@ -381,6 +618,32 @@ % \cs{draw_path_lineto:n} \Arg{point} % \end{syntax} % Joins the current path to the \meta{point} with a straight line. +% In general, for reliable treatment by viewers, a \cs{draw_path_moveto:n} +% operation should precede the first use of a \cs{draw_path_lineto:n} +% on a path. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 1cm , 1cm } +% \draw_path_lineto:n { 2cm , 1cm } +% \draw_path_lineto:n { 3cm , 0.5cm } +% \draw_path_lineto:n { 3cm , 0cm } +% \draw_color_fill:n { yellow!80!black } +% \draw_path_use_clear:n { fill , stroke } +% \draw_end: +% \end{demo} +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 1cm , 1cm } +% \draw_path_lineto:n { 2cm , 1cm } +% \draw_path_moveto:n { 2cm , 1cm } % Begins a new part +% \draw_path_lineto:n { 3cm , 0.5cm } +% \draw_path_lineto:n { 3cm , 0cm } +% \draw_color_fill:n { yellow!80!black } +% \draw_path_use_clear:n { fill , stroke } +% \draw_end: +% \end{demo} % \end{function} % % \begin{function}{\draw_path_curveto:nnn} @@ -388,7 +651,21 @@ % \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}. +% cubic Bézier points \meta{control1} and \meta{control2}. The bounding box +% of the path (and image) will fully-contain the curve and control points, +% \emph{i.e.}~it may be bigger than strictly necessary to contain the curve +% \emph{alone}. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_curveto:nnn +% { 1cm , 1cm } % First control +% { 2cm , 1cm } % Second control +% { 3cm , 0cm } % End +% \draw_color_fill:n { yellow!80!black } +% \draw_path_use_clear:n { fill , stroke } +% \draw_end: +% \end{demo} % \end{function} % % \begin{function}{\draw_path_curveto:nn} @@ -396,7 +673,20 @@ % \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}. +% quadratic Bézier point \meta{control}. The bounding box +% of the path (and image) will fully-contain the curve and computed (cubic) +% control points, \emph{i.e.}~it may be bigger than strictly necessary to +% contain the curve \emph{alone}. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_curveto:nn +% { 1cm , 1cm } +% { 2cm , 0cm } +% \draw_color_fill:n { yellow!80!black } +% \draw_path_use_clear:n { fill , stroke } +% \draw_end: +% \end{demo} % \end{function} % % \begin{function}{\draw_path_arc:nnn, \draw_path_arc:nnnn} @@ -407,9 +697,26 @@ % 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. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_arc:nnn { 180 } { 90 } { 0.5cm } +% \draw_path_lineto:n { 3cm , 1.5cm } +% \draw_path_arc:nnn { 90 } { -45 } { 0.5cm } +% \draw_path_use_clear:n { fill } +% \draw_end: +% \end{demo} % % Note the interface here has a different argument ordering from that in % \pkg{pgf}, which has the two centers then the two radii. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_arc:nnnn { 180 } { 45 } { 2cm } { 1cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} % \end{function} % % \begin{function}{\draw_path_arc_axes:nnnn} @@ -417,15 +724,49 @@ % \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. +% ellipse with axes along \meta{vector1} and \meta{vector2} to the current +% path. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 2cm , 5mm } +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_moveto:n { 2cm , 5mm } +% \draw_path_arc_axes:nnnn { 0 } { 90 } +% { 2cm , 5mm } { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} % \end{function} % -% \begin{function}{\draw_path_ellipse:nnnn} +% \begin{function}{\draw_path_ellipse:nnn} % \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. +% \meta{vector2} to the current path. A new part is started if the path +% is already non-empty. Notice that the underlying drawing is constructed +% from arcs with appropriate moves: the interfaces is a more efficient +% convenience. +% \begin{demo} +% \draw_begin: +% \draw_path_ellipse:nnn +% { 1cm , 0cm } +% { 1.5cm , 0cm } +% { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \draw_color:n { red } +% \draw_path_ellipse:nnn +% { 1cm , 0cm } +% { 1cm , 1cm } +% { -0.5cm , 0.5cm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% +% Note that any transformation is applied to the completed ellipse rather than +% to the axes. % \end{function} % % \begin{function}{\draw_path_circle:nn} @@ -433,6 +774,7 @@ % \cs{draw_path_circle:nn} \Arg{center} \Arg{radius} % \end{syntax} % Appends a circle of \meta{radius} at \meta{center} to the current path. +% This is a shortcut for \cs{draw_path_ellipse:nnn}. % \end{function} % % \begin{function}{\draw_path_rectangle:nn, \draw_path_rectangle_corners:nn} @@ -443,44 +785,179 @@ % 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}. +% \begin{demo} +% \draw_begin: +% \draw_path_rectangle:nn +% { 1cm , 0cm } +% { 1.5cm , 1cm } +% \draw_path_rectangle:nn +% { 1.5cm , 0.25cm } +% { 1.5cm , 1cm } +% \draw_path_rectangle:nn +% { 2cm , 0.5cm } +% { 1.5cm , 1cm } +% \draw_path_use_clear:n { draw } +% \draw_end: +% \end{demo} +% \begin{demo} +% \draw_begin: +% \draw_path_rectangle_corners:nn +% { 1cm , 0cm } +% { 1.5cm , 1cm } +% \draw_path_use_clear:n { draw } +% \draw_end: +% \end{demo} % \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} +% \cs{draw_path_grid:nnnn} \Arg{xstep} \Arg{ystep} \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. +% Constructs a grid of \meta{xstep} and \meta{ystep} inside the rectangle +% defined by the \meta{lower-left} and the \meta{upper-right}, and appends +% this to the current path. The grid will be aligned such that grid lines +% pass through the origin, which may result in \enquote{protruding} ends +% if the start/end positions do not fully align. +% \begin{demo} +% \draw_begin: +% \draw_linewidth:n { 0.8pt } +% \draw_path_grid:nnnn +% { 1cm } { 1cm } +% { -3mm , -3mm } +% { 33mm , 23mm } +% \draw_path_use_clear:n { stroke } +% \draw_linewidth:n { 0.4pt } +% \draw_path_grid:nnnn +% { 1mm } { 1mm } +% { -1.5mm , -1.5mm } +% { 31.5mm , 21.5mm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} +% +% Any transformation is applied to the finished grid. +% \begin{demo} +% \draw_begin: +% \draw_transform_rotate:n { 10 } +% \draw_path_grid:nnnn +% { 1mm } { 2mm } +% { 0mm , 0mm } +% { 30mm , 30mm } +% \draw_path_use_clear:n { stroke } +% \draw_end: +% \end{demo} % \end{function} % -% \begin{function}{\draw_path_close:} +% \subsubsection{Path scope} +% +% \begin{function}{\draw_path_scope_begin:, \draw_path_scope_end:} % \begin{syntax} -% \cs{draw_path_close:} +% \cs{draw_path_scope_begin:} +% ... +% \cs{draw_path_scope_end:} % \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. +% Suspends (and saves) the current (partial) path, initialising a new +% path within the scope. Path operations are written to output only when +% used, so the scoped path is stored at the \pkg{expl3} level, not +% in the output. % \end{function} % -% \begin{function}{\draw_path_use:n, \draw_path_use_clear:n} +% \subsubsection{Path operations on canvas axes} +% +% For \emph{specialist} work, a small number of functions are provided +% which work relative to the canvas axes, \emph{i.e.}~these functions +% ignore the transformation matrix. +% +% \begin{function}{\draw_path_canvas_moveto:n} % \begin{syntax} -% \cs{draw_path_use:n} \Arg{action(s)} +% \cs{draw_path_canvas_moveto:n} \Arg{canvas point} % \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} +% Moves the reference point of the path to the \meta{canvas point}, but will +% not join this to any previous point. +% \end{function} +% +% \begin{function}{\draw_path_canvas_lineto:n} +% \begin{syntax} +% \cs{draw_path_canvas_lineto:n} \Arg{canvas point} +% \end{syntax} +% Joins the current path to the \meta{canvas point} with a straight line. +% \end{function} +% +% \begin{function}{\draw_path_canvas_curveto:nnn} +% \begin{syntax} +% \cs{draw_path_canvas_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}. These positions +% are given as canvas points. +% \end{function} +% +% \subsection{Bounding box} +% +% \begin{variable}{\l_draw_bb_update_bool} +% All functions automatically update the bounding box of the image, unless +% specified otherwise. This behavior is selectable using the +% \cs{l_draw_bb_update_bool} boolean. +% \end{variable} +% +% \subsection{Boxes and coffins} +% +% \begin{function}{\draw_box_use:N} +% \begin{syntax} +% \cs{draw_box_use:N} \meta{box} +% \end{syntax} +% Inserts the \meta{box} into a drawing, taking account of the current +% transformation matrix and shift, and adjusting the drawing bounding +% box to contain the (apparent) size of the box if this is active +% (see \cs{l_draw_bb_update_bool}). +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \hbox_set:Nn \l_tmpa_box +% { This~is~text. } +% \draw_box_use:N \l_tmpa_box +% \draw_end: +% \end{demo} +% \begin{demo} +% \draw_begin: +% \draw_transform_matrix:nnnn { 2 } { 0 } { 1 } { 2 } +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \hbox_set:Nn \l_tmpa_box +% { This~is~text. } +% \draw_box_use:N \l_tmpa_box +% \draw_end: +% \end{demo} +% \end{function} +% +% \begin{function}{\draw_coffin_use:Nnn} +% \begin{syntax} +% \cs{draw_coffin_use:N} \meta{coffin} \Arg{hpole} \Arg{vpole} +% \end{syntax} +% Inserts the \meta{coffin} into a drawing, taking account of the current +% transformation matrix and shift, and adjusting the drawing bounding +% box to contain the (apparent) size of the box if this is active +% (see \cs{l_draw_bb_update_bool}). The alignment point of the coffin to +% the origin is specified by the intersection of the \meta{hpole} and the +% \meta{vpole}. +% \begin{demo} +% \draw_begin: +% \draw_path_moveto:n { 0cm , 0cm } +% \draw_path_lineto:n { 0cm , 1cm } +% \draw_path_use_clear:n { stroke } +% \hcoffin_set:Nn \l_tmpa_coffin +% { This~is~text. } +% \draw_coffin_use:Nnn \l_tmpa_coffin { hc } { vc } +% \draw_end: +% \end{demo} % \end{function} % % \subsection{Color} % -% \begin{function}{\draw_color:n, \draw_fill:n, \draw_stroke:n} +% \begin{function}{\draw_color:n, \draw_color_fill:n, \draw_color_stroke:n} % \begin{syntax} % \cs{draw_color:n} \Arg{color expression} % \end{syntax} @@ -491,34 +968,28 @@ % % 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 +% may be adjusted using \cs{driver_draw_cm:nnnn}: 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{function} +% {\draw_transform_matrix:nnnn, \draw_transform_matrix_concat:nnnn} % \begin{syntax} -% \cs{draw_transform_concat:nnnnn} -% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector} +% \cs{draw_transform_matrix:nnnnn} +% \Arg{a} \Arg{b} \Arg{c} \Arg{d} % \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}. +% Applies the transformation matrix $[ \meta{a} \meta{b} \meta{c} \meta{d}]$. +% The basic version over-writes the current matrix, the |concat| version +% concatenates. +% This assignment is local. % \end{function} % -% \begin{function}{\draw_transform:nnnnn} +% \begin{function}{\draw_transform_shift:n, \draw_transform_shift_concat:n} % \begin{syntax} -% \cs{draw_transform:nnnnn} -% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector} +% \cs{draw_transform_shift:n} \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}. +% Applies the transformation \meta{vector} to points. The basic version +% over-writes the current vector, the |concat| version concatenates. +% This assignment is local. % \end{function} % % \begin{function}{\draw_transform_triangle:nnn} @@ -529,14 +1000,77 @@ % 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. +% This assignment is local. +% \end{function} +% +% \begin{function}{\draw_transform_rotate:n} +% \begin{syntax} +% \cs{draw_transform_rotate:n} \Arg{angle} +% \end{syntax} +% Applies a rotation by the \meta{angle}, measured anti-clockwise in degrees. +% This rotation is \emph{additional} to any prevailing transformation. +% This assignment is local. % \end{function} % -% \begin{function}{\draw_transform_invert:} +% \begin{function} +% { +% \draw_transform_scale:n, +% \draw_transform_xscale:n, +% \draw_transform_xscale:n +% } +% \begin{syntax} +% \cs{draw_transform_scale:n} \Arg{scale} +% \end{syntax} +% Applies the \meta{scale} in either $x$ or $y$ (or both). +% This scale is \emph{added} to any prevailing transformation. +% This assignment is local. +% \end{function} +% +% \begin{function} +% { +% \draw_transform_xshift:n, +% \draw_transform_yshift:n +% } +% \begin{syntax} +% \cs{draw_transform_shift:n} \Arg{vector} +% \cs{draw_transform_xshift:n} \Arg{xshift} +% \end{syntax} +% Applies an \meta{xshift} or \meta{yshift}, as appropriate. This shift is +% \emph{added} to any prevailing one. +% This assignment is local. +% \end{function} +% +% \begin{function} +% { +% \draw_transform_xslant:n, +% \draw_transform_yslant:n +% } +% \begin{syntax} +% \cs{draw_transform_xslant:n} \Arg{slant} +% \end{syntax} +% Applies the \meta{slant} (a factor) in either $x$ or $y$. +% This slant is \emph{added} to any prevailing transformation. +% This assignment is local. +% \end{function} +% +% \begin{function} +% {\draw_transform_matrix_invert:, \draw_transform_shift_invert:} +% \begin{syntax} +% \cs{draw_transform_matrix_invert:} +% \end{syntax} +% Inverts the current transformation matrix or shift vector, as +% appropriate. +% This assignment is local. +% \end{function} +% +% \begin{function} +% {\draw_transform_matrix_reset, \draw_transform_shift_reset:} % \begin{syntax} -% \cs{draw_transform_invert:} +% \cs{draw_transform_matrix_reset:} % \end{syntax} -% Inverts the current transformation matrix and reverses the current -% shift vector. +% Resets the current transformation matrix or shift vector, as +% appropriate. +% This assignment is local. % \end{function} % % \end{documentation} @@ -555,7 +1089,7 @@ % % \begin{macrocode} %<*package> -\ProvidesExplPackage{l3draw}{2018/02/21}{} +\ProvidesExplPackage{l3draw}{2018/03/05}{} {L3 Experimental core drawing support} %</package> % \end{macrocode} |