Debian Codegraph @

texmf-dist/doc/metapost/base/source-manual/mplibapi.tex

raw
1
2 \def\MPLIB{MPlib}
3 \def\MP{MetaPost}
4 \def\POSTSCRIPT{PostScript}
5 \def\PS{PostScript}
6 \def\SVG{SVG}
7 \def\PNG{PNG}
8 \def\MNG{MNG}
9 \def\TFM{{\sc tfm}}
10 \def\LUA{Lua}
11
12 \def\luatex#1{#1}
13
14 \setupinteraction[state=start] % don't forget this line!
15 \placebookmarks[section,subsection,subsubsection][section]
16 % \setupinteractionscreen[option=bookmark]
17
18 \definefontsynonym[TitleFont][Sans]
19 \definefontsynonym[SubTitleFont][Sans]
20
21 \def\StartTitlePage%
22 {\bgroup%\startstandardmakeup
23 \setupalign[middle]
24 \hbox{}\vfil
25 \let\\=\crlf}
26
27 \def\StopTitlePage%
28 {\vfil
29 \page\egroup%\stopstandardmakeup
30 }
31
32 \usetypescript[palatino]
33 \switchtobodyfont[palatino,10pt]
34
35 \nonknuthmode
36
37 \defineselector[title][max=2,n=2]
38
39 \def\ctypedef#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1#2#3}}}\bookmark{#2}}
40 \def\cenumeration#1{\subsubsection{\type{#1}}\bookmark{#1}}
41 \def\cfunction#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1 #2#3}}}\bookmark{#2}}
42
43
44 \starttext
45
46 \StartTitlePage
47 \centerline{\definedfont[TitleFont at 50pt]{\MPLIB}}
48 \blank[3*line]
49 \centerline{\definedfont[SubTitleFont at 24pt]{API documentation, version 2.00}}
50 \blank[3*line]
51 \centerline{Taco Hoekwater, September 2012 -- Luigi Scarso, February 2018}
52 \StopTitlePage
53
54 \section{Table of contents}
55
56 \setupselector[title][n=1]
57
58 \placecontent[criterium=all,level=subsection]
59
60 \setupselector[title][n=2]
61
62 \page
63
64 \section{Introduction}
65
66 This document describes the API to \MPLIB, allowing you to use
67 \MPLIB\ in your own applications. One such application is writing
68 bindings to interface with other programming languages. The
69 bindings to the \LUA\ scripting language is part of the \MPLIB\
70 distribution and also covered by this manual.
71
72 This is a first draft of both this document as well as the API, so
73 there may be errors or omissions in this document or strangenesses in
74 the API. If you believe something can be improved, please do not
75 hesitate to let us know. The contact email address is {\tt
76 [email protected]}.
77
78 The C paragraphs in this document assume you understand C code, the
79 Lua paragraphs assume you understand Lua code, and familiarity with
80 \MP\ is assumed throughout.
81
82 \subsection{Simple \MPLIB\ use}
83
84 There are two different approaches possible when running \MPLIB. The first
85 method is most suitable for programs that function as a command-line
86 frontend. It uses \quote{normal} \MP\ interface with I/O to and from files,
87 and needs very little setup to run. On the other hand, it also gives
88 almost no chance to control the \MPLIB\ behaviour.
89
90 Here is a C language example of how to do this:
91
92
93 \starttyping
94 #include "mplib.h"
95 int main (int argc, char **argv) {
96 MP mp;
97 MP_options *opt = mp_options();
98 opt->command_line = argv[1];
99 mp = mp_initialize(opt);
100 if (mp) {
101 int history = mp_run(mp);
102 mp_finish(mp);
103 exit (history);
104 } else {
105 exit (EXIT_FAILURE);
106 }
107 }
108 \stoptyping
109
110 This example will run in \quote{inimpost} mode. See below for how to
111 preload a macro package.
112
113 \subsection{Embedded \MPLIB\ use}
114
115 The second method does not run a file, but instead repeatedly executes
116 chunks of \MP\ language input that are passed to the library as
117 strings, with the output redirected to internal buffers instead of
118 directly to files.
119
120 Here is an example of how this second approach works, now using the
121 \LUA\ bindings:
122
123 \starttyping
124 local mplib = require('mplib')
125 local mp = mplib.new ({ ini_version = false,
126 mem_name = 'plain' })
127 if mp then
128 local l = mp:execute([[beginfig(1);
129 fill fullcircle scaled 20;
130 endfig;
131 ]])
132 if l and l.fig and l.fig[1] then
133 print (l.fig[1]:postscript())
134 end
135 mp:finish();
136 end
137 \stoptyping
138
139 This example preloads the \quote{plain} macro file.
140
141
142 \section{C API for core \MPLIB}
143
144 All of the types, structures, enumerations and functions that are
145 described in this section are defined in the header file \type{mplib.h}.
146
147 \subsection{Structures}
148
149 \ctypedef{}{MP_options}{}
150
151 This is a structure that contains the configurable parameters for a new \MPLIB\ instance. Because \MP\ differentiates
152 between \type{-ini} and \type{non-ini} modes, there are three types of settings: Those that apply in both cases, and
153 those that apply in only one of those cases.
154
155
156 \starttabulate[|l|l|l|p|]
157 \NC int \NC ini_version \NC 1 \NC set this to zero if you want to load a mem file.\NC \NR
158 \NC int \NC error_line \NC 79 \NC maximal length of error message lines\NC \NR
159 \NC int \NC half_error_line \NC 50 \NC halfway break point for error contexts\NC\NR
160 \NC int \NC max_print_line \NC 100 \NC maximal length of file output\NC \NR
161 \NC void * \NC userdata \NC NULL \NC for your personal use only, not used by the library\NC \NR
162 \NC char * \NC banner \NC NULL \NC string to use instead of default banner\NC \NR
163 \NC int \NC print_found_names\NC 0 \NC controls whether the asked name or the actual found
164 name of the file is used in messages\NC \NR
165 \NC int \NC file_line_error_style\NC 0 \NC when this option is nonzero, the library will use \type{file:line:error}
166 style formatting for error messages that occur while reading
167 from input files\NC \NR
168 \NC char * \NC command_line \NC NULL \NC input file name and rest of command line;
169 only used by \type{mp_run} interface\NC \NR
170 \NC int \NC interaction \NC 0 \NC explicit \type{mp_interaction_mode} (see below)\NC \NR
171 \NC int \NC noninteractive \NC 0 \NC set this nonzero to suppress user interaction,
172 only sensible if you want to use \type{mp_execute}\NC \NR
173 \NC int \NC random_seed \NC 0 \NC set this nonzero to force a specific random seed\NC \NR
174 \NC int \NC troff_mode \NC 0 \NC set this nonzero to initialize \quote{troffmode} \NC \NR
175 \NC char * \NC mem_name \NC NULL \NC explicit mem name to use instead of \type{plain.mem}.
176 ignored in \type{-ini} mode.\NC \NR
177 \NC char * \NC job_name \NC NULL \NC explicit job name to use instead of first input file\NC \NR
178 \NC mp_file_finder \NC find_file \NC NULL \NC function called for finding files \NC \NR
179 \NC mp_editor_cmd \NC run_editor \NC NULL \NC function called after \quote{E} error response\NC \NR
180 \NC mp_makempx_cmd \NC run_make_mpx \NC NULL \NC function called for the creation of mpx files\NC \NR
181 \NC int \NC math_mode \NC 0 \NC set this to \type{mp_math_double_mode} to use doubles
182 instead of scaled (\type{mp_math_scaled_mode}) values\NC \NR
183 \stoptabulate
184
185 To create an \type{MP_options} structure, you have to use the \type{mp_options()} function.
186
187 \ctypedef{}{MP}{}
188
189 This type is an opaque pointer to a \MPLIB\ instance, it is what you
190 have pass along as the first argument to (almost) all the \MPLIB\
191 functions. The actual C structure it points to has hundreds of fields,
192 but you should not use any of those directly. All configuration is done
193 via the \type{MP_options} structure, and there are accessor functions
194 for the fields that can be read out.
195
196 \ctypedef{}{mp_run_data}{}
197
198 When the \MPLIB\ instance is not interactive, any output is redirected
199 to this structure. There are a few string output streams, and a
200 linked list of output images.
201
202 \starttabulate[|l|l|p|]
203 \NC mp_stream \NC term_out \NC holds the terminal output \NC \NR
204 \NC mp_stream \NC error_out \NC holds error messages \NC \NR
205 \NC mp_stream \NC log_out \NC holds the log output \NC \NR
206 \NC mp_stream \NC ship_out \NC holds the exported EPS, SVG or PNG string \NC \NR
207 \NC mp_edge_object *\NC edges \NC linked list of generated pictures \NC \NR
208 \stoptabulate
209
210 \type{term_out} is equivalent to \type{stdout} in interactive use, and
211 \type{error_out} is equivalent to \type{stderr}. The \type{error_out}
212 is currently only used for memory allocation errors, the \MP\ error
213 messages are written to \type{term_out} (and are often duplicated to
214 \type{log_out} as well).
215
216 You need to include at least \type{mplibps.h} to be able to actually
217 make use of this list of images, see the next section for the details
218 on \type{mp_edge_object} lists.
219
220 See next paragraph for \type{mp_stream}.
221
222 \ctypedef{}{mp_stream}{}
223
224 This contains the data for a stream as well as some internal
225 bookkeeping variables. The fields that are of interest to you are:
226
227 \starttabulate[|l|l|p|]
228 \NC size_t \NC size \NC the internal buffer size\NC \NR
229 \NC char * \NC data \NC the actual data. \NC \NR
230 \stoptabulate
231
232 There is nothing in the stream unless the \type{size} field is
233 nonzero. There will not be embedded null characters (\type{\0})
234 in \type{data} except when \type{ship_out} is used for PNG output.
235
236 If \type{size} is nonzero, \type{strlen(data)} is guaranteed to be
237 less than that, and may be as low as zero (if \MPLIB\ has written an
238 empty string).
239
240 \subsection{Function prototype typedefs}
241
242 The following three function prototypes define functions that you can
243 pass to \MPLIB\ inside the \type{MP_options} structure.
244
245 \ctypedef{char * }{(*mp_file_finder)}{ (MP, const char*, const char*, int)}
246
247 \MPLIB\ calls this function whenever it needs to find a file. If you
248 do not set up the matching option field (\type{MP_options.find_file}),
249 \MPLIB\ will only be able to find files in the current directory.
250
251 The three function arguments are the requested file name, the file
252 mode (either \type{"r"} or \type{"w"}), and the file type (an
253 \type{mp_filetype}, see below).
254
255 The return value is a new string indicating the disk file name to be
256 used, or NULL if the named file can not be found. If the mode is
257 \type{"w"}, it is usually best to simply return a copy of the first
258 argument.
259
260
261 \ctypedef{void }{(*mp_editor_cmd)}{(MP, char*, int)}
262
263 This function is executed when a user has pressed \quote{E} as reply to an
264 \MP\ error, so it will only ever be called when \MPLIB\ in interactive mode.
265 The function arguments are the file name and the line number. When
266 this function is called, any open files are already closed.
267
268 \ctypedef{int }{(*mp_makempx_cmd)}{(MP, char*, char *)}
269
270 This function is executed when there is a need to start generating an
271 \type{mpx} file because (the first time a \type{btex} command was
272 encountered in the current input file).
273
274 The first argument is the input file name. This is the name that was given
275 in the \MP\ language, so it may not be the same as the name of the actual
276 file that is being used, depending on how your
277 \type{mp_file_finder} function behaves. The second argument is the
278 requested output name for mpx commands.
279
280 A zero return value indicates success, everything else indicates
281 failure to create a proper \type{mpx} file and will result in an \MP\ error.
282
283 \subsection{Enumerations}
284
285 \cenumeration{mp_filetype}
286
287 The \type{mp_file_finder} receives an \type{int} argument that is one of the following types:
288
289 \starttabulate[|l|p|]
290 \NC mp_filetype_program \NC Metapost language code (r)\NC \NR
291 \NC mp_filetype_log \NC Log output (w)\NC \NR
292 \NC mp_filetype_postscript \NC PostScript or SVG output (w)\NC \NR
293 \NC mp_filetype_bitmap \NC PNG output (w)\NC \NR
294 \NC mp_filetype_metrics \NC \TeX\ font metric file (r+w)\NC \NR
295 \NC mp_filetype_fontmap \NC Font map file (r)\NC \NR
296 \NC mp_filetype_font \NC Font PFB file (r)\NC \NR
297 \NC mp_filetype_encoding \NC Font encoding file (r)\NC \NR
298 \NC mp_filetype_text \NC \type{readfrom} and \type{write} files (r+w)\NC \NR
299 \stoptabulate
300
301 \cenumeration{mp_interaction_mode}
302
303 When \type{noninteractive} is zero, \MPLIB\ normally starts in a mode where it reports every error,
304 stops and asks the user for input. This initial mode can be overruled by using one of the following:
305
306 \starttabulate[|l|p|]
307 \NC mp_batch_mode \NC as with \type{batchmode} \NC \NR
308 \NC mp_nonstop_mode \NC as with \type{nonstopmode} \NC \NR
309 \NC mp_scroll_mode \NC as with \type{scrollmode} \NC \NR
310 \NC mp_error_stop_mode \NC as with \type{errorstopmode} \NC \NR
311 \stoptabulate
312
313 \cenumeration{mp_math_mode}
314
315 \starttabulate[|l|p|]
316 \NC mp_math_scaled_mode \NC uses scaled point data for numerical values \NC \NR
317 \NC mp_math_double_mode \NC uses IEEE double floating point data for numerical values \NC \NR
318 \NC mp_math_binary_mode \NC not used yet. \NC \NR
319 \NC mp_math_decimal_mode \NC not used yet. \NC \NR
320 \stoptabulate
321
322 \cenumeration{mp_history_state}
323
324 These are set depending on the current state of the interpreter.
325
326 \starttabulate[|l|p|]
327 \NC mp_spotless \NC still clean as a whistle \NC \NR
328 \NC mp_warning_issued \NC a warning was issued or something was \type{show}-ed \NC \NR
329 \NC mp_error_message_issued \NC an error has been reported \NC \NR
330 \NC mp_fatal_eror_stop \NC termination was premature due to error(s) \NC \NR
331 \NC mp_system_error_stop \NC termination was premature due to disaster
332 (out of system memory) \NC \NR
333 \stoptabulate
334
335
336 \cenumeration{mp_color_model}
337
338 Graphical objects always have a color model attached to them.
339
340 \starttabulate[|l|p|]
341 \NC mp_no_model \NC as with \type{withoutcolor} \NC \NR
342 \NC mp_grey_model \NC as with \type{withgreycolor} \NC \NR
343 \NC mp_rgb_model \NC as with \type{withrgbcolor} \NC \NR
344 \NC mp_cmyk_model \NC as with \type{withcmykcolor} \NC \NR
345 \stoptabulate
346
347
348 \cenumeration{mp_graphical_object_code}
349
350 There are eight different graphical object types.
351
352 \starttabulate[|l|p|]
353 \NC mp_fill_code \NC \type{addto contour} \NC \NR
354 \NC mp_stroked_code \NC \type{addto doublepath} \NC \NR
355 \NC mp_text_code \NC \type{addto also} (via \type{infont})\NC \NR
356 \NC mp_start_clip_code \NC \type{clip} \NC \NR
357 \NC mp_start_bounds_code \NC \NC \NR
358 \NC mp_stop_clip_code \NC \type{setbounds} \NC \NR
359 \NC mp_stop_bounds_code \NC \NC \NR
360 \NC mp_special_code \NC \type{special} \NC \NR
361 \stoptabulate
362
363
364 \subsection{Functions}
365
366 \cfunction{char *}{mp_metapost_version}{(void)}
367
368 Returns a copy of the \MPLIB\ version string.
369
370 \cfunction{MP_options *}{mp_options}{(void)}
371
372 Returns a properly initialized option structure, or \type{NULL} in case of allocation errors.
373
374 \cfunction{MP }{mp_initialize}{(MP_options *opt)}
375
376 Returns a pointer to a new \MPLIB\ instance, or \type{NULL} if initialisation failed.
377
378 String options are copied, so you can free any of those (and the \type{opt} structure)
379 immediately after the call to this function.
380
381 \cfunction{int }{mp_status}{(MP mp)}
382
383 Returns the current value of the interpreter error state, as a \type{mp_history_state}.
384 This function is useful after \type{mp_initialize}.
385
386 \cfunction{boolean }{mp_finished}{(MP mp)}
387
388 Returns the current value of \type{mp->finished}.
389 This function is useful to check if \type{mp_execute} will execute the string, because
390 if \type{mp->finished} is \type{true} it will return after resetting the streams.
391
392
393
394 \cfunction{int }{mp_run}{(MP mp)}
395
396 Runs the \MPLIB\ instance using the \type{command_line} and other items from the
397 \type{MP_options}. After the call to \type{mp_run}, the \MPLIB\ instance should be
398 closed off by calling \type{mp_finish}.
399
400 The return value is the current \type{mp_history_state}
401
402 \cfunction{void *}{mp_userdata}{(MP mp)}
403
404 Simply returns the pointer that was passed along as \type{userdata} in
405 the \type{MP_options} struct.
406
407 \cfunction{int }{mp_troff_mode}{(MP mp)}
408
409 Returns the value of \type{troff_mode} as copied from the
410 \type{MP_options} struct.
411
412 \cfunction{mp_run_data *}{mp_rundata}{(MP mp)}
413
414 Returns the information collected during the previous call to \type{mp_execute}.
415
416 \cfunction{int }{mp_execute}{(MP mp, char *s, size_t l)}
417
418 Executes string \type{s} with length \type{l} in the \MPLIB\
419 instance. This call can be repeated as often as is needed. The return
420 value is the current \type{mp_history_state}. To get at the produced
421 results, call \type {mp_rundata}.
422
423 \cfunction{void }{mp_finish}{(MP mp)}
424
425 This finishes off the use of the \MPLIB\ instance: it closes all files
426 and frees all the memory allocated by this instance.
427
428 \cfunction{double }{mp_get_char_dimension}{(MP mp,char*fname,int n,int t)}
429
430 This is a helper function that returns one of the dimensions of glyph
431 \type{n} in font \type{fname} as a double in PostScript (AFM)
432 units. The requested item \type{t} can be \type{'w'} (width),
433 \type{'h'} (height), or \type{'d'} (depth).
434
435 \cfunction{int }{mp_memory_usage}{(MP mp)}
436
437 Returns the current memory usage of this instance.
438
439 \cfunction{int }{mp_hash_usage}{(MP mp)}
440
441 Returns the current hash usage of this instance.
442
443 \cfunction{int }{mp_param_usage}{(MP mp)}
444
445 Returns the current simultaneous macro parameter usage of this instance.
446
447 \cfunction{int }{mp_open_usage}{(MP mp)}
448
449 Returns the current \type{input} levels of this instance.
450
451 \section{C API for path and knot manipulation}
452
453 \subsection{Enumerations}
454
455 \cenumeration{mp_knot_type}
456
457 Knots can have left and right types depending on their current
458 status. By the time you see them in the output, they are usually
459 either \type{mp_explicit} or \type{mp_endpoint}, but here is the full
460 list:
461
462 \starttabulate[|l|p|]
463 \NC mp_endpoint \NC \NC \NR
464 \NC mp_explicit \NC \NC \NR
465 \NC mp_given \NC \NC \NR
466 \NC mp_curl \NC \NC \NR
467 \NC mp_open \NC \NC \NR
468 \NC mp_end_cycle \NC \NC \NR
469 \stoptabulate
470
471 \cenumeration{mp_knot_originator}
472
473 Knots can originate from two sources: they can be explicitly given by
474 the user, or they can be created by the \MPLIB\ program code (for
475 example as result of the \type{makepath} operator).
476
477 \starttabulate[|l|p|]
478 \NC mp_program_code \NC \NC \NR
479 \NC mp_metapost_user \NC \NC \NR
480 \stoptabulate
481
482
483 \subsection{Structures}
484
485 \ctypedef {}{mp_number}{}
486
487 Numerical values are represented by opaque structure pointers named \type{mp_number}.
488
489 \ctypedef {}{mp_knot}{}
490
491 Each \MPLIB\ path (a sequence of \MP\ points) is represented as a linked list
492 of structure pointers of the type \type{mp_knot}.
493
494 \starttabulate[|l|l|p|]
495 \NC mp_knot \NC next \NC the next knot, or NULL\NC \NR
496 \NC mp_knot_type \NC data.types.left_type \NC the \type{mp_knot_type} for the left side \NC \NR
497 \NC mp_knot_type \NC data.types.right_type \NC the \type{mp_knot_type} for the right side \NC \NR
498 \NC mp_number \NC x_coord \NC $x$\NC \NR
499 \NC mp_number \NC y_coord \NC $y$\NC \NR
500 \NC mp_number \NC left_x \NC $x$ of the left (incoming) control point\NC \NR
501 \NC mp_number \NC left_y \NC $y$ of the left (incoming) control point\NC \NR
502 \NC mp_number \NC right_x \NC $x$ of the right (outgoing) control point\NC \NR
503 \NC mp_number \NC right_y \NC $y$ of the right (outgoing) control point\NC \NR
504 \NC mp_knot_originator \NC originator \NC the \type{mp_knot_originator} \NC \NR
505 \stoptabulate
506
507 Paths are always represented as a circular list. The difference between cyclic and
508 non-cyclic paths is indicated by their \type{mp_knot_type}.
509
510 While the fields of the knot structure are in fact accessible, it is better to use
511 the access functions below as the internal structure tends to change.
512
513 \subsection{Functions for accessing knot data}
514
515 \cfunction{mp_number}{mp_knot_x_coord}{(MP mp,mp_knot p)}
516 Access the $x$ coordinate of the knot.
517 \cfunction{mp_number}{mp_knot_y_coord}{(MP mp,mp_knot p)}
518 Access the $y$ coordinate of the knot.
519 \cfunction{mp_number}{mp_knot_left_x}{(MP mp,mp_knot p)}
520 Access the $x$ coordinate of the left control point of the knot.
521 \cfunction{mp_number}{mp_knot_left_y}{(MP mp,mp_knot p)}
522 Access the $y$ coordinate of the left control point of the knot.
523 \cfunction{mp_number}{mp_knot_right_x}{(MP mp,mp_knot p)}
524 Access the $x$ coordinate of the right control point of the knot.
525 \cfunction{mp_number}{mp_knot_right_y}{(MP mp,mp_knot p)}
526 Access the $y$ coordinate of the right control point of the knot.
527 \cfunction{int}{mp_knot_left_type}{(MP mp,mp_knot p)}
528 Access the type of the knot on the left side.
529 \cfunction{int}{mp_knot_right_type}{(MP mp,mp_knot p)}
530 Access the type of the knot on the right side.
531 \cfunction{mp_knot}{mp_knot_next}{(MP mp,mp_knot p)}
532 Access the pointer to the next knot.
533 \cfunction{mp_number}{mp_knot_left_curl}{(MP mp,mp_knot p)}
534 Access the left curl of the knot (applies to unresolved knots, see below).
535 \cfunction{mp_number}{mp_knot_left_given}{(MP mp,mp_knot p)}
536 Access the left given value of the knot (applies to unresolved knots, see below).
537 \cfunction{mp_number}{mp_knot_left_tension}{(MP mp,mp_knot p)}
538 Access the left tension of the knot (applies to unresolved knots, see below).
539 \cfunction{mp_number}{mp_knot_right_curl}{(MP mp,mp_knot p)}
540 Access the right curl value of the knot (applies to unresolved knots, see below).
541 \cfunction{mp_number}{mp_knot_right_given}{(MP mp,mp_knot p)}
542 Access the right given value of the knot (applies to unresolved knots, see below).
543 \cfunction{mp_number}{mp_knot_right_tension}{(MP mp,mp_knot p)}
544 Access the right tension value of the knot (applies to unresolved knots, see below).
545
546 \cfunction{double}{mp_number_as_double}{(MP mp,mp_number n)}
547
548 Converts an \type{mp_number} to \type{double}.
549
550 \subsection{Functions for creating and modifying knot data}
551
552 \cfunction{mp_knot}{mp_create_knot}{(MP mp)}
553
554 Allocates and returns a new knot. Returns \type{NULL} on (malloc) failure.
555
556 \cfunction{int}{mp_set_knot}{(MP mp,mp_knot p,double x,double y)}
557
558 Fills in the coordinate of knot \type{p}. \type{x1} and \type{y1} values should be
559 within the proper range for the current numerical mode.
560 Return 1 on success, 0 on failure.
561
562 \cfunction{int}{mp_close_path}{(MP mp,mp_knot p,mp_knot q)}
563
564 Connects \type{p} and \type{q} using an \quote{endpoint join}, where \type{p} is the last knot
565 of the path, and \type{q} is the first knot. The right tension of \type{p} and the
566 left tension of \type{q} are (re)set to the default of 1.0.
567
568 Because all knot list data structures are always circular, this is needed to end the path
569 properly even if the path is not intended cyclic (or use \type{mp_close_path_cycle()},
570 if it is indeed a cycle).
571 Return 1 on success, 0 on failure.
572
573 \cfunction{int}{mp_close_path_cycle}{(MP mp,mp_knot p,mp_knot q)}
574
575 Connects \type{p} and \type{q} using an \quote{open join}, where \type{p} is the last knot
576 of the path, and \type{q} is the first knot. The right tension of \type{p} and the
577 left tension of \type{q} are (re)set to the default of 1.0.
578
579 This is needed to mimic metapost's \type{cycle}.
580 return 1 on success, 0 on failure.
581
582 \cfunction{mp_knot}{mp_append_knot}{(MP mp,mp_knot p,double x,double y)}
583
584 Appends a knot to previous knot \type{q}, and returns the new knot.
585 This is a convenience method combining \type{mp_create_knot()}, \type{mp_set_knot()}, and
586 (if \type{q} is not NULL) \type{mp_close_path_cycle()}.
587 Returns NULL on failure.
588
589 \cfunction{int}{mp_set_knot_left_curl}{(MP mp,mp_knot q,double value)}
590
591 Sets the left curl value for a knot.
592 \type{fabs(value)} should be less than 4096.0
593 return 1 on success, 0 on failure.
594
595 \cfunction{int}{mp_set_knot_right_curl}{(MP mp,mp_knot q,double value)}
596
597 Sets the right curl value for a knot.
598 \type{fabs(value)} should be less than 4096.0
599 return 1 on success, 0 on failure.
600
601 \cfunction{int}{mp_set_knot_curl}{(MP mp,mp_knot q,double value)}
602
603 Sets the curl value for a knot.
604 \type{fabs(value)} should be less than 4096.0
605 return 1 on success, 0 on failure.
606
607 \cfunction{int}{mp_set_knotpair_curls}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)}
608
609 A convenience method that calls \type{mp_set_knot_curl(mp,p,t1)} and \type{mp_set_knot_curl(mp,q,t2)}
610 return 1 if both succeed, 0 otherwise.
611
612 \cfunction{int}{mp_set_knot_direction}{(MP mp,mp_knot q,double x,double y)}
613
614 Sets the direction \type{{x,y}} value for a knot.
615 \type{fabs(x)} and \type{fabs(y)} should be less than 4096.0
616 return 1 on success, 0 on failure.
617
618 \cfunction{int}{mp_set_knotpair_directions}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)}
619
620 A convenience method that calls
621 \type{mp_set_knot_direction(mp,p,x1,y1)} and \type{mp_set_knot_direction(mp,p,x2,y2)}
622 return 1 if both succeed, 0 otherwise.
623
624 \cfunction{int}{mp_set_knotpair_tensions}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)}
625
626 Sets the tension specifiers for a pair of connected knots.
627 \type{fabs(t1)} and \type{fabs(t2)} should be more than 0.75 and less than 4096.0
628 return 1 on success, 0 on failure.
629
630 \cfunction{int}{mp_set_knot_left_tension}{(MP mp, mp_knot p, double t1)}
631
632 Set the left tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0
633 return 1 on success, 0 on failure.
634
635 \cfunction{int}{mp_set_knot_right_tension}{(MP mp, mp_knot p, double t1)}
636
637 Set the right tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0
638 return 1 on success, 0 on failure.
639
640 \cfunction{int}{mp_set_knot_left_control}{(MP mp, mp_knot p, double x1, double y1)}
641 \cfunction{int}{mp_set_knot_right_control}{(MP mp, mp_knot p, double x1, double y1)}
642
643 Sets explicit left or right control for a knot. \type{x1} and \type{y1} values should be
644 within the proper range for the current numerical mode.
645 return 1 on success, 0 on failure.
646
647 \cfunction{int}{mp_set_knotpair_controls}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)}
648
649 Sets explicit controls for a knot pair. All four \type{x} and \type{y} values should be
650 within the proper range for the current numerical mode.
651 return 1 on success, 0 on failure.
652
653 \cfunction{int}{mp_solve_path}{(MP mp,mp_knot first)}
654
655 Finds explicit controls for the knot list at \type{first}, which
656 is changed in-situ. Returns 0 if there was any kind of error, in which
657 case \type{first} is unmodified. There can be quite a set of potential errors,
658 mostly harmless processing errors.
659 However, be aware that it is also possible that there are internal mplib
660 memory allocation errors. A distinction between those can not be made
661 at the moment.
662 Return 1 on success, 0 on failure.
663
664 \cfunction{void}{mp_free_path}{(MP mp,mp_knot p)}
665
666 Frees the memory of a path.
667
668 \subsection{Example usage}
669
670 Since the above function list is quite dry and not that easy to grasp,
671 here are two examples of how to use it. First a simple example
672 (\type{mp_dump_path()} code is given below).
673
674
675 \starttyping
676 #include <stdio.h>
677 #include <stdlib.h>
678 #include <string.h>
679 #include "mplib.h"
680
681 int main (int argc, char ** argv) {
682 MP mp ;
683 mp_knot p, first, q;
684 MP_options * opt = mp_options () ;
685 opt -> command_line = NULL;
686 opt -> noninteractive = 1 ;
687 mp = mp_initialize ( opt ) ;
688 if ( ! mp ) exit ( EXIT_FAILURE ) ;
689
690 /* Equivalent Metapost code:
691
692 path p;
693 p := (0,0)..(10,10)..(10,-5)..cycle;
694
695 */
696 first = p = mp_append_knot(mp,NULL,0,0);
697 if ( ! p ) exit ( EXIT_FAILURE ) ;
698 q = mp_append_knot(mp,p,10,10);
699 if ( ! q ) exit ( EXIT_FAILURE ) ;
700 p = mp_append_knot(mp,q,10,-5);
701 if ( ! p ) exit ( EXIT_FAILURE ) ;
702 mp_close_path_cycle(mp, p, first);
703 /* mp_dump_path(mp, first); */
704 if (mp_solve_path(mp, first)) {
705 /* mp_dump_path(mp, first); */
706 }
707 mp_free_path(mp, first);
708 mp_finish ( mp ) ;
709 free(opt);
710 return 0;
711 }
712 \stoptyping
713
714 For some more challenging path input, here is a more elaborate
715 example of the path processing code:
716
717 \starttyping
718 /* Equivalent Metapost code:
719
720 path p;
721 p := (0,0)..
722 (2,20)--
723 (10, 5)..controls (2,2) and (9,4.5)..
724 (3,10)..tension 3 and atleast 4 ..
725 (1,14){2,0} .. {0,1}(5,-4);
726 */
727 first = p = mp_append_knot(mp,NULL,0,0);
728 q = mp_append_knot(mp,p,2,20);
729 p = mp_append_knot(mp,q,10,5);
730 if (!mp_set_knotpair_curls(mp, q,p, 1.0, 1.0))
731 exit ( EXIT_FAILURE ) ;
732 q = mp_append_knot(mp,p,3,10);
733 if (!mp_set_knotpair_controls(mp, p,q, 2.0, 2.0, 9.0, 4.5))
734 exit ( EXIT_FAILURE ) ;
735 p = mp_append_knot(mp,q,1,14);
736 if (!mp_set_knotpair_tensions(mp,q,p, 3.0, -4.0))
737 exit ( EXIT_FAILURE ) ;
738 q = mp_append_knot(mp,p,5,-4);
739 if (!mp_set_knotpair_directions(mp, p,q, 2.0, 0.0, 0.0, 1.0))
740 exit ( EXIT_FAILURE ) ;
741
742 mp_close_path(mp, q, first);
743
744 /* mp_dump_path(mp, first); */
745 if (mp_solve_path(mp, first)) {
746 /* mp_dump_path(mp, first); */
747 }
748 mp_free_path(mp, first);
749 \stoptyping
750
751 And here is the source code for the \type{mp_dump_path} function,
752 which produces path output that is similar to Metapost's
753 \type{tracingchoices} report.
754
755 \starttyping
756 #include <math.h>
757 #include <stdio.h>
758 #include <stdlib.h>
759 #include <string.h>
760 #include "mplib.h"
761
762 #define ROUNDED_ZERO(v) (fabs((v))<0.00001 ? 0 : (v))
763 #define PI 3.1415926535897932384626433832795028841971
764 #define RADIANS(a) (mp_number_as_double(mp,(a)) / 16.0) * PI/180.0
765
766 void mp_dump_path (MP mp, mp_knot h) {
767 mp_knot p, q;
768 if (h == NULL) return;
769 p = h;
770 do {
771 q=mp_knot_next(mp,p);
772 if ( (p==NULL)||(q==NULL) ) {
773 printf("\n???");
774 return; /* this won't happen */
775 }
776 printf ("(%g,%g)", mp_number_as_double(mp,mp_knot_x_coord(mp,p)),
777 mp_number_as_double(mp,mp_knot_y_coord(mp,p)));
778 switch (mp_knot_right_type(mp,p)) {
779 case mp_endpoint:
780 if ( mp_knot_left_type(mp,p)==mp_open ) printf("{open?}");
781 if ( (mp_knot_left_type(mp,q)!=mp_endpoint)||(q!=h) )
782 q=NULL; /* force an error */
783 goto DONE;
784 break;
785 case mp_explicit:
786 printf ("..controls (%g,%g)",
787 mp_number_as_double(mp,mp_knot_right_x(mp,p)),
788 mp_number_as_double(mp,mp_knot_right_y(mp,p)));
789 printf(" and ");
790 if ( mp_knot_left_type(mp,q)!=mp_explicit ) {
791 printf("??");
792 } else {
793 printf ("(%g,%g)",mp_number_as_double(mp,mp_knot_left_x(mp,q)),
794 mp_number_as_double(mp,mp_knot_left_y(mp,q)));
795 }
796 goto DONE;
797 break;
798 case mp_open:
799 if ( (mp_knot_left_type(mp,p)!=mp_explicit)
800 &&
801 (mp_knot_left_type(mp,p)!=mp_open) ) {
802 printf("{open?}");
803 }
804 break;
805 case mp_curl:
806 case mp_given:
807 if ( mp_knot_left_type(mp,p)==mp_open )
808 printf("??");
809 if ( mp_knot_right_type(mp,p)==mp_curl ) {
810 printf("{curl %g}", mp_number_as_double(mp,mp_knot_right_curl(mp,p)));
811 } else {
812 double rad = RADIANS(mp_knot_right_curl(mp,p));
813 double n_cos = ROUNDED_ZERO(cos(rad)*4096);
814 double n_sin = ROUNDED_ZERO(sin(rad)*4096);
815 printf("{%g,%g}", n_cos, n_sin);
816 }
817 break;
818 }
819 if ( mp_knot_left_type(mp,q)<=mp_explicit ) {
820 printf("..control?"); /* can't happen */
821 } else if ((mp_number_as_double(mp,mp_knot_right_tension(mp,p))!=(1.0))||
822 (mp_number_as_double(mp,mp_knot_left_tension(mp,q)) !=(1.0))) {
823 printf("..tension ");
824 if ( mp_number_as_double(mp,mp_knot_right_tension(mp,p))<0.0 )
825 printf("atleast ");
826 printf("%g", fabs(mp_number_as_double(mp,mp_knot_right_tension(mp,p))));
827 if (mp_number_as_double(mp,mp_knot_right_tension(mp,p)) !=
828 mp_number_as_double(mp,mp_knot_left_tension(mp,q))) {
829 printf(" and ");
830 if (mp_number_as_double(mp,mp_knot_left_tension(mp,q))< 0.0)
831 printf("atleast ");
832 printf("%g", fabs(mp_number_as_double(mp,mp_knot_left_tension(mp,q))));
833 }
834 }
835 DONE:
836 p=q;
837 if ( p!=h || mp_knot_left_type(mp,h)!=mp_endpoint) {
838 printf ("\n ..");
839 if ( mp_knot_left_type(mp,p) == mp_given ) {
840 double rad = RADIANS(mp_knot_left_curl(mp,p));
841 double n_cos = ROUNDED_ZERO(cos(rad)*4096);
842 double n_sin = ROUNDED_ZERO(sin(rad)*4096);
843 printf("{%g,%g}", n_cos, n_sin);
844 } else if ( mp_knot_left_type(mp,p) ==mp_curl ){
845 printf("{curl %g}", mp_number_as_double(mp,mp_knot_left_curl(mp,p)));
846 }
847 }
848 } while (p!=h);
849 if ( mp_knot_left_type(mp,h)!=mp_endpoint )
850 printf("cycle");
851 printf (";\n");
852 }
853 \stoptyping
854
855 The above function is much complicated because of all the knot type
856 cases that can only happen {\it before} \type{mp_solve_path()} is
857 called. A version that only prints processed paths and is less
858 scared of using direct field access would be much shorter:
859
860 \starttyping
861 void mp_dump_solved_path (MP mp, mp_knot h) {
862 mp_knot p, q;
863 if (h == NULL) return;
864 p = h;
865 do {
866 q=mp_knot_next(mp,p);
867 printf ("(%g,%g)..controls (%g,%g) and (%g,%g)",
868 mp_number_as_double(mp,p->x_coord),
869 mp_number_as_double(mp,p->y_coord),
870 mp_number_as_double(mp,p->right_x),
871 mp_number_as_double(mp,p->right_y),
872 mp_number_as_double(mp,q->left_x),
873 mp_number_as_double(mp,q->left_y));
874 p=q;
875 if ( p!=h || h->data.types.left_type!=mp_endpoint) {
876 printf ("\n ..");
877 }
878 } while (p!=h);
879 if ( h->data.types.left_type!=mp_endpoint )
880 printf("cycle");
881 printf (";\n");
882 }
883 \stoptyping
884
885 \page
886 \section{C API for graphical backend functions}
887 \bookmark{C API for graphical backend functions}
888
889 These are all defined in \type{mplibps.h}
890
891 \subsection{Structures}
892
893 The structures in this section are used by the items in the body of
894 the \type{edges} field of an \type{mp_rundata} structure. They are
895 presented here in a bottom-up manner.
896
897 \ctypedef {}{mp_gr_knot}{}
898
899 These are like \type{mp_knot}, except that all \type{mp_number} values
900 have been simplified to \type{double}.
901
902 \ctypedef {}{mp_color}{}
903
904 The graphical object that can be colored, have two fields to define
905 the color: one for the color model and one for the color values. The
906 structure for the color values is defined as follows:
907
908 \starttabulate[|l|l|p|]
909 \NC double \NC a_val \NC see below\NC \NR
910 \NC double \NC b_val \NC --\NC \NR
911 \NC double \NC c_val \NC --\NC \NR
912 \NC double \NC d_val \NC --\NC \NR
913 \stoptabulate
914
915 All graphical objects that have \type{mp_color} fields also have
916 \type{mp_color_model} fields. The color model decides the meaning of
917 the four data fields:
918
919 \starttabulate[|l|c|c|c|c|]
920 \NC color model value \NC a_val \NC b_val \NC c_val \NC d_val \NC \FR
921 \NC mp_no_model \NC -- \NC -- \NC -- \NC -- \NC \NR
922 \NC mp_grey_model \NC grey \NC -- \NC -- \NC -- \NC \NR
923 \NC mp_rgb_model \NC red \NC green \NC blue \NC \NC \NR
924 \NC mp_cmyk_model \NC cyan \NC magenta \NC yellow\NC black \NC \NR
925 \stoptabulate
926
927 \ctypedef {}{mp_dash_object}{}
928
929 Dash lists are represented like this:
930
931 \starttabulate[|l|l|p|]
932 \NC double * \NC array \NC an array of dash lengths, terminated by $-1$.\NC \NR
933 \NC double \NC offset\NC the dash array offset (as in PostScript) \NC \NR
934 \stoptabulate
935
936 \ctypedef {}{mp_graphic_object}{}
937
938 Now follow the structure definitions of the objects that can appear
939 inside a figure (this is called an \quote{edge structure} in the
940 internal WEB documentation).
941
942 There are eight different graphical object types, but there are seven
943 different C structures. Type \type{mp_graphic_object} represents the
944 base line of graphical object types. It has only two fields:
945
946 \starttabulate[|l|l|p|]
947 \NC mp_graphical_object_code \NC type \NC \NC \NR
948 \NC struct mp_graphic_object * \NC next \NC next object or NULL \NC \NR
949 \stoptabulate
950
951 Because every graphical object has at least these two fields, the body
952 of a picture is represented as a linked list of
953 \type{mp_graphic_object} items. Each object in turn can then be
954 typecast to the proper type depending on its \type{type}.
955
956 The two \quote{missing} objects in the explanations below are the ones
957 that match \type{mp_stop_clip_code} and \type{mp_stop_bounds_code}:
958 these have no extra fields besides \type{type} and \type{next}.
959
960 \ctypedef {}{mp_fill_object}{}
961
962 Contains the following fields on top of the ones defined by \type{mp_graphic_object}:
963
964 \starttabulate[|l|l|p|]
965 \NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR
966 \NC char * \NC post_script \NC this is the result of \type{withpostscript}\NC \NR
967 \NC mp_color \NC color \NC the color value of this object\NC \NR
968 \NC mp_color_model \NC color_model \NC the color model\NC \NR
969 \NC unsigned char \NC ljoin \NC the line join style; values have the same meaning
970 as in \PS: 0 for mitered, 1 for round, 2 for beveled.\NC \NR
971 \NC mp_gr_knot \NC path_p \NC the (always cyclic) path\NC \NR
972 \NC mp_gr_knot \NC htap_p \NC a possible reversed path (see below)\NC \NR
973 \NC mp_gr_knot \NC pen_p \NC a possible pen (see below)\NC \NR
974 \NC double \NC miterlim \NC the miter limit\NC \NR
975 \stoptabulate
976
977 Even though this object is called an \type{mp_fill_object}, it can be the result of both
978 \type{fill} and \type{filldraw} in the \MP\ input. This means that there can be a pen
979 involved as well. The final output should behave as follows:
980
981 \startitemize
982 \item If there is no \type{pen_p}; simply fill \type{path_p}.
983 \item If there is a one-knot pen (\type{pen_p->next} = \type{pen_p}) then fill \type{path_p}
984 and also draw \type{path_p} with the \type{pen_p}. Do not forget to take \type{ljoin} and
985 \type{miterlim} into account when drawing with the pen.
986 \item If there is a more complex pen (\type{pen_p->next} != \type{pen_p}) then its path
987 has already been preprocessed for you: \type{path_p} and \type{htap_p} already incorporate
988 its shape.
989 \stopitemize
990
991 \ctypedef {}{mp_stroked_object}{}
992
993 Contains the following fields on top of the ones defined by \type{mp_graphic_object}:
994
995 \starttabulate[|l|l|p|]
996 \NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR
997 \NC char * \NC post_script \NC this is the result of \type{withpostscript} \NC \NR
998 \NC mp_color \NC color \NC color value \NC \NR
999 \NC mp_color_model \NC color_model \NC color model \NC \NR
1000 \NC unsigned char \NC ljoin \NC the line join style \NC \NR
1001 \NC unsigned char \NC lcap \NC the line cap style; values have the same meaning
1002 as in \PS: 0 for butt ends, 1 for round ends, 2 for projecting ends.\NC \NR
1003 \NC mp_gr_knot \NC path_p \NC the path \NC \NR
1004 \NC mp_gr_knot \NC pen_p \NC the pen \NC \NR
1005 \NC double \NC miterlim \NC miter limit \NC \NR
1006 \NC mp_dash_object * \NC dash_p \NC a possible dash list\NC \NR
1007 \stoptabulate
1008
1009 \ctypedef {}{mp_text_object}{}
1010
1011 Contains the following fields on top of the ones defined by \type{mp_graphic_object}:
1012
1013 \starttabulate[|l|l|p|]
1014 \NC char * \NC pre_script \NC this is the result of \type{withprescript}\NC \NR
1015 \NC char * \NC post_script\NC this is the result of \type{withpostscript}\NC \NR
1016 \NC mp_color \NC color \NC color value \NC \NR
1017 \NC mp_color_model \NC color_model\NC color model \NC \NR
1018 \NC char * \NC text_p \NC string to be placed \NC \NR
1019 \NC char * \NC font_name \NC the \MP\ font name\NC \NR
1020 \NC double \NC font_dsize \NC size of the font\NC \NR
1021 \NC double \NC width \NC width of the picture resulting from the string\NC \NR
1022 \NC double \NC height \NC height\NC \NR
1023 \NC double \NC depth \NC depth\NC \NR
1024 \NC double \NC tx \NC transformation component\NC \NR
1025 \NC double \NC ty \NC transformation component\NC \NR
1026 \NC double \NC txx \NC transformation component\NC \NR
1027 \NC double \NC tyx \NC transformation component\NC \NR
1028 \NC double \NC txy \NC transformation component\NC \NR
1029 \NC double \NC tyy \NC transformation component\NC \NR
1030 \stoptabulate
1031
1032 All fonts are loaded by \MPLIB\ at the design size (but not all fonts have the same design
1033 size). If text is to be scaled, this happens via the transformation components.
1034
1035 \ctypedef {}{mp_clip_object}{}
1036
1037 Contains the following field on top of the ones defined by \type{mp_graphic_object}:
1038
1039 \starttabulate[|l|l|p|]
1040 \NC mp_gr_knot \NC path_p \NC defines the clipping path that is in effect until
1041 the object with the matching \type{mp_stop_clip_code} is encountered\NC \NR
1042 \stoptabulate
1043
1044 \ctypedef {}{mp_bounds_object}{}
1045
1046 Contains the following field on top of the ones defined by \type{mp_graphic_object}:
1047
1048 \starttabulate[|l|l|p|]
1049 \NC mp_gr_knot \NC path_p \NC the path that was used for boundary calculation \NC \NR
1050 \stoptabulate
1051
1052 This object can be ignored when output is generated, it only has effect on the boudingbox
1053 of the following objects and that has been taken into account already.
1054
1055 \ctypedef {}{mp_special_object}{}
1056
1057 This represents the output generated by a \MP\ \type{special} command. It
1058 contains the following field on top of the ones defined by \type{mp_graphic_object}:
1059
1060 \starttabulate[|l|l|p|]
1061 \NC char *\NC pre_script \NC the special string\NC \NR
1062 \stoptabulate
1063
1064 Each \type{special} command generates one object. All of the relevant
1065 \type{mp_special_object}s for a figure are linked together at the start
1066 of that figure.
1067
1068 \ctypedef {}{mp_edge_object}{}
1069
1070 \starttabulate[|l|l|p|]
1071 \NC mp_edge_object * \NC next \NC points to the next figure (or NULL)\NC \NR
1072 \NC mp_graphic_object * \NC body \NC a linked list of objects in this figure \NC \NR
1073 \NC char * \NC filename \NC this would have been the used filename if a \PS\ file
1074 would have been generated\NC \NR
1075 \NC MP \NC parent \NC a pointer to the instance that created
1076 this figure\NC \NR
1077 \NC double \NC minx \NC lower-left $x$ of the bounding box\NC \NR
1078 \NC double \NC miny \NC lower-left $y$ of the bounding box\NC \NR
1079 \NC double \NC maxx \NC upper right $x$ of the bounding box\NC \NR
1080 \NC double \NC maxy \NC upper right $y$ of the bounding box\NC \NR
1081 \NC double \NC width \NC value of \type{charwd};
1082 this would become the \TFM\ width (but without the potential rounding correction for \TFM\ file format)\NC \NR
1083 \NC double \NC height \NC similar for height (\type{charht})\NC \NR
1084 \NC double \NC depth \NC similar for depth (\type{chardp})\NC \NR
1085 \NC double \NC ital_corr \NC similar for italic correction (\type{charic})\NC \NR
1086 \NC int \NC charcode \NC Value of \type{charcode} (rounded, but not
1087 modulated for \TFM's 256 values yet)\NC \NR
1088 \stoptabulate
1089
1090 \subsection{Functions}
1091
1092 \cfunction{int }{mp_ps_ship_out}{(mp_edge_object*hh,int prologues,int procset)}
1093
1094 If you have an \type{mp_edge_object}, you can call this function. It will
1095 generate the \PS\ output for the figure and save it internally. A subsequent call to
1096 \type{mp_rundata} will find the generated text in the \type{ship_out} field.
1097
1098 Returns zero for success.
1099
1100 \cfunction{int }{mp_svg_ship_out}{(mp_edge_object*hh,int prologues)}
1101
1102 If you have an \type{mp_edge_object}, you can call this function. It will
1103 generate the \SVG\ output for the figure and save it internally. A subsequent call to
1104 \type{mp_rundata} will find the generated text in the \type{ship_out} field.
1105
1106 Returns zero for success.
1107
1108
1109 \cfunction{int }{mp_png_ship_out}{(mp_edge_object*hh, char *options)}
1110
1111 If you have an \type{mp_edge_object}, you can call this function. It will
1112 generate the \PNG\ bitmap for the figure and save it internally. A subsequent call to
1113 \type{mp_rundata} will find the generated data in the \type{ship_out} field.
1114
1115 Note: the \type{options} structure follows the same syntax as in the Metapost language,
1116 and can be NULL.
1117
1118 Returns zero for success.
1119
1120
1121 \cfunction{void }{mp_gr_toss_objects}{(mp_edge_object*hh)}
1122
1123 This frees a single \type{mp_edge_object} and its \type{mp_graphic_object} contents.
1124
1125 \cfunction{void }{mp_gr_toss_object}{(mp_graphic_object*p)}
1126
1127 This frees a single \type{mp_graphic_object} object.
1128
1129 \cfunction{mp_graphic_object *}{mp_gr_copy_object}{(MP mp,mp_graphic_object*p)}
1130
1131 This creates a deep copy of a \type{mp_graphic_object} object.
1132
1133 \section{C API for label generation (a.k.a. makempx)}
1134
1135 The following are all defined in \type{mpxout.h}.
1136
1137 \subsection {Structures}
1138
1139 \ctypedef {}{MPX}{}
1140
1141 An opaque pointer that is passed on to the file_finder.
1142
1143 \ctypedef {}{mpx_options}{}
1144
1145 This structure holds the option fields for \type{mpx} generation.
1146 You have to fill in all fields except \type{mptexpre}, that
1147 one defaults to \type{mptexpre.tex}
1148
1149
1150 \starttabulate[|l|l|p|]
1151 \NC mpx_modes \NC mode \NC \NC \NR
1152 \NC char * \NC cmd \NC the command (or sequence of commands) to run\NC \NR
1153 \NC char * \NC mptexpre \NC prepended to the generated \TeX\ file\NC \NR
1154 \NC char * \NC mpname \NC input file name \NC \NR
1155 \NC char * \NC mpxname \NC output file name\NC \NR
1156 \NC char * \NC banner \NC string to be printed to the generated to-be-typeset file\NC \NR
1157 \NC int \NC debug \NC When nonzero, \type{mp_makempx} outputs some debug information and do not delete temp files\NC \NR
1158 \NC mpx_file_finder \NC find_file \NC \NC \NR
1159 \stoptabulate
1160
1161 \subsection{Function prototype typedefs}
1162
1163 \ctypedef{char * }{(*mpx_file_finder)}{ (MPX, const char*, const char*, int)}
1164
1165 The return value is a new string indicating the disk file to be used.
1166 The arguments are the file name, the file mode (either \type{"r"} or \type{"w"}),
1167 and the file type (an \type{mpx_filetype}, see below). If the mode is \type{"w"},
1168 it is usually best to simply return a copy of the first argument.
1169
1170 \subsection{Enumerations}
1171
1172 \cenumeration{mpx_modes}
1173
1174 \starttabulate[|l|p|]
1175 \NC mpx_tex_mode \NC \NC \NR
1176 \NC mpx_troff_mode \NC \NC \NR
1177 \stoptabulate
1178
1179 \cenumeration{mpx_filetype}
1180
1181 \starttabulate[|l|p|]
1182 \NC mpx_tfm_format \NC \TeX\ or Troff ffont metric file \NC \NR
1183 \NC mpx_vf_format \NC \TeX\ virtual font file \NC \NR
1184 \NC mpx_trfontmap_format \NC Troff font map \NC \NR
1185 \NC mpx_trcharadj_format \NC Troff character shift information \NC \NR
1186 \NC mpx_desc_format \NC Troff DESC file \NC \NR
1187 \NC mpx_fontdesc_format \NC Troff FONTDESC file \NC \NR
1188 \NC mpx_specchar_format \NC Troff special character definition\NC \NR
1189 \stoptabulate
1190
1191 \subsection{Functions}
1192
1193 \cfunction{int }{mpx_makempx}{(mpx_options *mpxopt)}
1194
1195 A return value of zero is success, non-zero values indicate errors.
1196
1197 \page
1198
1199 \section{Lua API}
1200
1201 The \MP\ library interface registers itself in the table \type{mplib}.
1202
1203 \subsection{\luatex{mplib.version}}
1204
1205 Returns the \MPLIB\ version.
1206
1207 \starttyping
1208 <string> s = mplib.version()
1209 \stoptyping
1210
1211 \subsection{\luatex{mplib.new}}
1212
1213 To create a new metapost instance, call
1214
1215 \starttyping
1216 <mpinstance> mp = mplib.new({...})
1217 \stoptyping
1218
1219 This creates the \type{mp} instance object. The \type{mp} instance object
1220 always starts out in so|-|called \quote{inimp} mode, there is no
1221 support for preload files.
1222
1223 The argument hash can have a number of different fields, as follows:
1224
1225 \starttabulate[|lT|l|p|p|]
1226 \NC \ssbf name \NC \bf type \NC \bf description \NC \bf default \NC\NR
1227 \NC error_line \NC number \NC error line width \NC 79 \NC\NR
1228 \NC print_line \NC number \NC line length in ps output \NC 100\NC\NR
1229 \NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR
1230 \NC interaction \NC string \NC the interaction mode, one of \type {batch}, \type {nonstop},
1231 \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR
1232 \NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR
1233 \NC math_mode \NC string \NC the number system mode, one of \type{scaled} or
1234 \type{double} \NC \type {scaled} \NC\NR
1235 \NC find_file \NC function \NC a function to find files \NC only local files\NC\NR
1236 \stoptabulate
1237
1238 The \type{find_file} function should be of this form:
1239
1240 \starttyping
1241 <string> found = finder (<string> name, <string> mode, <string> type)
1242 \stoptyping
1243
1244 with:
1245
1246 \starttabulate[|lT|l|p|]
1247 \NC name \NC the requested file \NC \NR
1248 \NC mode \NC the file mode: \type {r} or \type {w} \NC \NR
1249 \NC type \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR
1250 \stoptabulate
1251
1252 Return either the full pathname of the found file, or \type{nil} if
1253 the file cannot be found.
1254
1255 \subsection{\luatex{mp:statistics}}
1256
1257 You can request statistics with:
1258
1259 \starttyping
1260 <table> stats = mp:statistics()
1261 \stoptyping
1262
1263 This function returns the allocation statistics for an \MPLIB\
1264 instance. There are four fields, giving the maximum number of used
1265 items in each of four object classes:
1266
1267 \starttabulate[|lT|l|p|]
1268 \NC memory \NC number \NC allocated memory (in bytes)\NC\NR
1269 \NC hash \NC number \NC hash size (in entries)\NC\NR
1270 \NC params \NC number \NC simultaneous macro parameters\NC\NR
1271 \NC open \NC number \NC input file nesting levels\NC\NR
1272 \stoptabulate
1273
1274 \subsection{\luatex{mp:execute}}
1275
1276 You can ask the \METAPOST\ interpreter to run a chunk of code by calling
1277
1278 \starttyping
1279 local rettable = mp:execute('metapost language chunk')
1280 \stoptyping
1281
1282 for various bits of Metapost language input. Be sure to check the
1283 \type{rettable.status} (see below) because when a fatal \METAPOST\
1284 error occurs the \MPLIB\ instance will become unusable thereafter.
1285
1286 Generally speaking, it is best to keep your chunks small, but beware
1287 that all chunks have to obey proper syntax, like each of them is a
1288 small file. For instance, you cannot split a single statement over
1289 multiple chunks.
1290
1291 In contrast with the normal standalone \type{mpost} command, there is
1292 {\em no\/} implied \quote{input} at the start of the first chunk.
1293
1294 \subsection{\luatex{mp:finish}}
1295
1296 \starttyping
1297 local rettable = mp:finish()
1298 \stoptyping
1299
1300 If for some reason you want to stop using an \MPLIB\ instance while
1301 processing is not yet actually done, you can call \type{mp:finish}.
1302 Eventually, used memory will be freed and open files will be closed by
1303 the \LUA\ garbage collector, but an explicit \type{mp:finish} is the
1304 only way to capture the final part of the output streams.
1305
1306 \subsection{Result table}
1307
1308 The return value of \type{mp:execute} and \type{mp:finish} is a table
1309 with a few possible keys (only \type {status} is always guaranteed to be present).
1310
1311 \starttabulate[|l|l|p|]
1312 \NC log \NC string \NC output to the \quote {log} stream \NC \NR
1313 \NC term \NC string \NC output to the \quote {term} stream \NC \NR
1314 \NC error \NC string \NC output to the \quote {error} stream (only used for \quote {out of memory})\NC \NR
1315 \NC status \NC number \NC the return value: 0=good, 1=warning, 2=errors, 3=fatal error \NC \NR
1316 \NC fig \NC table \NC an array of generated figures (if any)\NC \NR
1317 \stoptabulate
1318
1319 When \type{status} equals~3, you should stop using this \MPLIB\ instance
1320 immediately, it is no longer capable of processing input.
1321
1322 If it is present, each of the entries in the \type{fig} array is a
1323 userdata representing a figure object, and each of those has a number of
1324 object methods you can call:
1325
1326 \starttabulate[|l|l|p|]
1327 \NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR
1328 \NC postscript \NC function \NC return a string that is the ps output of the \type{fig} \NC \NR
1329 \NC svg \NC function \NC return a string that is the svg output of the \type{fig} \NC \NR
1330 \NC png \NC function \NC return a string that is the png output of the \type{fig} \NC \NR
1331 \NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR
1332 \NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR
1333 \NC filename \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output
1334 would have written to in standalone mode\NC \NR
1335 \NC width \NC function \NC the \type{charwd} value \NC \NR
1336 \NC height \NC function \NC the \type{charht} value \NC \NR
1337 \NC depth \NC function \NC the \type{chardp} value \NC \NR
1338 \NC italcorr \NC function \NC the \type{charic} value \NC \NR
1339 \NC charcode \NC function \NC the (rounded) \type{charcode} value \NC \NR
1340 \stoptabulate
1341
1342 {\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object!
1343
1344 When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set
1345 of coordinates is larger than the second set, the picture is empty.
1346
1347 Graphical objects come in various types that each have a different list of
1348 accessible values. The types are: \type{fill}, \type{outline}, \type{text},
1349 \type{start_clip}, \type{stop_clip}, \type{start_bounds}, \type{stop_bounds}, \type{special}.
1350
1351 There is helper function (\type{mplib.fields(obj)}) to get the list of
1352 accessible values for a particular object, but you can just as easily
1353 use the tables given below).
1354
1355 All graphical objects have a field \type{type} that gives the object
1356 type as a string value, that not explicit mentioned in the tables. In
1357 the following, \type{number}s are \POSTSCRIPT\ points represented as
1358 a floating point number, unless stated otherwise. Field values that
1359 are of \type{table} are explained in the next section.
1360
1361 \subsubsection{fill}
1362
1363 \starttabulate[|l|l|p|]
1364 \NC path \NC table \NC the list of knots \NC \NR
1365 \NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR
1366 \NC pen \NC table \NC knots of the pen \NC \NR
1367 \NC color \NC table \NC the object's color \NC \NR
1368 \NC linejoin \NC number \NC line join style (bare number)\NC \NR
1369 \NC miterlimit \NC number \NC miter limit\NC \NR
1370 \NC prescript \NC string \NC the prescript text \NC \NR
1371 \NC postscript \NC string \NC the postscript text \NC \NR
1372 \stoptabulate
1373
1374 The entries \type{htap} and \type{pen} are optional.
1375
1376 There is helper function (\type{mplib.pen_info(obj)}) that returns
1377 a table containing a bunch of vital characteristics of the used pen
1378 (all values are floats):
1379
1380 \starttabulate[|l|l|p|]
1381 \NC width \NC number \NC width of the pen\NC \NR
1382 \NC rx \NC number \NC $x$ scale \NC \NR
1383 \NC sx \NC number \NC $xy$ multiplier \NC \NR
1384 \NC sy \NC number \NC $yx$ multiplier \NC \NR
1385 \NC ry \NC number \NC $y$ scale \NC \NR
1386 \NC tx \NC number \NC $x$ offset \NC \NR
1387 \NC ty \NC number \NC $y$ offset \NC \NR
1388 \stoptabulate
1389
1390 \subsubsection{outline}
1391
1392 \starttabulate[|l|l|p|]
1393 \NC path \NC table \NC the list of knots \NC \NR
1394 \NC pen \NC table \NC knots of the pen \NC \NR
1395 \NC color \NC table \NC the object's color \NC \NR
1396 \NC linejoin \NC number \NC line join style (bare number)\NC \NR
1397 \NC miterlimit \NC number \NC miter limit \NC \NR
1398 \NC linecap \NC number \NC line cap style (bare number)\NC \NR
1399 \NC dash \NC table \NC representation of a dash list\NC \NR
1400 \NC prescript \NC string \NC the prescript text \NC \NR
1401 \NC postscript \NC string \NC the postscript text \NC \NR
1402 \stoptabulate
1403
1404 The entry \type{dash} is optional.
1405
1406 \subsubsection{text}
1407
1408 \starttabulate[|l|l|p|]
1409 \NC text \NC string \NC the text \NC \NR
1410 \NC font \NC string \NC font tfm name \NC \NR
1411 \NC dsize \NC number \NC font size\NC \NR
1412 \NC color \NC table \NC the object's color \NC \NR
1413 \NC width \NC number \NC \NC \NR
1414 \NC height \NC number \NC \NC \NR
1415 \NC depth \NC number \NC \NC \NR
1416 \NC transform \NC table \NC a text transformation \NC \NR
1417 \NC prescript \NC string \NC the prescript text \NC \NR
1418 \NC postscript \NC string \NC the postscript text \NC \NR
1419 \stoptabulate
1420
1421 \subsubsection{special}
1422
1423 \starttabulate[|l|l|p|]
1424 \NC prescript \NC string \NC special text \NC \NR
1425 \stoptabulate
1426
1427 \subsubsection{start_bounds, start_clip}
1428
1429 \starttabulate[|l|l|p|]
1430 \NC path \NC table \NC the list of knots \NC \NR
1431 \stoptabulate
1432
1433 \subsubsection{stop_bounds, stop_clip}
1434
1435 Here are no fields available.
1436
1437 \subsection{Subsidiary table formats}
1438
1439 \subsubsection{Paths and pens}
1440
1441 Paths and pens (that are really just a special type of paths as far as
1442 \MPLIB\ is concerned) are represented by an array where each entry
1443 is a table that represents a knot.
1444
1445 \starttabulate[|lT|l|p|]
1446 \NC left_type \NC string \NC when present: 'endpoint', but ususally absent \NC \NR
1447 \NC right_type \NC string \NC like \type{left_type}\NC \NR
1448 \NC x_coord \NC number \NC $x$ coordinate of this knot\NC \NR
1449 \NC y_coord \NC number \NC $y$ coordinate of this knot\NC \NR
1450 \NC left_x \NC number \NC $x$ coordinate of the precontrol point of this knot\NC \NR
1451 \NC left_y \NC number \NC $y$ coordinate of the precontrol point of this knot\NC \NR
1452 \NC right_x \NC number \NC $x$ coordinate of the postcontrol point of this knot\NC \NR
1453 \NC right_y \NC number \NC $y$ coordinate of the postcontrol point of this knot\NC \NR
1454 \stoptabulate
1455
1456 There is one special case: pens that are (possibly transformed)
1457 ellipses have an extra string-valued key \type{type} with value
1458 \type{elliptical} besides the array part containing the knot list.
1459
1460 \subsubsection{Colors}
1461
1462 A color is an integer array with 0, 1, 3 or 4 values:
1463
1464 \starttabulate[|l|l|p|]
1465 \NC 0 \NC marking only \NC no values \NC\NR
1466 \NC 1 \NC greyscale \NC one value in the range (0,1), \quote {black} is 0 \NC\NR
1467 \NC 3 \NC RGB \NC three values in the range (0,1), \quote {black} is 0,0,0 \NC\NR
1468 \NC 4 \NC CMYK \NC four values in the range (0,1), \quote {black} is 0,0,0,1 \NC\NR
1469 \stoptabulate
1470
1471 If the color model of the internal object was \type{unitialized}, then
1472 it was initialized to the values representing \quote {black} in the colorspace
1473 \type{defaultcolormodel} that was in effect at the time of the \type{shipout}.
1474
1475 \subsubsection{Transforms}
1476
1477 Each transform is a six-item array.
1478
1479 \starttabulate[|l|l|p|]
1480 \NC 1 \NC number \NC represents x \NC\NR
1481 \NC 2 \NC number \NC represents y \NC\NR
1482 \NC 3 \NC number \NC represents xx \NC\NR
1483 \NC 4 \NC number \NC represents yx \NC\NR
1484 \NC 5 \NC number \NC represents xy \NC\NR
1485 \NC 6 \NC number \NC represents yy \NC\NR
1486 \stoptabulate
1487
1488 Note that the translation (index 1 and 2) comes first. This differs
1489 from the ordering in \POSTSCRIPT, where the translation comes last.
1490
1491 \subsubsection{Dashes}
1492
1493 Each \type{dash} is two-item hash, using the same model as \POSTSCRIPT\
1494 for the representation of the dashlist. \type{dashes} is an array of
1495 \quote {on} and \quote {off}, values, and \type{offset} is the phase of the pattern.
1496
1497 \starttabulate[|l|l|p|]
1498 \NC dashes \NC hash \NC an array of on-off numbers \NC\NR
1499 \NC offset \NC number \NC the starting offset value \NC\NR
1500 \stoptabulate
1501
1502 \subsection{Character size information}
1503
1504 These functions find the size of a glyph in a defined font. The
1505 \type{fontname} is the same name as the argument to \type{infont};
1506 the \type{char} is a glyph id in the range 0 to 255; the returned
1507 \type{w} is in AFM units.
1508
1509 \subsubsection{\luatex{mp.char_width}}
1510
1511 \starttyping
1512 <number> w = mp.char_width(<string> fontname, <number> char)
1513 \stoptyping
1514
1515 \subsubsection{\luatex{mp.char_height}}
1516
1517 \starttyping
1518 <number> w = mp.char_height(<string> fontname, <number> char)
1519 \stoptyping
1520
1521 \subsubsection{\luatex{mp.char_depth}}
1522
1523 \starttyping
1524 <number> w = mp.char_depth(<string> fontname, <number> char)
1525 \stoptyping
1526
1527 \subsection{Solving path control points}
1528
1529 \starttyping
1530 <boolean> success = mp.solve_path(<table> knots, <boolean> cyclic)
1531 \stoptyping
1532
1533 This modifies the \type{knots} table (which should contain an
1534 array of points in a path, with the substructure explained below)
1535 by filling in the control points. The boolean \type{cyclic} is
1536 used to determine whether the path should be the equivalent of
1537 \type{--cycle}. If the return value is \type{false}, there
1538 is an extra return argument containing the error string.
1539
1540 On entry, the individual knot tables can contain the values
1541 mentioned above (but typically the \type{left_{x,y}} and
1542 \type{right_{x,y}} will be missing). \type{{x,y}_coord} are
1543 both required. Also, some extra values are allowed:
1544 \starttabulate[|lT|l|p|]
1545 \NC left_tension \NC number \NC A tension specifier \NC \NR
1546 \NC right_tension \NC number \NC like \type{left_tension}\NC \NR
1547 \NC left_curl \NC number \NC A curl specifier\NC \NR
1548 \NC right_curl \NC number \NC like \type{left_curl}\NC \NR
1549 \NC direction_x \NC number \NC $x$ displacement of a direction specifier\NC \NR
1550 \NC direction_y \NC number \NC $y$ displacement of a direction specifier\NC \NR
1551 \stoptabulate
1552
1553 Note the following:
1554 \startitemize
1555 \item A knot has either a direction specifier, or a curl specifier, or a tension specification,
1556 or explicit control points, with the note that tensions, curls and control points are split
1557 in a left and a right side (directions apply to both sides equally).
1558 \item The absolute value of a tension specifier should be more than 0.75 and less than 4096.0,
1559 with negative values indicating \quote{\type{atleast}}.
1560 \item The absolute value of a direction or curl should be less than 4096.0.
1561 \item If a tension, curl, or direction is specified, then existing control points will be
1562 replaced by the newly computed value.
1563 \item Calling \type{solve_path} does not alter the used mplib instance.
1564 \stopitemize
1565
1566 \stoptext
1567
1568
1569
1570
1571
1572