| 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 |
|