diff options
Diffstat (limited to 'doc/context/sources/general/manuals/metafun/metafun-embedding.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/metafun/metafun-embedding.tex | 1208 |
1 files changed, 1208 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/metafun/metafun-embedding.tex b/doc/context/sources/general/manuals/metafun/metafun-embedding.tex new file mode 100644 index 000000000..10383fa3a --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-embedding.tex @@ -0,0 +1,1208 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-embedding + +\environment metafun-environment + +\startchapter[reference=sec:embedding,title={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 + +\startsection[title={Getting started}] + +\index{running} +\index{processing} + +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 \LUATEX\ in +combination with \CONTEXT\ \MKIV, although most will also work with other engines +and \MKII. 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 \LUA\ based command line interface to +\CONTEXT. If the source code is embedded in the file \type {mytext.tex}, you can +say: + +\starttyping +context mytext +\stoptyping + +We will use color, and in \MKIV\ color is enabled by default. If you don't want +color you can tell \CONTEXT, so + +\starttyping +\setupcolors[state=stop] +\starttext + Some \color[blue]{text} and/or \color[green]{graphics}. +\stoptext +\stoptyping + +comes out in black and white. + +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 wiki pages. + +\stopsection + +\startsection[title={External graphics}] + +\index {graphics+external} + +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 + +But, now that we have instant \METAPOST\ available in \LUATEX, there is no need +for external images and we can collect them in libraries, as we will see later +on. + +\stopsection + +\startsection[title={Integrated graphics}] + +\index{graphics+embedded} + +An integrated graphic is defined in the document source or in a style definition +file. The most primitive way of doing this is just inserting the code: + +\starttyping +\startMPcode + fill fullcircle scaled 200pt withcolor .625white ; +\stopMPcode +\stoptyping + +Such a graphic is used once at the spot where it is defined. In this document we +also generate graphics while we finish a page, so there is a good chance that +when we have constructed a graphic which will be called on the next page, the +wrong graphic is placed. + +For this reason there are 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 + +Notice the use of \type {OverlayWidth} and \type {OverlayHeight}. These variables +are set for each call to \METAPOST. 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 + +A shorter variant is: + +\starttyping +\startuniqueMPgraphic{name} + fill OverlayBox withcolor .625yellow ; + draw OverlayBox withcolor .625red ; +\stopuniqueMPgraphic +\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] +\startuseMPgraphic{demo} + draw unitsquare + xscaled 5cm yscaled 1cm + withpen pencircle scaled 2mm + withcolor .625red ; +\stopuseMPgraphic +\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 + \scale[width=5cm,height=1cm]{\useMPgraphic{demo}}\quad + \scale[width=8cm,height=1cm]{\useMPgraphic{demo}}% +\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 virtual 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}} + +Optionally you can specify a name and an instance. This has the advantage that +the graphics don't interfere with the regular inline graphics. Here the instance +used is \type {extrafun} and the name where the run is stored is \type {mydemo}. + +\startbuffer +\startMPrun{extrafun::mydemo} + input mfun-mrun-demo.mp ; +\stopMPrun + +\placefigure + {An external file can have multiple graphics. Here we show a few + images that we used to use on the \PRAGMA\ \CONTEXT\ website.} + {\startcombination[2*2] + {\externalfigure[mprun:extrafun::mydemo.1][height=6cm]} {downloads} + {\externalfigure[mprun:extrafun::mydemo.2][height=6cm]} {links} + {\externalfigure[mprun:extrafun::mydemo.3][height=6cm]} {mirrors} + {\externalfigure[mprun:extrafun::mydemo.4][height=6cm]} {team} + \stopcombination} +\stopbuffer + +\typebuffer + +Keep in mind that the whole file will be processed (using the built in library) +in order to get one graphic. Normally this is no big deal. + +\getbuffer + +\stopsection + +\startsection[title={Using \METAFUN\ but not \CONTEXT}] + +\index{graphics+standalone} + +If you don't want to use \CONTEXT\ but still want to use \METAFUN, a rather +convenient method is the following. Create a file that + +\starttyping +\startMPpage + % Your mp code goes here. You can use the textext + % macro as discussed later to deal with typeset text. +\stopMPpage +\stoptyping + +When you process that file with the \type {context} command you will get a \PDF\ +file that you can include in any application that can embed a \PDF\ image. In +this case your exposure to \CONTEXT\ is minimal. + +\stopsection + +\startsection[title={Graphic buffers}] + +\index{graphics+buffers} +\index{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. + +\stopsection + +\startsection[title={Communicating color}] + +\index{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 + +Originally \METAPOST\ only supported only the \RGB\ and gray color spaces. In \METAFUN\ +we also supported \CMYK\ and spot colors, using an extension mechanism that hooked into +the backend. At some point \METAPOST\ got native support for \CMYK. When you use mixed +color models you need to be aware of the fact that their related variables have different +types: + +\starttabulate[||T|T|] +\NC gray \NC numeric \NC s \NC \NR +\NC rgb \NC color \NC (r,g,b) \NC \NR +\NC cmyk \NC cmykcolor \NC (c,m,y,k) \NC \NR +\stoptabulate + +Because in \METAFUN\ (\type {mpiv}) we hook deeply into the \CONTEXT\ color +mechanisms we can use symbolic names instead. and these are just strings. + +There is a fundamental difference between a yellow as defined in \CONTEXT\ using +\CMYK\ and a \RGB\ yellow. + +\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:pass] 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}. \in {Figure} [fig:many yellows:fetch] we show the same colors but +this time we use a different method, one that avoids the \TEX\ macro. This method +can be used in \MKIV. We will use both methods in examples. + +\def\TestColor#1% + {\startuseMPgraphic{yellow} + fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1 ; + \stopuseMPgraphic + \useMPgraphic{yellow}} + +\startbuffer +\setuptype[style=\ttx]% +\startcombination[3*3] + {\TestColor{(0,0,1,0)}} {\type{(0,0,1,0)}} + {\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:pass] + {All kinds of yellow (passing valued from \TEX).} + {\getbuffer} + +\startbuffer +\setuptype[style=\ttx]% +\startcombination[3*3] + {\TestColor{(0,0,1,0)}} {\type{(0,0,1,0)}} + {\TestColor{(1,1,0)}} {\type{(1,1,0)}} + {\TestColor{(.5,.5,0)}} {\type{(.5,.5,0)}} + {\TestColor{"rgbyellow"}} {\type{"rgbyellow"}} + {\TestColor{"rgbdarkyellow"}} {\type{"rgbdarkyellow"}} + {\TestColor{.5namedcolor("rgbyellow")}} {\type{.5namedcolor("rgbyellow")}} + {\TestColor{"cmyyellow"}} {\type{"cmyyellow"}} + {\TestColor{"cmydarkyellow"}} {\type{"cmydarkyellow"}} + {\TestColor{.5namedcolor("cmyyellow")}} {\type{.5namedcolor("cmyyellow")}} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:many yellows:fetch] + {All kinds of yellow (fetching values from \TEX).} + {\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% + {\startMPcode + fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1 ; + \stopMPcode} + +\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{"red"}} {\type{"red")}} + {\TestColor{"darkred"}} {\type{"darkred")}} + {\TestColor{.625namedcolor("red")}} {\type{.625namedcolor("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 +when you create documents for screen and \CMYK\ when producing for print. + +In the \METAFUN\ macro collection there is a macro \type {cmyk} that takes four +arguments, representing the cyan, magenta, yellow, and black component. Nowadays +you don't need it as we have native \CMYK. + +\startbuffer +fill unitsquare xyscaled (10cm, 5mm) withcolor cmyk(1,0,.3,.3) ; +fill unitsquare xyscaled (10cm,-5mm) withcolor (1,.3,0,.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. + +In \CONTEXT\ you can influence this conversion by changing parameters related to +color handling: + +\starttyping +\setupcolors[cmyk=yes,rgb=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 {and} [fig:cmyk 2] 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 enabled.} + {\getbuffer[cmyk]} + +\placefigure + [here][fig:cmyk 2] + {\CMYK\ support disabled, no support in \METAPOST.} + {\setupcolors[cmyk=no]\getbuffer[cmyk]\setupcolors[cmyk=yes]} + +\stopsection + +% \startsection[title={Common definitions}] +% +% \index{inclusions} +% \index{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 +% +% {\em The following is only true for \CONTEXT\ \MKII ! Users of \MKIV\ can skip +% this section.} +% +% 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 you use \CONTEXT\ \MKII\ and \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. +% +% \stopsection + +\startsection[title={One page graphics}] + +An advantage of using \CONTEXT\ to make your \METAPOST\ graphics is 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-800} that +resides on the computer of the author. + +\typefile{mfun-800} + +Given that \CONTEXT\ is present on your system, you can process this file with: + +\starttyping +context mfun-800 +\stoptyping + +You can define many graphics in one file. Later you can include individual pages +from the resulting \PDF\ file in your document: + +\startbuffer +\placefigure + {A silly figure, demonstrating that stand||alone||graphics + can be made.} + {\typesetfile[mfun-800.tex][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 + +\stopsection + +\startsection[title={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,factor=no]\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 +scales and straightforward, non||weighted, gray scales. + +\placefigure + [here][fig:color circles] + {The advantage of weighted gray over linear gray.} + {\getbuffer\setupcolors[state=start,factor=yes]} % just to be sure + +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. + +\stopsection + +\startsection[title={Instances}] + +There are a few instances predefined and if you want to isolate your own +graphics from whatever \CONTEXT\ itself cooks up, you can define more as the +extra overhead can be neglected. + +\starttabulate[|T|T|T|T|T|] +\BC name \BC format \BC extensions \BC initializations \BC method \NC \NR +\NC metafun \NC metafun \NC yes \NC yes \NC \NC \NR +\NC extrafun \NC metafun \NC yes \NC yes \NC \NC \NR +\NC lessfun \NC metafun \NC \NC \NC \NC \NR +\NC doublefun \NC metafun \NC yes \NC yes \NC double \NC \NR +\NC binaryfun \NC metafun \NC yes \NC yes \NC binary \NC \NR +\NC decimalfun \NC metafun \NC yes \NC yes \NC decimal \NC \NR +\stoptabulate + +According to this the \type {doublefun} instance is defined as: + +\starttyping +\defineMPinstance + [doublefun] + [format=metafun, + extensions=yes, + initializations=yes, + method=double] +\stoptyping + +The \type {extensions} key relates to: + +\starttyping +\startMPextensions + % some code +\stopMPextensions +\stoptyping + +that are used to pass (common) extensions to the instance. The \type +{initializations} key relates to: + +\starttyping +\startMPinitializations + % some code +\stopMPinitializations +\stoptyping + +that are used to communicate \TEX\ properties to the instance (they are +expanded each graphic). Instance bound definitions can be set with: + +\starttyping +\startMPdefinitions{doublefun} + % some code +\stopMPdefinitions +\stoptyping + +We do have more instances, for instance for the chemical subsystem. If you load +the \type {graph} module you get a double precision \type {graph} instance. We might +use more private ones in the future. + +When you make graphic pages, you can do this: + +\starttyping +\startMPpage[instance=doublefun] + % some code +\stopMPpage +\stoptyping + +When you use the other commands you can optionally specify an instance: + +\startbuffer[metafun] +\startMPcode{metafun} + draw textext(decimal pi) scaled 2 withcolor .625red ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[extrafun] +\startMPcode{extrafun} + draw textext(decimal pi) scaled 2 withcolor .625green ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[doublefun] +\startMPcode{doublefun} + draw textext(decimal pi) scaled 2 withcolor .625blue ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[binaryfun] +\startMPcode{binaryfun} + draw textext(decimal pi) scaled 2 withcolor .625yellow ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[decimalfun] +\startMPcode{decimalfun} + draw textext(decimal pi) scaled 2 withcolor .375white ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\typebuffer[metafun,extrafun,doublefun,binaryfun,decimalfun] + +The result is shown in \in {figure} [fig:instances] and as expected there +is a different value for $\pi$ reported. + +\startplacefigure[reference=fig:instances,title={Instances can use different number systems.}] + \startcombination[1*5] + {\getbuffer[metafun]} {metafun} + {\getbuffer[extrafun]} {extrafun} + {\getbuffer[doublefun]} {doublefun} + {\getbuffer[binaryfun]} {binaryfun} + {\getbuffer[decimalfun]} {decimalfun} + \stopcombination +\stopplacefigure + +You need to be aware of the fact that the results of a (for instance) double +instance can differ from a scaled (the default) one. As long as graphics can be +processed in both models (which is the case as long as the dimensions stay below +4096 base points) the outcome is probably not that different. However, we've seen +that the accuracy of for instance $\pi$ (just a variable) differs. I like to use +random values and the random generators are definitely different: each of the +number libraries has its own implementation. Let's look at that. We define two +random graphic generators: + +\startbuffer +\startuseMPgraphic{normaldeviate} + randomseed := 100 ; + draw fullsquare + withpen pencircle scaled 1/200 + withcolor .5white ; + for i=1 upto 500 : + draw (normaldeviate,normaldeviate) + scaled 1/3 + withpen pencircle scaled 1/30 + withtransparency (1,.5) ; + endfor ; + setbounds currentpicture to + boundingbox fullcircle + enlarged 1/2 ; + currentpicture := + currentpicture + xsized (2TextWidth/5) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +And: + +\startbuffer +\startuseMPgraphic{uniformdeviate} + randomseed := 100 ; + draw fullsquare + withpen pencircle scaled 1/200 + withcolor .5white ; + for i=1 upto 500 : + draw (-1/2 + uniformdeviate 1,-1/2 + uniformdeviate 1) + withpen pencircle scaled 1/30 + withtransparency (1,.5) ; + endfor ; + setbounds currentpicture to + boundingbox fullcircle + enlarged 1/2 ; + currentpicture := + currentpicture + xsized (2TextWidth/5) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We show the results for a normaldeviate in \in {figure} [fig:random:1] \in {upto} +[fig:random:4] you see the randomizers per number system. In \in {figure} +[fig:random:compared] we demonstrate that the scaled version has its own variant. + +\unexpanded\def\TestRandomFun#1#2#3% + {\startMPcode{#1} + draw image(\includeMPgraphic{#2}) + withcolor #3 ; + \stopMPcode} + +\startplacefigure[reference=fig:random:1,title={The scaled randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{metafun} {normaldeviate} {darkred}} {normaldeviate} + {\TestRandomFun{metafun} {uniformdeviate}{darkred}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:2,title={The double randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{doublefun} {normaldeviate} {darkgreen}} {normaldeviate} + {\TestRandomFun{doublefun} {uniformdeviate}{darkgreen}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:3,title={The decimal randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{decimalfun}{normaldeviate} {darkblue}} {normaldeviate} + {\TestRandomFun{decimalfun}{uniformdeviate}{darkblue}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:4,title={The binary randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{binaryfun} {normaldeviate} {darkyellow}} {normaldeviate} + {\TestRandomFun{binaryfun} {uniformdeviate}{darkyellow}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:compared,title={Normaldeviate and uniformdeviate overlayed.}] + \pushrandomseed + \startcombination[2*1] + \bgroup + \startoverlay + {\TestRandomFun{metafun} {normaldeviate} {darkred}} + {\TestRandomFun{doublefun} {normaldeviate} {darkgreen}} + {\TestRandomFun{decimalfun}{normaldeviate} {darkblue}} + {\TestRandomFun{binaryfun} {normaldeviate} {darkyellow}} + \stopoverlay + \egroup {normaldeviate} + \bgroup + \startoverlay + {\TestRandomFun{metafun} {uniformdeviate}{darkred}} + {\TestRandomFun{doublefun} {uniformdeviate}{darkgreen}} + {\TestRandomFun{decimalfun}{uniformdeviate}{darkblue}} + {\TestRandomFun{binaryfun} {uniformdeviate}{darkyellow}} + \stopoverlay + \egroup {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\stopsection + +\stopchapter + +\stopcomponent |