summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex
blob: 64332eca3edaeb9de1965ec83c5ac4005343e719 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
% Copyright 2007 by Mark Wibrow
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section[Reimplementing the Computations of the Mathematical Engine]
  {Reimplementing the Computations of the\\ Mathematical Engine}

\label{pgfmath-reimplement}

Perhaps you are not satisfied with the Maclaurin series for
$e^x$. Perhaps you have a fantastically more accurate
and efficient way of calculating the sine or cosine of angles. Perhaps
 you would like the library to interface with a package such as |fp| 
 for fixed-point arithmetic (but note that |fp| is \emph{very} slow).
In these case you will want to replace the current implementations of
the computations done by the mathematical engine by your own code. 

The mathematical engine was designed with such a replacement in
mind. For this reason, the operations and functions like |\pgfmathadd|
are implemented in the following manner: 

\begin{itemize}
\item |\pgfmath|\meta{function name} 

  This macro is the ``public'' interface for the function
  \meta{function name}. All arguments passed to this macro are 
  evaluated using |\pgfmathparse| and then passed on to the following
  function:
  
\item |\pgfmath|\meta{function name}|@|
  
  This macro is the ``non-public'' implementation of the functions 
  algorithm (but note that, for speed, the parser calls this macro 
  rather than the ``public'' one). Arguments passed to this macro 
  are expected to be numbers \emph{without units}. This is the macro 
  which should be rewritten with your prize-winning new algorithm.
	
\end{itemize}

The effect of |\pgfmath|\meta{function name}|@| should be to set the
macro |\pgfmathresult| to the correct value (namely to the result of
the computation without units). Furthermore, the function should have
no other side effects, that is, it should not change any global
values. One way to achieve this is to use the following code:

\begin{codeexample}[code only]
\def\pgfmath...@#1#2...{%
   \begingroup%
      ... code for algorithm XXX ...
      \pgfmath@returnone\pgfmath@x%
   \endgroup%
}
\end{codeexample}


The macro |\pgfmath@returnone<macro>| uses some |\aftergroup| magic to
save result of the algorithm, by defining |\pgfmathresult| as the 
expansion of |<macro>| \emph{without units}. |<macro>| can be a macro
containing a number (with or without units), or a dimension or count
(or possibly a skip) register. By performing the algorithm within a
\TeX{} group, \pgfname{} registers such as |\pgf@x|, |\pgf@y| and 
|\c@pgf@counta|, |\c@pgfcountb|, and so forth can be used at will.
Note that current the implementation uses |\pgfmath@x|, |\pgfmath@y|, 
and |\c@pgfmath@counta|, |\c@pgfmath@countb| throughout, so for 
consistency these should be employed. Whilst they are currently |\let|
to their \pgfname{} equivalents (see |pgfmathutil.code.tex|), this 
could change (as could the \pgfname{} registers), so keeping things
consistent is probably a good idea.