Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-graphics.tex

raw
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