diff options
Diffstat (limited to 'src/cd/cd.html')
| -rw-r--r-- | src/cd/cd.html | 1156 |
1 files changed, 1156 insertions, 0 deletions
diff --git a/src/cd/cd.html b/src/cd/cd.html new file mode 100644 index 0000000..31471b1 --- /dev/null +++ b/src/cd/cd.html @@ -0,0 +1,1156 @@ +<HTML><HEAD> +<META HTTP-EQUIV="author" CONTENT="G. Edward Johnson (lorax@nist.gov)"> +<META HTTP-EQUIV="keywords" CONTENT="CGM, computer graphics metafile, vector graphics, ansi standard, nist, graphics library"> +<META HTTP-EQUIV="abstract" CONTENT="CGM Draw is a freely available library for generating CGM files from a C program. With CGM Draw your code can quickly draw images complete with lines, arcs, rectangles, polygons, and text."> +<LINK HREF="mailto:lorax@nist.gov"> +<TITLE>CD -- CGM Draw Documentation</TITLE> +</HEAD> +<BODY> +<H1>CD Documentation</H1> +<H2>A graphics library for fast CGM creation</H2> +<P>Follow this link for the +<A HREF="http://speckle.ncsl.nist.gov/~lorax/cgm/cd.html">latest version +of the CD documentation</A>.</P> + +<H3>Table of Contents</H3> +<UL> + <LI><A HREF="#notice">Credits and license terms</A></LI> + <LI><A HREF="#whatsnew">What's new</A></LI> + <LI><A HREF="#whatis">What is cd?</A></LI> + <LI><A HREF="#required">What else do I need to use cd?</A> + <LI><A HREF="#get">How do I get cd?</A></LI> + <LI><A HREF="#build">How do I build cd?</A></LI> + <LI><A HREF="#basics">cd basics: using cd in your program</A></LI> + <LI><A HREF="#reference">Function and type reference by category</A></LI> + <LI><A HREF="#replacegd">Using cd instead of gd</A></LI> + <LI><A HREF="#informing"><strong>Please</strong> + tell us you're using cd!</A></LI> + +</UL> + +<A NAME="notice"><H3>Credits and license terms</H3></A> + +<P>cd was written by <A HREF="http://speckle.ncsl.nist.gov/~lorax/">G. +Edward Johnson</A> at the <A HREF="http://www.nist.gov/">National +Institute of Standards and Technology</A>. You may use this code +for any purpose, but please give us credit. If find cd useful, please +<A HREF="mailto:lorax@nist.gov">let us know</A>. +cd software produced by NIST, an agency of the U.S. government, +is by statute not subject to copyright in the United States. +Recipients of this software assume all responsibilities associated +with its operation, modification and maintenance. +</P><P> +Some of this code is from the gd library written by Thomas Boutell. +Mr. Boutell did not help with this project, so do not send him questions +about cd. +Code from gd is clearly marked in the source. Additionally, this document +is patterned after the gd documentation, some portions have been copied +verbatim. gd is covered by the following license.</P> +<P> +gd 1.2 is copyright 1994, 1995, Quest Protein Database Center, +Cold Spring Harbor Labs. Permission granted to copy and distribute +this work provided that this notice remains intact. Credit +for the library must be given to the Quest Protein Database Center, +Cold Spring Harbor Labs, in all derived works. This does not +affect your ownership of the derived work itself, and the intent +is to assure proper credit for Quest, not to interfere with your +use of gd. If you have questions, ask. ("Derived works" +includes all programs that utilize the library. Credit must +be given in user-visible documentation.)</P> +<P> +The Quest Protein Database Center is funded under Grant P41-RR02188 by +the National Institutes of Health. +</P> +<A NAME="whatsnew"><H3>What's new?</H3></A> +<H4>Version 1.2</H4> +<P> +<UL> + <LI>New Text attributes: + <UL> + <LI>cdSetTextPath sets the text direction as right, left, up, or down</LI> + <LI>cdSetTextOrient sets the angle of the text</LI> + </UL></LI> + <LI>Multiple pictures in a file. Now you can put more than one + picture in a cgm file, see cdCgmNewPic for details.</LI> + <LI>Internal changes like using short int's in some places so it may + take less space in memory when using 16 or 64 bit compilers.</LI> + <LI>New example programs. + <UL> + <LI>cdtext to show the new text attributes.</LI> + <LI>cdmulti to show the multiple picture capability.</LI> + </UL></LI> +</UL> + +<H4>Version 1.1</H4> +<P>Thanks to Wolfgang Glunz <wogl@weisshorn.zfe.siemens.de> who purified it, +pointed out some bugs and did the Borland makefile. +<UL> + <LI>Switched from using malloc to calloc most cases, solving an off + by one error in a function I then eliminated.</LI> + <LI>Added a Makefile for Borland Turbo C++</LI> + <LI>Fixed a couple of spelling errors, cleared out some dead code, and + some other trivial things.</LI> + <LI>Added a new example program cdsimple which walks you through some + basics.</LI> + <LI>Added a new function <EM>cdPolyLine</EM> for when you want lines + with more than two points</LI> +</UL> +</P> + +<H4>Version 1.0</H4> +<P>Basically, everything is new, this is the first release. +</P> +<A NAME="whatis"><H3>What is cd?</H3></A> +<P> +cd is a graphics library. It allows your code to quickly draw +images complete with lines, arcs, rectangles, polygons, text, and multiple +colors. most geometric shapes can be filled or have a hatch pattern as well. +The output is a CGM file. If you are unsure of what CGM is, or if +CGM is appropriate for your project, see the +<A HREF="http://speckle.ncsl.nist.gov/~lsr/cgm.htm">NIST CGM Homepage</A>. +</P><P> +Every effort has been made to ensure that the generated cgm files +conform to the standard, however, if you do not use the library +properly, you could generate invalid metafiles that no one is able +to read, so be careful. +</P> + + +<A NAME="required"><H3>What else do I need to use cd?</H3></A> +<P> +To use cd, you will need an ANSI C compiler. Any full-ANSI-standard +C compiler should be adequate, although those with PCs will need to replace +the Makefile with one of their own. <STRONG>The cc compiler released +with SunOS 4.1.3 is not an ANSI C compiler. Get gcc, which is freely +available. See the Sun-related newsgroups for more information.</STRONG> +</P><P> +You will also want a CGM viewer, if you do not already have +one for your system, since you will need a good way to check the +results of your work. +</P> +<A NAME="get"><H3>How do I get cd?</H3></A> +<P> + +You can +<A HREF="ftp://zing.ncsl.nist.gov/cgm/"> +fetch cd as a gzip'ed tar file</A>, or you can FTP it directly from +zing.ncsl.nist.gov in the subdirectory cgm. +</P> +<A NAME="build"><H3>How do I build cd?</H3></A> +<P> +<em>Note:</em> if you have a non-Unix system, you will need +to acquire versions of "gunzip" and "tar" suitable for +your system. Both have been ported to PC and Mac +environments. Consult newsgroups relevant to your +particular system. +<PRE> +gunzip cd1.2.tar.gz +tar -xf cd1.2.tar +</PRE> +This will create the directory "cd1.2" beneath the current +directory. +</P><P> +change to this directory and examine the Makefile, which you may need +to change slightly depending on your installation (or more than +slightly for a Windows or Mac environment). +On UNIX systems the command "make all" will create the cd library +and three example programs, <EM>cdsimple</EM>, <EM>cdtest</EM>, +and <EM>color16</EM>. If you are using Borland Turbo C++ version 3 +(or later I hope) try to make it using makefile.bor +</P><P> +CGM files are always in Network Byte order, Big-Endian systems use this +ordering. I wrote this on a Big-Endian machine, but it seems to work on +Little-Endian's as well. I have Tested cd on Sun's, Ultrix, Linux, +IRIX, and DOS (Borland). +If you get it to run on other systems, drop me a note. +</P> + +<A NAME="basics"><H3>cd basics: using cd in your program</H3></A> +<P> +cd lets you create CGM images on the fly. To use cd in your +program, include the file cd.h, and link with the libcd.a +library produced by "make libcd.a", under Unix. You will +need to adapt the makefile for your needs if you are using +a non-Unix operating system, but this is very straightforward. +</P><P> +Look at the example programs included in this distribution for +examples of using cd. The programs are <EM>cdsimple</EM> which is +a heavily commented program that makes a small cgm. <EM>cdtest</EM> which +makes a cgm with every different kind of shape you can use. It +has lines, circles, arcs, ellipses, rectangles, polygons, and text as +well as examples for setting the attributes for them. So look +at it closely, it is your friend. The other example program, +<EM>color16</EM> allocates 16 colors using cdImageColor16 (these +are the 16 standard Windows colors). Than it draws a rectangle +with each of them. These programs are created automatically when you +"make all". +</P> + + +<H2><A NAME="reference">Function and Type reference</A></H2> +<UL> + <LI><A HREF="#types">Types</A></LI> + <UL> + <LI><A HREF="#cdImage">Image</A></LI> + <LI><A HREF="#cdImagePtr">Image Pointer</A></LI> + <LI><A HREF="#cdPoint">Point</A></LI> + <LI><A HREF="#cdPointPtr">Point Pointer</A></LI> + </UL> + <LI><A HREF="#creating">Image creation, destruction, and saving</A></LI> + <UL> + <LI><A HREF="#cdImageCreate">Creation</A></LI> + <LI><A HREF="#cdImageDestroy">Destruction</A></LI> + <LI><A HREF="#cdImageCgm">Saving</A></LI> + </UL> + <LI><A HREF="#drawing">Drawing functions</A> + <UL> + <LI><A HREF="#cdLine">Lines</A></LI> + <LI><A HREF="#cdPolyLine">Polylines</A></LI> + <LI><A HREF="#cdRectangle">Rectangles</A></LI> + <LI><A HREF="#cdCircle">Circles</A></LI> + <LI><A HREF="#cdArc3Pt">Arcs</A></LI> + <LI><A HREF="#cdArc3PtClose">Closed Arcs</A></LI> + <LI><A HREF="#cdEllipse">Ellipses</A></LI> + <LI><A HREF="#cdPolygon">Polygons</A></LI> + </UL> + </LI> + <LI><A HREF="#fonts">Font and text-handling functions</A></LI> + <UL> + <LI><A HREF="#cdSetTextAttrib">Text Attributes</A> + <UL> + <LI><A HREF="#cdSetTextFont">The Font of text</A></LI> + <LI><A HREF="#cdSetTextColor">The Color of text</A></LI> + <LI><A HREF="#cdSetTextHeight">The Height of text</A></LI> + <LI><A HREF="#cdSetTextPath">The path text follows</A></LI> + <LI><A HREF="#cdSetTextOrient">The angle of text</A></LI> + </UL></LI> + <LI><A HREF="#cdText">Writing Text</A></LI> + </UL> + <LI><A HREF="#attrib">Line, Edge, and Fill attributes</A></LI> + <UL> + <LI><A HREF="#cdSetLineAttrib">Line Attributes</A> + <UL> + <LI><A HREF="#cdSetLineType">Line Type</A> + <LI><A HREF="#cdSetLineWidth">Line Width</A> + <LI><A HREF="#cdSetLineColor">Line Color</A> + </UL></LI> + <LI><A HREF="#cdSetShapeFillAttrib">Filled Area Attributes</A> + <UL> + <LI><A HREF="#cdSetFillStyle">Interior Style</A> + <LI><A HREF="#cdSetFillColor">Fill Color</A> + <LI><A HREF="#cdSetFillHatch">Hatch Index</A> + </UL></LI> + <LI><A HREF="#cdSetShapeEdgeAttrib">Exterior Filled Area Attributes</A> + <UL> + <LI><A HREF="#cdSetEdgeType">Edge Type</A> + <LI><A HREF="#cdSetEdgeWidth">Edge Width</A> + <LI><A HREF="#cdSetEdgeColor">Edge Colour</A> + <LI><A HREF="#cdSetEdgeVis">Edge Visibility</A> + </UL></LI> + </UL> + <LI><A HREF="#colors">Color handling functions</A></LI> + <UL> + <LI><A HREF="#cdImageColorAllocate">Allocate a new color</A></LI> + <LI><A HREF="#cdImageColorClosest">Find a close match</A></LI> + <LI><A HREF="#cdImageColorExact">Find an exact match</A></LI> + <LI><A HREF="#cdImageColorsTotal">Number of allocated colors</A></LI> + <LI><A HREF="#cdImageColorRed">Red portion of color</A></LI> + <LI><A HREF="#cdImageColorGreen">Green portion of color</A></LI> + <LI><A HREF="#cdImageColorBlue">Blue portion of color</A></LI> + </UL> + <LI><A HREF="#constants">Constants</A></LI> +</UL> + +<H3><A NAME="types">Types</A></H3> +<!-- ***** Types ***** --> +<DL> +<DT> +<A NAME="cdImage">cdImage</A> +<STRONG>(Type)</STRONG></DT> + <DD>The data structure in which cd stores images. + <A HREF="#cdImageCreate">cdImageCreate</A> returns a pointer to this + type, and other functions expect to receive a pointer to this type as + their first argument. + </DD> + +<DT> +<A NAME="cdImagePtr">cdImagePtr</A> +<STRONG>(Type)</STRONG></DT> + <DD>A pointer to an image structure. + <A HREF="#cdImageCreate">cdImageCreate</A> returns this type, and the other + functions expect it as the first argument. you may read the members + <EM>sx</EM> (size of x axis), <EM>sy</EM> (size of y axis), + <EM>colorsTotal</EM> (total colors allocated), <EM>red</EM> (red component + of colors; an array of 256 integers between 0 and 255), + <EM>green</EM> (green commponent of colors), and <EM>blue</EM> (blue + component of colors). Please do so using the macros provided. + <STRONG>Do Not</STRONG> set the members directly from your code, use + the functions provided. + </DD> + +<DT> +<A NAME="cdPoint">cdPoint</A> +<STRONG>(Type)</STRONG></DT> + <DD>Represents a collection of points in the coordinate space of the image; + used by <A HREF="#cdPolygon">cdPolygon</A> and + by <A HREF="#cdPolyLine">cdPolyLine</A>. + </P><P> + cdPointPtr is defined in cd.h, basically, it is an array of integer pairs + p[m].x and p[m].y containing the x and y values respectively. pcnt + is the number of points in this array (not the index of the last point, + which is pcnt-1). pcnt must be at least 3 for polygons or 2 for + polylines. + </P><P> + Declare it with <CODE>cdPoint points[pcnt]</CODE> where <EM>pcnt</EM> + is the upper limit of the number of points you wish to have. then fill + it in with <CODE>points[0].x = x0; points[0].y = y0;</CODE> and the like. + </DD> + +<DT> +<A NAME="cdPointPtr">cdPointPtr</A> +<STRONG>(Type)</STRONG> + <DD>A pointer to a <A HREF="#cdPoint">cdPoint</A> structure; passed + as an argument to <A HREF="#cdPolygon">cdPolygon</A> + and to <A HREF="#cdPolyLine">cdPolyLine</A>. + </DD> + +</DL> + + +<H3><A NAME="creating">Image creation, destruction, and saving</A></H3> +<!-- ***** Image Functions ***** --> + +<DL> +<DT> +<A NAME="cdImageCreate">cdImageCreate(int sx, int sy)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageCreate is called to create images. Invoke cdImageCreate with + the x and y dimensions of the desired image. cdImageCreate returns a + <A HREF="#cdImagePtr">cdImagePtr</A> to the new image, or NULL if unable + to allocate the image. The image must eventually be destroyed + using <A HREF="#cdImageDestroy">cdImageDestroy</A> + </DD> + +<DT> +<A NAME="cdImageDestroy">cdImageDestroy(cdImagePtr im)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageDestroy is used to free the memory associated with + and image. It is important to invoke cdImageDestroy before exiting + your program or assigning a new image to a + <A HREF="#cdImagePtr">cdImagePtr</A> variable. + </DD> + +<DT> +<A NAME="cdCgmNewPic">cdCgmNewPic(cdImagePtr im, int sticky)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdCgmNewPic allows for a single CGM file to contain multiple + pictures. If <EM>sticky</EM> is 0 then all attributes will be reset to + their default condition and the color table will be cleared. + If <EM>sticky</EM> is 1 then all attributes and the color table will + be carried over to the new picture. + <STRONG>NOTE:</STRONG> as of now (version 1.2) the only allowable value + for <EM>sticky</EM> is 0. If you set it to 1, the function will fail. + </DD> + +<DT> +<A NAME="cdImageCgm">cdImageCgm(cdImagePtr im, FILE *out)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageCgm outputs the specified image to the specified file + in the CGM image format. The file must be open for + writing. Under MSDOS, it is important to use "wb" as opposed to simply + "w" as the mode when opening the file, and under UNIX there is no penalty + for doing so. cdImageCgm does <EM>not</EM> close the file, your code + must do that. + </DD> + +</DL> + + +<H3><A NAME="drawing">Drawing Functions</A></H3> +<!-- ***** Drawing Functions ***** --> + +<DL> +<DT> +<A NAME="cdLine">int cdLine(cdImagePtr im, int x1, int y1, int x2, int y2)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Polyline; Elem Class 4; Elem ID 1<BR> + Returns 1 for success, 0 for failure. + cdLine is used to draw a line between two endpoints (x1,y1) and (x2,y2) + This line is drawn using the attributes set by + <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> + The attributes that may be set are <A HREF="#cdSetLineType">Line Type</A>, + <A HREF="#cdSetLineWidth">Line Width</A>, or + <A HREF="#cdSetLineColor">Line Color</A>. + The endpoints must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdPolyLine">int cdPolyLine(cdImagePtr im, cdPointPtr p, int n)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Polyline; Elem Class 4; Elem ID 1<BR> + Returns 1 for success, 0 for failure. + cdPolyLine draws a line connecting all the points specified by + <A HREF="#cdPointPtr">cdPointPtr</A>. <em>n</EM> is the number of + points in cdPointPtr, (not the index of the last point, which is n-1). + This line is drawn using the attributes set by + <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> + The attributes that may be set are <A HREF="#cdSetLineType">Line Type</A>, + <A HREF="#cdSetLineWidth">Line Width</A>, or + <A HREF="#cdSetLineColor">Line Color</A>. + Note that it uses line attributes not edge attributes for drawing the + line. + The endpoints must be within the bounds of the picture. + </P><P> + cdPointPtr is defined in cd.h, basically, it is two arrays of integers + p[m].x and p[m].y containing the x and y values respectively. n + is the number of points in this array (not the index of the last point, + which is n-1). n must be at least 2 (otherwise + you really don't have much of a line, it is closer to a point.) + </P></DD> + +<DT> +<A NAME="cdRectangle">int cdRectangle(cdImagePtr im, int x1, int y1, int x2, int y2)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: rectangle; Elem Class 4; Elem ID 11<BR> + Returns 1 for success, 0 for failure. + cdRectangle draws a line which has (x1,y1) as the upper left corner + and (x2,y2) as the lower right corner. + This rectangle is drawn using the + attributes set by <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> + and by <A HREF="#cdSetShapeEdgeAttrib">cdSetShapeEdgeAttrib</A>. + The fill attributes that may be set are + <A HREF="#cdSetFillStyle">Fill Style</A>, + <A HREF="#cdSetFillColor">Fill Color</A>, or + <A HREF="#cdSetFillHatch">Fill Hatch</A>. + The edge attributes that may be set are + <A HREF="#cdSetEdgeType">Edge Type</A>, + <A HREF="#cdSetEdgeWidth">Edge Width</A>, + <A HREF="#cdSetEdgeColor">Edge Color</A>, or + <A HREF="#cdSetEdgeVis">Edge Visibility</A>. + Note that it uses Edge attributes not line attributes for drawing the + perimeter of the rectangle. + The Rectangle must be within the bounds of the picture. + </DD> + + +<DT> +<A NAME="cdCircle">int cdCircle(cdImagePtr im, int cx, int cy, int r)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: circle; Elem Class 4; Elem ID 12<BR> + Returns 1 for success, 0 for failure. + cdCircle draws a circle which has center (cx, cy) and radius r. + This circle is drawn using the attributes set by + <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> + and by <A HREF="#cdSetShapeEdgeAttrib">cdSetShapeEdgeAttrib</A>. + The fill attributes that may be set are + <A HREF="#cdSetFillStyle">Fill Style</A>, + <A HREF="#cdSetFillColor">Fill Color</A>, or + <A HREF="#cdSetFillHatch">Fill Hatch</A>. + The edge attributes that may be set are + <A HREF="#cdSetEdgeType">Edge Type</A>, + <A HREF="#cdSetEdgeWidth">Edge Width</A>, + <A HREF="#cdSetEdgeColor">Edge Color</A>, or + <A HREF="#cdSetEdgeVis">Edge Visibility</A>. + Note that it uses Edge attributes not line attributes for drawing the + perimeter of the Circle. + The Circle must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdArc3Pt">int cdArc3Pt(cdImagePtr im, int sx, int sy, int ix, int iy, int ex, int ey)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Cicular Arc 3 Point; Elem Class 4; Elem ID 13<BR> + Returns 1 for success, 0 for failure. + cdArc3Pt draws an arc specified by the given points. (sx,sy) is the + start of the arc, (ix,iy) is the middle of the arc, and (ex,ey) is the + end of the arc. + This arc is drawn using the attributes set by + <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> + The attributes that may be set are <A HREF="#cdSetLineType">Line Type</A>, + <A HREF="#cdSetLineWidth">Line Width</A>, or + <A HREF="#cdSetLineColor">Line Color</A>. + Note that it uses Line attributesfor drawing + the perimiter of the arc, not Edge attributes like + <A HREF="#cdArc3PtClose">cdArc3PtClose</A>. + The Arc must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdArc3PtClose">int cdArc3PtClose(cdImagePtr im, int sx, int sy, int ix, int iy, int ex, int ey, int cl)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Cicular Arc 3 Point Close; Elem Class 4; Elem ID 14<BR> + Returns 1 for success, 0 for failure. + cdArc3PtClose draws an arc specified by the given points. (sx,sy) is the + start of the arc, (ix,iy) is the middle of the arc, and (ex,ey) is the + end of the arc. The arc is closed base on <EM>cl</EM>. If <EM>cl</EM> is + 0 then pie closure will be used, resulting in a pie shaped slice. if + <EM>cl</EM> is 1 then cord closure will be used and a straight line will + be drawn from one endpoint to the other. + This arc is drawn using the attributes set by + <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> + and by <A HREF="#cdSetShapeEdgeAttrib">cdSetShapeEdgeAttrib</A>. + The fill attributes that may be set are + <A HREF="#cdSetFillStyle">Fill Style</A>, + <A HREF="#cdSetFillColor">Fill Color</A>, or + <A HREF="#cdSetFillHatch">Fill Hatch</A>. + The edge attributes that may be set are + <A HREF="#cdSetEdgeType">Edge Type</A>, + <A HREF="#cdSetEdgeWidth">Edge Width</A>, + <A HREF="#cdSetEdgeColor">Edge Color</A>, or + <A HREF="#cdSetEdgeVis">Edge Visibility</A>. + Note that it uses Edge attributes for drawing the + perimeter of the arc, not Line attributes like + <A HREF="#cdArc3Pt">cdArc3Pt</A>. + The Arc must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdEllipse">int cdEllipse(cdImagePtr im, int cx, int cy, int d1x, int d1y, int d2x, int d2y)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Ellipse; Elem Class 4; Elem ID 17<BR> + Returns 1 for success, 0 for failure. + cdEllipse draws an ellipse specified by the given points. (cx,cy) is + the center, (d1x,d1y) is the endpoint of the first conjugate diameter, + (d2x, d2y) is the endpoint of the second conjugate diameter. I can't + really explain this one, if you come up with a good description, + <A HREF="mailto:lorax@nist.gov" NAME="Ellipse Description">mail me</A>. + This ellipse is drawn using the attributes set by + <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> + and by <A HREF="#cdSetShapeEdgeAttrib">cdSetShapeEdgeAttrib</A>. + The fill attributes that may be set are + <A HREF="#cdSetFillStyle">Fill Style</A>, + <A HREF="#cdSetFillColor">Fill Color</A>, or + <A HREF="#cdSetFillHatch">Fill Hatch</A>. + The edge attributes that may be set are + <A HREF="#cdSetEdgeType">Edge Type</A>, + <A HREF="#cdSetEdgeWidth">Edge Width</A>, + <A HREF="#cdSetEdgeColor">Edge Color</A>, or + <A HREF="#cdSetEdgeVis">Edge Visibility</A>. + Note that it uses Edge attributes not line attributes for drawing the + perimeter of the Ellipse. + The Ellipse must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdPolygon">int cdPolygon(cdImagePtr im, cdPointPtr p, int n)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Polygon; Elem Class 4; Elem ID 7<BR> + Returns 1 for success, 0 for failure. + cdPolygon draws a closed polygon connecting the points specified by + <A HREF="#cdPointPtr">cdPointPtr</A>. <em>n</EM> is the number of + points in cdPointPtr, (not the index of the last point, which is n-1). + This polygon is drawn using the attributes set by + <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> + and by <A HREF="#cdSetShapeEdgeAttrib">cdSetShapeEdgeAttrib</A>. + The fill attributes that may be set are + <A HREF="#cdSetFillStyle">Fill Style</A>, + <A HREF="#cdSetFillColor">Fill Color</A>, or + <A HREF="#cdSetFillHatch">Fill Hatch</A>. + The edge attributes that may be set are + <A HREF="#cdSetEdgeType">Edge Type</A>, + <A HREF="#cdSetEdgeWidth">Edge Width</A>, + <A HREF="#cdSetEdgeColor">Edge Color</A>, or + <A HREF="#cdSetEdgeVis">Edge Visibility</A>. + Note that it uses Edge attributes not line attributes for drawing the + perimeter of the polygon. + The polygon must be within the bounds of the picture. + </P><P> + cdPointPtr is defined in cd.h, basically, it is two arrays of integers + p[m].x and p[m].y containing the x and y values respectively. n + is the number of points in this array (not the index of the last point, + which is n-1). n must be at least 3 (otherwise + you really don't have much of a polygon, it is closer to a line.) + </P></DD> + +</DL> + + +<H3><A NAME="fonts">Font and text-handling functions</A></H3> +<!-- ***** Font and text-handling Functions ***** --> +<DL> +<DT> +<A NAME="cdSetTextAttrib">int cdSetTextAttrib(cdImagePtr im, int font, int color, int height)</A> +<STRONG>(Function)</STRONG></DT> + <DD> + Returns 1 for success, 0 for failure. + cdSetTextAttrib sets the attributes for text elements. + The <A HREF="#fonts">Font functions</A> are affected by this. + These attributes stay in effect until they are changed, you don't + have to call this function every time. If you call the function with + a value of -1 for any of the attributes they will not be changed. If + you call the function with the same value for an attribute as it + already has, it will not be changed (so you don't have to worry about + bloating your CGM with redundant attribute changes.) + It calls three functions. <A HREF="#cdSetTextFont">cdSetTextFont</A> + to set the index into the font table, + <A HREF="#cdSetTextColor">cdSetTextColor</A> with <EM>color</EM> to set + the forground color of the text, and + <A HREF="#cdSetTextHeight">cdSetTextHeight</A> with <EM>height</EM> to + set the height of the text. + You may also call any of the three functions individually if you like. + </DD> + +<DT> +<A NAME="cdText">int cdText(cdImagePtr im, int x, int y, const char *ts)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Graphic Primitive: Text; Elem Class 4; Elem ID 4<BR> + Returns 1 for success, 0 for failure. + cdText puts a string of text <EM>ts</EM> starting at position (x,y) + The Text is drawn using the attributes set with + <A HREF="#cdSetTextAttrib">cdSetTextAttrib</A>. The attributes that + may be set are: + <A HREF="#cdSetTextFont">cdSetTextFont</A>, + <A HREF="#cdSetTextColor">cdSetTextColor</A>, or + <A HREF="#cdSetTextHeight">cdSetTextHeight</A>. + The point where the text starts must be within the bounds of the picture. + </DD> + +<DT> +<A NAME="cdSetTextPath">int cdSetTextPath(cdImagePtr im, int tpath)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Text Path; Elem Class 5; Elem ID 17<BR> + Returns 1 for success, 0 for failure. + sets the path of the text to <EM>tpath</EM>. tpath is an integer + with one of the following values + <UL> + <LI>0 for right</LI> + <LI>1 for left</LI> + <LI>2 for up</LI> + <LI>3 for down</LI> + </UL> + These are all relative to the charater base vector and up vector. If you + haven't changed them (with <A HREF="#cdSetTextOrient">cdSetTextOrient</A> + then the direction of the text will be right to left for 0, left to right + for 1, bottom to top for 2, and top to bottom for 3. Each individual + letter will still be facing in the normal direction. If you want to + rotate the text use <A HREF="#cdSetTextOrient">cdSetTextOrient</A>. + </P><P> + Things get more interesting if you use + <A HREF="#cdSetTextOrient">cdSetTextOrient</A> with this function. + A more exact definition of <EM>tpath</EM> is + <UL> + <LI>0 right -- the direction of the character base vector</LI> + <LI>1 left -- 180 degrees from the direction of the character + base vector</LI> + <LI>2 up -- the direction of the character up vector</LI> + <LI>3 down -- 180 degrees from the direction of the character + up vector</LI> + </UL> + </P> + </DD> + +<DT> +<A NAME="cdSetTextOrient">int cdSetTextOrient(cdImagePtr im, int xup, int yup, int xbase, int ybase)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Character Orientation; Elem Class 5; Elem ID 16<BR> + Returns 1 for success, 0 for failure. + (xbase,ybase) is the run and the rise of the line that the text is + written along. For regular text that is rotated, set xup = -ybase + and yup = xbase. Setting it to something different will result in + skewed text (which may be what you want.) Text written from bottom to + top at a 90 degree angle would have the following parameters + xup=-1, yup=0, xbase=0, ybase=1 + </P><P> + This function adds the Orientation to the metafile every time. + It does not interpert an attribute value of -1 as no change like many + functions do, although if you + put in the same numbers it won't re-add it to the meta file. + </P></DD> + +<DT> +<A NAME="cdSetTextFont">int cdSetTextFont(cdImagePtr im, int font)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Text Font Index; Elem Class 5; Elem ID 10<BR> + Returns 1 for success, 0 for failure. + Sets the font index to <EM>font</EM>. It is an index into the + font table, the possible values are: + <UL> + <LI>1 for Times</LI> + <LI>2 for Times Bold</LI> + <LI>3 for Times Italic</LI> + <LI>4 for Times Bold Italic</LI> + <LI>5 for Helvetica</LI> + <LI>6 for Helvetica Bold</LI> + <LI>7 for Helvetica Italic</LI> + <LI>8 for Helvetica Bold Italic</LI> + </UL> + <EM>font</EM> must be one of these values or the function will fail. + See <A HREF="#cdSetTextAttrib">cdSetTextAttrib</A> for more information + on this and related functions. + </DD> + +<DT> +<A NAME="cdSetTextColor">int cdSetTextColor(cdImagePtr im, int color)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Text Colour; Elem Class 5; Elem ID 14<BR> + Returns 1 for success, 0 for failure. + Sets the foreground color of text to <EM>color</EM>. This should be + an integer which is an index into the color table that you have + previously allocated. See <A HREF="#cdSetTextAttrib">cdSetTextAttrib</A> + for more information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetTextHeight">int cdSetTextHeight(cdImagePtr im, int height)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Character Height; Elem Class 5; Elem ID 15<BR> + Returns 1 for success, 0 for failure. + <EM>height</EM> is an integer for the height of the text you are displaying. + Bigger numbers make larger text. The size of the text is dependent on + the size of the picture. + See <A HREF="#cdSetTextAttrib">cdSetTextAttrib</A> + for more information on this and related functions. + </DD> + +</DL> + + +<H3><A NAME="attrib">Line, Edge, and Fill attributes</A></H3> +<!-- ***** Line, Edge, and Fill Attributes ***** --> +<DL> +<DT> +<A NAME="cdSetLineAttrib">int cdSetLineAttrib(cdImagePtr im, int lntype, int lnwidth, int lncolor)</A> +<STRONG>(Function)</STRONG></DT> + <DD> + Returns 1 for success, 0 for failure. + cdSetLineAttrib sets the attributes for lines and non-closed area elements. + The <A HREF="#drawing">drawing functions</A> affected are + <UL> + <LI><A HREF="#cdLine">Lines</A></LI> + <LI><A HREF="#cdArc3Pt">Arcs</A></LI> + </UL> + These attributes stay in effect until they are changed, you + don't have to call this function every time. If you call the function with + a value of -1 for any of the attributes they will not be changed. If + you call the function with the same value for an attribute as it + already has, it will not be changed (so you don't have to worry about + bloating your CGM with redundant attribute changes.) + It calls three functions. <A HREF="#cdSetLineType">cdSetLineType</A> + with <EM>lntype</EM> to set the line type (solid, dashed, etc), + <A HREF="#cdSetLineWidth">cdSetLineWidth</A> with <EM>lnwidth</EM> to + set how wide the line is, and <A HREF="#cdSetLineColor">cdSetLineColor</A> + to set the color of the line. + You may also call any of the three functions individually if you like. + </DD> + +<DT> +<A NAME="cdSetShapeFillAttrib">int cdSetShapeFillAttrib(cdImagePtr im, int instyle, int incolor, int inhatch)</A> +<STRONG>(Function)</STRONG></DT> + <DD> + Returns 1 for success, 0 for failure. + cdSetShapeFillAttrib sets the attributes for the interior of closed area + elements. + The <A HREF="#drawing">drawing functions</A>affected are + <UL> + <LI><A HREF="#cdRectangle">Rectangles</A></LI> + <LI><A HREF="#cdCircle">Circles</A></LI> + <LI><A HREF="#cdArc3PtClose">Closed Arcs</A></LI> + <LI><A HREF="#cdEllipse">Ellipses</A></LI> + </UL> + These attributes stay in effect until they are changed, you + don't have to call this function every time. If you call the function with + a value of -1 for any of the attributes they will not be changed. If + you call the function with the same value for an attribute as it + already has, it will not be changed (so you don't have to worry about + bloating your CGM with repetitive attribute changes. + It calls three functions. + <A HREF="#cdSetFillStyle">cdSetFillStyle</A> with <EM>instyle</EM> to set + the interior style (solid, hatch, empty), + <A HREF="#cdSetFillColor">cdSetFillColor</A> with <EM>incolor</EM> to set + the interior color (used if instyle is solid or hatch), and + <A HREF="#cdSetFillHatch">cdSetFillHatch</A> with <EM>inhatch</EM> to set + the hatch style (hor lines, vert lines, crosshatch, etc) (used if + instyle is hatch). + You may also call any of the three functions individually if you like. + </DD> + +<DT> +<A NAME="cdSetShapeEdgeAttrib">int cdSetShapeEdgeAttrib(cdImagePtr im, int edtype, int edwidth, int edcolor, int edvis)</A> +<STRONG>(Function)</STRONG></DT> + <DD> + Returns 1 for success, 0 for failure. + cdSetShapeEdgeAttrib sets the attributes for the perimeter of + Filled area elements. It might seem logical to use the line attributes + instead, but that is not the case. + The <A HREF="#drawing">drawing functions</A>affected are + <UL> + <LI><A HREF="#cdRectangle">Rectangles</A></LI> + <LI><A HREF="#cdCircle">Circles</A></LI> + <LI><A HREF="#cdArc3PtClose">Closed Arcs</A></LI> + <LI><A HREF="#cdEllipse">Ellipses</A></LI> + </UL> + These attributes stay in effect until they are changed, you + don't have to call this function every time. If you call the function with + a value of -1 for any of the attributes they will not be changed. If + you call the function with the same value for an attribute as it + already has, it will not be changed (so you don't have to worry about + bloating your CGM with redundant attribute changes.) + cdSetShapeEdgeAttrib calls three functions. + <A HREF="#cdSetEdgeType">cdSetEdgeType</A> with <EM>edtype</EM> to set + the edge type (solid, dashed, etc), + <A HREF="#cdSetEdgeWidth">cdSetEdgeWidth</A> with <EM>edwidth</EM> to set + the width of the line around the perimeter, + <A HREF="#cdSetEdgeColor">cdSetEdgeColor</A> with <EM>edcolor</EM> to set + the color of the line around the perimeter, and + <A HREF="#cdSetEdgeVis">cdSetEdgeVis</A> with <EM>edvis</EM> to determine + if the line around the perimeter is visible. + You may also call any of the three functions individually if you like. + </DD> + +<DT> +<A NAME="cdSetLineType">int cdSetLineType(cdImagePtr im, int lntype)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Line Type; Elem Class 5; Elem ID 2<BR> + Returns 1 for success, 0 for failure. + <EM>lntype</EM> is the line type which is an integer with possible values + of: + <UL> + <LI>1 for a solid line</LI> + <LI>2 for a dashed line</LI> + <LI>3 for a dotted line</LI> + <LI>4 for a dash-dot line</LI> + <LI>5 for a dash-dot-dot line</LI> + </UL> + <EM>lntype</EM> must be one of these values or the function will fail. + See <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> for more information + on this and related functions. + </DD> + +<DT> +<A NAME="cdSetLineWidth">int cdSetLineWidth(cdImagePtr im, int lnwidth)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Line Width; Elem Class 5; Elem ID 3<BR> + Returns 1 for success, 0 for failure. + <EM>lnwidth</EM> is an integer giving the width of lines. With an + image of height Y with line width 1 the displayed width will be 1/Y%. + As an example, if you image is x=5, y=10, and you set line width = 1, + and draw a vertical line, the resulting line will cover 20% of + horizontal area. (I think anyway). + See <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> for more information + on this and related functions. + </DD> + +<DT> +<A NAME="cdSetLineColor">int cdSetLineColor(cdImagePtr im, int lncolor)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Line Colour; Elem Class 5; Elem ID 4<BR> + Returns 1 for success, 0 for failure. + Sets the line color to <EM>lncolor</EM>. This should be an integer + which is an index into the color table that you have previously + allocated. + See <A HREF="#cdSetLineAttrib">cdSetLineAttrib</A> for more information + on this and related functions. + </DD> + +<DT> +<A NAME="cdSetFillStyle">int cdSetFillStyle(cdImagePtr im, int instyle)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Interior Style; Elem Class 5; Elem ID 22<BR> + Returns 1 for success, 0 for failure. + Sets the style of the interior of filled area elements. + <EM>instyle</EM> is the interior style which is an integer with + possible values of: + <UL> + <LI>0 for hollow. No filling, but the boundary (bounding line) of the + filled area is drawn using the fill colour currently selected. + The boundary of a "hollow" filled area is considered to be the + representation of the interior. The boundary is distinct from the edge, + and is drawn only for "hollow" filled areas</LI> + <LI>1 for solid. Fill the interior using the fill colour currently + selected</LI> + <LI>3 for hatch. Fill the interior using the fill colour and hatch index + currently selected.</LI> + <LI>4 for empty. No filling is done and no boundary is drawn, i.e., + nothing is done to represent the interior. The only potentially + visible component of an "empty" filled area is the edge, subject + to EDGE VISIBILITY and other edge attributes.</LI> + </UL> + <EM>instyle</EM> must be one of these values or the function will fail. + So, basically, if you want an interior which is transparent and you can + see what is underneath it, use "empty" otherwise fill it in with a + hatch or solid color. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetFillColor">int cdSetFillColor(cdImagePtr im, int incolor)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Fill Colour; Elem Class 5; Elem ID 23<BR> + Returns 1 for success, 0 for failure. + Sets the fill color to <EM>incolor</EM>. This should be an integer + which is an index into the color table that you have previously + allocated. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetFillHatch">int cdSetFillHatch(cdImagePtr im, int inhatch)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Hatch Index; Elem Class 5; Elem ID 24<BR> + Returns 1 for success, 0 for failure. + Sets the hatch pattern for the interior of filled-area elements to + <EM>inhatch</EM>. The <A HREF="#cdSetFillStyle">fill style</A> + must be set to hatch for this to have an effect. the value for + <EM>inhatch</EM> is the hatch style, which is an integer with possible values + of: + <UL> + <LI>1 for horizontal lines</LI> + <LI>2 for vertcal lines</LI> + <LI>3 for positive slope parallel lines</LI> + <LI>4 for negative slope parallel lines</LI> + <LI>5 for horizontal/vertical crosshatch </LI> + <LI>6 for positive/negative slope crosshatch </LI> + </UL> + <EM>lntype</EM> must be one of these values or the function will fail. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeFillAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetEdgeType">int cdSetEdgeType(cdImagePtr im, int edtype)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Edge Type; Elem Class 5; Elem ID 27<BR> + Returns 1 for success, 0 for failure. + <EM>edtype</EM> is the edge type which is an integer with possible values + of: + <UL> + <LI>1 for a solid line</LI> + <LI>2 for a dashed line</LI> + <LI>3 for a dotted line</LI> + <LI>4 for a dash-dot line</LI> + <LI>5 for a dash-dot-dot line</LI> + </UL> + <EM>edtype</EM> must be one of these values or the function will fail. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeEdgeAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetEdgeWidth">int cdSetEdgeWidth(cdImagePtr im, int edwidth)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Edge Width; Elem Class 5; Elem ID 28<BR> + Returns 1 for success, 0 for failure. + <EM>edwidth</EM> is an integer giving the width of the perimeter lines. + With an image of height X with line width 1 the displayed width will be 1/X%. + As an example, if you image is x=5, y=10, and you set line width = 1, + and draw a vertical line, the resulting line will cover 20% of + horizontal area. (I think anyway). + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeEdgeAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetEdgeColor">int cdSetEdgeColor(cdImagePtr im, int edcolor)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Edge Color; Elem Class 5; Elem ID 29<BR> + Returns 1 for success, 0 for failure. + Sets the color of the perimeter lines to <EM>edcolor</EM>. This + should be an integer which is an index into the color table that + you have previously allocated. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeEdgeAttrib</A> for more + information on this and related functions. + </DD> + +<DT> +<A NAME="cdSetEdgeVis">int cdSetEdgeVis(cdImagePtr im, int edvis)</A> +<STRONG>(Function)</STRONG></DT> + <DD>Attribute: Edge Visibility; Elem Class 5; Elem ID 30<BR> + Returns 1 for success, 0 for failure. + <EM>edvis</EM> is an integer that can have one of the following values. + <UL> + <LI>0 for invisible edges</LI> + <LI>1 for visible edges</LI> + </UL> + If you set the edge visibility to off (invisible edges) than you will + not see the edges, regardless of what other edge attributes are set. + The other attributes will still be set and turning the edge visibility + to on will make edges using the current edge styles. + See <A HREF="#cdSetShapeFillAttrib">cdSetShapeEdgeAttrib</A> for more + information on this and related functions. + </DD> + +</DL> + + +<H3><A NAME="colors">Color handling functions</A></H3> +<!-- ***** Color Handling Functions ***** --> +<DL> +<DT> +<A NAME="cdImageColorAllocate">int cdImageColorAllocate(cdImagePtr im, int r, int g, int b)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageColorAllocate finds the first available color index in + the image specified, sets its RGB values to those requested + (255 is the maximum for each), and returns the index of the new color + table entry. When creating a new image, the first time you invoke this + function, you are setting the background color for that image. + <P> + In the event that all <A HREF="#cdMaxColors">cdMaxColors</A> colors + (256) have been allocated already, cdImageColorAllocate will return + -1 to indicate failure, otherwise it will return the index into the + color table allocated. (Note that most functions return 0 on failure, but + 0 is a valid color table entry.) + </P><P> + cdImageColorAllocate does not check for existing colors that match + your request, you might want to use + <A HREF="#cdImageColorExact">cdImageColorExact</A> prior to calling this + function to keep from defining multiple indexes with the same color. If + color alocation fails, use + <A HREF="#cdImageColorClosest">cdImageColorClosest</A> to find the + nearest matching color. + </DD> + +<DT> +<A NAME="cdImageColorClosest">int cdImageColorClosest(cdImagePtr im, int r, int g, int b)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageColorClosest searches the colors which have been + defined thus far in the image specified and returns the + index of the color with RGB values closest to those of the + request. (Closeness is determined by Euclidian distance, + which is used to determine the distance in three-dimensional color + space between colors.) + <P> + If no colors have yet been allocated in the image, + gdImageColorClosest returns -1. + </P><P> + This function is most useful as a backup method for choosing + a drawing color when an image already contains + <A HREF="#cdMaxColors">cdMaxColors</A> (256) colors and + no more can be allocated. + See <A HREF="#cdImageColorExact">cdImageColorExact</A> + for a method of locating exact matches only. + </P></DD> + +<DT> +<A NAME="cdImageColorExact">int cdImageColorExact(cdImagePtr im, int r, int g, int b)</A> +<STRONG>(Function)</STRONG></DT> + <DD>cdImageColorExact searches the colors which have been + defined thus far in the image specified and returns the + index of the first color with RGB values which exactly + match those of the request. If no allocated color matches the + request precisely, cdImageColorExact returns -1. + See <A HREF="#cdImageColorClosest">cdImageColorClosest</A> + for a way to find the color closest to the color requested. + </DD> + +<DT><A NAME="cdImageColorsTotal">int cdImageColorsTotal(cdImagePtr im)</A> +<STRONG>(Macro)</STRONG> + <DD>cdImageColorsTotal is a macro which returns the number of + colors currently allocated in the image. Use this macro + to obtain this information; do not access the structure + directly. + </DD> + +<DT> +<A NAME="cdImageColorRed">int cdImageColorRed(cdImagePtr im, int c)</A> +<STRONG>(Macro)</STRONG> + <DD>cdImageColorRed is a macro which returns the red portion + of the specified color in the image. Use this macro + to obtain this information; do not access the structure + directly. + </DD> + +<DT> +<A NAME="cdImageColorGreen">int cdImageColorGreen(cdImagePtr im, int c)</A> +<STRONG>(Macro)</STRONG> + <DD>cdImageColorGreen is a macro which returns the green portion + of the specified color in the image. Use this macro + to obtain this information; do not access the structure + directly. + </DD> + +<DT> +<A NAME="cdImageColorBlue">int cdImageColorBlue(cdImagePtr im, int c)</A> +<STRONG>(Macro)</STRONG> + <DD>cdImageColorBlue is a macro which returns the green portion + of the specified color in the image. Use this macro + to obtain this information; do not access the structure + directly. + </DD> + +</DL> + + +<H3><A NAME="constants">Constants</A></H3> +<!-- ***** Constants ***** --> + +<DL> +<DT> +<A NAME="cdMaxColors">cdMaxColors</A> +<STRONG>Constant</STRONG></DT> + <DD>cdMaxColors is the maximum number of colors that can be allocated in + a CGM picture. the CGM standard allows for many different ways of + allocating colors, but I have chosen to limit this library to + 8 bit indexed color. This means the <EM>maximum</EM> value of this + is 256. If you really wanted to you could make it smaller though it + would not have an effect on the resulting file size. + </DD> + +<DT> +<A NAME="CDSTARTLISTSIZE">CDSTARTLISTSIZE</A> +<STRONG>Constant</STRONG></DT> + <DD>When you create an image, a buffer is allocated to hold the drawing + commands. This is the initial size of the buffer in bytes. When it is + filled, the size gets increased by + <A HREF="#CDGROWLISTSIZE">CDGROWLISTSIZE</A>. + If you know you are going to be working with very small CGM's then + make this a small number. If you know your CGM's will be large increase + this number. If CDSTARTLISTSIZE is smaller than the header information + than it will have to grow before you do anything. I wouldn't make it + smaller than 1024. Try to make it as large as the average picture you make. + </DD> + +<DT> +<A NAME="CDGROWLISTSIZE">CDGROWLISTSIZE</A> +<STRONG>Constant</STRONG></DT> + <DD>When you create an image, a buffer is allocated to hold the drawing + commands. When the buffer is filled, the size is increased by the amount + given in CDGROWLISTSIZE (in bytes). If you know that most of the CGM's you + create will be near the size of <A HREF="#CDSTARTLISTSIZE">CDSTARTLISTSIZE</A> + than make this number small. If there is lots of variablility in the + size of your CGM's, make this number large. If CDGROWLISTSIZE is + larger than CDSTARTLISTSIZE, you should probably increase the value + of CDSTARTLISTSIZE. If CDGROWLISTSIZE is smaller than the largest + CGM element you create than it will be growing alot, so I wouldn't + make it smaller than about 1024. + </DD> + +</DL> + + +<H3><A NAME="replacegd">Using cd instead of gd</A></H3> +<P> +CD was designed to be easy to use instead of gd (or with gd, if you want +to be able to produce both). However, There are significate differences +between the way CGM handles attributes versus the way gd does. In particular, +gd requires you to put the line color in the function call to draw lines, +CD does not, Color, like the other attributes only need to be set when +they are changed. I recomend that you read over the documentation of both +to see what the differences are, and make appropriate changes to your +code. If you really want to make as few changes as possible to your +code, I have provided two functions to help you. <EM>cdImageLine</EM> +takes the same parameters as <EM>gdImageLine</EM> and will draw +a solid line of the color specified. <EM>cdImageRectangle</EM> +draws a hollow rectangle with solid edges of the color specified. I +did this by drawing four lines, so it is not a true rectangle. +Again, I recomend you use <EM>cdLine</EM> and <EM>cdRectangle</EM> +instead of these, but they are there if you want them. + +<H3><A NAME="informing">Please tell us you're using cd!</A></H3> +<P> +When you contact us and let us know you are using cd, +you help us justify the time spent in maintaining and improving +it. So please let us know. If the results are publicly +visible on the web, a URL is a wonderful thing to receive, but +if it's not a publicly visible project, a simple note is just +as welcome. +</P> + + +<HR><EM> +<A HREF="http://speckle.ncsl.nist.gov/~lorax/index.html"> +G. Edward Johnson</A><BR> +<A HREF="mailto:lorax@nist.gov" TITLE="WEB: CGM Draw Comment">lorax@nist.gov</A> +</EM></BR> +</BODY></HTML> |