From caf25dfae684ed65214dd09846671e982b2641d0 Mon Sep 17 00:00:00 2001 From: Taco Hoekwater Date: Sun, 16 Jun 2013 16:01:27 +0000 Subject: new metapost release (1.803) documentation files git-svn-id: svn://tug.org/texlive/trunk@30834 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/metapost/base/mpboxes.pdf | Bin 371656 -> 371656 bytes Master/texmf-dist/doc/metapost/base/mpgraph.pdf | Bin 467564 -> 467564 bytes Master/texmf-dist/doc/metapost/base/mpintro.pdf | Bin 235016 -> 234831 bytes Master/texmf-dist/doc/metapost/base/mplibapi.pdf | Bin 243123 -> 277200 bytes Master/texmf-dist/doc/metapost/base/mpman.pdf | Bin 898520 -> 899838 bytes .../doc/metapost/base/source-manual/TODO | 35 +- .../doc/metapost/base/source-manual/mplibapi.tex | 729 +++++++++++++++++---- .../base/source-manual/mpman-app-optab.tex | 2 +- .../doc/metapost/base/source-manual/mpman.tex | 16 +- 9 files changed, 639 insertions(+), 143 deletions(-) diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf index 01f96ce402b..d1d0fcccc7d 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf and b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf differ diff --git a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf index 019931a2783..8be16292908 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf and b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf differ diff --git a/Master/texmf-dist/doc/metapost/base/mpintro.pdf b/Master/texmf-dist/doc/metapost/base/mpintro.pdf index 97ecbd78560..29b6d37175d 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpintro.pdf and b/Master/texmf-dist/doc/metapost/base/mpintro.pdf differ diff --git a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf index 3be7d5703d2..caabad494c1 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf and b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf differ diff --git a/Master/texmf-dist/doc/metapost/base/mpman.pdf b/Master/texmf-dist/doc/metapost/base/mpman.pdf index a5f889d2b7c..cafe45a9eee 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpman.pdf and b/Master/texmf-dist/doc/metapost/base/mpman.pdf differ diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/TODO b/Master/texmf-dist/doc/metapost/base/source-manual/TODO index 5b1a7aec305..0c99309afbc 100644 --- a/Master/texmf-dist/doc/metapost/base/source-manual/TODO +++ b/Master/texmf-dist/doc/metapost/base/source-manual/TODO @@ -31,18 +31,41 @@ mp-implementors list or alternatively the metapost list. *** Wanted For Release *** ***************************** +* Discussion of floating point vs. fixed point numbers: + + + needs complete review of the manual ... + + + description of new command-line option + +* Describe PNG backend. + +* Describe prescriptpart/postscriptpart. + +* Describe envelope primitive/macro. + + + + +***************************** +*** Short term issues *** +***************************** + Integrating Text and Graphics: -* (SH) Fix bad description of prologues in table ivartab. -* (SH) Move discussion of prologues to sec. workflow2. +* Fix bad description of prologues in table ivartab. +* Move discussion of prologues to sec. workflow2. + +Advanced Graphics: +* Describe turningnumber (mention differences in sec. 'MetaPost + Versus METAFONT'). Notes on the MetaPost Workflow: -* (SH) Describe variables jobname, charcode. +* Describe variables jobname, charcode. Reference Manual: * Describe environment variables and configuration files. Legacy Information: -* (SH) Cite original Hobby papers. +* Cite original Hobby papers. @@ -59,7 +82,7 @@ Integrating Text and Graphics: scattered around mpman. * More information and examples on alternatives for calling TeX or LaTeX from within MetaPost. -* (SH) Revise (and add more) flow charts for MetaPost workflow. +* Revise (and add more) flow charts for MetaPost workflow. * Describe whitespace handling of verbatimtex/btex/etex. * Why is verbatimtex\end{document}etex "safer", cf. sec. 13.1? * Discuss difference between "draw withpen" and @@ -67,7 +90,7 @@ Integrating Text and Graphics: Advanced Graphics: * Add a sub-section discussing colours. -* (SH) Colour cars and change code example in section piccomp. +* Colour cars and change code example in section piccomp. Reference Manual: * Describe missing variables, constants, and operators. diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex index a18e5e01fb0..97aa825db1c 100644 --- a/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex @@ -3,6 +3,9 @@ \def\MP{MetaPost} \def\POSTSCRIPT{PostScript} \def\PS{PostScript} +\def\SVG{SVG} +\def\PNG{PNG} +\def\MNG{MNG} \def\TFM{{\sc tfm}} \def\LUA{Lua} @@ -31,9 +34,11 @@ \nonknuthmode -\def\ctypedef#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}} +\defineselector[title][max=2,n=2] + +\def\ctypedef#1#2#3{\subsubsection[#2]{\select{title}{\type{#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}} +\def\cfunction#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1 #2#3}}}\bookmark{#2}} \starttext @@ -41,15 +46,19 @@ \StartTitlePage \centerline{\definedfont[TitleFont at 50pt]{\MPLIB}} \blank[3*line] -\centerline{\definedfont[SubTitleFont at 24pt]{API documentation}} +\centerline{\definedfont[SubTitleFont at 24pt]{API documentation, version 1.800}} \blank[3*line] -\centerline{Taco Hoekwater, July 2008} +\centerline{Taco Hoekwater, September 2012} \StopTitlePage \section{Table of contents} +\setupselector[title][n=1] + \placecontent[criterium=all,level=subsection] +\setupselector[title][n=2] + \page \section{Introduction} @@ -82,7 +91,6 @@ Here is a C language example of how to do this: \starttyping -#include #include "mplib.h" int main (int argc, char **argv) { MP mp; @@ -99,7 +107,8 @@ int main (int argc, char **argv) { } \stoptyping -This example will run in \quote{inimpost} mode. +This example will run in \quote{inimpost} mode. See below for how to +preload a macro package. \subsection{Embedded \MPLIB\ use} @@ -127,7 +136,7 @@ if mp then end \stoptyping -This example loads a previously generated \quote{plain} mem file. +This example preloads the \quote{plain} macro file. \section{C API for core \MPLIB} @@ -143,20 +152,12 @@ This is a structure that contains the configurable parameters for a new \MPLIB\ 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 @@ -177,6 +178,8 @@ those that apply in only one of those cases. \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 +\NC int \NC math_mode \NC 0 \NC set this to \type{mp_math_double_mode} to use doubles + instead of scaled (\type{mp_math_scaled_mode}) values\NC \NR \stoptabulate To create an \type{MP_options} structure, you have to use the \type{mp_options()} function. @@ -186,21 +189,22 @@ To create an \type{MP_options} structure, you have to use the \type{mp_options() 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 +but you should not use any of those directly. All configuration 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 +When the \MPLIB\ instance is not interactive, any output is redirected 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 +\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_stream \NC ship_out \NC holds the exported EPS, SVG or PNG string \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 @@ -209,8 +213,9 @@ 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. +You need to include at least \type{mplibps.h} to be able to actually +make use of this list of images, see the next section for the details +on \type{mp_edge_object} lists. See next paragraph for \type{mp_stream}. @@ -225,7 +230,8 @@ bookkeeping variables. The fields that are of interest to you are: \stoptabulate There is nothing in the stream unless the \type{size} field is -nonzero. There will not be embedded zeroes in \type{data}. +nonzero. There will not be embedded null characters (\type{\0}) +in \type{data} except when \type{ship_out} is used for PNG output. 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 @@ -234,7 +240,7 @@ 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. +pass to \MPLIB\ inside the \type{MP_options} structure. \ctypedef{char * }{(*mp_file_finder)}{ (MP, const char*, const char*, int)} @@ -265,9 +271,9 @@ 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 +The first argument is the input file name. This is the name that was given +in the \MP\ language, so it may not be the same as the name of the actual +file that is being used, depending on how your \type{mp_file_finder} function behaves. The second argument is the requested output name for mpx commands. @@ -283,8 +289,8 @@ The \type{mp_file_finder} receives an \type{int} argument that is one of the fol \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_postscript \NC PostScript or SVG output (w)\NC \NR +\NC mp_filetype_bitmap \NC PNG output (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 @@ -304,6 +310,15 @@ stops and asks the user for input. This initial mode can be overruled by using o \NC mp_error_stop_mode \NC as with \type{errorstopmode} \NC \NR \stoptabulate +\cenumeration{mp_math_mode} + +\starttabulate[|l|p|] +\NC mp_math_scaled_mode \NC uses scaled point data for numerical values \NC \NR +\NC mp_math_double_mode \NC uses IEEE double floating point data for numerical values \NC \NR +\NC mp_math_binary_mode \NC not used yet. \NC \NR +\NC mp_math_decimal_mode \NC not used yet. \NC \NR +\stoptabulate + \cenumeration{mp_history_state} These are set depending on the current state of the interpreter. @@ -330,34 +345,6 @@ Graphical objects always have a color model attached to them. \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. @@ -453,40 +440,457 @@ Returns the current simultaneous macro parameter usage of this instance. Returns the current \type{input} levels of this instance. -\section{C API for graphical backend functions} +\section{C API for path and knot manipulation} -These are all defined in \type{mplibps.h} +\subsection{Enumerations} -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). +\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 \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_number}{} + +Numerical values are represented by opaque structure pointers named \type{mp_number}. \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}. +of structure pointers 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 \NC next \NC the next knot, or NULL\NC \NR +\NC mp_knot_type \NC data.types.left_type \NC the \type{mp_knot_type} for the left side \NC \NR +\NC mp_knot_type \NC data.types.right_type \NC the \type{mp_knot_type} for the right side \NC \NR +\NC mp_number \NC x_coord \NC $x$\NC \NR +\NC mp_number \NC y_coord \NC $y$\NC \NR +\NC mp_number \NC left_x \NC $x$ of the left (incoming) control point\NC \NR +\NC mp_number \NC left_y \NC $y$ of the left (incoming) control point\NC \NR +\NC mp_number \NC right_x \NC $x$ of the right (outgoing) control point\NC \NR +\NC mp_number \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 +Paths are always represented as a circular list. The difference between cyclic and +non-cyclic paths is indicated by their \type{mp_knot_type}. + +While the fields of the knot structure are in fact accessible, it is better to use +the access functions below as the internal structure tends to change. + +\subsection{Functions for accessing knot data} + +\cfunction{mp_number}{mp_knot_x_coord}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the knot. +\cfunction{mp_number}{mp_knot_y_coord}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the knot. +\cfunction{mp_number}{mp_knot_left_x}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the left control point of the knot. +\cfunction{mp_number}{mp_knot_left_y}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the left control point of the knot. +\cfunction{mp_number}{mp_knot_right_x}{(MP mp,mp_knot p)} +Access the $x$ coordinate of the right control point of the knot. +\cfunction{mp_number}{mp_knot_right_y}{(MP mp,mp_knot p)} +Access the $y$ coordinate of the right control point of the knot. +\cfunction{int}{mp_knot_left_type}{(MP mp,mp_knot p)} +Access the type of the knot on the left side. +\cfunction{int}{mp_knot_right_type}{(MP mp,mp_knot p)} +Access the type of the knot on the right side. +\cfunction{mp_knot}{mp_knot_next}{(MP mp,mp_knot p)} +Access the pointer to the next knot. +\cfunction{mp_number}{mp_knot_left_curl}{(MP mp,mp_knot p)} +Access the left curl of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_left_given}{(MP mp,mp_knot p)} +Access the left given value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_left_tension}{(MP mp,mp_knot p)} +Access the left tension of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_curl}{(MP mp,mp_knot p)} +Access the right curl value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_given}{(MP mp,mp_knot p)} +Access the right given value of the knot (applies to unresolved knots, see below). +\cfunction{mp_number}{mp_knot_right_tension}{(MP mp,mp_knot p)} +Access the right tension value of the knot (applies to unresolved knots, see below). + +\cfunction{double}{mp_number_as_double}{(MP mp,mp_number n)} + +Converts an \type{mp_number} to \type{double}. + +\subsection{Functions for creating and modifying knot data} + +\cfunction{mp_knot}{mp_create_knot}{(MP mp)} + +Allocates and returns a new knot. Returns \type{NULL} on (malloc) failure. + +\cfunction{int}{mp_set_knot}{(MP mp,mp_knot p,double x,double y)} + +Fills in the coordinate of knot \type{p}. \type{x1} and \type{y1} values should be +within the proper range for the current numerical mode. +Return 1 on success, 0 on failure. + +\cfunction{int}{mp_close_path}{(MP mp,mp_knot p,mp_knot q)} + +Connects \type{p} and \type{q} using an \quote{endpoint join}, where \type{p} is the last knot +of the path, and \type{q} is the first knot. The right tension of \type{p} and the +left tension of \type{q} are (re)set to the default of 1.0. + +Because all knot list data structures are always circular, this is needed to end the path +properly even if the path is not intended cyclic (or use \type{mp_close_path_cycle()}, +if it is indeed a cycle). +Return 1 on success, 0 on failure. + +\cfunction{int}{mp_close_path_cycle}{(MP mp,mp_knot p,mp_knot q)} + +Connects \type{p} and \type{q} using an \quote{open join}, where \type{p} is the last knot +of the path, and \type{q} is the first knot. The right tension of \type{p} and the +left tension of \type{q} are (re)set to the default of 1.0. + +This is needed to mimic metapost's \type{cycle}. +return 1 on success, 0 on failure. + +\cfunction{mp_knot}{mp_append_knot}{(MP mp,mp_knot p,double x,double y)} + +Appends a knot to previous knot \type{q}, and returns the new knot. +This is a convenience method combining \type{mp_create_knot()}, \type{mp_set_knot()}, and +(if \type{q} is not NULL) \type{mp_close_path_cycle()}. +Returns NULL on failure. + +\cfunction{int}{mp_set_knot_left_curl}{(MP mp,mp_knot q,double value)} + +Sets the left curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_right_curl}{(MP mp,mp_knot q,double value)} + +Sets the right curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_curl}{(MP mp,mp_knot q,double value)} + +Sets the curl value for a knot. +\type{fabs(value)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_curls}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)} + +A convenience method that calls \type{mp_set_knot_curl(mp,p,t1)} and \type{mp_set_knot_curl(mp,q,t2)} +return 1 if both succeed, 0 otherwise. + +\cfunction{int}{mp_set_knot_direction}{(MP mp,mp_knot q,double x,double y)} + +Sets the direction \type{{x,y}} value for a knot. +\type{fabs(x)} and \type{fabs(y)} should be less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_directions}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)} + +A convenience method that calls +\type{mp_set_knot_direction(mp,p,x1,y1)} and \type{mp_set_knot_direction(mp,p,x2,y2)} +return 1 if both succeed, 0 otherwise. + +\cfunction{int}{mp_set_knotpair_tensions}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)} + +Sets the tension specifiers for a pair of connected knots. +\type{fabs(t1)} and \type{fabs(t2)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_left_tension}{(MP mp, mp_knot p, double t1)} + +Set the left tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_right_tension}{(MP mp, mp_knot p, double t1)} + +Set the right tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0 +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knot_left_control}{(MP mp, mp_knot p, double x1, double y1)} +\cfunction{int}{mp_set_knot_right_control}{(MP mp, mp_knot p, double x1, double y1)} + +Sets explicit left or right control for a knot. \type{x1} and \type{y1} values should be +within the proper range for the current numerical mode. +return 1 on success, 0 on failure. + +\cfunction{int}{mp_set_knotpair_controls}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)} + +Sets explicit controls for a knot pair. All four \type{x} and \type{y} values should be +within the proper range for the current numerical mode. +return 1 on success, 0 on failure. + +\cfunction{int}{mp_solve_path}{(MP mp,mp_knot first)} + +Finds explicit controls for the knot list at \type{first}, which +is changed in-situ. Returns 0 if there was any kind of error, in which +case \type{first} is unmodified. There can be quite a set of potential errors, +mostly harmless processing errors. +However, be aware that it is also possible that there are internal mplib +memory allocation errors. A distinction between those can not be made +at the moment. +Return 1 on success, 0 on failure. + +\cfunction{void}{mp_free_path}{(MP mp,mp_knot p)} + +Frees the memory of a path. + +\subsection{Example usage} + +Since the above function list is quite dry and not that easy to grasp, +here are two examples of how to use it. First a simple example +(\type{mp_dump_path()} code is given below). + + +\starttyping +#include +#include +#include +#include "mplib.h" + +int main (int argc, char ** argv) { + MP mp ; + mp_knot p, first, q; + MP_options * opt = mp_options () ; + opt -> command_line = NULL; + opt -> noninteractive = 1 ; + mp = mp_initialize ( opt ) ; + if ( ! mp ) exit ( EXIT_FAILURE ) ; + + /* Equivalent Metapost code: + + path p; + p := (0,0)..(10,10)..(10,-5)..cycle; + + */ + first = p = mp_append_knot(mp,NULL,0,0); + if ( ! p ) exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,10,10); + if ( ! q ) exit ( EXIT_FAILURE ) ; + p = mp_append_knot(mp,q,10,-5); + if ( ! p ) exit ( EXIT_FAILURE ) ; + mp_close_path_cycle(mp, p, first); + /* mp_dump_path(mp, first); */ + if (mp_solve_path(mp, first)) { + /* mp_dump_path(mp, first); */ + } + mp_free_path(mp, first); + mp_finish ( mp ) ; + free(opt); + return 0; +} +\stoptyping + +For some more challenging path input, here is a more elaborate +example of the path processing code: + +\starttyping + /* Equivalent Metapost code: + + path p; + p := (0,0).. + (2,20)-- + (10, 5)..controls (2,2) and (9,4.5).. + (3,10)..tension 3 and atleast 4 .. + (1,14){2,0} .. {0,1}(5,-4); + */ + first = p = mp_append_knot(mp,NULL,0,0); + q = mp_append_knot(mp,p,2,20); + p = mp_append_knot(mp,q,10,5); + if (!mp_set_knotpair_curls(mp, q,p, 1.0, 1.0)) + exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,3,10); + if (!mp_set_knotpair_controls(mp, p,q, 2.0, 2.0, 9.0, 4.5)) + exit ( EXIT_FAILURE ) ; + p = mp_append_knot(mp,q,1,14); + if (!mp_set_knotpair_tensions(mp,q,p, 3.0, -4.0)) + exit ( EXIT_FAILURE ) ; + q = mp_append_knot(mp,p,5,-4); + if (!mp_set_knotpair_directions(mp, p,q, 2.0, 0.0, 0.0, 1.0)) + exit ( EXIT_FAILURE ) ; + + mp_close_path(mp, q, first); + + /* mp_dump_path(mp, first); */ + if (mp_solve_path(mp, first)) { + /* mp_dump_path(mp, first); */ + } + mp_free_path(mp, first); +\stoptyping + +And here is the source code for the \type{mp_dump_path} function, +which produces path output that is similar to Metapost's +\type{tracingchoices} report. + +\starttyping +#include +#include +#include +#include +#include "mplib.h" + +#define ROUNDED_ZERO(v) (fabs((v))<0.00001 ? 0 : (v)) +#define PI 3.1415926535897932384626433832795028841971 +#define RADIANS(a) (mp_number_as_double(mp,(a)) / 16.0) * PI/180.0 + +void mp_dump_path (MP mp, mp_knot h) { + mp_knot p, q; + if (h == NULL) return; + p = h; + do { + q=mp_knot_next(mp,p); + if ( (p==NULL)||(q==NULL) ) { + printf("\n???"); + return; /* this won't happen */ + } + printf ("(%g,%g)", mp_number_as_double(mp,mp_knot_x_coord(mp,p)), + mp_number_as_double(mp,mp_knot_y_coord(mp,p))); + switch (mp_knot_right_type(mp,p)) { + case mp_endpoint: + if ( mp_knot_left_type(mp,p)==mp_open ) printf("{open?}"); + if ( (mp_knot_left_type(mp,q)!=mp_endpoint)||(q!=h) ) + q=NULL; /* force an error */ + goto DONE; + break; + case mp_explicit: + printf ("..controls (%g,%g)", + mp_number_as_double(mp,mp_knot_right_x(mp,p)), + mp_number_as_double(mp,mp_knot_right_y(mp,p))); + printf(" and "); + if ( mp_knot_left_type(mp,q)!=mp_explicit ) { + printf("??"); + } else { + printf ("(%g,%g)",mp_number_as_double(mp,mp_knot_left_x(mp,q)), + mp_number_as_double(mp,mp_knot_left_y(mp,q))); + } + goto DONE; + break; + case mp_open: + if ( (mp_knot_left_type(mp,p)!=mp_explicit) + && + (mp_knot_left_type(mp,p)!=mp_open) ) { + printf("{open?}"); + } + break; + case mp_curl: + case mp_given: + if ( mp_knot_left_type(mp,p)==mp_open ) + printf("??"); + if ( mp_knot_right_type(mp,p)==mp_curl ) { + printf("{curl %g}", mp_number_as_double(mp,mp_knot_right_curl(mp,p))); + } else { + double rad = RADIANS(mp_knot_right_curl(mp,p)); + double n_cos = ROUNDED_ZERO(cos(rad)*4096); + double n_sin = ROUNDED_ZERO(sin(rad)*4096); + printf("{%g,%g}", n_cos, n_sin); + } + break; + } + if ( mp_knot_left_type(mp,q)<=mp_explicit ) { + printf("..control?"); /* can't happen */ + } else if ((mp_number_as_double(mp,mp_knot_right_tension(mp,p))!=(1.0))|| + (mp_number_as_double(mp,mp_knot_left_tension(mp,q)) !=(1.0))) { + printf("..tension "); + if ( mp_number_as_double(mp,mp_knot_right_tension(mp,p))<0.0 ) + printf("atleast "); + printf("%g", fabs(mp_number_as_double(mp,mp_knot_right_tension(mp,p)))); + if (mp_number_as_double(mp,mp_knot_right_tension(mp,p)) != + mp_number_as_double(mp,mp_knot_left_tension(mp,q))) { + printf(" and "); + if (mp_number_as_double(mp,mp_knot_left_tension(mp,q))< 0.0) + printf("atleast "); + printf("%g", fabs(mp_number_as_double(mp,mp_knot_left_tension(mp,q)))); + } + } + DONE: + p=q; + if ( p!=h || mp_knot_left_type(mp,h)!=mp_endpoint) { + printf ("\n .."); + if ( mp_knot_left_type(mp,p) == mp_given ) { + double rad = RADIANS(mp_knot_left_curl(mp,p)); + double n_cos = ROUNDED_ZERO(cos(rad)*4096); + double n_sin = ROUNDED_ZERO(sin(rad)*4096); + printf("{%g,%g}", n_cos, n_sin); + } else if ( mp_knot_left_type(mp,p) ==mp_curl ){ + printf("{curl %g}", mp_number_as_double(mp,mp_knot_left_curl(mp,p))); + } + } + } while (p!=h); + if ( mp_knot_left_type(mp,h)!=mp_endpoint ) + printf("cycle"); + printf (";\n"); +} +\stoptyping + +The above function is much complicated because of all the knot type +cases that can only happen {\it before} \type{mp_solve_path()} is +called. A version that only prints processed paths and is less +scared of using direct field access would be much shorter: + +\starttyping +void mp_dump_solved_path (MP mp, mp_knot h) { + mp_knot p, q; + if (h == NULL) return; + p = h; + do { + q=mp_knot_next(mp,p); + printf ("(%g,%g)..controls (%g,%g) and (%g,%g)", + mp_number_as_double(mp,p->x_coord), + mp_number_as_double(mp,p->y_coord), + mp_number_as_double(mp,p->right_x), + mp_number_as_double(mp,p->right_y), + mp_number_as_double(mp,q->left_x), + mp_number_as_double(mp,q->left_y)); + p=q; + if ( p!=h || h->data.types.left_type!=mp_endpoint) { + printf ("\n .."); + } + } while (p!=h); + if ( h->data.types.left_type!=mp_endpoint ) + printf("cycle"); + printf (";\n"); +} +\stoptyping + +\page +\section{C API for graphical backend functions} +\bookmark{C API for graphical backend functions} + +These are all defined in \type{mplibps.h} + +\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_gr_knot}{} + +These are like \type{mp_knot}, except that all \type{mp_number} values +have been simplified to \type{double}. + \ctypedef {}{mp_color}{} The graphical object that can be colored, have two fields to define @@ -494,10 +898,10 @@ 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 +\NC double \NC a_val \NC see below\NC \NR +\NC double \NC b_val \NC --\NC \NR +\NC double \NC c_val \NC --\NC \NR +\NC double \NC d_val \NC --\NC \NR \stoptabulate All graphical objects that have \type{mp_color} fields also have @@ -517,9 +921,8 @@ the four data fields: 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 +\NC double * \NC array \NC an array of dash lengths, terminated by $-1$.\NC \NR +\NC double \NC offset\NC the dash array offset (as in PostScript) \NC \NR \stoptabulate \ctypedef {}{mp_graphic_object}{} @@ -537,7 +940,7 @@ base line of graphical object types. It has only two fields: \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 +Because every graphical object has at least these two fields, 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}. @@ -557,10 +960,10 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj \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 +\NC mp_gr_knot \NC path_p \NC the (always cyclic) path\NC \NR +\NC mp_gr_knot \NC htap_p \NC a possible reversed path (see below)\NC \NR +\NC mp_gr_knot \NC pen_p \NC a possible pen (see below)\NC \NR +\NC double \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 @@ -573,7 +976,8 @@ involved as well. The final output should behave as follows: 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}. +has already been preprocessed for you: \type{path_p} and \type{htap_p} already incorporate +its shape. \stopitemize \ctypedef {}{mp_stroked_object}{} @@ -588,9 +992,9 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj \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_gr_knot \NC path_p \NC the path \NC \NR +\NC mp_gr_knot \NC pen_p \NC the pen \NC \NR +\NC double \NC miterlim \NC miter limit \NC \NR \NC mp_dash_object * \NC dash_p \NC a possible dash list\NC \NR \stoptabulate @@ -605,16 +1009,16 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj \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 +\NC double \NC font_dsize \NC size of the font\NC \NR +\NC double \NC width \NC width of the picture resulting from the string\NC \NR +\NC double \NC height \NC height\NC \NR +\NC double \NC depth \NC depth\NC \NR +\NC double \NC tx \NC transformation component\NC \NR +\NC double \NC ty \NC transformation component\NC \NR +\NC double \NC txx \NC transformation component\NC \NR +\NC double \NC tyx \NC transformation component\NC \NR +\NC double \NC txy \NC transformation component\NC \NR +\NC double \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 @@ -625,7 +1029,7 @@ size). If text is to be scaled, this happens via the transformation components. 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 +\NC mp_gr_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 @@ -634,7 +1038,7 @@ Contains the following field on top of the ones defined by \type{mp_graphic_obje 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 +\NC mp_gr_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 @@ -662,15 +1066,15 @@ of that figure. 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}; +\NC double \NC minx \NC lower-left $x$ of the bounding box\NC \NR +\NC double \NC miny \NC lower-left $y$ of the bounding box\NC \NR +\NC double \NC maxx \NC upper right $x$ of the bounding box\NC \NR +\NC double \NC maxy \NC upper right $y$ of the bounding box\NC \NR +\NC double \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 double \NC height \NC similar for height (\type{charht})\NC \NR +\NC double \NC depth \NC similar for depth (\type{chardp})\NC \NR +\NC double \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 @@ -681,10 +1085,31 @@ this would become the \TFM\ width (but without the potential rounding correction 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. +\type{mp_rundata} will find the generated text in the \type{ship_out} field. + +Returns zero for success. + +\cfunction{int }{mp_svg_ship_out}{(mp_edge_object*hh,int prologues)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \SVG\ output for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated text in the \type{ship_out} field. + +Returns zero for success. + + +\cfunction{int }{mp_png_ship_out}{(mp_edge_object*hh, char *options)} + +If you have an \type{mp_edge_object}, you can call this function. It will +generate the \PNG\ bitmap for the figure and save it internally. A subsequent call to +\type{mp_rundata} will find the generated data in the \type{ship_out} field. + +Note: the \type{options} structure follows the same syntax as in the Metapost language, +and can be NULL. 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. @@ -783,23 +1208,22 @@ To create a new metapost instance, call mp = mplib.new({...}) \stoptyping -This creates the \type{mp} instance object. The argument hash can have a number of -different fields, as follows: +This creates the \type{mp} instance object. The \type{mp} instance object +always starts out in so|-|called \quote{inimp} mode, there is no +support for preload files. + +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 interaction \NC string \NC the interaction mode, one of \type {batch}, \type {nonstop}, + \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR \NC job_name \NC string \NC \type {--jobname} \NC \type {mpout} \NC\NR +\NC math_mode \NC string \NC the number system mode, one of \type{scaled} or + \type{double} \NC \type {scaled} \NC\NR \NC find_file \NC function \NC a function to find files \NC only local files\NC\NR \stoptabulate @@ -814,7 +1238,7 @@ 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 +\NC type \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR \stoptabulate Return either the full pathname of the found file, or \type{nil} if @@ -828,15 +1252,15 @@ You can request statistics with: 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: +This function returns the allocation statistics for an \MPLIB\ +instance. There are four fields, giving the maximum number of used +items in each of four 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 +\NC memory \NC number \NC allocated memory (in bytes)\NC\NR +\NC hash \NC number \NC hash size (in entries)\NC\NR +\NC params \NC number \NC simultaneous macro parameters\NC\NR +\NC open \NC number \NC input file nesting levels\NC\NR \stoptabulate \subsection{\luatex{mp:execute}} @@ -895,6 +1319,7 @@ object methods you can call: \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 png \NC function \NC return a string that is the png 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 @@ -1091,6 +1516,44 @@ the \type{char} is a glyph id in the range 0 to 255; the returned w = mp.char_depth( fontname, char) \stoptyping +\subsection{Solving path control points} + +\starttyping + success = mp.solve_path(
knots, cyclic) +\stoptyping + +This modifies the \type{knots} table (which should contain an +array of points in a path, with the substructure explained below) +by filling in the control points. The boolean \type{cyclic} is +used to determine whether the path should be the equivalent of +\type{--cycle}. If the return value is \type{false}, there +is an extra return argument containing the error string. + +On entry, the individual knot tables can contain the values +mentioned above (but typically the \type{left_{x,y}} and +\type{right_{x,y}} will be missing). \type{{x,y}_coord} are +both required. Also, some extra values are allowed: +\starttabulate[|lT|l|p|] +\NC left_tension \NC number \NC A tension specifier \NC \NR +\NC right_tension \NC number \NC like \type{left_tension}\NC \NR +\NC left_curl \NC number \NC A curl specifier\NC \NR +\NC right_curl \NC number \NC like \type{left_curl}\NC \NR +\NC direction_x \NC number \NC $x$ displacement of a direction specifier\NC \NR +\NC direction_y \NC number \NC $y$ displacement of a direction specifier\NC \NR +\stoptabulate + +Note the following: +\startitemize +\item A knot has either a direction specifier, or a curl specifier, or a tension specification, + or explicit control points, with the note that tensions, curls and control points are split + in a left and a right side (directions apply to both sides equally). +\item The absolute value of a tension specifier should be more than 0.75 and less than 4096.0, + with negative values indicating \quote{\type{atleast}}. +\item The absolute value of a direction or curl should be less than 4096.0. +\item If a tension, curl, or direction is specified, then existing control points will be + replaced by the newly computed value. +\item Calling \type{solve_path} does not alter the used mplib instance. +\stopitemize \stoptext diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex index baa97fa9009..dd779479d43 100644 --- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex @@ -1,4 +1,4 @@ -\svnInfo $Id: mpman-app-optab.tex 1598 2011-04-05 14:14:16Z taco $ +\svnInfo $Id: mpman-app-optab.tex 1438 2010-10-26 20:08:17Z stephanhennig $ %%% Two notes on column specification: %%% (i) Column widths are manually chosen as small as possible to allow %%% for a wider last X column. diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex index 274c2982ead..a38cb529578 100644 --- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex +++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex @@ -1,4 +1,4 @@ -% $Id: mpman.tex 1599 2011-04-05 14:15:45Z taco $ +% $Id: mpman.tex 1920 2013-06-13 14:21:25Z stephanhennig $ % MetaPost manual, by John Hobby. License at end. \listfiles \RequirePackage{ifpdf} @@ -12,8 +12,8 @@ \fi \documentclass{article} % article is NOT the original style \usepackage[nofancy]{svninfo}% Access VCS information. -\svnInfo $Id: mpman.tex 1599 2011-04-05 14:15:45Z taco $ -\newcommand*{\mpversion}{1.504} +\svnInfo $Id: mpman.tex 1920 2013-06-13 14:21:25Z stephanhennig $ +\newcommand*{\mpversion}{1.503} \usepackage[T1]{fontenc} \usepackage{lmodern} @@ -91,6 +91,16 @@ \begin{titlepage} \vbox to \textheight {% \vskip0pt + \raisebox{0pt}[0pt][0pt]{% + \begin{minipage}{\linewidth} + \emph{The manual currently doesn't cover all recent features of + MetaPost, such as the PNG backend or support for calculations + in different number systems. We'll try to keep up. For more + information, please refer to the + \href{https://foundry.supelec.fr/scm/viewvc.php/trunk/CHANGES?view=markup&revision=1919&root=metapost}{change + log}. Sorry for the inconvenience!} + \end{minipage}% + } \vfil \vfil \vfil -- cgit v1.2.3