diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex | 1101 |
1 files changed, 1101 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex new file mode 100644 index 00000000000..a18e5e01fb0 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex @@ -0,0 +1,1101 @@ + +\def\MPLIB{MPlib} +\def\MP{MetaPost} +\def\POSTSCRIPT{PostScript} +\def\PS{PostScript} +\def\TFM{{\sc tfm}} +\def\LUA{Lua} + +\def\luatex#1{#1} + +\setupinteraction[state=start] % don't forget this line! +\placebookmarks[section,subsection,subsubsection][section] +% \setupinteractionscreen[option=bookmark] + +\definefontsynonym[TitleFont][Sans] +\definefontsynonym[SubTitleFont][Sans] + +\def\StartTitlePage% + {\bgroup%\startstandardmakeup + \setupalign[middle] + \hbox{}\vfil + \let\\=\crlf} + +\def\StopTitlePage% + {\vfil + \page\egroup%\stopstandardmakeup + } + +\usetypescript[palatino] +\switchtobodyfont[palatino,10pt] + +\nonknuthmode + +\def\ctypedef#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}} +\def\cenumeration#1{\subsubsection{\type{#1}}\bookmark{#1}} +\def\cfunction#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}} + + +\starttext + +\StartTitlePage +\centerline{\definedfont[TitleFont at 50pt]{\MPLIB}} +\blank[3*line] +\centerline{\definedfont[SubTitleFont at 24pt]{API documentation}} +\blank[3*line] +\centerline{Taco Hoekwater, July 2008} +\StopTitlePage + +\section{Table of contents} + +\placecontent[criterium=all,level=subsection] + +\page + +\section{Introduction} + +This document describes the API to \MPLIB, allowing you to use +\MPLIB\ in your own applications. One such application is writing +bindings to interface with other programming languages. The +bindings to the \LUA\ scripting language is part of the \MPLIB\ +distribution and also covered by this manual. + +This is a first draft of both this document as well as the API, so +there may be errors or omissions in this document or strangenesses in +the API. If you believe something can be improved, please do not +hesitate to let us know. The contact email address is {\tt +metapost@tug.org}. + +The C paragraphs in this document assume you understand C code, the +Lua paragraphs assume you understand Lua code, and familiarity with +\MP\ is assumed throughout. + +\subsection{Simple \MPLIB\ use} + +There are two different approaches possible when running \MPLIB. The first +method is most suitable for programs that function as a command-line +frontend. It uses \quote{normal} \MP\ interface with I/O to and from files, +and needs very little setup to run. On the other hand, it also gives +almost no chance to control the \MPLIB\ behaviour. + +Here is a C language example of how to do this: + + +\starttyping +#include <stdlib.h> +#include "mplib.h" +int main (int argc, char **argv) { + MP mp; + MP_options *opt = mp_options(); + opt->command_line = argv[1]; + mp = mp_initialize(opt); + if (mp) { + int history = mp_run(mp); + mp_finish(mp); + exit (history); + } else { + exit (EXIT_FAILURE); + } +} +\stoptyping + +This example will run in \quote{inimpost} mode. + +\subsection{Embedded \MPLIB\ use} + +The second method does not run a file, but instead repeatedly executes +chunks of \MP\ language input that are passed to the library as +strings, with the output redirected to internal buffers instead of +directly to files. + +Here is an example of how this second approach works, now using the +\LUA\ bindings: + +\starttyping +local mplib = require('mplib') +local mp = mplib.new ({ ini_version = false, + mem_name = 'plain' }) +if mp then + local l = mp:execute([[beginfig(1); + fill fullcircle scaled 20; + endfig; + ]]) + if l and l.fig and l.fig[1] then + print (l.fig[1]:postscript()) + end + mp:finish(); +end +\stoptyping + +This example loads a previously generated \quote{plain} mem file. + + +\section{C API for core \MPLIB} + +All of the types, structures, enumerations and functions that are +described in this section are defined in the header file \type{mplib.h}. + +\subsection{Structures} + +\ctypedef{}{MP_options}{} + +This is a structure that contains the configurable parameters for a new \MPLIB\ instance. Because \MP\ differentiates +between \type{-ini} and \type{non-ini} modes, there are three types of settings: Those that apply in both cases, and +those that apply in only one of those cases. + +\starttabulate[|l|l|l|p|] +\NC int \NC ini_version \NC 1 \NC set this to zero if you want to load a mem file.\NC \NR +\NC int \NC error_line \NC 79 \NC maximal length of error message lines\NC \NR +\NC int \NC half_error_line \NC 50 \NC halfway break point for error contexts\NC\NR +\NC int \NC max_print_line \NC 100 \NC maximal length of file output\NC \NR +\NC unsigned \NC hash_size \NC 16384 \NC size of the internal hash (always a multiple of 2). + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC param_size \NC 150 \NC number of simultaneously active macro parameters. + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC max_in_open \NC 10 \NC maximum level of \type{input} nesting. + ignored in \type{non-ini} mode, read from mem file\NC \NR +\NC int \NC main_memory \NC 5000 \NC size of the main memory array in 8-byte words; + in \type{non-ini} mode only used if larger than the + value stored in the mem file\NC\NR +\NC void * \NC userdata \NC NULL \NC for your personal use only, not used by the library\NC \NR +\NC char * \NC banner \NC NULL \NC string to use instead of default banner\NC \NR +\NC int \NC print_found_names\NC 0 \NC controls whether the asked name or the actual found + name of the file is used in messages\NC \NR +\NC int \NC file_line_error_style\NC 0 \NC when this option is nonzero, the library will use \type{file:line:error} + style formatting for error messages that occur while reading + from input files\NC \NR +\NC char * \NC command_line \NC NULL \NC input file name and rest of command line; + only used by \type{mp_run} interface\NC \NR +\NC int \NC interaction \NC 0 \NC explicit \type{mp_interaction_mode} (see below)\NC \NR +\NC int \NC noninteractive \NC 0 \NC set this nonzero to suppress user interaction, + only sensible if you want to use \type{mp_execute}\NC \NR +\NC int \NC random_seed \NC 0 \NC set this nonzero to force a specific random seed\NC \NR +\NC int \NC troff_mode \NC 0 \NC set this nonzero to initialize \quote{troffmode} \NC \NR +\NC char * \NC mem_name \NC NULL \NC explicit mem name to use instead of \type{plain.mem}. + ignored in \type{-ini} mode.\NC \NR +\NC char * \NC job_name \NC NULL \NC explicit job name to use instead of first input file\NC \NR +\NC mp_file_finder \NC find_file \NC NULL \NC function called for finding files \NC \NR +\NC mp_editor_cmd \NC run_editor \NC NULL \NC function called after \quote{E} error response\NC \NR +\NC mp_makempx_cmd \NC run_make_mpx \NC NULL \NC function called for the creation of mpx files\NC \NR +\stoptabulate + +To create an \type{MP_options} structure, you have to use the \type{mp_options()} function. + +\ctypedef{}{MP}{} + +This type is an opaque pointer to a \MPLIB\ instance, it is what you +have pass along as the first argument to (almost) all the \MPLIB\ +functions. The actual C structure it points to has hundreds of fields, +but you should not use any of those directly. All confuration is done +via the \type{MP_options} structure, and there are accessor functions +for the fields that can be read out. + +\ctypedef{}{mp_run_data}{} + +When the \MPLIB\ instance is not interactive, any output is redirect +to this structure. There are a few string output streams, and a +linked list of output images. + +\starttabulate[|l|l|p|] +\NC mp_stream \NC term_out \NC holds the terminal output \NC \NR +\NC mp_stream \NC error_out \NC holds error messages \NC \NR +\NC mp_stream \NC log_out \NC holds the log output \NC \NR +\NC mp_edge_object *\NC edges \NC linked list of generated pictures \NC \NR +\stoptabulate + +\type{term_out} is equivalent to \type{stdout} in interactive use, and +\type{error_out} is equivalent to \type{stderr}. The \type{error_out} +is currently only used for memory allocation errors, the \MP\ error +messages are written to \type{term_out} (and are often duplicated to +\type{log_out} as well). + +You need to include \type{mplibps.h} to be able to actually make use this list of images, +see the next section for the details on \type{mp_edge_object} lists. + +See next paragraph for \type{mp_stream}. + +\ctypedef{}{mp_stream}{} + +This contains the data for a stream as well as some internal +bookkeeping variables. The fields that are of interest to you are: + +\starttabulate[|l|l|p|] +\NC size_t \NC size \NC the internal buffer size\NC \NR +\NC char * \NC data \NC the actual data. \NC \NR +\stoptabulate + +There is nothing in the stream unless the \type{size} field is +nonzero. There will not be embedded zeroes in \type{data}. + +If \type{size} is nonzero, \type{strlen(data)} is guaranteed to be +less than that, and may be as low as zero (if \MPLIB\ has written an +empty string). + +\subsection{Function prototype typedefs} + +The following three function prototypes define functions that you can +pass to \MPLIB\ insert the \type{MP_options} structure. + +\ctypedef{char * }{(*mp_file_finder)}{ (MP, const char*, const char*, int)} + +\MPLIB\ calls this function whenever it needs to find a file. If you +do not set up the matching option field (\type{MP_options.find_file}), +\MPLIB\ will only be able to find files in the current directory. + +The three function arguments are the requested file name, the file +mode (either \type{"r"} or \type{"w"}), and the file type (an +\type{mp_filetype}, see below). + +The return value is a new string indicating the disk file name to be +used, or NULL if the named file can not be found. If the mode is +\type{"w"}, it is usually best to simply return a copy of the first +argument. + + +\ctypedef{void }{(*mp_editor_cmd)}{(MP, char*, int)} + +This function is executed when a user has pressed \quote{E} as reply to an +\MP\ error, so it will only ever be called when \MPLIB\ in interactive mode. +The function arguments are the file name and the line number. When +this function is called, any open files are already closed. + +\ctypedef{int }{(*mp_makempx_cmd)}{(MP, char*, char *)} + +This function is executed when there is a need to start generating an +\type{mpx} file because (the first time a \type{btex} command was +encountered in the current input file). + +The first arguments is the input file name. This is the name that was given +in the \MP\ language, so it may not be the same as name of the actual +file that is being used, depending on how you your +\type{mp_file_finder} function behaves. The second argument is the +requested output name for mpx commands. + +A zero return value indicates success, everything else indicates +failure to create a proper \type{mpx} file and will result in an \MP\ error. + +\subsection{Enumerations} + +\cenumeration{mp_filetype} + +The \type{mp_file_finder} receives an \type{int} argument that is one of the following types: + +\starttabulate[|l|p|] +\NC mp_filetype_program \NC Metapost language code (r)\NC \NR +\NC mp_filetype_log \NC Log output (w)\NC \NR +\NC mp_filetype_postscript \NC PostScript output (w)\NC \NR +\NC mp_filetype_memfile \NC Mem file (r+w)\NC \NR +\NC mp_filetype_metrics \NC \TeX\ font metric file (r+w)\NC \NR +\NC mp_filetype_fontmap \NC Font map file (r)\NC \NR +\NC mp_filetype_font \NC Font PFB file (r)\NC \NR +\NC mp_filetype_encoding \NC Font encoding file (r)\NC \NR +\NC mp_filetype_text \NC \type{readfrom} and \type{write} files (r+w)\NC \NR +\stoptabulate + +\cenumeration{mp_interaction_mode} + +When \type{noninteractive} is zero, \MPLIB\ normally starts in a mode where it reports every error, +stops and asks the user for input. This initial mode can be overruled by using one of the following: + +\starttabulate[|l|p|] +\NC mp_batch_mode \NC as with \type{batchmode} \NC \NR +\NC mp_nonstop_mode \NC as with \type{nonstopmode} \NC \NR +\NC mp_scroll_mode \NC as with \type{scrollmode} \NC \NR +\NC mp_error_stop_mode \NC as with \type{errorstopmode} \NC \NR +\stoptabulate + +\cenumeration{mp_history_state} + +These are set depending on the current state of the interpreter. + +\starttabulate[|l|p|] +\NC mp_spotless \NC still clean as a whistle \NC \NR +\NC mp_warning_issued \NC a warning was issued or something was \type{show}-ed \NC \NR +\NC mp_error_message_issued \NC an error has been reported \NC \NR +\NC mp_fatal_eror_stop \NC termination was premature due to error(s) \NC \NR +\NC mp_system_error_stop \NC termination was premature due to disaster + (out of system memory) \NC \NR +\stoptabulate + + +\cenumeration{mp_color_model} + +Graphical objects always have a color model attached to them. + +\starttabulate[|l|p|] +\NC mp_no_model \NC as with \type{withoutcolor} \NC \NR +\NC mp_grey_model \NC as with \type{withgreycolor} \NC \NR +\NC mp_rgb_model \NC as with \type{withrgbcolor} \NC \NR +\NC mp_cmyk_model \NC as with \type{withcmykcolor} \NC \NR +\stoptabulate + + +\cenumeration{mp_knot_type} + +Knots can have left and right types depending on their current +status. By the time you see them in the output, they are usually +either \type{mp_explicit} or \type{mp_endpoint}, but here is the full +list: + +\starttabulate[|l|p|] +\NC mp_endpoint \NC \NC \NR +\NC mp_explicit \NC \NC \NR +\NC mp_given \NC \NC \NR +\NC mp_curl \NC \NC \NR +\NC mp_open \NC \NC \NR +\NC mp_end_cycle \NC \NC \NR +\stoptabulate + +\cenumeration{mp_knot_originator} + +Knots can originate from two sources: they can be explicitly given by +the user, or they can be created by the \MPLIB\ program code (for +example as result of the \type{makepath} operator). + +\starttabulate[|l|p|] +\NC mp_program_code \NC \NC \NR +\NC mp_metapost_user \NC \NC \NR +\stoptabulate + + +\cenumeration{mp_graphical_object_code} + +There are eight different graphical object types. + +\starttabulate[|l|p|] +\NC mp_fill_code \NC \type{addto contour} \NC \NR +\NC mp_stroked_code \NC \type{addto doublepath} \NC \NR +\NC mp_text_code \NC \type{addto also} (via \type{infont})\NC \NR +\NC mp_start_clip_code \NC \type{clip} \NC \NR +\NC mp_start_bounds_code \NC \NC \NR +\NC mp_stop_clip_code \NC \type{setbounds} \NC \NR +\NC mp_stop_bounds_code \NC \NC \NR +\NC mp_special_code \NC \type{special} \NC \NR +\stoptabulate + + +\subsection{Functions} + +\cfunction{char *}{mp_metapost_version}{(void)} + +Returns a copy of the \MPLIB\ version string. + +\cfunction{MP_options *}{mp_options}{(void)} + +Returns a properly initialized option structure, or \type{NULL} in case of allocation errors. + +\cfunction{MP }{mp_initialize}{(MP_options *opt)} + +Returns a pointer to a new \MPLIB\ instance, or \type{NULL} if initialisation failed. + +String options are copied, so you can free any of those (and the \type{opt} structure) +immediately after the call to this function. + +\cfunction{int }{mp_status}{(MP mp)} + +Returns the current value of the interpreter error state, as a \type{mp_history_state}. +This function is useful after \type{mp_initialize}. + +\cfunction{int }{mp_run}{(MP mp)} + +Runs the \MPLIB\ instance using the \type{command_line} and other items from the +\type{MP_options}. After the call to \type{mp_run}, the \MPLIB\ instance should be +closed off by calling \type{mp_finish}. + +The return value is the current \type{mp_history_state} + +\cfunction{void *}{mp_userdata}{(MP mp)} + +Simply returns the pointer that was passed along as \type{userdata} in +the \type{MP_options} struct. + +\cfunction{int }{mp_troff_mode}{(MP mp)} + +Returns the value of \type{troff_mode} as copied from the +\type{MP_options} struct. + +\cfunction{mp_run_data *}{mp_rundata}{(MP mp)} + +Returns the information collected during the previous call to \type{mp_execute}. + +\cfunction{int }{mp_execute}{(MP mp, char *s, size_t l)} + +Executes string \type{s} with length \type{l} in the \MPLIB\ +instance. This call can be repeated as often as is needed. The return +value is the current \type{mp_history_state}. To get at the produced +results, call \type {mp_rundata}. + +\cfunction{void }{mp_finish}{(MP mp)} + +This finishes off the use of the \MPLIB\ instance: it closes all files +and frees all the memory allocated by this instance. + +\cfunction{double }{mp_get_char_dimension}{(MP mp,char*fname,int n,int t)} + +This is a helper function that returns one of the dimensions of glyph +\type{n} in font \type{fname} as a double in PostScript (AFM) +units. The requested item \type{t} can be \type{'w'} (width), +\type{'h'} (height), or \type{'d'} (depth). + +\cfunction{int }{mp_memory_usage}{(MP mp)} + +Returns the current memory usage of this instance. + +\cfunction{int }{mp_hash_usage}{(MP mp)} + +Returns the current hash usage of this instance. + +\cfunction{int }{mp_param_usage}{(MP mp)} + +Returns the current simultaneous macro parameter usage of this instance. + +\cfunction{int }{mp_open_usage}{(MP mp)} + +Returns the current \type{input} levels of this instance. + +\section{C API for graphical backend functions} + +These are all defined in \type{mplibps.h} + +Unless otherwise stated, the \type{int} fields that express \MP\ values +should be interpreted as scaled points: the 32bits are divided into an +integer part and a fraction part so that the value $65536$ equals +1~\PS\ point (of which there are exactly 72 in an inch). + + +\subsection{Structures} + +The structures in this section are used by the items in the body of +the \type{edges} field of an \type{mp_rundata} structure. They are +presented here in a bottom-up manner. + +\ctypedef {}{mp_knot}{} + +Each \MPLIB\ path (a sequence of \MP\ points) is represented as a linked list +of structures of the type \type{mp_knot}. + +\starttabulate[|l|l|p|] +\NC struct mp_knot * \NC next \NC the next knot, or NULL\NC \NR +\NC mp_knot_type \NC left_type \NC the \type{mp_knot_type} for the left side \NC \NR +\NC mp_knot_type \NC right_type \NC the \type{mp_knot_type} for the right side \NC \NR +\NC signed int \NC x_coord \NC $x$\NC \NR +\NC signed int \NC y_coord \NC $y$\NC \NR +\NC signed int \NC left_x \NC $x$ of the left (incoming) control point\NC \NR +\NC signed int \NC left_y \NC $y$ of the left (incoming) control point\NC \NR +\NC signed int \NC right_x \NC $x$ of the right (outgoing) control point\NC \NR +\NC signed int \NC right_y \NC $y$ of the right (outgoing) control point\NC \NR +\NC mp_knot_originator \NC originator \NC the \type{mp_knot_originator} \NC \NR +\stoptabulate + +\ctypedef {}{mp_color}{} + +The graphical object that can be colored, have two fields to define +the color: one for the color model and one for the color values. The +structure for the color values is defined as follows: + +\starttabulate[|l|l|p|] +\NC int \NC a_val \NC see below, values are in scaled points\NC \NR +\NC int \NC b_val \NC --\NC \NR +\NC int \NC c_val \NC --\NC \NR +\NC int \NC d_val \NC --\NC \NR +\stoptabulate + +All graphical objects that have \type{mp_color} fields also have +\type{mp_color_model} fields. The color model decides the meaning of +the four data fields: + +\starttabulate[|l|c|c|c|c|] +\NC color model value \NC a_val \NC b_val \NC c_val \NC d_val \NC \FR +\NC mp_no_model \NC -- \NC -- \NC -- \NC -- \NC \NR +\NC mp_grey_model \NC grey \NC -- \NC -- \NC -- \NC \NR +\NC mp_rgb_model \NC red \NC green \NC blue \NC \NC \NR +\NC mp_cmyk_model \NC cyan \NC magenta \NC yellow\NC black \NC \NR +\stoptabulate + +\ctypedef {}{mp_dash_object}{} + +Dash lists are represented like this: + +\starttabulate[|l|l|p|] +\NC int * \NC array \NC an array of dash lengths, terminated by $-1$. + the values are in scaled points\NC \NR +\NC int \NC offset\NC the dash array offset (as in PostScript) \NC \NR +\stoptabulate + +\ctypedef {}{mp_graphic_object}{} + +Now follow the structure definitions of the objects that can appear +inside a figure (this is called an \quote{edge structure} in the +internal WEB documentation). + +There are eight different graphical object types, but there are seven +different C structures. Type \type{mp_graphic_object} represents the +base line of graphical object types. It has only two fields: + +\starttabulate[|l|l|p|] +\NC mp_graphical_object_code \NC type \NC \NC \NR +\NC struct mp_graphic_object * \NC next \NC next object or NULL \NC \NR +\stoptabulate + +Because every graphical object has at least these two types, the body +of a picture is represented as a linked list of +\type{mp_graphic_object} items. Each object in turn can then be +typecast to the proper type depending on its \type{type}. + +The two \quote{missing} objects in the explanations below are the ones +that match \type{mp_stop_clip_code} and \type{mp_stop_bounds_code}: +these have no extra fields besides \type{type} and \type{next}. + +\ctypedef {}{mp_fill_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR +\NC char * \NC post_script \NC this is the result of \type{withpostscript}\NC \NR +\NC mp_color \NC color \NC the color value of this object\NC \NR +\NC mp_color_model \NC color_model \NC the color model\NC \NR +\NC unsigned char \NC ljoin \NC the line join style; values have the same meaning + as in \PS: 0 for mitered, 1 for round, 2 for beveled.\NC \NR +\NC mp_knot * \NC path_p \NC the (always cyclic) path\NC \NR +\NC mp_knot * \NC htap_p \NC a possible reversed path (see below)\NC \NR +\NC mp_knot * \NC pen_p \NC a possible pen (see below)\NC \NR +\NC int \NC miterlim \NC the miter limit\NC \NR +\stoptabulate + +Even though this object is called an \type{mp_fill_object}, it can be the result of both +\type{fill} and \type{filldraw} in the \MP\ input. This means that there can be a pen +involved as well. The final output should behave as follows: + +\startitemize +\item If there is no \type{pen_p}; simply fill \type{path_p}. +\item If there is a one-knot pen (\type{pen_p->next} = \type{pen_p}) then fill \type{path_p} +and also draw \type{path_p} with the \type{pen_p}. Do not forget to take \type{ljoin} and +\type{miterlim} into account when drawing with the pen. +\item If there is a more complex pen (\type{pen_p->next} != \type{pen_p}) then its path +has already been preprocessed for you. fill \type{path_p} and \type{htap_p}. +\stopitemize + +\ctypedef {}{mp_stroked_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript} \NC \NR +\NC char * \NC post_script \NC this is the result of \type{withpostscript} \NC \NR +\NC mp_color \NC color \NC color value \NC \NR +\NC mp_color_model \NC color_model \NC color model \NC \NR +\NC unsigned char \NC ljoin \NC the line join style \NC \NR +\NC unsigned char \NC lcap \NC the line cap style; values have the same meaning + as in \PS: 0 for butt ends, 1 for round ends, 2 for projecting ends.\NC \NR +\NC mp_knot * \NC path_p \NC the path \NC \NR +\NC mp_knot * \NC pen_p \NC the pen \NC \NR +\NC int \NC miterlim \NC miter limit \NC \NR +\NC mp_dash_object * \NC dash_p \NC a possible dash list\NC \NR +\stoptabulate + +\ctypedef {}{mp_text_object}{} + +Contains the following fields on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char * \NC pre_script \NC this is the result of \type{withprescript}\NC \NR +\NC char * \NC post_script\NC this is the result of \type{withpostscript}\NC \NR +\NC mp_color \NC color \NC color value \NC \NR +\NC mp_color_model \NC color_model\NC color model \NC \NR +\NC char * \NC text_p \NC string to be placed \NC \NR +\NC char * \NC font_name \NC the \MP\ font name\NC \NR +\NC unsigned int \NC font_dsize \NC size of the font\NC \NR +\NC int \NC width \NC width of the picture resulting from the string\NC \NR +\NC int \NC height \NC height\NC \NR +\NC int \NC depth \NC depth\NC \NR +\NC int \NC tx \NC transformation component\NC \NR +\NC int \NC ty \NC transformation component\NC \NR +\NC int \NC txx \NC transformation component\NC \NR +\NC int \NC tyx \NC transformation component\NC \NR +\NC int \NC txy \NC transformation component\NC \NR +\NC int \NC tyy \NC transformation component\NC \NR +\stoptabulate + +All fonts are loaded by \MPLIB\ at the design size (but not all fonts have the same design +size). If text is to be scaled, this happens via the transformation components. + +\ctypedef {}{mp_clip_object}{} + +Contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC mp_knot * \NC path_p \NC defines the clipping path that is in effect until + the object with the matching \type{mp_stop_clip_code} is encountered\NC \NR +\stoptabulate + +\ctypedef {}{mp_bounds_object}{} + +Contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC mp_knot * \NC path_p \NC the path that was used for boundary calculation \NC \NR +\stoptabulate + +This object can be ignored when output is generated, it only has effect on the boudingbox +of the following objects and that has been taken into account already. + +\ctypedef {}{mp_special_object}{} + +This represents the output generated by a \MP\ \type{special} command. It +contains the following field on top of the ones defined by \type{mp_graphic_object}: + +\starttabulate[|l|l|p|] +\NC char *\NC pre_script \NC the special string\NC \NR +\stoptabulate + +Each \type{special} command generates one object. All of the relevant +\type{mp_special_object}s for a figure are linked together at the start +of that figure. + +\ctypedef {}{mp_edge_object}{} + +\starttabulate[|l|l|p|] +\NC mp_edge_object * \NC next \NC points to the next figure (or NULL)\NC \NR +\NC mp_graphic_object * \NC body \NC a linked list of objects in this figure \NC \NR +\NC char * \NC filename \NC this would have been the used filename if a \PS\ file + would have been generated\NC \NR +\NC MP \NC parent \NC a pointer to the instance that created + this figure\NC \NR +\NC int \NC minx \NC lower-left $x$ of the bounding box\NC \NR +\NC int \NC miny \NC lower-left $y$ of the bounding box\NC \NR +\NC int \NC maxx \NC upper right $x$ of the bounding box\NC \NR +\NC int \NC maxy \NC upper right $y$ of the bounding box\NC \NR +\NC int \NC width \NC value of \type{charwd}; +this would become the \TFM\ width (but without the potential rounding correction for \TFM\ file format)\NC \NR +\NC int \NC height \NC similar for height (\type{charht})\NC \NR +\NC int \NC depth \NC similar for depth (\type{chardp})\NC \NR +\NC int \NC ital_corr \NC similar for italic correction (\type{charic})\NC \NR +\NC int \NC charcode \NC Value of \type{charcode} (rounded, but not + modulated for \TFM's 256 values yet)\NC \NR +\stoptabulate + +\subsection{Functions} + +\cfunction{int }{mp_ps_ship_out}{(mp_edge_object*hh,int prologues,int procset)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \PS\ output for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated text in the \type{ps_out} field. + +Returns zero for success. + +\cfunction{void }{mp_gr_toss_objects}{(mp_edge_object*hh)} + +This frees a single \type{mp_edge_object} and its \type{mp_graphic_object} contents. + +\cfunction{void }{mp_gr_toss_object}{(mp_graphic_object*p)} + +This frees a single \type{mp_graphic_object} object. + +\cfunction{mp_graphic_object *}{mp_gr_copy_object}{(MP mp,mp_graphic_object*p)} + +This creates a deep copy of a \type{mp_graphic_object} object. + +\section{C API for label generation (a.k.a. makempx)} + +The following are all defined in \type{mpxout.h}. + +\subsection {Structures} + +\ctypedef {}{MPX}{} + +An opaque pointer that is passed on to the file_finder. + +\ctypedef {}{mpx_options}{} + +This structure holds the option fields for \type{mpx} generation. +You have to fill in all fields except \type{mptexpre}, that +one defaults to \type{mptexpre.tex} + + +\starttabulate[|l|l|p|] +\NC mpx_modes \NC mode \NC \NC \NR +\NC char * \NC cmd \NC the command (or sequence of commands) to run\NC \NR +\NC char * \NC mptexpre \NC prepended to the generated \TeX\ file\NC \NR +\NC char * \NC mpname \NC input file name \NC \NR +\NC char * \NC mpxname \NC output file name\NC \NR +\NC char * \NC banner \NC string to be printed to the generated to-be-typeset file\NC \NR +\NC int \NC debug \NC When nonzero, \type{mp_makempx} outputs some debug information and do not delete temp files\NC \NR +\NC mpx_file_finder \NC find_file \NC \NC \NR +\stoptabulate + +\subsection{Function prototype typedefs} + +\ctypedef{char * }{(*mpx_file_finder)}{ (MPX, const char*, const char*, int)} + +The return value is a new string indicating the disk file to be used. +The arguments are the file name, the file mode (either \type{"r"} or \type{"w"}), +and the file type (an \type{mpx_filetype}, see below). If the mode is \type{"w"}, +it is usually best to simply return a copy of the first argument. + +\subsection{Enumerations} + +\cenumeration{mpx_modes} + +\starttabulate[|l|p|] +\NC mpx_tex_mode \NC \NC \NR +\NC mpx_troff_mode \NC \NC \NR +\stoptabulate + +\cenumeration{mpx_filetype} + +\starttabulate[|l|p|] +\NC mpx_tfm_format \NC \TeX\ or Troff ffont metric file \NC \NR +\NC mpx_vf_format \NC \TeX\ virtual font file \NC \NR +\NC mpx_trfontmap_format \NC Troff font map \NC \NR +\NC mpx_trcharadj_format \NC Troff character shift information \NC \NR +\NC mpx_desc_format \NC Troff DESC file \NC \NR +\NC mpx_fontdesc_format \NC Troff FONTDESC file \NC \NR +\NC mpx_specchar_format \NC Troff special character definition\NC \NR +\stoptabulate + +\subsection{Functions} + +\cfunction{int }{mpx_makempx}{(mpx_options *mpxopt)} + +A return value of zero is success, non-zero values indicate errors. + +\page + +\section{Lua API} + +The \MP\ library interface registers itself in the table \type{mplib}. + +\subsection{\luatex{mplib.version}} + +Returns the \MPLIB\ version. + +\starttyping +<string> s = mplib.version() +\stoptyping + +\subsection{\luatex{mplib.new}} + +To create a new metapost instance, call + +\starttyping +<mpinstance> mp = mplib.new({...}) +\stoptyping + +This creates the \type{mp} instance object. The argument hash can have a number of +different fields, as follows: + +\starttabulate[|lT|l|p|p|] +\NC \ssbf name \NC \bf type \NC \bf description \NC \bf default \NC\NR +\NC error_line \NC number \NC error line width \NC 79 \NC\NR +\NC print_line \NC number \NC line length in ps output \NC 100\NC\NR +\NC main_memory \NC number \NC total memory size \NC 5000\NC\NR +\NC hash_size \NC number \NC hash size \NC 16384 \NC\NR +\NC param_size \NC number \NC max. active macro parameters\NC 150\NC\NR +\NC max_in_open \NC number \NC max. input file nestings \NC 10\NC\NR +\NC random_seed \NC number \NC the initial random seed \NC variable\NC\NR +\NC interaction \NC string \NC the interaction mode, one of +\type {batch}, \type {nonstop}, \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR +\NC ini_version \NC boolean \NC the --ini switch \NC true \NC\NR +\NC mem_name \NC string \NC \type {--mem} \NC \type {plain} \NC\NR +\NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR +\NC find_file \NC function \NC a function to find files \NC only local files\NC\NR +\stoptabulate + +The \type{find_file} function should be of this form: + +\starttyping +<string> found = finder (<string> name, <string> mode, <string> type) +\stoptyping + +with: + +\starttabulate[|lT|l|p|] +\NC name \NC the requested file \NC \NR +\NC mode \NC the file mode: \type {r} or \type {w} \NC \NR +\NC type \NC the kind of file, one of: \type {mp}, \type {mem}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR +\stoptabulate + +Return either the full pathname of the found file, or \type{nil} if +the file cannot be found. + +\subsection{\luatex{mp:statistics}} + +You can request statistics with: + +\starttyping +<table> stats = mp:statistics() +\stoptyping + +This function returns the vital statistics for an \MPLIB\ instance. There are four +fields, giving the maximum number of used items in each of the four +statically allocated object classes: + +\starttabulate[|lT|l|p|] +\NC main_memory \NC number \NC memory size \NC\NR +\NC hash_size \NC number \NC hash size\NC\NR +\NC param_size \NC number \NC simultaneous macro parameters\NC\NR +\NC max_in_open \NC number \NC input file nesting levels\NC\NR +\stoptabulate + +\subsection{\luatex{mp:execute}} + +You can ask the \METAPOST\ interpreter to run a chunk of code by calling + +\starttyping +local rettable = mp:execute('metapost language chunk') +\stoptyping + +for various bits of Metapost language input. Be sure to check the +\type{rettable.status} (see below) because when a fatal \METAPOST\ +error occurs the \MPLIB\ instance will become unusable thereafter. + +Generally speaking, it is best to keep your chunks small, but beware +that all chunks have to obey proper syntax, like each of them is a +small file. For instance, you cannot split a single statement over +multiple chunks. + +In contrast with the normal standalone \type{mpost} command, there is +{\em no\/} implied \quote{input} at the start of the first chunk. + +\subsection{\luatex{mp:finish}} + +\starttyping +local rettable = mp:finish() +\stoptyping + +If for some reason you want to stop using an \MPLIB\ instance while +processing is not yet actually done, you can call \type{mp:finish}. +Eventually, used memory will be freed and open files will be closed by +the \LUA\ garbage collector, but an explicit \type{mp:finish} is the +only way to capture the final part of the output streams. + +\subsection{Result table} + +The return value of \type{mp:execute} and \type{mp:finish} is a table +with a few possible keys (only \type {status} is always guaranteed to be present). + +\starttabulate[|l|l|p|] +\NC log \NC string \NC output to the \quote {log} stream \NC \NR +\NC term \NC string \NC output to the \quote {term} stream \NC \NR +\NC error \NC string \NC output to the \quote {error} stream (only used for \quote {out of memory})\NC \NR +\NC status \NC number \NC the return value: 0=good, 1=warning, 2=errors, 3=fatal error \NC \NR +\NC fig \NC table \NC an array of generated figures (if any)\NC \NR +\stoptabulate + +When \type{status} equals~3, you should stop using this \MPLIB\ instance +immediately, it is no longer capable of processing input. + +If it is present, each of the entries in the \type{fig} array is a +userdata representing a figure object, and each of those has a number of +object methods you can call: + +\starttabulate[|l|l|p|] +\NC boundingbox \NC function \NC returns the bounding box, as an array of 4 values\NC \NR +\NC postscript \NC function \NC return a string that is the ps output of the \type{fig} \NC \NR +\NC svg \NC function \NC return a string that is the svg output of the \type{fig} \NC \NR +\NC objects \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR +\NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR +\NC filename \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output + would have written to in standalone mode\NC \NR +\NC width \NC function \NC the \type{charwd} value \NC \NR +\NC height \NC function \NC the \type{charht} value \NC \NR +\NC depth \NC function \NC the \type{chardp} value \NC \NR +\NC italcorr \NC function \NC the \type{charic} value \NC \NR +\NC charcode \NC function \NC the (rounded) \type{charcode} value \NC \NR +\stoptabulate + +{\bf NOTE:} you can call \type{fig:objects()} only once for any one \type{fig} object! + +When the boundingbox represents a \quote {negated rectangle}, i.e.\ when the first set +of coordinates is larger than the second set, the picture is empty. + +Graphical objects come in various types that each have a different list of +accessible values. The types are: \type{fill}, \type{outline}, \type{text}, +\type{start_clip}, \type{stop_clip}, \type{start_bounds}, \type{stop_bounds}, \type{special}. + +There is helper function (\type{mplib.fields(obj)}) to get the list of +accessible values for a particular object, but you can just as easily +use the tables given below). + +All graphical objects have a field \type{type} that gives the object +type as a string value, that not explicit mentioned in the tables. In +the following, \type{number}s are \POSTSCRIPT\ points represented as +a floating point number, unless stated otherwise. Field values that +are of \type{table} are explained in the next section. + +\subsubsection{fill} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC htap \NC table \NC the list of knots for the reversed trajectory \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miter limit\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entries \type{htap} and \type{pen} are optional. + +There is helper function (\type{mplib.pen_info(obj)}) that returns +a table containing a bunch of vital characteristics of the used pen +(all values are floats): + +\starttabulate[|l|l|p|] +\NC width \NC number \NC width of the pen\NC \NR +\NC rx \NC number \NC $x$ scale \NC \NR +\NC sx \NC number \NC $xy$ multiplier \NC \NR +\NC sy \NC number \NC $yx$ multiplier \NC \NR +\NC ry \NC number \NC $y$ scale \NC \NR +\NC tx \NC number \NC $x$ offset \NC \NR +\NC ty \NC number \NC $y$ offset \NC \NR +\stoptabulate + +\subsubsection{outline} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\NC pen \NC table \NC knots of the pen \NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC linejoin \NC number \NC line join style (bare number)\NC \NR +\NC miterlimit \NC number \NC miter limit \NC \NR +\NC linecap \NC number \NC line cap style (bare number)\NC \NR +\NC dash \NC table \NC representation of a dash list\NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +The entry \type{dash} is optional. + +\subsubsection{text} + +\starttabulate[|l|l|p|] +\NC text \NC string \NC the text \NC \NR +\NC font \NC string \NC font tfm name \NC \NR +\NC dsize \NC number \NC font size\NC \NR +\NC color \NC table \NC the object's color \NC \NR +\NC width \NC number \NC \NC \NR +\NC height \NC number \NC \NC \NR +\NC depth \NC number \NC \NC \NR +\NC transform \NC table \NC a text transformation \NC \NR +\NC prescript \NC string \NC the prescript text \NC \NR +\NC postscript \NC string \NC the postscript text \NC \NR +\stoptabulate + +\subsubsection{special} + +\starttabulate[|l|l|p|] +\NC prescript \NC string \NC special text \NC \NR +\stoptabulate + +\subsubsection{start_bounds, start_clip} + +\starttabulate[|l|l|p|] +\NC path \NC table \NC the list of knots \NC \NR +\stoptabulate + +\subsubsection{stop_bounds, stop_clip} + +Here are no fields available. + +\subsection{Subsidiary table formats} + +\subsubsection{Paths and pens} + +Paths and pens (that are really just a special type of paths as far as +\MPLIB\ is concerned) are represented by an array where each entry +is a table that represents a knot. + +\starttabulate[|lT|l|p|] +\NC left_type \NC string \NC when present: 'endpoint', but ususally absent \NC \NR +\NC right_type \NC string \NC like \type{left_type}\NC \NR +\NC x_coord \NC number \NC $x$ coordinate of this knot\NC \NR +\NC y_coord \NC number \NC $y$ coordinate of this knot\NC \NR +\NC left_x \NC number \NC $x$ coordinate of the precontrol point of this knot\NC \NR +\NC left_y \NC number \NC $y$ coordinate of the precontrol point of this knot\NC \NR +\NC right_x \NC number \NC $x$ coordinate of the postcontrol point of this knot\NC \NR +\NC right_y \NC number \NC $y$ coordinate of the postcontrol point of this knot\NC \NR +\stoptabulate + +There is one special case: pens that are (possibly transformed) +ellipses have an extra string-valued key \type{type} with value +\type{elliptical} besides the array part containing the knot list. + +\subsubsection{Colors} + +A color is an integer array with 0, 1, 3 or 4 values: + +\starttabulate[|l|l|p|] +\NC 0 \NC marking only \NC no values \NC\NR +\NC 1 \NC greyscale \NC one value in the range (0,1), \quote {black} is 0 \NC\NR +\NC 3 \NC RGB \NC three values in the range (0,1), \quote {black} is 0,0,0 \NC\NR +\NC 4 \NC CMYK \NC four values in the range (0,1), \quote {black} is 0,0,0,1 \NC\NR +\stoptabulate + +If the color model of the internal object was \type{unitialized}, then +it was initialized to the values representing \quote {black} in the colorspace +\type{defaultcolormodel} that was in effect at the time of the \type{shipout}. + +\subsubsection{Transforms} + +Each transform is a six-item array. + +\starttabulate[|l|l|p|] +\NC 1 \NC number \NC represents x \NC\NR +\NC 2 \NC number \NC represents y \NC\NR +\NC 3 \NC number \NC represents xx \NC\NR +\NC 4 \NC number \NC represents yx \NC\NR +\NC 5 \NC number \NC represents xy \NC\NR +\NC 6 \NC number \NC represents yy \NC\NR +\stoptabulate + +Note that the translation (index 1 and 2) comes first. This differs +from the ordering in \POSTSCRIPT, where the translation comes last. + +\subsubsection{Dashes} + +Each \type{dash} is two-item hash, using the same model as \POSTSCRIPT\ +for the representation of the dashlist. \type{dashes} is an array of +\quote {on} and \quote {off}, values, and \type{offset} is the phase of the pattern. + +\starttabulate[|l|l|p|] +\NC dashes \NC hash \NC an array of on-off numbers \NC\NR +\NC offset \NC number \NC the starting offset value \NC\NR +\stoptabulate + +\subsection{Character size information} + +These functions find the size of a glyph in a defined font. The +\type{fontname} is the same name as the argument to \type{infont}; +the \type{char} is a glyph id in the range 0 to 255; the returned +\type{w} is in AFM units. + +\subsubsection{\luatex{mp.char_width}} + +\starttyping +<number> w = mp.char_width(<string> fontname, <number> char) +\stoptyping + +\subsubsection{\luatex{mp.char_height}} + +\starttyping +<number> w = mp.char_height(<string> fontname, <number> char) +\stoptyping + +\subsubsection{\luatex{mp.char_depth}} + +\starttyping +<number> w = mp.char_depth(<string> fontname, <number> char) +\stoptyping + + +\stoptext + + + + + + |