From 54732448eb933607bdcb11a457756741dc4e0b44 Mon Sep 17 00:00:00 2001 From: Hans Hagen Date: Mon, 30 Dec 2019 20:42:59 +0100 Subject: 2019-12-30 19:16:00 --- .../manuals/luametatex/luametatex-metapost.tex | 479 +++++++++++++++++++++ 1 file changed, 479 insertions(+) create mode 100644 doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex (limited to 'doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex') diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex new file mode 100644 index 000000000..3f0d0a945 --- /dev/null +++ b/doc/context/sources/general/manuals/luametatex/luametatex-metapost.tex @@ -0,0 +1,479 @@ +% language=uk + +% lua.newtable + +\environment luametatex-style + +\startcomponent luametatex-metapost + +\startchapter[reference=metapost,title={The \METAPOST\ library \type {mplib}}] + +\startsection[title={Process management}][library=mplib] + +\topicindex {\METAPOST} +\topicindex {\METAPOST+mplib} +\topicindex {images+mplib} +\topicindex {images+\METAPOST} + +\libindex{version} + +The \METAPOST\ library interface registers itself in the table \type {mplib}. It +is based on \MPLIB\ version \ctxlua {context(mplib.version())}. + +\subsection{\type {new}} + +\libindex{new} + +To create a new \METAPOST\ instance, call + +\startfunctioncall + mp = mplib.new({...}) +\stopfunctioncall + +This creates the \type {mp} instance object. The argument hash can have a number +of different fields, as follows: + +\starttabulate[|l|l|pl|pl|] +\DB name \BC type \BC description \BC default \NC \NR +\TB +\NC \type{error_line} \NC number \NC error line width \NC 79 \NC \NR +\NC \type{print_line} \NC number \NC line length in ps output \NC 100 \NC \NR +\NC \type{random_seed} \NC number \NC the initial random seed \NC variable \NC \NR +\NC \type{math_mode} \NC string \NC the number system to use: + \type {scaled}, + \type {double} or + % \type {binary} or + \type {decimal} \NC \type {scaled} \NC \NR +\NC \type{interaction} \NC string \NC the interaction mode: + \type {batch}, + \type {nonstop}, + \type {scroll} or + \type {errorstop} \NC \type {errorstop} \NC \NR +\NC \type{job_name} \NC string \NC a compatibility value \NC \type {mpout} \NC \NR +\NC \type{find_file} \NC function \NC a function to find files \NC only local files \NC \NR +\NC \type{utf8} \NC boolean \NC permit characters in the + range 128 upto 255 to be + part of names \NC \type {false} \NC \NR +\LL +\stoptabulate + +The binary mode is no longer available in the \LUATEX\ version of \MPLIB. It +offers no real advantage and brings a ton of extra libraries with platform +specific properties that we can now avoid. We might introduce a high resolution +scaled variant at some point but only when it pays of performance wise. + +The \type {find_file} function should be of this form: + +\starttyping + found = finder ( name, mode, type) +\stoptyping + +with: + +\starttabulate[|l|p|] +\DB name \BC the requested file \NC \NR +\TB +\NC \type{mode} \NC the file mode: \type {r} or \type {w} \NC \NR +\NC \type{type} \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, + \type {pfb}, \type {enc} \NC \NR +\LL +\stoptabulate + +Return either the full path name of the found file, or \type {nil} if the file +cannot be found. + +Note that the new version of \MPLIB\ no longer uses binary mem files, so the way +to preload a set of macros is simply to start off with an \type {input} command +in the first \type {execute} call. + +When you are processing a snippet of text starting with \type {btex} and +ending with either \type {etex} or \type {verbatimtex}, the \METAPOST\ +\type {texscriptmode} parameter controls how spaces and newlines get honoured. +The default value is~1. Possible values are: + +\starttabulate[|l|p|] +\DB name \BC meaning \NC \NR +\TB +\NC \type {0} \NC no newlines \NC \NR +\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR +\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR +\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR +\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR +\LL +\stoptabulate + +That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes. +An \type {etex} has to be followed by a space or \type {;} or be at the end of a +line and preceded by a space or at the beginning of a line. + +\subsection{\type {statistics}} + +\libindex{statistics} + +You can request statistics with: + +\startfunctioncall + stats = mp:statistics() +\stopfunctioncall + +This function returns the vital statistics for an \MPLIB\ instance. There are +four fields, giving the maximum number of used items in each of four allocated +object classes: + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{main_memory} \NC number \NC memory size \NC \NR +\NC \type{hash_size} \NC number \NC hash size\NC \NR +\NC \type{param_size} \NC number \NC simultaneous macro parameters\NC \NR +\NC \type{max_in_open} \NC number \NC input file nesting levels\NC \NR +\LL +\stoptabulate + +Note that in the new version of \MPLIB, this is informational only. The objects +are all allocated dynamically, so there is no chance of running out of space +unless the available system memory is exhausted. + +\subsection{\type {execute}} + +\libindex{execute} + +You can ask the \METAPOST\ interpreter to run a chunk of code by calling + +\startfunctioncall +
rettable = execute(mp,"metapost code") +\stopfunctioncall + +for various bits of \METAPOST\ language input. Be sure to check the \type +{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the +\MPLIB\ instance will become unusable thereafter. + +Generally speaking, it is best to keep your chunks small, but beware that all +chunks have to obey proper syntax, like each of them is a small file. For +instance, you cannot split a single statement over multiple chunks. + +In contrast with the normal stand alone \type {mpost} command, there is +\notabene {no} implied \quote{input} at the start of the first chunk. + +\subsection{\type {finish}} + +\libindex{finish} + +\startfunctioncall +
rettable = finish(mp) +\stopfunctioncall + +If for some reason you want to stop using an \MPLIB\ instance while processing is +not yet actually done, you can call \type {finish}. Eventually, used memory +will be freed and open files will be closed by the \LUA\ garbage collector, but +an explicit \type {finish} is the only way to capture the final part of the +output streams. + +\stopsection + +\startsection[title={The end result}] + +\libindex {fields} + +The return value of \type {execute} and \type {finish} is a table with a +few possible keys (only \type {status} is always guaranteed to be present). + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{log} \NC string \NC output to the \quote {log} stream \NC \NR +\NC \type{term} \NC string \NC output to the \quote {term} stream \NC \NR +\NC \type{error} \NC string \NC output to the \quote {error} stream + (only used for \quote {out of memory}) \NC \NR +\NC \type{status} \NC number \NC the return value: + \type {0} = good, + \type {1} = warning, + \type {2} = errors, + \type {3} = fatal error \NC \NR +\NC \type{fig} \NC table \NC an array of generated figures (if any) \NC \NR +\LL +\stoptabulate + +When \type {status} equals~3, you should stop using this \MPLIB\ instance +immediately, it is no longer capable of processing input. + +If it is present, each of the entries in the \type {fig} array is a userdata +representing a figure object, and each of those has a number of object methods +you can call: + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{boundingbox} \NC function \NC returns the bounding box, as an array of 4 + values \NC \NR +\NC \type{postscript} \NC function \NC returns a string that is the ps output of the + \type {fig}. this function accepts two optional + integer arguments for specifying the values of + \type {prologues} (first argument) and \type + {procset} (second argument) \NC \NR +\NC \type{svg} \NC function \NC returns a string that is the svg output of the + \type {fig}. This function accepts an optional + integer argument for specifying the value of + \type {prologues} \NC \NR +\NC \type{objects} \NC function \NC returns the actual array of graphic objects in + this \type {fig} \NC \NR +\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic + objects in this \type {fig} \NC \NR +\NC \type{filename} \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\ + output would have written to in stand alone + mode \NC \NR +\NC \type{width} \NC function \NC the \type {fontcharwd} value \NC \NR +\NC \type{height} \NC function \NC the \type {fontcharht} value \NC \NR +\NC \type{depth} \NC function \NC the \type {fontchardp} value \NC \NR +\NC \type{italcorr} \NC function \NC the \type {fontcharit} value \NC \NR +\NC \type{charcode} \NC function \NC the (rounded) \type {charcode} value \NC \NR +\LL +\stoptabulate + +Note: you can call \type {fig:objects()} only once for any one \type {fig} +object! + +When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the +first set of coordinates is larger than the second set, the picture is empty. + +Graphical objects come in various types that each has a different list of +accessible values. The types are: \type {fill}, \type {outline}, \type {text}, +\type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds}, +\type {special}. + +There is a helper function (\type {mplib.fields(obj)}) to get the list of +accessible values for a particular object, but you can just as easily use the +tables given below. + +All graphical objects have a field \type {type} that gives the object type as a +string value; it is not explicit mentioned in the following tables. In the +following, \type {number}s are \POSTSCRIPT\ points represented as a floating +point number, unless stated otherwise. Field values that are of type \type +{table} are explained in the next section. + +\subsection{fill} + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{path} \NC table \NC the list of knots \NC \NR +\NC \type{htap} \NC table \NC the list of knots for the reversed trajectory \NC \NR +\NC \type{pen} \NC table \NC knots of the pen \NC \NR +\NC \type{color} \NC table \NC the object's color \NC \NR +\NC \type{linejoin} \NC number \NC line join style (bare number)\NC \NR +\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR +\NC \type{prescript} \NC string \NC the prescript text \NC \NR +\NC \type{postscript} \NC string \NC the postscript text \NC \NR +\LL +\stoptabulate + +The entries \type {htap} and \type {pen} are optional. + +\subsection{outline} + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{path} \NC table \NC the list of knots \NC \NR +\NC \type{pen} \NC table \NC knots of the pen \NC \NR +\NC \type{color} \NC table \NC the object's color \NC \NR +\NC \type{linejoin} \NC number \NC line join style (bare number) \NC \NR +\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR +\NC \type{linecap} \NC number \NC line cap style (bare number) \NC \NR +\NC \type{dash} \NC table \NC representation of a dash list \NC \NR +\NC \type{prescript} \NC string \NC the prescript text \NC \NR +\NC \type{postscript} \NC string \NC the postscript text \NC \NR +\LL +\stoptabulate + +The entry \type {dash} is optional. + +\subsection{text} + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{text} \NC string \NC the text \NC \NR +\NC \type{font} \NC string \NC font tfm name \NC \NR +\NC \type{dsize} \NC number \NC font size \NC \NR +\NC \type{color} \NC table \NC the object's color \NC \NR +\NC \type{width} \NC number \NC \NC \NR +\NC \type{height} \NC number \NC \NC \NR +\NC \type{depth} \NC number \NC \NC \NR +\NC \type{transform} \NC table \NC a text transformation \NC \NR +\NC \type{prescript} \NC string \NC the prescript text \NC \NR +\NC \type{postscript} \NC string \NC the postscript text \NC \NR +\LL +\stoptabulate + +\subsection{special} + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{prescript} \NC string \NC special text \NC \NR +\LL +\stoptabulate + +\subsection{start_bounds, start_clip} + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{path} \NC table \NC the list of knots \NC \NR +\LL +\stoptabulate + +\subsubsection{stop_bounds, stop_clip} + +Here are no fields available. + +\stopsection + +\startsection[title={Subsidiary table formats}] + +\subsection{Paths and pens} + +Paths and pens (that are really just a special type of paths as far as \MPLIB\ is +concerned) are represented by an array where each entry is a table that +represents a knot. + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{left_type} \NC string \NC when present: endpoint, but usually absent \NC \NR +\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR +\NC \type{x_coord} \NC number \NC X coordinate of this knot \NC \NR +\NC \type{y_coord} \NC number \NC Y coordinate of this knot \NC \NR +\NC \type{left_x} \NC number \NC X coordinate of the precontrol point of this knot \NC \NR +\NC \type{left_y} \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR +\NC \type{right_x} \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR +\NC \type{right_y} \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR +\LL +\stoptabulate + +There is one special case: pens that are (possibly transformed) ellipses have an +extra string-valued key \type {type} with value \type {elliptical} besides the +array part containing the knot list. + +\subsection{Colors} + +A color is an integer array with 0, 1, 3 or 4 values: + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{0} \NC marking only \NC no values \NC \NR +\NC \type{1} \NC greyscale \NC one value in the range $(0,1)$, \quote {black} is $0$ \NC \NR +\NC \type{3} \NC \RGB \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$ \NC \NR +\NC \type{4} \NC \CMYK \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR +\LL +\stoptabulate + +If the color model of the internal object was \type {uninitialized}, then it was +initialized to the values representing \quote {black} in the colorspace \type +{defaultcolormodel} that was in effect at the time of the \type {shipout}. + +\subsection{Transforms} + +Each transform is a six|-|item array. + +\starttabulate[|l|l|p|] +\DB index \BC type \BC explanation \NC \NR +\TB +\NC \type{1} \NC number \NC represents x \NC \NR +\NC \type{2} \NC number \NC represents y \NC \NR +\NC \type{3} \NC number \NC represents xx \NC \NR +\NC \type{4} \NC number \NC represents yx \NC \NR +\NC \type{5} \NC number \NC represents xy \NC \NR +\NC \type{6} \NC number \NC represents yy \NC \NR +\LL +\stoptabulate + +Note that the translation (index 1 and 2) comes first. This differs from the +ordering in \POSTSCRIPT, where the translation comes last. + +\subsection{Dashes} + +Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the +representation of the dashlist. \type {dashes} is an array of \quote {on} and +\quote {off}, values, and \type {offset} is the phase of the pattern. + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{dashes} \NC hash \NC an array of on-off numbers \NC \NR +\NC \type{offset} \NC number \NC the starting offset value \NC \NR +\LL +\stoptabulate + +\subsection{Pens and \type {pen_info}} + +\libindex{pen_info} + +There is helper function (\type {pen_info(obj)}) that returns a table containing +a bunch of vital characteristics of the used pen (all values are floats): + +\starttabulate[|l|l|p|] +\DB field \BC type \BC explanation \NC \NR +\TB +\NC \type{width} \NC number \NC width of the pen \NC \NR +\NC \type{sx} \NC number \NC $x$ scale \NC \NR +\NC \type{rx} \NC number \NC $xy$ multiplier \NC \NR +\NC \type{ry} \NC number \NC $yx$ multiplier \NC \NR +\NC \type{sy} \NC number \NC $y$ scale \NC \NR +\NC \type{tx} \NC number \NC $x$ offset \NC \NR +\NC \type{ty} \NC number \NC $y$ offset \NC \NR +\LL +\stoptabulate + +\stopsection + +\startsection[title=Acessors] + +\subsection[title={Character size information}] + +\libindex{char_width} +\libindex{char_height} +\libindex{char_depth} + +These functions find the size of a glyph in a defined font. The \type {fontname} +is the same name as the argument to \type {infont}; the \type {char} is a glyph +id in the range 0 to 255; the returned \type {w} is in AFM units. + + +\startfunctioncall + w = char_width(mp, fontname, char) + h = char_height(mp, fontname, char) + d = char_depth(mp, fontname, char) +\stopfunctioncall + +These are rather useless and might become obsolete. + +\subsection{\type {get_[boolean|numeric|string|path]}} + +\libindex{get_boolean} +\libindex{get_numeric} +\libindex{get_path} +\libindex{get_string} + +When a script call brings you from the \METAPOST\ run (temporarily) back to +\LUA\ you can access variables, but only if they are known (so for instance +anonymous capsules like loop variables are not accessible). + +\startfunctioncall + w = get_boolean(mp, name) + n = get_numeric(mp, name) + s = get_string (mp, name) +
p = get_path (mp, name) +\stopfunctioncall + +The path is returned a a table with subtables that have six numbers: the +coordinates of the point, pre- and postcontrol. A \type {cycle} fields indicates +if a path is cyclic. + +\stopsection + +\stopchapter + +\stopcomponent -- cgit v1.2.3