| 1 |
% language=uk |
| 2 |
|
| 3 |
% mp solve_path |
| 4 |
|
| 5 |
\environment luatex-style |
| 6 |
|
| 7 |
\startcomponent luatex-graphics |
| 8 |
|
| 9 |
\startchapter[reference=graphics,title={The graphic libraries}] |
| 10 |
|
| 11 |
\startsection[title={The \type {img} library}][library=img] |
| 12 |
|
| 13 |
\topicindex {images} |
| 14 |
\topicindex {images+library} |
| 15 |
\topicindex {graphics} |
| 16 |
|
| 17 |
The \type {img} library can be used as an alternative to \orm {pdfximage} and |
| 18 |
\orm {pdfrefximage}, and the associated \quote {satellite} commands like \type |
| 19 |
{\pdfximagebbox}. Image objects can also be used within virtual fonts via the |
| 20 |
\type {image} command listed in~\in {section} [virtualfonts]. |
| 21 |
|
| 22 |
\subsection{\type {new}} |
| 23 |
|
| 24 |
\libindex{new} |
| 25 |
|
| 26 |
\startfunctioncall |
| 27 |
<image> var = img.new() |
| 28 |
<image> var = img.new(<table> image_spec) |
| 29 |
\stopfunctioncall |
| 30 |
|
| 31 |
This function creates a userdata object of type \quote {image}. The \type |
| 32 |
{image_spec} argument is optional. If it is given, it must be a table, and that |
| 33 |
table must contain a \type {filename} key. A number of other keys can also be |
| 34 |
useful, these are explained below. |
| 35 |
|
| 36 |
You can either say |
| 37 |
|
| 38 |
\starttyping |
| 39 |
a = img.new() |
| 40 |
\stoptyping |
| 41 |
|
| 42 |
followed by |
| 43 |
|
| 44 |
\starttyping |
| 45 |
a.filename = "foo.png" |
| 46 |
\stoptyping |
| 47 |
|
| 48 |
or you can put the file name (and some or all of the other keys) into a table |
| 49 |
directly, like so: |
| 50 |
|
| 51 |
\starttyping |
| 52 |
a = img.new({filename='foo.pdf', page=1}) |
| 53 |
\stoptyping |
| 54 |
|
| 55 |
The generated \type {<image>} userdata object allows access to a set of |
| 56 |
user|-|specified values as well as a set of values that are normally filled in |
| 57 |
and updated automatically by \LUATEX\ itself. Some of those are derived from the |
| 58 |
actual image file, others are updated to reflect the \PDF\ output status of the |
| 59 |
object. |
| 60 |
|
| 61 |
There is one required user-specified field: the file name (\type {filename}). It |
| 62 |
can optionally be augmented by the requested image dimensions (\type {width}, |
| 63 |
\type {depth}, \type {height}), user|-|specified image attributes (\type {attr}), |
| 64 |
the requested \PDF\ page identifier (\type {page}), the requested boundingbox |
| 65 |
(\type {pagebox}) for \PDF\ inclusion, the requested color space object (\type |
| 66 |
{colorspace}). |
| 67 |
|
| 68 |
The function \type {img.new} does not access the actual image file, it just |
| 69 |
creates the \type {<image>} userdata object and initializes some memory |
| 70 |
structures. The \type {<image>} object and its internal structures are |
| 71 |
automatically garbage collected. |
| 72 |
|
| 73 |
Once the image is scanned, all the values in the \type {<image>} except \type |
| 74 |
{width}, \type {height} and \type {depth}, become frozen, and you cannot change |
| 75 |
them any more. |
| 76 |
|
| 77 |
You can use \type {pdf.setignoreunknownimages(1)} (or at the \TEX\ end the \lpr |
| 78 |
{pdfvariable} \type {ignoreunknownimages}) to get around a quit when no known |
| 79 |
image type is found (based on name or preamble). Beware: this will not catch |
| 80 |
invalid images and we cannot guarantee side effects. A zero dimension image is |
| 81 |
still included when requested. No special flags are set. A proper workflow will |
| 82 |
not rely in such a catch but make sure that images are valid. |
| 83 |
|
| 84 |
\subsection{\type {fields}} |
| 85 |
|
| 86 |
\libindex{fields} |
| 87 |
|
| 88 |
\startfunctioncall |
| 89 |
<table> keys = img.fields() |
| 90 |
\stopfunctioncall |
| 91 |
|
| 92 |
This function returns a list of all the possible \type {image_spec} keys, both |
| 93 |
user-supplied and automatic ones. |
| 94 |
|
| 95 |
\starttabulate[|l|l|p|] |
| 96 |
\DB field name \BC type \BC description \NC \NR |
| 97 |
\TB |
| 98 |
\NC \type{attr} \NC string \NC the image attributes for \LUATEX \NC \NR |
| 99 |
\NC \type{bbox} \NC table \NC table with 4 boundingbox dimensions \type |
| 100 |
{llx}, \type {lly}, \type {urx} and \type |
| 101 |
{ury} overruling the \type {pagebox} entry \NC \NR |
| 102 |
\NC \type{colordepth} \NC number \NC the number of bits used by the color space \NC \NR |
| 103 |
\NC \type{colorspace} \NC number \NC the color space object number \NC \NR |
| 104 |
\NC \type{depth} \NC number \NC the image depth for \LUATEX \NC \NR |
| 105 |
\NC \type{filename} \NC string \NC the image file name \NC \NR |
| 106 |
\NC \type{filepath} \NC string \NC the full (expanded) file name of the image\NC \NR |
| 107 |
\NC \type{height} \NC number \NC the image height for \LUATEX \NC \NR |
| 108 |
\NC \type{imagetype} \NC string \NC one of \type {pdf}, \type {png}, \type {jpg}, |
| 109 |
\type {jp2} or \type {jbig2} \NC \NR |
| 110 |
\NC \type{index} \NC number \NC the \PDF\ image name suffix \NC \NR |
| 111 |
\NC \type{objnum} \NC number \NC the \PDF\ image object number \NC \NR |
| 112 |
\NC \type{page} \NC number \NC the identifier for the requested image page \NC \NR |
| 113 |
\NC \type{pagebox} \NC string \NC the requested bounding box, one of |
| 114 |
\type {none}, \type {media}, \type {crop}, |
| 115 |
\type {bleed}, \type {trim}, \type {art} \NC \NR |
| 116 |
\NC \type{pages} \NC number \NC the total number of available pages \NC \NR |
| 117 |
\NC \type{rotation} \NC number \NC the image rotation from included \PDF\ file, |
| 118 |
in multiples of 90~deg. \NC \NR |
| 119 |
\NC \type{stream} \NC string \NC the raw stream data for an \type {/Xobject} |
| 120 |
\type {/Form} object\NC \NR |
| 121 |
\NC \type{transform} \NC number \NC the image transform, integer number 0..7 \NC \NR |
| 122 |
\NC \type{orientation} \NC number \NC the (jpeg) image orientation, integer number 1..8 |
| 123 |
(0 for unset) \NC \NR |
| 124 |
\NC \type{width} \NC number \NC the image width for \LUATEX \NC \NR |
| 125 |
\NC \type{xres} \NC number \NC the horizontal natural image resolution |
| 126 |
(in \DPI) \NC \NR |
| 127 |
\NC \type{xsize} \NC number \NC the natural image width \NC \NR |
| 128 |
\NC \type{yres} \NC number \NC the vertical natural image resolution |
| 129 |
(in \DPI) \NC \NR |
| 130 |
\NC \type{ysize} \NC number \NC the natural image height \NC \NR |
| 131 |
\NC \type{visiblefilename} \NC string \NC when set, this name will find its way in the |
| 132 |
\PDF\ file as \type {PTEX} specification; when |
| 133 |
an empty string is assigned nothing is written |
| 134 |
to file; otherwise the natural filename is |
| 135 |
taken \NC \NR |
| 136 |
\NC \type{userpassword} \NC string \NC the userpassword needed for opening a \PDF\ file \NC \NR |
| 137 |
\NC \type{ownerpassword} \NC string \NC the ownerpassword needed for opening a \PDF\ file \NC \NR |
| 138 |
\NC \type{keepopen} \NC boolean \NC keep the \PDF\ file open \NC \NR |
| 139 |
\NC \type{nobbox} \NC boolean \NC don't add a boundingbox specification for streams \NC \NR |
| 140 |
\NC \type{nolength} \NC boolean \NC don't add length key nor compress for streams \NC \NR |
| 141 |
\NC \type{nosize} \NC boolean \NC don't add size fields for streams \NC \NR |
| 142 |
\LL |
| 143 |
\stoptabulate |
| 144 |
|
| 145 |
A running (undefined) dimension in \type {width}, \type {height}, or \type |
| 146 |
{depth} is represented as \type {nil} in \LUA, so if you want to load an image at |
| 147 |
its \quote {natural} size, you do not have to specify any of those three fields. |
| 148 |
|
| 149 |
The \type {stream} parameter allows to fabricate an \type {/XObject} \type |
| 150 |
{/Form} object from a string giving the stream contents, e.g., for a filled |
| 151 |
rectangle: |
| 152 |
|
| 153 |
\startfunctioncall |
| 154 |
a.stream = "0 0 20 10 re f" |
| 155 |
\stopfunctioncall |
| 156 |
|
| 157 |
When writing the image, an \type {/Xobject} \type {/Form} object is created, like |
| 158 |
with embedded \PDF\ file writing. The object is written out only once. The \type |
| 159 |
{stream} key requires that also the \type {bbox} table is given. The \type |
| 160 |
{stream} key conflicts with the \type {filename} key. The \type {transform} key |
| 161 |
works as usual also with \type {stream}. |
| 162 |
|
| 163 |
The \type {bbox} key needs a table with four boundingbox values, e.g.: |
| 164 |
|
| 165 |
\startfunctioncall |
| 166 |
a.bbox = { "30bp", 0, "225bp", "200bp" } |
| 167 |
\stopfunctioncall |
| 168 |
|
| 169 |
This replaces and overrules any given \type {pagebox} value; with given \type |
| 170 |
{bbox} the box dimensions coming with an embedded \PDF\ file are ignored. The |
| 171 |
\type {xsize} and \type {ysize} dimensions are set accordingly, when the image is |
| 172 |
scaled. The \type {bbox} parameter is ignored for non-\PDF\ images. |
| 173 |
|
| 174 |
The \type {transform} allows to mirror and rotate the image in steps of 90~deg. |
| 175 |
The default value~$0$ gives an unmirrored, unrotated image. Values $1-3$ give |
| 176 |
counterclockwise rotation by $90$, $180$, or $270$~degrees, whereas with values |
| 177 |
$4-7$ the image is first mirrored and then rotated counterclockwise by $90$, |
| 178 |
$180$, or $270$~degrees. The \type {transform} operation gives the same visual |
| 179 |
result as if you would externally preprocess the image by a graphics tool and |
| 180 |
then use it by \LUATEX. If a \PDF\ file to be embedded already contains a \type |
| 181 |
{/Rotate} specification, the rotation result is the combination of the \type |
| 182 |
{/Rotate} rotation followed by the \type {transform} operation. |
| 183 |
|
| 184 |
\subsection{\type {scan}} |
| 185 |
|
| 186 |
\libindex{scan} |
| 187 |
|
| 188 |
\startfunctioncall |
| 189 |
<image> var = img.scan(<image> var) |
| 190 |
<image> var = img.scan(<table> image_spec) |
| 191 |
\stopfunctioncall |
| 192 |
|
| 193 |
When you say \type {img.scan(a)} for a new image, the file is scanned, and |
| 194 |
variables such as \type {xsize}, \type {ysize}, image \type {type}, number of |
| 195 |
\type {pages}, and the resolution are extracted. Each of the \type {width}, \type |
| 196 |
{height}, \type {depth} fields are set up according to the image dimensions, if |
| 197 |
they were not given an explicit value already. An image file will never be |
| 198 |
scanned more than once for a given image variable. With all subsequent \type |
| 199 |
{img.scan(a)} calls only the dimensions are again set up (if they have been |
| 200 |
changed by the user in the meantime). |
| 201 |
|
| 202 |
For ease of use, you can do right-away a |
| 203 |
|
| 204 |
\starttyping |
| 205 |
<image> a = img.scan { filename = "foo.png" } |
| 206 |
\stoptyping |
| 207 |
|
| 208 |
without a prior \type {img.new}. |
| 209 |
|
| 210 |
Nothing is written yet at this point, so you can do \type {a=img.scan}, retrieve |
| 211 |
the available info like image width and height, and then throw away \type {a} |
| 212 |
again by saying \type {a=nil}. In that case no image object will be reserved in |
| 213 |
the PDF, and the used memory will be cleaned up automatically. |
| 214 |
|
| 215 |
\subsection{\type {copy}} |
| 216 |
|
| 217 |
\libindex{copy} |
| 218 |
|
| 219 |
\startfunctioncall |
| 220 |
<image> var = img.copy(<image> var) |
| 221 |
<image> var = img.copy(<table> image_spec) |
| 222 |
\stopfunctioncall |
| 223 |
|
| 224 |
If you say \type {a = b}, then both variables point to the same \type {<image>} |
| 225 |
object. if you want to write out an image with different sizes, you can do |
| 226 |
\type {b = img.copy(a)}. |
| 227 |
|
| 228 |
Afterwards, \type {a} and \type {b} still reference the same actual image |
| 229 |
dictionary, but the dimensions for \type {b} can now be changed from their |
| 230 |
initial values that were just copies from \type {a}. |
| 231 |
|
| 232 |
\subsection{\type {write}, \type {immediatewrite}, \type {immediatewriteobject}} |
| 233 |
|
| 234 |
\topicindex {images+injection} |
| 235 |
\topicindex {images+immediate} |
| 236 |
\topicindex {images+object} |
| 237 |
|
| 238 |
\libindex{write} |
| 239 |
\libindex{immediatewrite} |
| 240 |
\libindex{immediatewriteobject} |
| 241 |
|
| 242 |
\startfunctioncall |
| 243 |
<image> var = img.write(<image> var) |
| 244 |
<image> var = img.write(<table> image_spec) |
| 245 |
\stopfunctioncall |
| 246 |
|
| 247 |
By \type {img.write(a)} a \PDF\ object number is allocated, and a rule node of |
| 248 |
subtype \type {image} is generated and put into the output list. By this the |
| 249 |
image \type {a} is placed into the page stream, and the image file is written out |
| 250 |
into an image stream object after the shipping of the current page is finished. |
| 251 |
|
| 252 |
Again you can do a terse call like |
| 253 |
|
| 254 |
\starttyping |
| 255 |
img.write { filename = "foo.png" } |
| 256 |
\stoptyping |
| 257 |
|
| 258 |
The \type {<image>} variable is returned in case you want it for later |
| 259 |
processing. You can also write an object. |
| 260 |
|
| 261 |
By \type {img.immediatewrite(a)} a \PDF\ object number is allocated, and the |
| 262 |
image file for image \type {a} is written out immediately into the \PDF\ file as |
| 263 |
an image stream object (like with \prm {immediate}\orm {pdfximage}). The object |
| 264 |
number of the image stream dictionary is then available by the \type {objnum} |
| 265 |
key. No \type {pdf_refximage} whatsit node is generated. You will need an |
| 266 |
\type {img.write(a)} or \type {img.node(a)} call to let the image appear on the |
| 267 |
page, or reference it by another trick; else you will have a dangling image |
| 268 |
object in the \PDF\ file. |
| 269 |
|
| 270 |
\startfunctioncall |
| 271 |
<image> var = img.immediatewrite(<image> var) |
| 272 |
<image> var = img.immediatewrite(<table> image_spec) |
| 273 |
\stopfunctioncall |
| 274 |
|
| 275 |
Also here you can do a terse call like |
| 276 |
|
| 277 |
\starttyping |
| 278 |
a = img.immediatewrite { filename = "foo.png" } |
| 279 |
\stoptyping |
| 280 |
|
| 281 |
The \type {<image>} variable is returned and you will most likely need it. |
| 282 |
|
| 283 |
The next function is kind of special as it copies an object from a (\PDF) image |
| 284 |
file. This features is experimental and might disappear. |
| 285 |
|
| 286 |
\startfunctioncall |
| 287 |
<integer> objnum = img.immediatewriteobject(<image> var, <integer> objnum) |
| 288 |
<integer> objnum = img.immediatewriteobject(<table> image_spec, <integer> objnum) |
| 289 |
\stopfunctioncall |
| 290 |
|
| 291 |
\subsection{\type {node}} |
| 292 |
|
| 293 |
\libindex{node} |
| 294 |
|
| 295 |
\startfunctioncall |
| 296 |
<node> n = img.node(<image> var) |
| 297 |
<node> n = img.node(<table> image_spec) |
| 298 |
\stopfunctioncall |
| 299 |
|
| 300 |
This function allocates a \PDF\ object number and returns a whatsit node of |
| 301 |
subtype \type {pdf_refximage}, filled with the image parameters \type {width}, |
| 302 |
\type {height}, \type {depth}, and \type {objnum}. Also here you can do a terse |
| 303 |
call like: |
| 304 |
|
| 305 |
\starttyping |
| 306 |
n = img.node ({ filename = "foo.png" }) |
| 307 |
\stoptyping |
| 308 |
|
| 309 |
This example outputs an image: |
| 310 |
|
| 311 |
\starttyping |
| 312 |
node.write(img.node{filename="foo.png"}) |
| 313 |
\stoptyping |
| 314 |
|
| 315 |
\subsection{\type {types}} |
| 316 |
|
| 317 |
\topicindex {images+types} |
| 318 |
|
| 319 |
\libindex{types} |
| 320 |
|
| 321 |
\startfunctioncall |
| 322 |
<table> types = img.types() |
| 323 |
\stopfunctioncall |
| 324 |
|
| 325 |
This function returns a list with the supported image file type names, currently |
| 326 |
these are \type {pdf}, \type {png}, \type {jpg}, \type {jp2} (JPEG~2000), and |
| 327 |
\type {jbig2}. |
| 328 |
|
| 329 |
\subsection{\type {boxes}} |
| 330 |
|
| 331 |
\libindex{boxes} |
| 332 |
|
| 333 |
\startfunctioncall |
| 334 |
<table> boxes = img.boxes() |
| 335 |
\stopfunctioncall |
| 336 |
|
| 337 |
This function returns a list with the supported \PDF\ page box names, currently |
| 338 |
these are \type {media}, \type {crop}, \type {bleed}, \type {trim}, and \type |
| 339 |
{art}, all in lowercase. |
| 340 |
|
| 341 |
The \PDF\ file is kept open after its properties are determined. After inclusion, |
| 342 |
which happens when the page that references the image is flushed, the file is |
| 343 |
closed. This means that when you have thousands of images on one page, your |
| 344 |
operating system might decide to abort the run. When you include more than one |
| 345 |
page from a \PDF\ file you can set the \type {keepopen} flag when you allocate an |
| 346 |
image object, or pass the \type {keepopen} directive when you refer to the image |
| 347 |
with \lpr {useimageresource}. This only makes sense when you embed many pages. |
| 348 |
An \prm {immediate} applied to \lpr {saveimageresource} will also force a |
| 349 |
close after inclusion. |
| 350 |
|
| 351 |
\starttyping |
| 352 |
\immediate\useimageresource{foo.pdf}% |
| 353 |
\saveimageresource \lastsavedimageresourceindex % closed |
| 354 |
\useimageresource{foo.pdf}% |
| 355 |
\saveimageresource \lastsavedimageresourceindex % kept open |
| 356 |
\useimageresource{foo.pdf}% |
| 357 |
\saveimageresource keepopen\lastsavedimageresourceindex % kept open |
| 358 |
|
| 359 |
\directlua{img.write(img.scan{ file = "foo.pdf" })} % closed |
| 360 |
\directlua{img.write(img.scan{ file = "foo.pdf", keepopen = true })} % kept open |
| 361 |
\stoptyping |
| 362 |
|
| 363 |
\stopsection |
| 364 |
|
| 365 |
\startsection[title={The \type {mplib} library}][library=mplib] |
| 366 |
|
| 367 |
\topicindex {\METAPOST} |
| 368 |
\topicindex {\METAPOST+mplib} |
| 369 |
\topicindex {images+mplib} |
| 370 |
\topicindex {images+\METAPOST} |
| 371 |
|
| 372 |
\libindex{version} |
| 373 |
|
| 374 |
The \MP\ library interface registers itself in the table \type {mplib}. It is |
| 375 |
based on \MPLIB\ version \ctxlua {context(mplib.version())}. |
| 376 |
|
| 377 |
\subsection{\type {new}} |
| 378 |
|
| 379 |
\libindex{new} |
| 380 |
|
| 381 |
To create a new \METAPOST\ instance, call |
| 382 |
|
| 383 |
\startfunctioncall |
| 384 |
<mpinstance> mp = mplib.new({...}) |
| 385 |
\stopfunctioncall |
| 386 |
|
| 387 |
This creates the \type {mp} instance object. The argument hash can have a number |
| 388 |
of different fields, as follows: |
| 389 |
|
| 390 |
\starttabulate[|l|l|pl|pl|] |
| 391 |
\DB name \BC type \BC description \BC default \NC \NR |
| 392 |
\TB |
| 393 |
\NC \type{error_line} \NC number \NC error line width \NC 79 \NC \NR |
| 394 |
\NC \type{print_line} \NC number \NC line length in ps output \NC 100 \NC \NR |
| 395 |
\NC \type{random_seed} \NC number \NC the initial random seed \NC variable \NC \NR |
| 396 |
\NC \type{math_mode} \NC string \NC the number system to use: |
| 397 |
\type {scaled}, |
| 398 |
\type {double} or |
| 399 |
% \type {binary} or |
| 400 |
\type {decimal} \NC \type {scaled} \NC \NR |
| 401 |
\NC \type{interaction} \NC string \NC the interaction mode: |
| 402 |
\type {batch}, |
| 403 |
\type {nonstop}, |
| 404 |
\type {scroll} or |
| 405 |
\type {errorstop} \NC \type {errorstop} \NC \NR |
| 406 |
\NC \type{job_name} \NC string \NC \type {--jobname} \NC \type {mpout} \NC \NR |
| 407 |
\NC \type{find_file} \NC function \NC a function to find files \NC only local files \NC \NR |
| 408 |
\LL |
| 409 |
\stoptabulate |
| 410 |
|
| 411 |
The binary mode is no longer available in the \LUATEX\ version of \MPLIB. It |
| 412 |
offers no real advantage and brings a ton of extra libraries with platform |
| 413 |
specific properties that we can now avoid. We might introduce a high resolution |
| 414 |
scaled variant at some point but only when it pays of performance wise. |
| 415 |
|
| 416 |
The \type {find_file} function should be of this form: |
| 417 |
|
| 418 |
\starttyping |
| 419 |
<string> found = finder (<string> name, <string> mode, <string> type) |
| 420 |
\stoptyping |
| 421 |
|
| 422 |
with: |
| 423 |
|
| 424 |
\starttabulate[|l|p|] |
| 425 |
\DB name \BC the requested file \NC \NR |
| 426 |
\TB |
| 427 |
\NC \type{mode} \NC the file mode: \type {r} or \type {w} \NC \NR |
| 428 |
\NC \type{type} \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, |
| 429 |
\type {pfb}, \type {enc} \NC \NR |
| 430 |
\LL |
| 431 |
\stoptabulate |
| 432 |
|
| 433 |
Return either the full path name of the found file, or \type {nil} if the file |
| 434 |
cannot be found. |
| 435 |
|
| 436 |
Note that the new version of \MPLIB\ no longer uses binary mem files, so the way |
| 437 |
to preload a set of macros is simply to start off with an \type {input} command |
| 438 |
in the first \type {execute} call. |
| 439 |
|
| 440 |
When you are processing a snippet of text starting with \type {btex} and |
| 441 |
ending with either \type {etex} or \type {verbatimtex}, the \METAPOST\ |
| 442 |
\type {texscriptmode} parameter controls how spaces and newlines get honoured. |
| 443 |
The default value is~1. Possible values are: |
| 444 |
|
| 445 |
\starttabulate[|l|p|] |
| 446 |
\DB name \BC meaning \NC \NR |
| 447 |
\TB |
| 448 |
\NC \type {0} \NC no newlines \NC \NR |
| 449 |
\NC \type {1} \NC newlines in \type {verbatimtex} \NC \NR |
| 450 |
\NC \type {2} \NC newlines in \type {verbatimtex} and \type {etex} \NC \NR |
| 451 |
\NC \type {3} \NC no leading and trailing strip in \type {verbatimtex} \NC \NR |
| 452 |
\NC \type {4} \NC no leading and trailing strip in \type {verbatimtex} and \type {btex} \NC \NR |
| 453 |
\LL |
| 454 |
\stoptabulate |
| 455 |
|
| 456 |
That way the \LUA\ handler (assigned to \type {make_text}) can do what it likes. |
| 457 |
An \type {etex} has to be followed by a space or \type {;} or be at the end of a |
| 458 |
line and preceded by a space or at the beginning of a line. |
| 459 |
|
| 460 |
\subsection{\type {statistics}} |
| 461 |
|
| 462 |
\libindex{statistics} |
| 463 |
|
| 464 |
You can request statistics with: |
| 465 |
|
| 466 |
\startfunctioncall |
| 467 |
<table> stats = mp:statistics() |
| 468 |
\stopfunctioncall |
| 469 |
|
| 470 |
This function returns the vital statistics for an \MPLIB\ instance. There are |
| 471 |
four fields, giving the maximum number of used items in each of four allocated |
| 472 |
object classes: |
| 473 |
|
| 474 |
\starttabulate[|l|l|p|] |
| 475 |
\DB field \BC type \BC explanation \NC \NR |
| 476 |
\TB |
| 477 |
\NC \type{memory} \NC number \NC memory size \NC \NR |
| 478 |
\NC \type{hash} \NC number \NC hash size\NC \NR |
| 479 |
\NC \type{params} \NC number \NC simultaneous macro parameters\NC \NR |
| 480 |
\NC \type{open} \NC number \NC input file nesting levels\NC \NR |
| 481 |
\LL |
| 482 |
\stoptabulate |
| 483 |
|
| 484 |
Note that in the new version of \MPLIB, this is informational only. The objects |
| 485 |
are all allocated dynamically, so there is no chance of running out of space |
| 486 |
unless the available system memory is exhausted. |
| 487 |
|
| 488 |
\subsection{\type {execute}} |
| 489 |
|
| 490 |
\libindex{execute} |
| 491 |
|
| 492 |
You can ask the \METAPOST\ interpreter to run a chunk of code by calling |
| 493 |
|
| 494 |
\startfunctioncall |
| 495 |
<table> rettable = execute(mp,"metapost code") |
| 496 |
\stopfunctioncall |
| 497 |
|
| 498 |
for various bits of \METAPOST\ language input. Be sure to check the \type |
| 499 |
{rettable.status} (see below) because when a fatal \METAPOST\ error occurs the |
| 500 |
\MPLIB\ instance will become unusable thereafter. |
| 501 |
|
| 502 |
Generally speaking, it is best to keep your chunks small, but beware that all |
| 503 |
chunks have to obey proper syntax, like each of them is a small file. For |
| 504 |
instance, you cannot split a single statement over multiple chunks. |
| 505 |
|
| 506 |
In contrast with the normal stand alone \type {mpost} command, there is |
| 507 |
\notabene {no} implied \quote{input} at the start of the first chunk. |
| 508 |
|
| 509 |
\subsection{\type {finish}} |
| 510 |
|
| 511 |
\libindex{finish} |
| 512 |
|
| 513 |
\startfunctioncall |
| 514 |
<table> rettable = finish(mp) |
| 515 |
\stopfunctioncall |
| 516 |
|
| 517 |
If for some reason you want to stop using an \MPLIB\ instance while processing is |
| 518 |
not yet actually done, you can call \type{finish}. Eventually, used memory |
| 519 |
will be freed and open files will be closed by the \LUA\ garbage collector, but |
| 520 |
an explicit \type{finish} is the only way to capture the final part of the |
| 521 |
output streams. |
| 522 |
|
| 523 |
\subsection{Result table} |
| 524 |
|
| 525 |
\libindex {fields} |
| 526 |
|
| 527 |
The return value of \type {execute} and \type {finish} is a table with a |
| 528 |
few possible keys (only \type {status} is always guaranteed to be present). |
| 529 |
|
| 530 |
\starttabulate[|l|l|p|] |
| 531 |
\DB field \BC type \BC explanation \NC \NR |
| 532 |
\TB |
| 533 |
\NC \type{log} \NC string \NC output to the \quote {log} stream \NC \NR |
| 534 |
\NC \type{term} \NC string \NC output to the \quote {term} stream \NC \NR |
| 535 |
\NC \type{error} \NC string \NC output to the \quote {error} stream |
| 536 |
(only used for \quote {out of memory}) \NC \NR |
| 537 |
\NC \type{status} \NC number \NC the return value: |
| 538 |
\type {0} = good, |
| 539 |
\type {1} = warning, |
| 540 |
\type {2} = errors, |
| 541 |
\type {3} = fatal error \NC \NR |
| 542 |
\NC \type{fig} \NC table \NC an array of generated figures (if any) \NC \NR |
| 543 |
\LL |
| 544 |
\stoptabulate |
| 545 |
|
| 546 |
When \type {status} equals~3, you should stop using this \MPLIB\ instance |
| 547 |
immediately, it is no longer capable of processing input. |
| 548 |
|
| 549 |
If it is present, each of the entries in the \type {fig} array is a userdata |
| 550 |
representing a figure object, and each of those has a number of object methods |
| 551 |
you can call: |
| 552 |
|
| 553 |
\starttabulate[|l|l|p|] |
| 554 |
\DB field \BC type \BC explanation \NC \NR |
| 555 |
\TB |
| 556 |
\NC \type{boundingbox} \NC function \NC returns the bounding box, as an array of 4 |
| 557 |
values \NC \NR |
| 558 |
\NC \type{postscript} \NC function \NC returns a string that is the ps output of the |
| 559 |
\type {fig}. this function accepts two optional |
| 560 |
integer arguments for specifying the values of |
| 561 |
\type {prologues} (first argument) and \type |
| 562 |
{procset} (second argument) \NC \NR |
| 563 |
\NC \type{svg} \NC function \NC returns a string that is the svg output of the |
| 564 |
\type {fig}. This function accepts an optional |
| 565 |
integer argument for specifying the value of |
| 566 |
\type {prologues} \NC \NR |
| 567 |
\NC \type{objects} \NC function \NC returns the actual array of graphic objects in |
| 568 |
this \type {fig} \NC \NR |
| 569 |
\NC \type{copy_objects} \NC function \NC returns a deep copy of the array of graphic |
| 570 |
objects in this \type {fig} \NC \NR |
| 571 |
\NC \type{filename} \NC function \NC the filename this \type {fig}'s \POSTSCRIPT\ |
| 572 |
output would have written to in stand alone |
| 573 |
mode \NC \NR |
| 574 |
\NC \type{width} \NC function \NC the \type {fontcharwd} value \NC \NR |
| 575 |
\NC \type{height} \NC function \NC the \type {fontcharht} value \NC \NR |
| 576 |
\NC \type{depth} \NC function \NC the \type {fontchardp} value \NC \NR |
| 577 |
\NC \type{italcorr} \NC function \NC the \type {fontcharit} value \NC \NR |
| 578 |
\NC \type{charcode} \NC function \NC the (rounded) \type {charcode} value \NC \NR |
| 579 |
\LL |
| 580 |
\stoptabulate |
| 581 |
|
| 582 |
Note: you can call \type {fig:objects()} only once for any one \type {fig} |
| 583 |
object! |
| 584 |
|
| 585 |
When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the |
| 586 |
first set of coordinates is larger than the second set, the picture is empty. |
| 587 |
|
| 588 |
Graphical objects come in various types that each has a different list of |
| 589 |
accessible values. The types are: \type {fill}, \type {outline}, \type {text}, |
| 590 |
\type {start_clip}, \type {stop_clip}, \type {start_bounds}, \type {stop_bounds}, |
| 591 |
\type {special}. |
| 592 |
|
| 593 |
There is a helper function (\type {mplib.fields(obj)}) to get the list of |
| 594 |
accessible values for a particular object, but you can just as easily use the |
| 595 |
tables given below. |
| 596 |
|
| 597 |
All graphical objects have a field \type {type} that gives the object type as a |
| 598 |
string value; it is not explicit mentioned in the following tables. In the |
| 599 |
following, \type {number}s are \POSTSCRIPT\ points represented as a floating |
| 600 |
point number, unless stated otherwise. Field values that are of type \type |
| 601 |
{table} are explained in the next section. |
| 602 |
|
| 603 |
\subsubsection{fill} |
| 604 |
|
| 605 |
\starttabulate[|l|l|p|] |
| 606 |
\DB field \BC type \BC explanation \NC \NR |
| 607 |
\TB |
| 608 |
\NC \type{path} \NC table \NC the list of knots \NC \NR |
| 609 |
\NC \type{htap} \NC table \NC the list of knots for the reversed trajectory \NC \NR |
| 610 |
\NC \type{pen} \NC table \NC knots of the pen \NC \NR |
| 611 |
\NC \type{color} \NC table \NC the object's color \NC \NR |
| 612 |
\NC \type{linejoin} \NC number \NC line join style (bare number)\NC \NR |
| 613 |
\NC \type{miterlimit} \NC number \NC miterlimit\NC \NR |
| 614 |
\NC \type{prescript} \NC string \NC the prescript text \NC \NR |
| 615 |
\NC \type{postscript} \NC string \NC the postscript text \NC \NR |
| 616 |
\LL |
| 617 |
\stoptabulate |
| 618 |
|
| 619 |
The entries \type {htap} and \type {pen} are optional. |
| 620 |
|
| 621 |
\subsubsection{outline} |
| 622 |
|
| 623 |
\starttabulate[|l|l|p|] |
| 624 |
\DB field \BC type \BC explanation \NC \NR |
| 625 |
\TB |
| 626 |
\NC \type{path} \NC table \NC the list of knots \NC \NR |
| 627 |
\NC \type{pen} \NC table \NC knots of the pen \NC \NR |
| 628 |
\NC \type{color} \NC table \NC the object's color \NC \NR |
| 629 |
\NC \type{linejoin} \NC number \NC line join style (bare number) \NC \NR |
| 630 |
\NC \type{miterlimit} \NC number \NC miterlimit \NC \NR |
| 631 |
\NC \type{linecap} \NC number \NC line cap style (bare number) \NC \NR |
| 632 |
\NC \type{dash} \NC table \NC representation of a dash list \NC \NR |
| 633 |
\NC \type{prescript} \NC string \NC the prescript text \NC \NR |
| 634 |
\NC \type{postscript} \NC string \NC the postscript text \NC \NR |
| 635 |
\LL |
| 636 |
\stoptabulate |
| 637 |
|
| 638 |
The entry \type {dash} is optional. |
| 639 |
|
| 640 |
\subsubsection{text} |
| 641 |
|
| 642 |
\starttabulate[|l|l|p|] |
| 643 |
\DB field \BC type \BC explanation \NC \NR |
| 644 |
\TB |
| 645 |
\NC \type{text} \NC string \NC the text \NC \NR |
| 646 |
\NC \type{font} \NC string \NC font tfm name \NC \NR |
| 647 |
\NC \type{dsize} \NC number \NC font size \NC \NR |
| 648 |
\NC \type{color} \NC table \NC the object's color \NC \NR |
| 649 |
\NC \type{width} \NC number \NC \NC \NR |
| 650 |
\NC \type{height} \NC number \NC \NC \NR |
| 651 |
\NC \type{depth} \NC number \NC \NC \NR |
| 652 |
\NC \type{transform} \NC table \NC a text transformation \NC \NR |
| 653 |
\NC \type{prescript} \NC string \NC the prescript text \NC \NR |
| 654 |
\NC \type{postscript} \NC string \NC the postscript text \NC \NR |
| 655 |
\LL |
| 656 |
\stoptabulate |
| 657 |
|
| 658 |
\subsubsection{special} |
| 659 |
|
| 660 |
\starttabulate[|l|l|p|] |
| 661 |
\DB field \BC type \BC explanation \NC \NR |
| 662 |
\TB |
| 663 |
\NC \type{prescript} \NC string \NC special text \NC \NR |
| 664 |
\LL |
| 665 |
\stoptabulate |
| 666 |
|
| 667 |
\subsubsection{start_bounds, start_clip} |
| 668 |
|
| 669 |
\starttabulate[|l|l|p|] |
| 670 |
\DB field \BC type \BC explanation \NC \NR |
| 671 |
\TB |
| 672 |
\NC \type{path} \NC table \NC the list of knots \NC \NR |
| 673 |
\LL |
| 674 |
\stoptabulate |
| 675 |
|
| 676 |
\subsubsection{stop_bounds, stop_clip} |
| 677 |
|
| 678 |
Here are no fields available. |
| 679 |
|
| 680 |
\subsection{Subsidiary table formats} |
| 681 |
|
| 682 |
\subsubsection{Paths and pens} |
| 683 |
|
| 684 |
Paths and pens (that are really just a special type of paths as far as \MPLIB\ is |
| 685 |
concerned) are represented by an array where each entry is a table that |
| 686 |
represents a knot. |
| 687 |
|
| 688 |
\starttabulate[|l|l|p|] |
| 689 |
\DB field \BC type \BC explanation \NC \NR |
| 690 |
\TB |
| 691 |
\NC \type{left_type} \NC string \NC when present: endpoint, but usually absent \NC \NR |
| 692 |
\NC \type{right_type} \NC string \NC like \type {left_type} \NC \NR |
| 693 |
\NC \type{x_coord} \NC number \NC X coordinate of this knot \NC \NR |
| 694 |
\NC \type{y_coord} \NC number \NC Y coordinate of this knot \NC \NR |
| 695 |
\NC \type{left_x} \NC number \NC X coordinate of the precontrol point of this knot \NC \NR |
| 696 |
\NC \type{left_y} \NC number \NC Y coordinate of the precontrol point of this knot \NC \NR |
| 697 |
\NC \type{right_x} \NC number \NC X coordinate of the postcontrol point of this knot \NC \NR |
| 698 |
\NC \type{right_y} \NC number \NC Y coordinate of the postcontrol point of this knot \NC \NR |
| 699 |
\LL |
| 700 |
\stoptabulate |
| 701 |
|
| 702 |
There is one special case: pens that are (possibly transformed) ellipses have an |
| 703 |
extra string-valued key \type {type} with value \type {elliptical} besides the |
| 704 |
array part containing the knot list. |
| 705 |
|
| 706 |
\subsubsection{Colors} |
| 707 |
|
| 708 |
A color is an integer array with 0, 1, 3 or 4 values: |
| 709 |
|
| 710 |
\starttabulate[|l|l|p|] |
| 711 |
\DB field \BC type \BC explanation \NC \NR |
| 712 |
\TB |
| 713 |
\NC \type{0} \NC marking only \NC no values \NC \NR |
| 714 |
\NC \type{1} \NC greyscale \NC one value in the range $(0,1)$, \quote {black} is $0$ \NC \NR |
| 715 |
\NC \type{3} \NC \RGB \NC three values in the range $(0,1)$, \quote {black} is $0,0,0$ \NC \NR |
| 716 |
\NC \type{4} \NC \CMYK \NC four values in the range $(0,1)$, \quote {black} is $0,0,0,1$ \NC \NR |
| 717 |
\LL |
| 718 |
\stoptabulate |
| 719 |
|
| 720 |
If the color model of the internal object was \type {uninitialized}, then it was |
| 721 |
initialized to the values representing \quote {black} in the colorspace \type |
| 722 |
{defaultcolormodel} that was in effect at the time of the \type {shipout}. |
| 723 |
|
| 724 |
\subsubsection{Transforms} |
| 725 |
|
| 726 |
Each transform is a six|-|item array. |
| 727 |
|
| 728 |
\starttabulate[|l|l|p|] |
| 729 |
\DB index \BC type \BC explanation \NC \NR |
| 730 |
\TB |
| 731 |
\NC \type{1} \NC number \NC represents x \NC \NR |
| 732 |
\NC \type{2} \NC number \NC represents y \NC \NR |
| 733 |
\NC \type{3} \NC number \NC represents xx \NC \NR |
| 734 |
\NC \type{4} \NC number \NC represents yx \NC \NR |
| 735 |
\NC \type{5} \NC number \NC represents xy \NC \NR |
| 736 |
\NC \type{6} \NC number \NC represents yy \NC \NR |
| 737 |
\LL |
| 738 |
\stoptabulate |
| 739 |
|
| 740 |
Note that the translation (index 1 and 2) comes first. This differs from the |
| 741 |
ordering in \POSTSCRIPT, where the translation comes last. |
| 742 |
|
| 743 |
\subsubsection{Dashes} |
| 744 |
|
| 745 |
Each \type {dash} is two-item hash, using the same model as \POSTSCRIPT\ for the |
| 746 |
representation of the dashlist. \type {dashes} is an array of \quote {on} and |
| 747 |
\quote {off}, values, and \type {offset} is the phase of the pattern. |
| 748 |
|
| 749 |
\starttabulate[|l|l|p|] |
| 750 |
\DB field \BC type \BC explanation \NC \NR |
| 751 |
\TB |
| 752 |
\NC \type{dashes} \NC hash \NC an array of on-off numbers \NC \NR |
| 753 |
\NC \type{offset} \NC number \NC the starting offset value \NC \NR |
| 754 |
\LL |
| 755 |
\stoptabulate |
| 756 |
|
| 757 |
\subsection{Pens and \type {pen_info}} |
| 758 |
|
| 759 |
\libindex{pen_info} |
| 760 |
|
| 761 |
There is helper function (\type {pen_info(obj)}) that returns a table containing |
| 762 |
a bunch of vital characteristics of the used pen (all values are floats): |
| 763 |
|
| 764 |
\starttabulate[|l|l|p|] |
| 765 |
\DB field \BC type \BC explanation \NC \NR |
| 766 |
\TB |
| 767 |
\NC \type{width} \NC number \NC width of the pen \NC \NR |
| 768 |
\NC \type{sx} \NC number \NC $x$ scale \NC \NR |
| 769 |
\NC \type{rx} \NC number \NC $xy$ multiplier \NC \NR |
| 770 |
\NC \type{ry} \NC number \NC $yx$ multiplier \NC \NR |
| 771 |
\NC \type{sy} \NC number \NC $y$ scale \NC \NR |
| 772 |
\NC \type{tx} \NC number \NC $x$ offset \NC \NR |
| 773 |
\NC \type{ty} \NC number \NC $y$ offset \NC \NR |
| 774 |
\LL |
| 775 |
\stoptabulate |
| 776 |
|
| 777 |
\subsection{Character size information} |
| 778 |
|
| 779 |
These functions find the size of a glyph in a defined font. The \type {fontname} |
| 780 |
is the same name as the argument to \type {infont}; the \type {char} is a glyph |
| 781 |
id in the range 0 to 255; the returned \type {w} is in AFM units. |
| 782 |
|
| 783 |
\subsubsection{\type {char_width}} |
| 784 |
|
| 785 |
\libindex{char_width} |
| 786 |
|
| 787 |
\startfunctioncall |
| 788 |
<number> w = char_width(mp,<string> fontname, <number> char) |
| 789 |
\stopfunctioncall |
| 790 |
|
| 791 |
\subsubsection{\type {char_height}} |
| 792 |
|
| 793 |
\libindex{char_height} |
| 794 |
|
| 795 |
\startfunctioncall |
| 796 |
<number> w = char_height(mp,<string> fontname, <number> char) |
| 797 |
\stopfunctioncall |
| 798 |
|
| 799 |
\subsubsection{\type {char_depth}} |
| 800 |
|
| 801 |
\libindex{char_depth} |
| 802 |
|
| 803 |
\startfunctioncall |
| 804 |
<number> w = char_depth(mp,<string> fontname, <number> char) |
| 805 |
\stopfunctioncall |
| 806 |
|
| 807 |
\subsubsection{\type {get_[boolean|numeric|string|path]}} |
| 808 |
|
| 809 |
\libindex{get_boolean} |
| 810 |
\libindex{get_numeric} |
| 811 |
\libindex{get_path} |
| 812 |
\libindex{get_string} |
| 813 |
|
| 814 |
When a script call brings you from the \METAPOST\ run (temporarily) back to |
| 815 |
\LUA\ you can access variables, but only if they are known (so for instance |
| 816 |
anonymous capsules like loop variables are not accessible). |
| 817 |
|
| 818 |
\startfunctioncall |
| 819 |
<boolean> w = get_boolean(mp,<string> name) |
| 820 |
<number> n = get_numeric(mp,<string> name) |
| 821 |
<string> s = get_string (mp,<string> name) |
| 822 |
<table> p = get_path (mp,<string> name) |
| 823 |
\stopfunctioncall |
| 824 |
|
| 825 |
The path is returned as a table with subtables that have six numbers: the |
| 826 |
coordinates of the point, pre- and postcontrol. A \type {cycle} fields indicates |
| 827 |
if a path is cyclic. |
| 828 |
|
| 829 |
\stopsection |
| 830 |
|
| 831 |
\stopchapter |