% output=pdftex engine=pdftex language=uk
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\startcomponent mfun-003

\environment mfun-000

\chapter [sec:embedding] {Embedded graphics}

\startintro

In addition to the \type {beginfig}||\type {endfig} method,
there are other ways to define and include a \METAPOST\
graphic. Each method has its advantages and disadvantages.

In the previous chapter we were still assuming that the
graphic was defined in its own file. In this chapter we will
introduce the interface between \CONTEXT\ and \METAPOST\ and
demonstrate how the definitions of the graphics can be
embedded in the document source.

\stopintro

\section {Getting started}

From now on, we will assume that you have \CONTEXT\ running
on your platform. Since \PDF\ has full graphics support, we
also assume that you use \PDFTEX, or know how to go from
\DVI\ to \PDF. Since this document is not meant as a
\CONTEXT\ tutorial, we will limit this introduction to the
basics needed to run the examples.

A simple document looks like:

\starttyping
\starttext
  Some text.
\stoptext
\stoptyping

You can process this document with the \PERL\ based command
line interface to \CONTEXT. If the source code is embedded in
the file \type {mytext.tex}, you can say:

\starttyping
texexec --pdf mytext
\stoptyping

As an alternative to \type {--pdf}, you can explicitly set
the output driver in your document:

\starttyping
\setupoutput[pdftex]
\starttext
  Some text and/or graphics.
\stoptext
\stoptyping

Yet another alternative is:

\starttyping
% interface=english output=pdftex
\starttext
  Some text and/or graphics.
\stoptext
\stoptyping

Here the \type {interface} directive tells \TEXEXEC\ that it
should force the english user interface.

We will use color, and since traditionally \TEX\ is rather
unaware of color, this feature is turned off by default, so,
if you want to see color, you should type:

\starttyping
\setupcolors[state=start]
\starttext
  Some \color[blue]{text} and/or \color[green]{graphics}.
\stoptext
\stoptyping

As an alternative, you can run \TEXEXEC\ like:

\starttyping
texexec --pdf --color mytext
\stoptyping

In later chapters we will occasionally see some more
\CONTEXT\ commands show up. If you want to know more about
what \CONTEXT\ can do for you, we recommend the beginners
manual and the reference manual, as well as the manual that
comes with \TEXEXEC.

\section {External graphics}

Since \TEX\ has no graphic capabilities built in, a graphic
is referred to as an external figure. A \METAPOST\ graphic
often has a number as suffix, so embedding such a graphic
is done by:

\starttyping
\externalfigure[graphic.123][width=4cm]
\stoptyping

An alternative method is to separate the definition from the
inclusion. An example of a definition is:

\starttyping
\useexternalfigure[pentastar][star.803][height=4cm]
\useexternalfigure[octostar] [star.804][pentastar]
\stoptyping

Here, the second definition inherits the characteristics
from the first one. These graphics can be summoned like:

\starttyping
\placefigure
  {A five||point star drawn by \METAPOST.}
  {\externalfigure[pentastar]}
\stoptyping

Here the stars are defined as stand||alone graphics, in a file
called \type {star.mp}. Such a file can look like:

\starttyping
def star (expr size, n, pos) =
  for a=0 step 360/n until round(360*(1-1/n)) :
    draw (origin -- (size/2,0))
      rotatedaround (origin,a) shifted pos ;
  endfor ;
enddef ;

beginfig(803) ;
  pickup pencircle scaled 2mm ; star(2cm,5,origin) ;
endfig ;

beginfig(804) ;
  pickup pencircle scaled 1mm ; star(1cm,8,origin) ;
  pickup pencircle scaled 2mm ; star(2cm,7,(3cm,0)) ;
endfig ;

end.
\stoptyping

This \type {star} macro will produce graphics like:

\startbuffer
def star (expr size, n, pos) =
  for a=0 step 360/n until round(360*(1-1/n)) :
    draw (origin -- (size/2,0))
      rotatedaround (origin,a) shifted pos ;
  endfor ;
enddef ;

for i=5 upto 10 :
  drawoptions (withpen pencircle scaled 2mm withcolor .625red) ;
  star(1cm,i,origin shifted (i*2cm,0)) ;
endfor ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\section {Integrated graphics}

An integrated graphic is defined in the document source or
in a style definition file. The most primitive way of doing
this is beginning with the definition of the graphic.

\starttyping
\startMPgraphic
  fill fullcircle scaled 200pt withcolor .625white ;
\stopMPgraphic
\stoptyping

Next the graphic can be loaded, using:

\starttyping
\loadcurrentMPgraphic{optional setups}
\stoptyping

Finally, the graphic is placed in the document with:

\starttyping
\placeMPgraphic
\stoptyping

The optional setups are passed on to the figure inclusion
macro, which in \CONTEXT\ is the command \type
{\externalfigure}.

Since every definition replaces the previous one, this
method forces you to embed the definitions in the running
text. In this document we also generate graphics while we
finish a page, so there is a good change that when we have
constructed a graphic which will be called on the next page,
the wrong graphic is placed.

Therefore you may as well forget these commands, since there
are more convenient ways of defining and using graphics,
which have the added advantage that you can predefine
multiple graphics, thereby separating the definitions from
the usage.

The first alternative is a {\em usable} graphic. Such a
graphic is calculated anew each time it is used. An example
of a usable graphic is:

\starttyping
\startuseMPgraphic{name}
  fill fullcircle scaled 200pt withcolor .625yellow ;
\stopuseMPgraphic
\stoptyping

When you put this definition in the preamble of your
document, you can place this graphic anywhere in the file,
saying:

\starttyping
\useMPgraphic{name}
\stoptyping

As said, this graphic is calculated each time it is placed,
which can be time consuming. Apart from the time aspect,
this also means that the graphic itself is incorporated many
times. Therefore, for graphics that don't change, \CONTEXT\
provides {\em reusable} graphics:

\starttyping
\startreusableMPgraphic{name}
  fill fullcircle scaled 200pt withcolor .625yellow;
\stopreusableMPgraphic
\stoptyping

This definition is accompanied by:

\starttyping
\reuseMPgraphic{name}
\stoptyping

Imagine that we use a graphic as a background for a button. We
can create a unique and reusable graphic by saying:

\starttyping
\def\MyGraphic%
  {\startreusableMPgraphic{name:\overlaywidth:\overlayheight}
      path p ; p := unitsquare
        xscaled \overlaywidth yscaled \overlayheight ;
      fill p withcolor .625yellow ;
      draw p withcolor .625red ;
   \stopreusableMPgraphic
   \reuseMPgraphic{name:\overlaywidth:\overlayheight}}
\stoptyping

After this we can say:

\starttyping
\defineoverlay[my graphic][\MyGraphic]
\button[background=my graphic,frame=off]{Go Home}[firstpage]
\stoptyping

Say that we have a 30pt by 20pt button, then the identifier
will be \type {name:30pt:20pt}. Different dimensions will
lead to other identifiers, so this sort of makes the
graphics unique.

We can bypass the ugly looking \type {\def} by using a
third class of embedded graphics, the {\em unique} graphics.

\starttyping
\startuniqueMPgraphic{name}
  path p ; p := unitsquare
    xscaled \overlaywidth yscaled \overlayheight ;
  fill p withcolor .625yellow ;
  draw p withcolor .625red ;
\stopuniqueMPgraphic
\stoptyping

Now we can say:

\starttyping
\defineoverlay[my graphic][\uniqueMPgraphic{name}]
\button[background=my graphic,frame=off]{Go Home}[firstpage]
\stoptyping

You may wonder why unique graphics are needed when a single
graphic might be used multiple times by scaling it to fit
the situation. Since a unique graphic is calculated for each
distinctive case, we can be sure that the current
circumstances are taken into account. Also, scaling would
result in incomparable graphics. Consider the following
definition:

\startbuffer[a]
\startMPgraphic
  draw unitsquare
    xscaled 5cm yscaled 1cm
    withpen pencircle scaled 2mm
    withcolor .625red ;
\stopMPgraphic
\stopbuffer

\typebuffer[a]

Since we reuse the graphic, the dimensions are sort of
fixed, and because the graphic is calculated once, scaling
it will result in incompatible line widths.

\startbuffer[b]
\hbox \bgroup
  \loadcurrentMPgraphic{width=5cm,height=1cm}\placeMPgraphic \quad
  \loadcurrentMPgraphic{width=8cm,height=1cm}\placeMPgraphic \egroup
\stopbuffer

\startlinecorrection[blank]
\getbuffer[a,b]
\stoplinecorrection

These graphics were placed with:

\typebuffer[b]

Imagine what happens when we add some buttons to an
interactive document without taking care of this side
effect. All the frames would look different. Consider the
following example.

\startbuffer[a]
\startuniqueMPgraphic{right or wrong}
  pickup pencircle scaled .075 ;
  fill unitsquare withcolor .8white ;
  draw unitsquare withcolor .625red ;
  currentpicture := currentpicture
    xscaled \overlaywidth yscaled \overlayheight ;
\stopuniqueMPgraphic
\stopbuffer

\typebuffer[a]

Let's define this graphic as a background to some buttons.

\startbuffer[b]
\defineoverlay[button][\uniqueMPgraphic{right or wrong}]
\setupbuttons[background=button,frame=off]
\stopbuffer

\startbuffer[c]
\hbox
  {\button {previous}          [previouspage]\quad
   \button {next}              [nextpage]\quad
   \button {index}             [index]\quad
   \button {table of contents} [content]}
\stopbuffer

\typebuffer[b,c]

The buttons will look like:

\startlinecorrection[blank]
\setupinteraction[state=start,color=,contrastcolor=]
\getbuffer[a,b,c]
\stoplinecorrection

Compare these with:

\startbuffer[a]
\startuniqueMPgraphic{wrong or right}
  pickup pencircle scaled 3pt ;
  path p ; p := unitsquare
    xscaled \overlaywidth yscaled \overlayheight ;
  fill p withcolor .8white ;
  draw p withcolor .625red ;
\stopuniqueMPgraphic
\stopbuffer

\startlinecorrection[blank]
\getbuffer[a,b]
\defineoverlay[button][\uniqueMPgraphic{wrong or right}]
\setupinteraction[state=start,color=,contrastcolor=]
\getbuffer[c]
\stoplinecorrection

Here the graphic was defined as:

\typebuffer[a]

The last class of embedded graphics are the {\em runtime}
graphics. When a company logo is defined in a separate file
\type {mylogos.mp}, you can run this file by saying:

\starttyping
\startMPrun
  input mylogos ;
\stopMPrun
\stoptyping

The source for the logo is stored in a file named \type
{mylogos.mp}.

\startbuffer
beginfig(21) ;
  draw fullsquare            withcolor .625red ;
  draw fullsquare rotated 45 withcolor .625red ;
  picture cp ; cp := currentpicture ;
  def copy = addto currentpicture also cp enddef ;
  copy scaled .9 withcolor .625white  ;
  copy scaled .7 withcolor .625yellow ;
  copy scaled .6 withcolor .625white  ;
  copy scaled .4 withcolor .625red    ;
  copy scaled .3 withcolor .625white  ;
  fill fullcircle scaled .2 withcolor .625yellow ;
  currentpicture := currentpicture scaled 50 ;
endfig ;
end .
\stopbuffer

\typebuffer

In this example the result is available in the file \type
{mprun.21}. This file can be included in the normal way,
using:

\starttyping
\externalfigure[mprun.21][width=5cm]
\stoptyping

\startuseMPgraphic{dummy logo}
  draw fullsquare            withcolor .625red ;
  draw fullsquare rotated 45 withcolor .625red ;
  picture cp ; cp := currentpicture ;
  def copy = addto currentpicture also cp enddef ;
  copy scaled .9 withcolor .625white  ;
  copy scaled .7 withcolor .625yellow ;
  copy scaled .6 withcolor .625white  ;
  copy scaled .4 withcolor .625red    ;
  copy scaled .3 withcolor .625white  ;
  fill fullcircle scaled .2 withcolor .625yellow ;
  currentpicture := currentpicture scaled 3cm ;
\stopuseMPgraphic

\placefigure
  {The logo is defined in the file \type {mylogos.mp} as
   figure~21 and processed by means of the \type {mprun}
   method.}
  {\useMPgraphic{dummy logo}}

\section {Graphic buffers}

In addition to the macros defined in the previous section,
you can use \CONTEXT's buffers to handle graphics. This can
be handy when making documentation, so it makes sense to
spend a few words on them.

A buffer is a container for content that is to be (re|)|used
later on. The main reason for their existence is that they
were needed for typesetting manuals and articles on \TEX. By
putting the code snippets in buffers, we don't have to key
in the code twice, since we can either show the code of
buffers verbatim, or process the code as part of the text
flow. This means that the risk of mismatch between the code
shown and the typeset text is minimized.

\startbuffer[a]
\startbuffer
You are reading the \METAFUN\ manual.
\stopbuffer
\stopbuffer

\typebuffer[a]

This buffer can be typeset verbatim using \type {\typebuffer}
and processed using \type {\getbuffer}, as we will do now:

\blank \getbuffer[a] \blank

An other advantage of using buffers, is that they help you
keeping the document source clean. In many places in this
manual we put table or figure definitions in a buffer and
pass the buffer to another command, like:

\starttyping
\placefigure{A very big table}{\getbuffer}
\stoptyping

Sometimes it makes sense to collect buffers in separate
files. In that case we give them names.

\startbuffer
\startbuffer[mfun]
You are reading the \METAFUN\ manual.
\stopbuffer
\stopbuffer

This time we should say \type {\typebuffer[mfun]} to typeset
the code verbatim. Instead of \TEX\ code, we can put
\METAPOST\ definitions in buffers.

\startbuffer
\startbuffer[graphic]
draw fullcircle scaled 2cm ;
\stopbuffer
\stopbuffer

Buffers can be used to stepwise build graphics. By putting
code in multiple buffers, you can selectively process this
code.

\startbuffer
\startbuffer[red]
drawoptions(withcolor .625red) ;
\stopbuffer

\startbuffer[yellow]
drawoptions(withcolor .625yellow) ;
\stopbuffer
\stopbuffer

\typebuffer

We can now include the same graphic in two colors by simply
using different buffers. This time we use the special
command \type {\processMPbuffer}, since \type {\getbuffer}
will typeset the code fragment, which is not what we want.

\startbuffer
\startlinecorrection[blank]
\processMPbuffer[red,graphic]
\stoplinecorrection
\stopbuffer

\typebuffer

The line correction macros take care of proper spacing
around the graphic. The \type {[blank]} directive tells
\CONTEXT\ to add more space before and after the graphic.

\startbuffer
\startlinecorrection[blank]
\processMPbuffer[yellow,graphic]
\stoplinecorrection
\stopbuffer

\typebuffer

Which mechanism you use, (multiple) buffers or (re|)|usable
graphics, depends on your preferences. Buffers are slower but
don't take memory, while (re|)|usable graphics are stored in
memory which means that they are accessed faster.

\section {Communicating color}

Now that color has moved to the desktop, even simple
documents have become more colorful, so we need a way to
consistently apply color to text as well as graphics. In
\CONTEXT, colors are called by name.

The next definitions demonstrate that we can define a color
using different color models, \RGB\ or \CMYK. Depending on
the configuration, \CONTEXT\ will convert one color system
to the other, \RGB\ to \CMYK, or vice versa. The full
repertoire of color components that can be set is as follows.

\starttyping
\definecolor[color one]  [r=.1, g=.2, b=.3]
\definecolor[color two]  [c=.4, m=.5, y=.6, k=.7]
\definecolor[color three][s=.8]
\stoptyping

The numbers are limited to the range $0\dots1$ and represent
percentages. Black is represented by:

\starttyping
\definecolor[black 1] [r=0, g=0, b=0]
\definecolor[black 2] [c=0, m=0, y=0, k=1]
\definecolor[black 3] [s=0]
\stoptyping

Predefined colors are passed to \METAPOST\ graphics via the
\type {\MPcolor}. First we define some colors.

\starttyping
\definecolor[darkyellow][y=.625] % a CMYK color
\definecolor[darkred]   [r=.625] % a RGB color
\definecolor[darkgray]  [s=.625] % a gray scale
\stoptyping

These are the colors we used in this document. The next
example uses two of them.

\startbuffer
\startuseMPgraphic{color demo}
  pickup pencircle scaled 1mm ;
  path p ; p := fullcircle xscaled 10cm yscaled 1cm ;
  fill p withcolor \MPcolor{darkgray} ;
  draw p withcolor \MPcolor{darkred} ;
\stopuseMPgraphic

\useMPgraphic{color demo}
\stopbuffer

\typebuffer

The previous example uses a pure \RGB\ red shade, combined
with a gray fill.

\startlinecorrection[blank]
\getbuffer
\stoplinecorrection

Since \METAPOST\ does not support the \CMYK\ color space and
native gray scales |<|although gray colors are reduced to
the more efficient \POSTSCRIPT\ \type {setgray} operators in
the output|>| the macro \type {\MPcolor} takes care of the
translation from \CMYK\ to \RGB\ as well as gray to \RGB.
However, there is a fundamental difference between a yellow
as defined in \CONTEXT\ using \CMYK\ and a \RGB\ yellow in
\METAPOST.

\startbuffer
\definecolor[cmyyellow]    [y=1]
\definecolor[rgbyellow]    [r=1,g=1]

\definecolor[cmydarkyellow][y=.625]
\definecolor[rgbdarkyellow][r=.625,g=.625]
\stopbuffer

\typebuffer \getbuffer

\in {Figure} [fig:many yellows] demonstrates what happens
when we multiply colors by a factor. Since we are not
dealing with real \CMYK\ colors, multiplication gives
different results for \CMYK\ colors passed as \type
{\MPcolor}.

\def\TestColor#1%
  {\startuseMPgraphic{yellow}
     fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1 ;
   \stopuseMPgraphic
   \useMPgraphic{yellow}}

\startbuffer
\setuptype[style=\ttx]\setupcolors[mpcmyk=no]%
\startcombination[3*3]
  {\TestColor{yellow}}                  {\type{yellow}}
  {\TestColor{(1,1,0)}}                 {\type{(1,1,0)}}
  {\TestColor{(.5,.5,0)}}               {\type{(.5,.5,0)}}
  {\TestColor{\MPcolor{rgbyellow}}}     {\type{\MPcolor{rgbyellow}}}
  {\TestColor{\MPcolor{rgbdarkyellow}}} {\type{\MPcolor{rgbdarkyellow}}}
  {\TestColor{.5\MPcolor{rgbyellow}}}   {\type{.5\MPcolor{rgbyellow}}}
  {\TestColor{\MPcolor{cmyyellow}}}     {\type{\MPcolor{cmyyellow}}}
  {\TestColor{\MPcolor{cmydarkyellow}}} {\type{\MPcolor{cmydarkyellow}}}
  {\TestColor{.5\MPcolor{cmyyellow}}}   {\type{.5\MPcolor{cmyyellow}}}
\stopcombination
\stopbuffer

\placefigure
  [here][fig:many yellows]
  {All kinds of yellow.}
  {\getbuffer}

So, \type {.625red} is the same as \type {[r=.5]}, but \type
{.625yellow} is not the same as \type {[y=.5]}, but matches
\type {[r=.5,g=.5]}. \in {Figure} [fig:some reds] shows
the pure and half reds.

\def\TestColor#1%
  {\startuseMPgraphic{red}
     fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1
   \stopuseMPgraphic
   \useMPgraphic{red}}

\startbuffer
\setuptype[style=\ttx]\setupcolors[mpcmyk=no]
\startcombination[3*2]
  {\TestColor{red}}               {\type{red}}
  {\TestColor{(1,0,0)}}           {\type{(1,0,0)}}
  {\TestColor{(.625,0,0)}}        {\type{(.625,0,0)}}
  {\TestColor{\MPcolor{red}}}     {\type{\MPcolor{red}}}
  {\TestColor{\MPcolor{darkred}}} {\type{\MPcolor{darkred}}}
  {\TestColor{.625\MPcolor{red}}} {\type{.625\MPcolor{red}}}
\stopcombination
\stopbuffer

\placefigure
  [here][fig:some reds]
  {Some kinds of red.}
  {\getbuffer}

In order to prevent problems, we advise you to stick to
\RGB\ color specifications when possible. That way you not
only prevent conversion problems, but also get more
predicatable results on printing and viewing devices.
However, reality demands that sometimes \CMYK\ colors are
used, so how can we deal with that?

In the \METAFUN\ macro collection there is a macro \type
{cmyk} that takes four arguments, representing the cyan,
magenta, yellow, and black component.

\startbuffer
fill fullsquare xyscaled (10cm,1cm) withcolor cmyk(1,0,.3,.3) ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

If you take a close look at the numbers, you will notice
that the cyan component results in a 100\% ink contribution.
You will also notice that 30\% black ink is added. This
means that we cannot safely convert this color to \RGB\
($r=1-c-k<0$) without losing information. Nevertheless the
previous blue bar is presented all right. This is due to
the fact that in \METAFUN\ the \CMYK\ colors are handled as
they should, even when \METAPOST\ does not support this color
model.

If you use this feature independent of \CONTEXT, you need to
enable it by setting \type {cmykcolors} to \type {true}. You
have to convert the resulting graphic to \PDF\ by using for
instance the \type {mptopdf} suite (see \in {appendix}
[sec:programs]).

In \CONTEXT\ you can influence this conversion by changing
parameters related to color handling:

\starttyping
\setupcolors[cmyk=yes,mpcmyk=no]
\stoptyping

Unless you know what you are doing, you don't have to change
the default settings (both \type {yes}). In the \CONTEXT\
reference manual you can also read how color reduction can be
handled.

Special care should be paid to gray scales. Combining equal
quantities of the three color inks will not lead to a gray
scale, but to a muddy brown shade.

\startbuffer
fill fullsquare xyscaled (10cm,  2cm) withcolor .5white ;
fill fullsquare xyscaled ( 6cm,1.5cm) withcolor cmyk(.5,.5,.5,0) ;
fill fullsquare xyscaled ( 2cm,  1cm) withcolor cmyk(0,0,0,.5) ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

In \in {figure} [fig:cmyk 1] \in {to} [fig:cmyk 3] you can
see some more colors defined in the \CMYK\ color space. When
you display the screen version of this document, you will
notice that the way colors are displayed can differ per
viewer. This is typical for \CMYK\ colors and has to do with
the fact that some assumptions are made with respect to the
(print) medium.

\startbuffer[mp]
  fill fullcircle xyscaled (3cm,1cm) withcolor \MPcolor{test} ;
\stopbuffer

\startbuffer[cmyk]
\startcombination[4*1]
  {\definecolor[test][c=1,y=.3,k=.3] \processMPbuffer[mp]} {c=1 y=.3 k=.3}
  {\definecolor[test][c=.9,y=.15]    \processMPbuffer[mp]} {c=.9 y=.15}
  {\definecolor[test][c=.25,y=.8]    \processMPbuffer[mp]} {c=.25 y=.8}
  {\definecolor[test][c=.45,y=.1]    \processMPbuffer[mp]} {c=.45 y=.1}
\stopcombination
\stopbuffer

\placefigure
  [here][fig:cmyk 1]
  {\CMYK\ support disabled,
   conversion to \RGB.}
  {\setupcolors[cmyk=no]\getbuffer[cmyk]}

\placefigure
  [here][fig:cmyk 2]
  {\CMYK\ support enabled,
   no support in \METAPOST.}
  {\setupcolors[cmyk=yes,mpcmyk=no]\getbuffer[cmyk]}

\placefigure
  [here][fig:cmyk 3]
  {\CMYK\ support enabled,
   no conversion to \RGB,
   support in \METAPOST}
  {\setupcolors[cmyk=yes]\getbuffer[cmyk]}

\section {Common definitions}

When using many graphics, there is a chance that they share
common definitions. Such shared components can be defined by:

\starttyping
\startMPinclusions
  color mycolor ; mycolor := .625red ;
\stopMPinclusions
\stoptyping

All \METAPOST\ graphics defined in the document end up in
the files \type {mpgraph.mp} and \type {mprun.mp}. When
processed, they produce (sometimes many) graphic files. When
using \TEXEXEC\ to process documents, these two files are
processed automatically after a run so that in a next run,
the right graphics are available.

When you are using the \type {web2c} distribution, \CONTEXT\
can call \METAPOST\ at runtime and thereby use the right
graphics instantaneously. In order to use this feature, you
have to enable \type {\write18} in the file \type
{texmf.cnf}. Also, in the file \type {cont-sys.tex}, that
holds local preferences, or in the document source, you
should say:

\starttyping
\runMPgraphicstrue
\stoptyping

This enables runtime generation of graphics using the low
level \TEX\ command \type {\write18}. First make sure that
your local brand of \TEX\ supports this feature. A simple
test is making a \TEX\ file with the following line:

\starttyping
\immediate\write18{echo It works}
\stoptyping

If this fails, you should consult the manual that comes with
your system, locate an expert or ask around on the \CONTEXT\
mailing list. Of course you can also decide to let \TEXEXEC\
take care of processing the graphics afterwards. This has
the advantage of being faster but has the disadvantage that
you need additional \TEX\ runs.

If you generate the graphics at run time, you should
consider to turn on graphic slot recycling, which means that
you often end up with fewer intermediate files:

\starttyping
\recycleMPslotstrue
\stoptyping

There are a few more low level switches and features, but
these go beyond the purpose of this manual. Some of these
features, like the option to add tokens to \type
{\everyMPgraphic} are for experts only, and fooling around
with them can interfere with existing features.

\section {One page graphics}

Although all of what is demonstrated in this document is
done in \CONTEXT, some of the features discussed here can
also be done in plain \TEX. In the \METAFUN\ distribution
there is a file called \type {plainfun.tex}, which loads the
appropriate \CONTEXT\ modules.

Many low level macros are rather generic, and can be used in
plain \TEX\ without problems. However, the big advantage of
using \CONTEXT\ is, that graphics can be part of the text
flow and that you can put them on layers. If you don't want
this, and only want to make stand alone graphics, you may
still consider using \CONTEXT\ for that purpose.

Another advantage is that when using \CONTEXT\ you don't have
to bother about specials, font inclusion and all those nasty
things that can spoil a good day. An example of such a graphic
is the file \type {mfun-888} that resides on the computer of
the author.

\typefile{mfun-888}

Given that the \CONTEXT\ english interface format is present
on your system, you can process this file with \TEXEXEC, for
instance using \PDFTEX. The \type {--once} directive saves
some runtime.

\starttyping
texexec --once --pdf mfun-888
\stoptyping

You can define many graphics in one file. The \TEXEXEC\
manual describes how to selectively process pages. If
you use \PDFTEX, you can include individual pages from \PDF\
files:

\startbuffer
\placefigure
  {A silly figure, demonstrating that stand||alone||graphics
   can be made.}
  {\externalfigure[mfun-888][page=1]}
\stopbuffer

\typebuffer

In this case the \type {page=1} specification is not really
needed. You can scale and manipulate the figure in any way
supported by the macro package that you use.

\getbuffer

\section {Managing resources}

A graphic consists of curves, either or not filled with a
given color. A graphic can also include text, which means
that fonts are used. Finally a graphic can have special
effects, like a shaded fill. Colors, fonts and special
effects go under the name resources, since they may demand
special care or support from the viewing or printing device.

When fonts are used, a \METAPOST\ file is not self
contained. This means that the postprocessing program has to
deal with the fonts. In \CONTEXT, the special driver |<|and
\PDFTEX\ support is considered as such|>| takes care of this.

Special effects, like shading, are supported by dedicated
\METAPOST\ modules. These are included in the \CONTEXT\
distribution and will be discussed later in \in {chapter}
[sec:effects].

Since \METAPOST\ supports color, an embedded graphic can be
rather colorful. However, when color support is disabled or
set up to convert colors to gray scales, \CONTEXT\ will
convert the colors in the graphics to gray scales.

\startbuffer[circle]
  colorcircle(4cm,red,green,blue) ;
\stopbuffer

\startbuffer
\startcombination[3*1]
  {\setupcolors[state=start]\processMPbuffer[circle]}                {full color}
  {\setupcolors[state=stop]\processMPbuffer[circle]}                 {weighted gray}
  {\setupcolors[state=stop]\weightGRAYfalse\processMPbuffer[circle]} {linear gray}
\stopcombination
\stopbuffer

You may wonder what the advantage is of weighted gray
conversion. \in {Figure} [fig:color circles] shows the
difference between natural colors, weighted gray scaled and
straightforward, non||weighted, gray scales.

\placefigure
  [here][fig:color circles]
  {The advantage of weighted gray over linear gray.}
  {\getbuffer}

When we convert color to gray, we use the following formula.
This kind of conversion also takes place in black and white
televisions.

\placeformula [-]
  \startformula
    G = .30r + .59g + .11b
  \stopformula

\in {Section} [sec:conversion] introduces the \type {grayed}
operation that you can use to convert a colored picture into
a gray one. This macro uses the same conversion method as
mentioned here.

\stopcomponent
