|
|
( for mimeTeX version 1.40 ) Click for: homepage, resume download mimeTeX |
more_examples... |
|
|
( for mimeTeX version 1.40 ) Click for: homepage, resume download mimeTeX |
more_examples... |
| - - T u t o r i a l - - | - - - - - - - - - - R e f e r e n c e - - - - - - - - - - | ||
|
(I) Introduction a. Quick Start b. Syntax Overview c. Examples d. Similar Tools e. Objectives f. GPL License |
(II) Building mimeTeX a. Download b. Compile c. Install d. Compile Options e. Command Line |
(III) Syntax Reference a. Math & White Space b. Symbols & Sizes & Modes c. Delimiters d. Accents & Arrows, etc. e. \begin{array} f. \picture( ){ } g. Other Commands h. Other Exceptions |
(IV) Appendices a. Fonts b. make_raster() c. gifsave.c Remarks |
MimeTeX is licensed under the
gpl.
It parses LaTeX math expressions, emitting either gif images
or mime xbitmaps of them, rather than the usual TeX dvi's.
And mimeTeX is an entirely separate little program that doesn't
use TeX in any way. Therefore, mimeTeX images are easily
inserted directly into html documents using a standard html
<img> tag, e.g.,
<img src="../cgi-bin/mimetex.cgi?f(x)=\int_{-\infty}^xe^{-t^2}dt"
border=0 align=absmiddle>
without intermediate dvi-to-gif conversion, and without storing lots
of little gif image files, one file for each converted expression.
The above example immediately generates the corresponding image, inserting
wherever you put that <img> tag.
This makes your web site and html documents more easily maintained.
Thus, mimeTeX is primarily intended to help you write native html documents containing math. In this sense it's a kind of "lightweight" alternative to MathML, with the advantage that mimeTeX preserves LaTeX syntax, and works with any browser and server. See mimeTeX's Objectives below for further discussion.
As a first example, we can re-display the normal distribution
illustrated above, using exactly the same <img> tag shown, as
. At mimeTeX's next larger font size it looks
like
, with arbitrary mean
and standard deviation
,
and also note the displaymath-style limits.
The remainder of this introductory tutorial section contains
You may now want to browse the additional examples below before proceeding, to make sure mimeTeX suits your needs before you invest more time learning to use it.
Unlike MathML, mimeTeX is as TeX-like as possible, so rather than continue reading you may prefer to just play with it yourself. To try out mimeTeX, just Submit any TeX math expression you like in the query box below. I've started you out with a little example already in the box. And here are just a few quickstart tips for entering your own mimeTeX expressions:
<img src="../cgi-bin/mimetex.cgi?\Large~f(x)=\Bigint_{-\infty}^xe^{-t^2}dt"
border=0 align=absmiddle>
To see numerous additional examples illustrating how to write html
<img> tags using mimeTeX, just view this page's source.
The typical mimeTeX <img> tag has the form
<img src="../cgi-bin/mimetex.cgi?any~valid~LaTeX/mimeTeX~expression"
border=0 align=absmiddle>
where ../cgi-bin/mimetex.cgi is the relative path from your html
page containing these tags to your compiled mimetex.cgi program, and
where any~valid~LaTeX/mimeTeX~expression is pretty much any valid
LaTeX math expression. But there are occasional exceptions where I
couldn't program mimeTeX to precisely mimic LaTeX syntax.
The syntax recognized by mimeTeX is as TeX-like as possible, but not always exactly compatible. This section contains a brief mimeTeX-versus-LaTeX syntax overview. A complete Syntax Reference is in Section III below, and subsection headers of this overview are links into the complete reference. And, to repeat, you may want to browse the additional examples below before proceeding, to make sure mimeTeX suits your needs before you invest more time learning to use it.
Since some browsers occasionally misinterpret typed blank spaces inside html query_string's, I've usually entered, e.g., \alpha~x instead of \alpha x wherever necessary. You may also want to use tildes (a ~) wherever blanks are required or desired, e.g., \frac~xy or \sqrt~z, etc. MimeTeX correctly interprets both ~'s and blanks, and all other usual whitespace characters. So use whatever's convenient as long as you're sure it's correctly interpreted inside query_string's by your browser.
Except inside text boxes, unescaped blanks, tildes (a ~), and all other usual whitespace characters are completely ignored by mimeTeX, just like they are in LaTeX math mode. As usual, you must explicitly write one of the recognized math spaces to put extra visible space in your rendered expressions.
MimeTeX supports math spaces \, \: \; as well as
\/ and \quad and \qquad and
(a \ followed by a blank).
You may also write \hspace{10} to insert a 10-pixel
(or any other number) space. There are no negative spaces.
MimeTeX has no \choose, but \left({n\atop~k}\right)
produces for binomial coefficients. And to help
shorten html query_string's required for more complicated expressions,
mimeTeX lets you abbreviate \left(...\right) as
\(...\) , so that \({n\atop~k}\)
renders the same binomial coefficient.
| Likewise, | \[...\] | are mimeTeX abbreviations for the corresponding LaTeX delimiters, i.e., you may write either \left(...\right) or its mimeTeX abbreviation \(...\), and ditto for these others. Note that \<...\> abbreviates \left\langle...\right\rangle , and \{...\} abbreviates \left\{...\right\} . | |
| \<...\> | |||
| \{...\} | |||
| \|...\| | |||
| And similarly, | \. | abbreviates either \left. or \right. | |
| and | \=...\= | is the mimeTeX abbreviation for LaTeX \left\|...\right\| |
As usual, unescaped {...}'s group subexpressions and aren't displayed at all. But escaped \{...\}'s are interpreted as abbreviations and therefore always sized to fit. If you need displayed but unsized {...}'s, write \lbrace...\rbrace for this purpose.
The usual LaTeX \right. may also be paired with any of the
automatically sized delimiters in mimeTeX, and it may optionally be
abbreviated as \. The same \. also serves
as an abbreviation for \left. MimeTeX correctly
interprets your intention if you correctly balance delimiters. For
example, either y=\left\{{this\atop~that}\right.
or y=\{{this\atop~that}\. renders the usual useful
construction
\atop works for two items only. MimeTeX also provides \begin{array}{lcr}a&b&c\\d&e&f\\etc\end{array} for vectors and matrices, to align equations, etc, all in the usual way. Solid \hline's (but not \cline's) and vertical l|c|r bars are available. And for dashed lines and bars, \hdash and l.c.r are also provided. The precise array syntax is a little more complicated, but the preceding "prototype" should help get you started. For example,
Besides \begin{array}, mimeTeX also tries to emulate the familiar LaTeX picture environment, as illustrated by Examples 12-13 below. MimeTeX's \picture implementation is somewhat less compatible with LaTeX's picture environment than \begin{array}, summarized above. Please see picture reference for detailed documentation, which is difficult to summarize here in a few words.
MimeTeX has many additional LaTeX-like features not mentioned in this brief overview, as well as various shortcomings, "gotchas" and differences vis-a-vis LaTeX. These should all be discussed, or at least mentioned, in the Syntax Reference section. And many are illustrated by the examples immediately below.
One particular "gotcha" to be aware of is that mimeTeX bindings are pretty much left-to-right. That is, although mimeTeX correctly interprets \frac12 as well as \frac1{x^2}, etc, the legal LaTeX expression x^\frac12 must be written x^{\frac12}. Otherwise, mimeTeX interprets it as {x^\frac}12, i.e., the same way x^\alpha12 would be interpreted, which is nonsense for \frac. The same "gotcha" also applies to other combinations of commands, e.g., you must write \sqrt{\frac\alpha\beta}, etc.
The Syntax Reference section contains much additional information. Or you can just begin playing with mimeTeX for yourself to see if it might have any potential usefulness for you, either now or maybe when more fully developed. Have fun!
Here are various additional random examples further demonstrating mimeTeX's features and usage (view the page source to see how they're done)...
| (1) |
| |
| (2) |
|
|
| (3) |
|
|
| (4) |
|
solution for quadratic |
| (5) |
|
demonstrating \frac{}{} for continued fraction |
| (6) |
|
for \left\{...\right. we may write \{...\. and note the accents |
| (7) |
|
\overbrace{}^{} and \underbrace{}_{} (TeXbook page 181, Exercise 18.41) |
| (8) |
|
|
| (9) |
|
demonstrating \begin{array}'s dashed lines |
| (10) |
|
using \begin{eqnarray} to align equations |
| (11) |
|
commutative diagram using \begin{array} |
| (12) |
|
mimeTeX \picture(size){pic_elems} "environment", illustrating the image charge - q for a grounded conducting sphere of radius a with a charge q at distance r > a outside it. |
| (13) |
|
\picture "environment"
illustrating the surface polarization charge induced by a uniform
electric field. Inside the slab of material, the volume polarization
charge clearly vanishes. The little |
Finally, illustrated below are some examples of the fonts and symbols available with mimeTeX. All symbols and sizes from cmr, cmmi. cmsy, cmex and rsfs should be available, but they're not all shown. Also not shown are various "constructed symbols" like \sqrt, accents, etc.
Several non-MathML solutions besides mimeTeX that also embed TeX-like math into html are discussed in the tex-faq, and at www.tug.org/interest.html. Two that you may want to look at are textogif and gladTeX. Both require separate setup procedures that use TeX to help generate external gif (or png) images of your equations, which are later included in your html document as it's being rendered.
MimeTeX, as far as I know, is the only such non-MathML package that has its own built-in parser and rendering engine, entirely independent of TeX, and therefore requires no setup procedure or external images whatsoever. It renders realtime, on-the-fly images directly from your LaTeX math embedded in html documents. This makes your html source documents more readable and easily maintained. Other packages may be modifiable to work as easily, or mimeTeX's ease-of-use features may not prove compelling. In any case, mimeTeX becomes one more available tool in your toolbox.
Although MathML is primarily intended for automated generation, widespread use of other markups by html/xml authors will eventually dilute the population of LaTeX-aware users. LaTeX is more than "TeX The Program"; LaTeX is its syntax. Knuth produced a test suite that validates any program claiming to be TeX, so no one version of the code is crucial. It's the syntax that's crucial. LaTeX will survive so long as a significant user population continues to use its syntax.
MathML and other markups pose a threat to the future of LaTeX's syntax in the large and growing html/xml market, so it's important to provide some LaTeX-compliant alternative. MimeTeX is meant to be a prototype alternative. It's probably too small and kludgey for a final solution. But it demonstrates feasibility, and is full-featured enough to measure potential interest in LaTeX-compliant alternatives to MathML.
Such alternatives provide a choice to new users, who will hopefully conclude that LaTeX is the easier and more intuitive syntax. And old users can continue using LaTeX syntax when they have to prepare native html/xml documents, i.e., when it's not adequate to run latex2html against native LaTeX documents.
MimeTeX's copyright is registered by me with the US Copyright Office, and I hereby license it to you under the terms and conditions of the GPL. There is no official support of any kind whatsoever, and you use mimeTeX entirely at your own risk, with no guarantee of any kind, in particular with no warranty of merchantability.
By using mimeTeX, you warrant that you have read, understood and agreed to these terms and conditions, and that you are at least 18 years of age and possess the legal right and ability to enter into this agreement and to use mimeTeX in accordance with it.
Hopefully, the law and ethics regarding computer programs will evolve to make this kind of obnoxious banter unnecessary. In the meantime, please forgive me my paranoia.
I've built and run mimeTeX under Linux and NetBSD using gcc. The source code is entirely ansi-standard C, and should compile and execute under all environments without any change whatsoever. Build instructions below are for Unix. Modify them as necessary for your particular situation.
A brief summary of the steps needed to build mimeTeX is
Download mimetex.zip and unzip it in any convenient working directory. Your working directory should now contain
| README | mimeTeX release notes |
| LICENSE | GPL license, under which you may use mimeTeX |
| mimetex.c | mimeTeX source program and all required functions |
| mimetex.h | header file for mimetex.c (and for gfuntype.c) |
| gfuntype.c | parses output from gftype -i and writes bitmap data |
| texfonts.h | output from several gfuntype runs, needed by mimetex.c |
| gifsave.c | gif library by Sverre H. Huseby http://shh.thathost.com |
| mimetex.html | this file, mimeTeX tutorial and user's manual |
To compile a mimeTeX executable that emits anti-aliased gif images (which is how the "official" mimetex.html page is displayed) issue the command
Or, for an executable that emits gif images without anti-aliasing, issue the command
Alternatively, to compile a mimeTeX executable that emits mime xbitmaps, just issue the command
Several other compile-line options available for mimetex.c are discussed below.
The gfuntype program is only needed if you plan to change the font information in texfonts.h, as explained in Appendix IVa below. In that case, compile gfuntype with the command
That's all there is to building mimeTeX.
You can now test mimetex.cgi from the Unix command line by typing,
e.g., ./mimetex.cgi x^2+y^2 which should emit an ascii raster
something like the left-hand illustration. And if you've compiled
mimeTeX with the anti-aliasing option -DAA,
then you'll also see the right-hand illustration.
It shows asterisks in the same positions as the left-hand illustration,
and anti-aliased grayscale colormap indexes assigned to neighboring
pixels; and you're also shown the actual rgb value for each index.
Ascii dump of bitmap image... Hex dump of colormap indexes...
...........**....................**... ..........1**1...................1**1..
..........*..*......*...........*..*.. ..........*23*......*............*23*..
.............*......*..............*.. .............*......*...............*..
....****.....*......*.....*..*.....*.. ...1****....2*......*.....2*..*....2*..
...*.*.*....*.......*....**..*....*... ...*.*.*...1*.......*.....**..*...1*...
.....*.....*.*..********..*..*...*.*.. ....1*1...2*.*..********..3*..*..2*.*..
.....*....****......*.....*..*..****.. ....2*2...****......*......*12*..****..
..*.*.*.............*.....*.*......... ..*.*.*.............*......*.*2........
...****.............*.....***......... ..1****.............*......***.........
....................*.......*......... ....................*........*.........
.........................*.*.......... ..........................*.*1.........
.........................**........... ..........................**1..........
The 5 colormap indexes denote rgb vals...
.-->255 1-->196 2-->186 3-->177 *-->0
If you get much fancier than x^2+y^2, just remember that many
characters have to be escaped from the Unix command line, e.g.,
x\<y, or f\(x\)=x^2, etc. Of course, you won't need
these extra escapes later, when mimetex.cgi runs from a browser.
And mimeTeX knows when you run it from a browser, automatically emitting
an xbitmap (if compiled with -DXBITMAP) or a gif (if compiled with -DGIF)
rather than the human-viewable ascii image illustrated above.
Once mimetex.cgi is working (and you're done playing with it), mv it to your server's cgi-bin/ directory (where cgi programs are expected), and chmod/chown it if necessary. Then mv mimetex.html to your server's htdocs/ directory. Now point your browser to www.yourdomain.com/mimetex.html , and it should be rendered exactly like my identical page at www.forkosh.com/mimetex.html .
One "gotcha": the two directories are typically of the form somewhere/www/cgi-bin/ and somewhere/www/htdocs/ , so I set up mimtex.html to get mimetex.cgi from the relative path ../cgi-bin/ . If your directories are non-conforming, you may have to edit the few dozen occurrences of ../cgi-bin/mimetex.cgi in mimetex.html . Sometimes a suitable symlink works; if not, you'll have to edit.
Either way, once mimetex.html displays properly, you can begin authoring html documents, using mimetex.cgi to render your math.
In addition to either -DXBITMAP or -DGIF on the compile line for mimetex.c, you may optionally include any or all of the following -D switches, whose functionality is discussed below.
Turns on anti-aliasing with default values for individual anti-aliasing parameters discussed below. If you specify -DAA then you needn't specify individual parameters unless you wish to override these defaults (conversely, if you do specify any individual parameter, then you needn't specify -DAA).
Note that anti-aliasing cannot be applied to mime xbitmaps, so if you do specify -DXBITMAP then don't specify -DAA.
And mimeTeX's anti-aliasing only works well on white (or light gray) backgrounds. Your html file probably contains a <body> tag of the form <body bgcolor="#ffffff" text="#000000"> which specifies black text on a pure white background. The background can be grayed down to maybe bgcolor="#e7e7e7", but much darker will begin to show white rings around mimeTeX's anti-aliased characters. This page is displayed using bgcolor="#f7f7f7".
At the present time, mimeTeX only provides a lowpass filtering algorithm for anti-aliasing, which is applied to the existing set of bitmap fonts. I'd eventually like to implement super-sampling on a larger set of fonts, or to use some other more effective procedure. Recommendations are solicited if you're familiar with text anti-aliasing, TeX fonts, etc.
MimeTeX's lowpass filter applies weights
to adjacent pixels, and CENTERWT
(whose default value is 10) to the center pixel of a nine-pixel
average.
I've modified the "canonical" lowpass algorithm, so that if the center pixel is black, then the anti-aliased value remains completely black regardless of adjacent pixels/weights. The intent is to prevent thin lines, typical for text, from getting washed out.
As a result, anti-aliased lines can only become heavier than they started. A low CENTERWT value will blur/spread out lines without washing out their centers. A high CENTERWT value will sharpen lines. Experimentation is recommended to determine what value works best for you (the "official" mimetex.html page, which you're probably viewing, is displayed using -DAA with default CENTERWT).
Besides CENTERWT, mimeTeX's lowpass algorithm differs from the "canonical" one in that the weighted grayscale value calculated for a pixel is applied to it _only_ if the summed weights of adjacent black pixels is greater than or equal to MINADJACENT (default 6); or, as above, originally black pixels remain black. That is, an originally white pixel remains white if the summed weights of adjacent black pixels is less than MINADJACENT.
As above, an originally white pixel remains white if the summed weights of adjacent black pixels is greater than MAXADJACENT (default 8). Note that default MINADJACENT=6 and MAXADJACENT=8 apply lowpass anti-aliasing only to originally white pixels surrounded by adjacent black pixels whose summed weights are between 6 and 8, inclusive. Experimentation with these two parameters is also recommended.
MimeTeX currently has six font sizes numbered 0-5, and always starts out in NORMALSIZE, whose default value is 2. Specify -DNORMALSIZE=3 on the compile line if you prefer mimeTeX to start in default size 3, etc.
Blocks mimeTeX requests from domains that may be using your mimetex.cgi (hence your server's resources) without permission. If REFERER is defined, mimeTeX looks for the environment variable HTTP_REFERER, and if found, performs a case-insensitive test to make sure HTTP_REFERER contains the authorized 'domain' as a substring. If given several 'domain's (second form) then HTTP_REFERER must contain either 'domain1' or 'domain2', or etc, as a (case-insensitive) substring.
If HTTP_REFERER fails to contain a substring matching any of these domain(s), mimeTeX emits an error message image. You may manually modify invalid_referer_msg, defined in function main(), to personalize the error message for your own site.
Note: if HTTP_REFERER is not found as an environment variable, mimeTeX correctly generates the requested expression rather than generating an error.
If an expression submitted to mimeTeX contains an unrecognzied escape sequence, e.g., "y=x+\abc+1", then mimeTeX generates a gif image containing an embedded warning in the form "y=x+[\abc?]+1". Or, if an expression contains an unrecognized character, i.e., one for which mimeTeX has no corresponding bitmap, then the embedded warning is [?]. If you want these warnings suppressed, either -DWARNINGS=0 or -DNOWARNINGS on the compile line tells mimeTeX to treat unrecognized/undisplayable input as white space.
MimeTeX usually runs from a browser, obtaining its input expression from a query_string. But you can also run mimeTeX from your Unix shell, supplying all input from the command line. This was briefly illustrated above, where you were advised to test your newly-compiled mimeTeX executable from the command line before installing it.
In addition to such simple testing, mimeTeX also provides some
possibly useful functionality from the command line. In particular,
you can store a gif (or xbitmap) image of any expression to a file.
The complete command-line syntax for mimeTeX is
./mimetex [ -d ] dump gif image to stdout
[ expression expression, e.g., x^2+y^2,
| -f input_file ] or read expression from file
[ -m msglevel ] verbosity of debugging output
[ -s fontsize ] default fontsize, 0-5
-d Rather than printing ascii debugging output, mimeTeX
dumps the actual gif (or xbitmap) to stdout, e.g.,
./mimetex -d x^2+y^2 > expression.gif
creates expression.gif containing an image of x^2+y^2
expression Place LaTeX expression directly on command
line, with no -switch preceding it, as in the example
immediately above, or...
-f Read expression from input_file (and automatically
assume -d switch). The input_file may contain the
expression on one line or spread out over many lines.
MimeTeX will concatanate all lines from input_file
to construct one long expression. Blanks, tabs, and
newlines are just ignored.
-m 0-99, controls verbosity level for debugging output
(usually used only while testing code).
-s 0-5, font size. As usual, the font size can
also be specified within the expression by a leading
preamble terminated by $, e.g., 3$f(x)=x^2 displays
f(x)=x^2 at font size 3, overriding -s. Default font
size is 2.
Since mimeTeX's syntax is as TeX-like as possible, we'll mostly discuss the occasional exceptions, which exist only to simplify my programming task, not to impose any syntactic aesthetics of mine on you. This section consists of short paragraphs that each discuss some aspect of mimeTeX where your LaTeX experience might not be precisely relevant.
Anything not discussed here that still doesn't behave like you expect is probably just not implemented. You may want to re-browse the quick-start tutorial above, which reviews information in this section, and contains some additional examples that may better illustrate implemented features. And you can also try out anything by submitting a query or from the command line, to quickly see whether or not it works.
Lengths in mimeTeX are all ultimately expressed in number of pixels. Several commands discussed below, including
and others, take length arguments (longarrow [ ]-arguments are optional mimeTeX extensions to LaTeX). MimeTeX's length-type arguments never take units, e.g., {10pt} and {1cm} are both invalid. Lengths always refer to number of pixels, optionally scaled by a user-specified \unitlength.MimeTeX's \unitlength{ } command lets you specify the number of pixels per "length unit", e.g., \unitlength{10}~\hspace{2.5} renders a 25-pixel space. Both \unitlength{ } and \hspace{ }'s length arguments may be integers or may contain decimal points. Ditto for all other mimeTeX commands that take length arguments. The default \unitlength is, you guessed it, 1.
A specified \unitlength applies to all subsequent terms, i.e., everything to its right. And several \unitlength's may be specified in the same expression, each one overriding those to its left. But if one or more \unitlength's appear within a { }-enclosed subexpression, then terms following its closing right } revert to the \unitlength in effect before its opening left {. For example,
Except inside text boxes, unescaped blanks, tildes (a ~), and all other usual whitespace characters are completely ignored by mimeTeX, just like they are in LaTeX math mode. As usual, you must explicitly write one of the recognized math spaces to put extra visible space in your rendered expressions.
MimeTeX supports math spaces \, \: \; as well as \/ and \quad and \qquad . You may also write \hspace{10} to insert a 10-pixel (or any other number) space, scaled by any preceding \unitlength, as illustrated just above. There are no negative spaces.
Although some browsers occasionally misinterpret typed blank spaces
inside html query_string's, mimeTeX also recognizes escaped blanks
(a \ followed by a blank) as math
spaces, just in case you can safely use them.
MimeTeX also supports \hfill{textwidth}, where textwidth is roughly equivalent to LaTeX's \textwidth, i.e., it's the total number of pixels, scaled by \unitlength, that your entire rendered expression will span. However, if \hfill{ } appears within a { }-enclosed subexpression, then it applies only to that subexpression. For example,
Finally, though not precisely belonging in the math space category, mimeTeX begins a new line when you write \\ . And you may optionally write \\[10] to put a 10-pixel, or any other number, vertical space, scaled by \unitlength, between lines. \array can be used to split long equations over several lines, as suggested by Example 10 above. But when that's not the best solution, you might write, for example,
Since some browsers occasionally misinterpret typed blank spaces inside html query_string's, I've usually entered, e.g., \alpha~x instead of \alpha x wherever necessary. You may also want to use tildes (a ~) wherever blanks are required or desired, e.g., \frac~xy or \sqrt~z, etc. MimeTeX correctly interprets both ~'s and blanks, and all other usual whitespace characters. So use whatever's convenient as long as you're sure it's correctly interpreted inside query_string's by your browser.
Some browsers also occasionally misinterpret linebreaks/newlines
inside the middle of long html query_string's. For example,
<img src="../cgi-bin/mimetex.cgi?f(x)=\frac1{\sigma\sqrt{2\pi}}
\bigint_{-\infty}^xe^{-\frac{(t-\mu)^2}{2\sig^2}}dt"
border=0 align=absmiddle>
breaks a long query_string over two lines. If your browser interprets
this correctly, then mimeTeX will render it correctly, too. Otherwise,
you'll have to enter long expressions on one big long line.
If you can break long query_string's over several lines, then you may
find mimeTeX's %%comments%% feature useful, too. Note that
comments must be preceded and followed by two %'s
rather than LaTeX's usual one. The above example could be
written
<img src="../cgi-bin/mimetex.cgi?f(x)=\frac1{\sigma\sqrt{2\pi}} %%normalization%%
\bigint_{-\infty}^xe^{-\frac{(t-\mu)^2}{2\sig^2}}dt %%integral%%"
border=0 align=absmiddle>
Besides whitespace, browsers may misinterpret embedded apostrophes, and especially quotes, within query strings. The a's and b's in Example 7 above actually use superscripted commas for apostrophes, i.e., a^,s and b^,s, and you can also use LaTeX \prime's, as in a^\prime~s. For quotes, you can use ^{,,} since " almost certainly won't work. Or, to help make things easier, in addition to the usual LaTeX \prime, mimeTeX recognizes \apostrophe and \quote and \percent, all with the obvious meanings.
For complete information about the characters and math symbols available in mimeTeX, you'll need to browse through the bottom 500-or-so lines of mimetex.h. And a few additional symbols like \ldots and \AA are defined by the mimeTeX preprocessor, function mimeprep( ) in mimetex.c Generally speaking, I've tried to encode the cmmi10, cmsy10, cmr10, cmex10 and rsfs10 families with "names", e.g., \alpha \beta \forall \sqcup, etc, identical to your LaTeX expectations. But there are various additions and omissions and exceptions vis-a-vis LaTeX. Two of these are:
In addition to several LaTeX symbols like \ldots and \AA, mentioned above, the mimeTeX preprocessor mimeprep( ) also recognizes various html special characters like <, >, , ", &, etc. Some web tools apparently translate characters like, e.g., > to >, even inside query_string's, so mimeTeX's preprocessor translates them back to LaTeX symbols for you.
MimeTeX currently has six font sizes, numbered 0-5, with default 2. The usual LaTeX declarations \tiny, \small, \normalsize (default), \large, \Large and \LARGE, placed anywhere in a mimeTeX expression, change font size at that point. And, as usual, a font size change inside a { }-subexpression remains in effect only within that subexpression.
In mimeTeX you may also write \fs{0},...,\fs{5} for \tiny,...,\LARGE. And since these arguments are all single digits, the even shorter form \fs0,...,\fs5 works equally well. For example,
| <img src="../cgi-bin/mimetex.cgi?f(x)=x^2"> | produces | |
| <img src="../cgi-bin/mimetex.cgi?\large~f(x)=x^2"> | |
|
| <img src="../cgi-bin/mimetex.cgi?\fs4f(x)=x^2"> | |
You'll soon notice that exponents and \frac's and \atop's are automatically rendered one size smaller than their base expressions. For example,
Explicit size declarations override mimeTeX's default sizing behavior. You can rewrite the preceding example as, say,
Preceding an \fs{ } size argument with + or
- specifies "relative" sizing. For example,
\fs3\text{abc{\fs{-2}def}ghi} produces
, rendering the "def"
in font size 1. Note that \fs{-2} affects only the
subexpression in which it appears, and that its braces
are no longer optional since -2 contains two characters.
For exponents (or any other size-changing commands like \frac),
MimeTeX is always in a math-like mode, so never surround your expressions with $'s. In fact, mimeTeX uses $'s to denote "preamble" terminators, e.g., see \array below.
Displaymath is automatically applied to all \bigxxx and \Bigxxx operators, e.g., super/subscripts are placed directly above/below \bigsum and \Bigsum, but "alongside" \sum. For example,
As usual, \nolimits turns displaymath off for the operator immediately preceding it. For example,
Also, \limits affects _any_ character or subexpression immediately preceding it. For example,
\limits or \nolimits at the very beginning of an expression (or of a { }-enclosed subexpression) affects _all_ super/subscripts within that expression (or subexpression), except for character classes Ordinary and Variable (TeXbook page 154). For example,
Finally, mimeTeX also has a text-like/roman mode entered by writing either \text{anything~at~all} or the equivalent LaTeX-2.09-like command {\rm~anything~at~all}, both of which render anything~at~all in roman (font family cmr10). \mbox{ } is recognized as a synonym for \text{ }. For italic, write \textit{anything~at~all} or {\it~anything~at~all}, both of which render anything~at~all in italic (font family cmmi10). All four forms respect spaces between words, except that the first/required ~ space after {\rm~etc} and {\it~etc} is still ignored. For example,
LaTeX's \left( and \right) may be written exactly like that, or may be abbreviated \( and \) in mimeTeX. Not all \left and \right LaTeX delimiters are currently available in mimeTeX, but those that are can be written in the usual way, or can be abbreviated as described above. The one exception is that \left\|...\right\| must instead be abbreviated \=...\= or can be written in full \left\|...\right\| as usual. The complete list of automatically sized delimiters available in mimeTeX is
| LaTeX or mimeTeX |
or mimeTeX abbreviation |
example... | ...renders |
| \left( ... \right) | \( ... \) | \(\frac1{1-x^2}\)^2 | |
| \left[ ... \right] | \[ ... \] | \[1+\frac~xn\]^n | |
| \left\{ ... \right\} | \{ ... \} | \{1^2,2^2,3^2,\ldots\} | |
| \left\langle ... \right\rangle | \< ... \> | \<\varphi|\hat~H|\phi\> | |
| \left| ... \right| | \| ... \| | \det\|\array{1&2\\3&4}\| | |
| \left\| ... \right\| | \= ... \= | \=x^2-y^2\= | |
| \left\{ ... \right. | \{ ... \. | y=\{{\rm~this\atop\rm~that}\. | |
| \left. ... \right\} | \. ... \} | \.{\rm~this\atop\rm~that}\}=y | |
Unescaped ( )'s and [ ]'s and | |'s and < >'s don't need to be balanced since mimeTeX just displays them like ordinary characters without any special significance. Ditto for the usual four \big( and \Big( and \bigg( and \Bigg(, and for their four right ) counterparts, which just display (...)'s at fixed larger sizes, and also have no special significance. All four big [ ]'s and < >'s and { }'s are also available as ordinary characters.
As usual, unescaped {...}'s aren't displayed at all, must be balanced, and have the usual special LaTeX significance. MimeTeX interprets escaped \{...\}'s as abbreviations for \left\{...\right\} and therefore always sizes them to fit. If you need displayed but unsized {...}'s, write \lbrace...\rbrace or any of the four \big{...\big}'s.
\vec{} \hat{} \bar{} \tilde{} \dot{} and \ddot{} are the only accents currently supported, and they're all "wide". You can write \widehat{} if you like, but there's absolutely no difference either way. \bar{} and \overline{} are identical.
All 32 usual LaTeX function names \arccos,...,\tanh are recognized by mimeTeX and treated in the usual way. MimeTeX also recognizes \tr for the trace. And those functions that normally take "limits" also behave as expected, e.g.,
All mimeTeX \long and \Long arrows take an optional [width] argument
that explicitly sets the arrow's width in pixels, scaled by
\unitlength. For example,
\longrightarrow[50] draws a 50-pixel wide arrow
, whereas just \longrightarrow calculates
a default width
, as usual. And, in addition to the usual
right, left and leftright arrows, there are also \long (and \Long) up,
down and updown arrows that take an optional [height] argument, also
scaled by any preceding \unitlength.
In the event that you actually want to place an []-enclosed expression
immediately following an "unsized" long arrow, just place a ~
space after the arrow, e.g., f:x\longrightarrow~[0,1] produces
. Without the intervening ~ space,
mimeTeX would have "eaten" the [0,1].
Super/subscripts immediately following all long/Long left/right arrows are displayed the same way \limits displays them, e.g.,
Super/subscripts immediately following all long/Long up/down arrows are treated correspondingly, i.e., superscripts are vertically centered to the arrow's left, and subscripts to its right. For example,
The \raisebox{height}{expression} and \rotatebox{angle}{expression} commands help you fine-tune and manipulate mimeTeX renderings. The height argument is number of pixels, scaled by \unitlength, and can be positive or negative. The angle argument is number of degrees, and can also be positive (for clockwise) or negative, but must be a multiple of 90. Finally, the expression can be any valid LaTeX/mimeTeX expression. For example, mimeTeX's preprocessor defines the LaTeX ?` symbol, an upside-down question mark, like
\ga displays \gamma, but just \g displays \gg (>>). That is, mimeTeX selects the shortest symbol or command which begins with whatever you type. This feature can help shorten an otherwise very long line, but it may be a bit dangerous.
The mimeTeX preprocessor, briefly mentioned above, is responsible for recognizing several LaTeX symbols like \ldots and several commands like \atop . These symbols and commands cannot be abbreviated. The special html characters like are also recognized by the preprocessor and cannot be abbreviated.
Rendering vectors and matrices, aligning equations, etc, is all done in the customary LaTeX way using \begin{array}{lcr}a&b&c\\d&e&f\\etc\end{array}, which you may write exactly like that. Or you may alternatively write the mimeTeX abbreviation \array{lcr$a&b&c\\d&e&f\\etc} for exactly the same effect. To facilitate aligning equations, \begin{eqnarray}a&b&c\\d&e&f\\etc\end{eqnarray} is also available, though it's simply an "alias" for \array{rcl$a&b&c\\d&e&f\\etc}. Internally, mimeTeX only recognizes this abbreviated \array{ } form, providing the others for LaTeX compatibility, and first rearranging them into the \array{ } form in the obvious way. We'll therefore primarily discuss \array{ }, mentioning the others only when the rearrangement isn't so obvious.
There's a built-in maximum of 32 columns and 32 rows.
\array{ }'s lcr$ "preamble" is optional. That is, it's okay to write \array{a&b&c...\\d&e&f...\\etc...} without the leading lcr...$. If absent, the (maximum) number of columns is determined automatically, and they're all centered by default. For \begin{eqnarray}...\end{eqnarray}, no explicit {lcr} argument is permitted, and rcl column alignment is assumed. For \begin{array}{lcr}...\end{array}, the {lcr} argument is optional, with all columns centered if it's not supplied. (Note that if you don't supply {lcr}, then the first non-white character following \begin{array} must not be {, or else mimeTeX will take it as introducing {lcr} rather than as the beginning of your first row.) \begin{matrix} and \begin{tabular} are both recognized as synonyms for \begin{array}. For example,
Solid \hline's (but not \cline's) and vertical l|c|r bars are available, as usual. For dashed lines and bars, \array{ } provides the additional features \hdash and l.c.r . \hline and \hdash may not be abbreviated. For example,
The default font size is unchanged by \array{ }, but you can explicitly control it in the usual way, e.g., {\large\array{...}} renders the entire array in font size 3. In addition to this "global" font size control, any &...& cell may contain font size declarations which are always local to that cell, e.g., &\fs{-1}...& renders that one cell one font size smaller than current.
\array{ }'s lcr$ "preamble" sets left,center,right
"horizontal justification" down columns of an array, as usual.
And "vertical justification" across rows defaults to
what we'll call baseline, i.e., aligned equations,
as in Example 10 above, display properly.
But the down arrows (for
and for
) in Example 11
require vertical centering across the middle row of that
array. So, in addition to lowercase lcr, mimeTeX's
\array{ } "preamble" may contain uppercase BC
to set baseline or center vertical justification across
the corresponding rows. For example, \array{rccclBCB$etc}
sets baseline justification for the first and third rows, and center
justification for the second row. With no BC's in the preamble,
all rows default to the usual B baseline justification.
See Examples 8-11 above for several \array{ } applications.
Besides \array{ }, mimeTeX also tries to emulate the
familiar LaTeX picture environment with the similar
\picture(width[,height]){(loc1){pic_elem1}(loc2){pic_elem2}...}
as illustrated by Examples 12-13 above.
Arguments surrounded by [ ]'s are optional.
If the optional [,height] is omitted, then height=width
is assumed. Locations (loc1) and (loc2) ... each denote
either a \put(loc) or a \multiput(loc), and each location
is of the form ([c]x,y[;xinc,yinc[;num]]).
A \put(loc) is denoted by a location of the form ([c]x,y) where x,y denotes the coordinate where the lower-left corner of the subsequent picture_element will be placed, unless the letter c precedes the x-number, in which case cx,y denotes the center point instead. The very lower-left corner of the entire picture is 0,0, and the upper-right corner is width-1,height-1. Note, for example, that you'd never want to specify location c0,0 since the picture_element would be mostly out-of-bounds (only its upper-right quadrant would be in-bounds).
A \multiput(loc) starts like a \put(loc), but location [c]x,y is followed by ;xinc,yinc[;num] indicating the x,y-increments applied to each of num repetitions of picture_element. If ;num is omitted, repetitions continue until the picture_element goes out-of-bounds of the specified width,height. Note that x,y are always positive or zero, but xinc,yinc may be postive, zero or negative.
The \picture(,){...} parameters width, height, x, y, xinc, yinc may be either integer or may contain a decimal point, and they're all scaled by \unitlength. The num parameter must be integer.
Picture_element's {pic_elem1} and {pic_elem2} ... may be any expressions recognized by mimeTeX, even including other \picture's nested to any level.
To help draw useful pictures, mimeTeX provides several drawing commands, \line(xinc,yinc)[{xlength}] and \circle(xdiam[,ydiam][;quadtants]).
_Without_ its optional {xlen} parameter, the expression (x,y){\line(xinc,yinc)} draws a straight line from point x,y to point x+xinc,y+yinc, where the inc's can be positive, zero or negative. Don't prefix location x,y with a leading c; the intended "corner" is determined by the signs of xinc and yinc. If given, the optional {xlen} parameter rescales the length of the line so its x-projection is xlen and its slope is unchanged.
Without optional ,ydiam and ;quadrants, the expression (x,y){\circle(xdiam)} draws a circle of diameter xdiam centered at x,y. Don't prefix location x,y with a leading c; centering is assumed. If ,ydiam is also given, then (x,y){\circle(xdiam,ydiam)} draws the ellipse inscribed in a rectangle of width xdiam and height ydiam centered at x,y. Finally, ;quadrants refers to an argument of the form ;1234 where each digit specifies a quadrant to be drawn, with 1 the upper-right quadrant and then proceeding counterclockwise, e.g., \circle(12;34) specifies the lower half of a circle whose diameter is twelve.
Besides Examples 12-13 above,
it's hard to resist illustrating
<img src="../cgi-bin/mimetex.cgi?~\unitlength{.6}~\picture(100){
~~(50,50){\circle(99)}~
~(20,55;50,0;2){+1$\hat\bullet}~~(50,40){\bullet}
~~(50,35){\circle(50,25;34)}~
~(50,35){\circle(50,45;34)}}"
border=0 align=absmiddle>
Various and sundry other LaTeX-like commands are also provided by mimeTeX. In addition to features explicitly discussed below, mimeTeX supports the usual sub_scripts and super^scripts, and most of the typical LaTeX commands, many already discussed above, including
\stackrel{ }{ } behaves as usual in LaTeX, rendering its first argument one font size smaller and centered above its second. For example,
"Conversely" to \stackrel{}{}, mimeTeX provides \relstack{}{}, which renders its second argument one font size smaller and centered below its first. For example, the \log function name doesn't treat limits like \lim_, but you can write, for example,
In case html border attributes aren't suitable, mimeTeX provides the usual \fbox{ } command, e.g.,
MimeTeX's bindings are pretty much left-to-right. For example, although mimeTeX correctly interprets \frac12 as well as \frac{1}{2}, etc, the legal LaTeX expression x^\frac12 must be written x^{\frac12}. Otherwise, mimeTeX interprets it as {x^\frac}12, i.e., the same way x^\alpha12 would be interpreted, which is entirely wrong for \frac. The same requirement also applies to other combinations of commands, e.g., you must write \sqrt{\frac\alpha\beta}, etc.
Programming information to help you modify mimeTeX's behavior, and to use its functionality in your own programs, is provided by these appendices. The currently available appendices discuss (a)how to modify or extend mimeTeX's fonts, (b)how to use mimeTeX's principal function, make_raster(), and (c)how to use Sverre Huseby's gifsave.c library.
The font information mimeTeX uses to render characters is derived from .gf font files (usually generated by metafont running against .mf files), which are then run through gftype -i and finally through my gfuntype program (supplied with your mimeTeX distribution).
The final output from each such sequence of three runs (metafont > gftype -i > gfuntype) gives mimeTeX the information it needs to render one particular font family at one particular size. The file texfonts.h supplied with your mimeTeX distribution collects the output from 30 such (sequences of) runs, representing five font families at six sizes each.
This collection of information in texfonts.h is "wired" into mimeTeX through tables maintained in mimetex.h. To change mimeTeX's fonts, you'll have to first modify (or totally replace) texfonts.h using your own gfuntype output, and then change mimetex.h to reflect your texfonts.h modifications.
This appendix provides a brief description of the above process, though you'll probably need at least some previous C programming experience to confidently accomplish it. Your motivation might be to add more fonts to mimeTeX, to change the font sizes I chose, or to add more font sizes, etc. MimeTeX's design permits all this to be easily done once you understand the process.
Running metafont to generate a .gf file from .mf source will usually be your very first step. A typical such run might be
Given the cmmi10.131gf file from this metafont run (or substitute any other .gf file you like), next run
Finally, run gfuntype against the typeout file you just generated with the command
The above sequence of three runs resulted in output file cmmi131.h, containing the font information mimeTeX needs for one font family (cmmi) at one font size (3). Repeat this sequence of three runs for each font size and each font family. Then pull all the output files into one big texfonts.h file (or write a small texfonts.h which just #include's them all).
For your information, the 30 sequences of runs represented
in the texfonts.h file supplied with your mimeTeX distribution
correspond to the following six inital metafont runs for cmr10
size=0 (.83gf) mf '\mode=eighthre; input cmr10'
1 (.100gf) mf '\mode=nextscrn; input cmr10'
2 (.118gf) mf '\mode=lview; input cmr10'
3 (.131gf) mf '\mode=onetz; mag=magstep(.5); input cmr10'
4 (.160gf) mf '\mode=itoh; input cmr10'
5 (.180gf) mf '\mode=lqlores; input cmr10'
Then ditto for the four other font families cmmi10, cmsy10, cmex10,
rsfs10. All the subsequent gftype and gfuntype runs just follow the
usual format described above.
To incorporate all this font information you just generated into
mimeTeX, edit your mimetex.h file and find the table that looks
like
static fontfamily fonttable[] =
{ /* -------------------------------------------------------------
family size=0, 1, 2, 3, 4, 5
------------------------------------------------------------- */
{ CMR10, { cmr83, cmr100, cmr118, cmr131, cmr160, cmr180 } },
{ CMMI10, { cmmi83, cmmi100, cmmi118, cmmi131, cmmi160, cmmi180 } },
{ CMSY10, { cmsy83, cmsy100, cmsy118, cmsy131, cmsy160, cmsy180 } },
{ CMEX10, { cmex83, cmex100, cmex118, cmex131, cmex160, cmex180 } },
{ RSFS10, { rsfs83, rsfs100, rsfs118, rsfs131, rsfs160, rsfs180 } },
{ -999, { NULL, NULL, NULL, NULL, NULL, NULL } }
} ; /* --- end-of-fonttable[] --- */
Note the 30 names cmr83...rsfs180 in the table. These must
correspond to (or must be changed to) the names following the -n
switch you specified for your gfuntype runs.
If you want more than six font sizes, first build up texfonts.h with all the necessary information. Then change LARGESTSIZE (and probably NORMALSIZE) in mimetex.h, and finally edit the above fonttable[] by extending the columns in each row up to your largest size.
You can also add new rows by #define'ing a new family, and then adding a whole lot of character definitions at the bottom of mimetex.h, all in the obvious way (i.e., it should become obvious after reviewing mimetex.h). A new row would be required, for example, to make another font available in mimeTeX.
mimeTeX converts an input LaTeX math expression to a corresponding GIF image in two steps. First, it converts the input LaTeX expression to a corresponding bitmap raster. Then Sverre Huseby's gifsave library, discussed below, converts that bitmap to the emitted gif. Though you never explicitly see that bitmap, it's mimeTeX's principal result. MimeTeX is written so any program can easily use its expression-to-bitmap conversion capability with just a single line of code. The following complete program demonstrates the simplest such use.
#include <stdio.h>
#include "mimetex.h"
int main ( int argc, char *argv[] )
{
raster *rp = make_raster(argv[1],NORMALSIZE);
type_raster(rp,stdout); /* display ascii image of raster */
}
Cut-and-paste the above sample code from this file to, say,
mimedemo.c (and fix the brackets around stdio.h). Then compile
cc mimedemo.c mimetex.c -lm -o mimedemo
and run it from your unix shell command line like
./mimedemo x^2+y^2
MimeTeX's expression-to-bitmap conversion is accomplished by the make_raster() call, whose first argument is just a pointer to a (null-terminated) string containing any mimeTeX-compliant LaTeX expression, and whose second argument is the mimeTeX font size to use (overridden if your expression contains a preamble). The ascii display of the bitmap raster returned by make_raster() results from the subsequent call to type_raster(). That's all this program does, but you could use make_raster()'s returned bitmap for any other purpose you have in mind.
MimeTeX's primary purpose is to emit either xbitmaps or gif images rather than ascii displays. And mimeTeX has anti-aliasing and various other options that further complicate its main() function compared to the simple example above. The example below demonstrates mimeTeX usage in the slightly more realistic situation where an input expression is converted to a gif, without anti-aliasing, and emitted on stdout.
#include <stdio.h>
#include <stdlib.h>
#include "mimetex.h"
/* --- global needed by callback function, below, for gifsave.c --- */
static raster *rp = NULL; /* 0/1 bitmap raster image */
/* --- callback function to return pixel value at col x, row y --- */
int GetPixel ( int x, int y ) /* pixel value will be 0 or 1 */
{ return (int)getpixel(rp,y,x); } /* just use getpixel() macro */
/* --- main() entry point --- */
int main ( int argc, char *argv[] )
{
/* --- get LaTeX expression from either browser query or command-line --- */
char *query = getenv("QUERY_STRING"), /* check for query string */
*expression = (query!=NULL? query : /* input either from query */
(argc>1? argv[1] : "f(x)=x^2")); /* or from command line */
/* ---- mimeTeX converts expression to bitmap raster ---- */
rp = make_raster(expression,NORMALSIZE); /* mimeTeX rasterizes expression */
/* ---- convert returned bitmap raster to gif, and emit it on stdout ---- */
if ( query != NULL ) /* Content-type line for browser */
fprintf( stdout, "Content-type: image/gif\n\n" );
/* --- initialize gifsave library and colors, and set transparent bg --- */
GIF_Create(NULL, rp->width, rp->height, 2, 8); /* init for black/white */
GIF_SetColor(0, 255, 255, 255); /* always set background white */
GIF_SetColor(1, 0, 0, 0); /* and foreground black */
GIF_SetTransparent(0); /* and set transparent background */
/* --- finally, emit compressed gif image (to stdout) --- */
GIF_CompressImage(0, 0, -1, -1, GetPixel);
GIF_Close();
}
Cut-and-paste as before, compile like
cc mimedemo.c mimetex.c gifsave.c
-lm -o mimedemo
and run it like the first example, but this time you may want to redirect
stdout
./mimedemo x^2+y^2 > mimedemo.gif
since output is now a gif image consisting of mostly unprintable bytes.
Input is typically from the command line as illustrated, but this example
checks for a browser query string too. That means you could actually
replace mimetex.cgi with this executable, though anti-aliasing wouldn't
be available.
Of course, this example's intent isn't to replace the mimetex.cgi executable, but rather to illustrate GIFSAVE library usage, documented in detail below. And this example also illustrates usage of several mimeTeX raster structure elements, like rp->width and rp->height. So you'll probably also want to refer to mimetex.h, which contains those raster structures and other relevant definitions. For instance, the example's GetPixel() callback function illustrates usage of the getpixel() macro in mimetex.h, to retrieve individual pixels by their x,y-coordinates. And there's a similar setpixel() macro in mimetex.h to store pixels. After completing all this reading, you'll be prepared to begin using mimeTeX functions in your own code.
The information below is taken from the README file accompanying Sverre Huseby's distribution of GIFSAVE. I've made a few small editorial modifications, including descriptions of the several minor changes necessary to support mimeTeX. And the mimeTeX example program immediately above uses GIFSAVE in a very straightforward way that should help clarify any questions which may remain after reading the documentation below.
INTRODUCTION
============
The GIFSAVE functions make it possible to save GIF images from
your own C programs.
GIFSAVE creates simple GIF files following the GIF87a standard.
Interlaced images cannot be created. There should only be
one image per file.
GIFSAVE consists of five functions, all returning type int,
and no separate header file is required.
The functions should be called in the order listed below
for each GIF-file. One file must be closed before a new one
can be created.
GIF_Create() creates new GIF-files. It takes parameters
specifying filename, screen size, number of colors,
and color resolution.
GIF_SetColor() sets up red, green, blue color components.
It should be called once for each possible color.
GIF_SetTransparent() is optional. If called, it sets the
color number of the color that should be transparent,
i.e., the background color shows through this one.
GIF_CompressImage() performs the compression of the image.
It accepts parameters describing the position and size
of the image on screen, and a user defined callback
function that is supposed to fetch the pixel values.
GIF_Close() terminates and closes the file.
To use these functions, you must also write a callback
function that returns the pixel values for each point
in the image.
THE FUNCTIONS
=============
GIF_Create()
------------
Function Creates a new GIF-file, and stores info on
the screen.
Syntax int GIF_Create(
char *filename,
int width, int height,
int numcolors, int colorres
);
Remarks Creates a new (or overwrites an existing)
GIF-file with the given filename. No
.GIF-extension is added.
If filename is passed as a NULL pointer,
output is directed to stdout.
The width- and height- parameters specify
the size of the image in pixels.
numcolors is the number of colors used in
the image.
colorres is number of bits used to encode a
primary color (red, green or blue).
In GIF-files, colors are built by combining
given amounts of each primary color.
On VGA-cards, each color is built by
combining red, green and blue values in
the range [0, 63]. Encoding the number 63
would require 6 bits, so colorres would be
set to 6.
Return value GIF_OK - OK
GIF_ERRCREATE - Error creating file
GIF_ERRWRITE - Error writing to file
GIF_OUTMEM - Out of memory
GIF_SetColor()
--------------
Function Specifies the primary color component of a
color used in the image.
Syntax void GIF_SetColor(
int colornum,
int red, int green, int blue
);
Remarks This function updates the colortable-values
for color number colornum in the image.
Should be called for each color in the range
[0, numcolors]
with red, green and blue components in the
range [0, (2^colorres)-1]
colorres and colornum are values previousely
given to the function GIF_Create().
Return value None
GIF_SetTransparent()
--------------------
Function Specifies the color number of the color
that should be considered transparent.
Syntax void GIF_SetTransparent(
int colornum
);
Remarks Need not be called at all. But if called,
should be called only once with colornum in
the range [0, numcolors] i.e., colornum
must be one of the values previously
given to GIF_SetColor().
Return value None
GIF_CompressImage()
-------------------
Function Compresses an image and stores it in the
current file.
Syntax int GIF_CompressImage(
int left, int top,
int width, int height,
int (*getpixel)(int x, int y)
);
Remarks The left- and top- parameters indicate the
image offset from the upper left corner of
the screen. They also give the start values
for calls to the userdefined callback
function.
width and height give the size of the image.
A value of -1 indicates the equivalent screen
size given in the call to GIF_Create().
If the image is supposed to cover the entire
screen, values 0, 0, -1, -1 should be given.
GIF_CompressImage() obtains the pixel values
by calling a user specified function. This
function is passed in the parameter getpixel.
See "callback()" further down for a
description of this function.
Return value GIF_OK - OK
GIF_ERRWRITE - Error writing to file
GIF_OUTMEM - Out of memory
GIF_Close()
-----------
Function Closes the GIF-file.
Syntax int GIF_Close(void);
Remarks This function writes a terminating descriptor
to the file, and then closes it. Also frees
memory used by the other functions of GIFSAVE.
Return value GIF_OK - OK
GIF_ERRWRITE - Error writing to file
THE CALLBACK FUNCTION
=====================
callback()
----------
Function Obtains pixel-values for the
GIF_CompressImage() -function.
Syntax int callback(int x, int y);
Remarks This function must be written by the
programmer. It should accept two integer
parameters specifying a point in the image,
and return the pixel value at this point.
The ranges for these parameters are as
follows
x : [img_left, img_left + img_width - 1]
y : [img_top, img_top + img_height - 1]
where img_left, img_top, img_width and
img_height are the values left, top, width
and height passed to GIF_CompressImage().
An example; if the screen has width 640 and
height 350, and the image covers the entire
screen, x will be in the range [0, 639]
and y in the range [0, 349].
callback() need not get its values from the
screen. The values can be fetched from a
memory array, they can be calculated for
each point requested, etc.
The function is passed as a parameter to
GIF_CompressImage(), and can thus have any
name, not only callback().
Return value Pixel value at the point requested. Should
be in the range [0, numcolors-1] where
numcolors is as specified to GIF_Create().
I hope you find mimeTeX useful. If so, a contribution to your country's TeX Users Group, or to the GNU project, is suggested, especially if you're a company that's currently profitable.
If you also like mimeTeX's source, I'm an independent contractor incorporated in the US as John Forkosh Associates, Inc. A resume is at www.forkosh.com or email john@forkosh.com