CD Documentation

A graphics library for fast CGM creation

Note that I no longer work at NIST, and most of the links to NIST will not work.

Table of Contents

Credits and license terms

cd was written by G. Edward Johnson at the National Institute of Standards and Technology. You may use this code for any purpose, but please give us credit. 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.

Some of this code is from the gd (GifDraw) 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.

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.)

The Quest Protein Database Center is funded under Grant P41-RR02188 by the National Institutes of Health.

What's new?

Version 1.3

Version 1.2

Version 1.1

Thanks to Wolfgang Glunz (Wolfgang.Glunz@mchp.siemens.de) who purified it, pointed out some bugs and did the Borland makefile.

Version 1.0

Basically, everything is new, this is the first release.

What is cd?

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 NIST CGM Homepage.

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.

What else do I need to use cd?

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. 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.

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.

How do I get cd?

You can fetch cd as a gzip'ed tar file.

How do I build cd?

Note: 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. 

gunzip cd1.3.tar.gz
tar -xf cd1.3.tar
This will create the directory "cd1.3" beneath the current directory.

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, cdsimple, cdtest, and color16. If you are using Borland Turbo C++ version 3 (or later I hope) try to make it using makefile.bor

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. Cd has been tested on Solaris 2, SunOs 4, Ultrix, Linux, IRIX, OpenVMS, and DOS (Borland). If you get it to run on other systems, drop me a note.

cd basics: using cd in your program

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.

Look at the example programs included in this distribution for examples of using cd. The programs are cdsimple which is a heavily commented program that makes a small cgm. cdtest 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, color16 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".

Function and Type reference

Types

cdImage (Type)

The data structure in which cd stores images. cdImageCreate returns a pointer to this type, and other functions expect to receive a pointer to this type as the first argument.

cdImagePtr (Type)

A pointer to an image structure. cdImageCreate returns this type, and the other functions expect it as the first argument. you may read the members sx (size of x axis), sy (size of y axis), colorsTotal (total colors allocated), red (red component of colors; an array of 256 integers between 0 and 255), green (green commponent of colors), and blue (blue component of colors). Please do so using the macros provided. Do Not set the members directly from your code, use the functions provided.

cdPoint (Type)

Represents a collection of points in the coordinate space of the image; used by cdPolygon by cdPolygonSet by cdPolyLine and by cdPolyMarker.

cdPointPtr is defined in cd.h, basically, it is an array of integer triples p[m].x and p[m].y containing the x and y values respectively and p[m].e containing the closure and edge visiblity flags. p[m].e is only used for cdPolygonSet. 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, 2 for polylines, or 1 for polymarkers.

Declare it with cdPoint points[pcnt] where pcnt is the upper limit of the number of points you wish to have. then fill it in with points[0].x = x0; points[0].y = y0; and the like.

p[m].e is used for cdPolygonSet. For other functions, p[m].e is ignored. Its value determines the visibility of the edge leaving that point. It is an integer with one of the following values:

cdPointPtr (Type)

A pointer to a cdPoint structure; passed as an argument to cdPolygon to cdPolygonSet to to cdPolyLine and to cdPolyMarker.

Image creation, destruction, and saving

cdImageCreate(int sx, int sy) (Function)

cdImageCreate is called to create images. Invoke cdImageCreate with the x and y dimensions of the desired image. cdImageCreate returns a cdImagePtr to the new image, or NULL if unable to allocate the image. The image must eventually be destroyed using cdImageDestroy

cdImageDestroy(cdImagePtr im) (Function)

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 cdImagePtr variable.

cdCgmNewPic(cdImagePtr im, int sticky) (Function)

cdCgmNewPic allows for a single CGM file to contain multiple pictures. If sticky is 0 then all attributes will be reset to their default condition and the color table will be cleared. If sticky is 1 then all attributes and the color table will be carried over to the new picture. NOTE: as of now (version 1.2) the only allowable value for sticky is 0. If you set it to 1, the function will fail.

cdImageCgm(cdImagePtr im, FILE *out) (Function)

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 not close the file, your code must do that.

Drawing Functions

int cdLine(cdImagePtr im, int x1, int y1, int x2, int y2) (Function)
Graphic Primitive: Polyline; Elem Class 4; Elem ID 1
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 cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. The endpoints must be within the bounds of the picture.
int cdPolyLine(cdImagePtr im, cdPointPtr p, int n) (Function)
Graphic Primitive: Polyline; Elem Class 4; Elem ID 1
Returns 1 for success, 0 for failure. cdPolyLine draws a line connecting all the points specified by cdPointPtr. n 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 cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. Note that it uses line attributes not edge attributes for drawing the line. The endpoints must be within the bounds of the picture.

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.)

int cdRectangle(cdImagePtr im, int x1, int y1, int x2, int y2) (Function)
Graphic Primitive: rectangle; Elem Class 4; Elem ID 11
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 cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. 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.
int cdCircle(cdImagePtr im, int cx, int cy, int r) (Function)
Graphic Primitive: circle; Elem Class 4; Elem ID 12
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 cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. 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.
int cdArc3Pt(cdImagePtr im, int sx, int sy, int ix, int iy, int ex, int ey) (Function)
Graphic Primitive: Cicular Arc 3 Point; Elem Class 4; Elem ID 13
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 cdSetLineAttrib The attributes that may be set are Line Type, Line Width, or Line Color. Note that it uses Line attributesfor drawing the perimiter of the arc, not Edge attributes like cdArc3PtClose. The Arc must be within the bounds of the picture.
int cdArc3PtClose(cdImagePtr im, int sx, int sy, int ix, int iy, int ex, int ey, int cl) (Function)
Graphic Primitive: Cicular Arc 3 Point Close; Elem Class 4; Elem ID 14
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 cl. If cl is 0 then pie closure will be used, resulting in a pie shaped slice. if cl 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 cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes for drawing the perimeter of the arc, not Line attributes like cdArc3Pt. The Arc must be within the bounds of the picture.
int cdEllipse(cdImagePtr im, int cx, int cy, int d1x, int d1y, int d2x, int d2y) (Function)
Graphic Primitive: Ellipse; Elem Class 4; Elem ID 17
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, mail me. This ellipse is drawn using the attributes set by cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. 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.
int cdPolygon(cdImagePtr im, cdPointPtr p, int n) (Function)
Graphic Primitive: Polygon; Elem Class 4; Elem ID 7
Returns 1 for success, 0 for failure. cdPolygon draws a closed polygon connecting the points specified by cdPointPtr. n 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 cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. 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.

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.)

int cdPolygonSet(cdImagePtr im, cdPointPtr p, int n) (Function)
Graphic Primitive: Polygon; Elem Class 4; Elem ID 8
Returns 1 for success, 0 for failure. cdPolygon draws a set of closed polygons connecting the points specified by cdPointPtr. n 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 cdSetShapeFillAttrib and by cdSetShapeEdgeAttrib. The fill attributes that may be set are Fill Style, Fill Color, or Fill Hatch. The edge attributes that may be set are Edge Type, Edge Width, Edge Color, or Edge Visibility. Note that it uses Edge attributes not line attributes for drawing the perimeter of the polygons. The polygons must be within the bounds of the picture.

You can draw several polygons with this command by the use of flags described in cdPoint.

A visible edge of a polygon will only be drawn if the current edge attribute is visible, however if the edge of the polygon is set to invisible and the current edge attribute is visible, it will not be drawn.

cdPointPtr is defined in cd.h, basically, it is three arrays of integers p[m].x and p[m].y containing the x and y values respectively and p[m].e containing the visibility of the edge leaving the point. See cdPoint for more details. 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.)

int cdMarker(cdImagePtr im, int x, int y) (Function)
Graphic Primitive: Polymarker; Elem Class 4; Elem ID 3
Returns 1 for success, 0 for failure. cdMarker draws a marker, at the point (x,Y) These markers are drawn using the attributes set by cdSetMarkerAttrib. The attributes that may be set are Marker Type, Marker Size, or Marker Color. Markers must be within the bounds of the picture.

Markers are point objects. They can be dots, pluses, astrisks, circles, or crosses. They generally take up less space than drawing them using other graphics elements.

int cdPolyMarker(cdImagePtr im, cdPointPtr p, int n) (Function)
Graphic Primitive: Polymarker; Elem Class 4; Elem ID 3
Returns 1 for success, 0 for failure. cdPolyMarker draws a set of markers, one for each point in cdPointPtr. n is the number of points in cdPointPtr, (not the index of the last point, which is n-1). These markers are drawn using the attributes set by cdSetMarkerAttrib. The attributes that may be set are Marker Type, Marker Size, or Marker Color. The markers must be within the bounds of the picture.

cdPointPtr is defined in cd.h, basically, it is three arrays of integers p[m].x and p[m].y containing the x and y values respectively and p[m].e containing the visibility of the edge leaving the point. See cdPoint for more details. 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 1.

Font and text-handling functions

int cdSetTextAttrib(cdImagePtr im, int font, int color, int height) (Function)
Returns 1 for success, 0 for failure. cdSetTextAttrib sets the attributes for text elements. The Font functions 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. cdSetTextFont to set the index into the font table, cdSetTextColor with color to set the forground color of the text, and cdSetTextHeight with height to set the height of the text. You may also call any of the three functions individually if you like.
int cdText(cdImagePtr im, int x, int y, const char *ts) (Function)
Graphic Primitive: Text; Elem Class 4; Elem ID 4
Returns 1 for success, 0 for failure. cdText puts a string of text ts starting at position (x,y) The Text is drawn using the attributes set with cdSetTextAttrib. The attributes that may be set are: cdSetTextFont, cdSetTextColor, or cdSetTextHeight. The point where the text starts must be within the bounds of the picture.
int cdSetTextPath(cdImagePtr im, int tpath) (Function)
Attribute: Text Path; Elem Class 5; Elem ID 17
Returns 1 for success, 0 for failure. sets the path of the text to tpath. tpath is an integer with one of the following values These are all relative to the charater base vector and up vector. If you haven't changed them (with cdSetTextOrient 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 cdSetTextOrient.

Things get more interesting if you use cdSetTextOrient with this function. A more exact definition of tpath is

int cdSetTextOrient(cdImagePtr im, int xup, int yup, int xbase, int ybase) (Function)
Attribute: Character Orientation; Elem Class 5; Elem ID 16
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. Text written from bottom to top at a 22.5 degree angle would have the following parameters: xup=-1, yup=2, xbase=2, ybase=1.

Skewed text can also be created with this function. (xup,yup) is the "Character Up Vector" which is the vertical line running from the bottom of the character to the top. The skew angle is computed independently of the (xbase,ybase) vector. If you change the Up vector, text will be skewed. (xup,yup) is the run and the rise of the up vector. Text written with a 45 degree skew would have the following parameters: xup=1, yup=1, xbase=1, ybase=0. Changing xup to 2, the skew angle becomes 22.5 degrees. You can, of course, have text that is both skewed and rotated by inserting the proper parameters.

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.

int cdSetTextFont(cdImagePtr im, int font) (Function)
Attribute: Text Font Index; Elem Class 5; Elem ID 10
Returns 1 for success, 0 for failure. Sets the font index to font. It is an index into the font table, the possible values are: font must be one of these values or the function will fail. See cdSetTextAttrib for more information on this and related functions.
int cdSetTextColor(cdImagePtr im, int color) (Function)
Attribute: Text Colour; Elem Class 5; Elem ID 14
Returns 1 for success, 0 for failure. Sets the foreground color of text to color. This should be an integer which is an index into the color table that you have previously allocated. See cdSetTextAttrib for more information on this and related functions.
int cdSetTextHeight(cdImagePtr im, int height) (Function)
Attribute: Character Height; Elem Class 5; Elem ID 15
Returns 1 for success, 0 for failure. height 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 cdSetTextAttrib for more information on this and related functions.

Line, Edge, Fill, and Marker attributes

int cdSetLineAttrib(cdImagePtr im, int lntype, int lnwidth, int lncolor) (Function)
Returns 1 for success, 0 for failure. cdSetLineAttrib sets the attributes for lines and non-closed area elements. The drawing functions affected are 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. cdSetLineType with lntype to set the line type (solid, dashed, etc), cdSetLineWidth with lnwidth to set how wide the line is, and cdSetLineColor to set the color of the line. You may also call any of the three functions individually if you like.
int cdSetShapeFillAttrib(cdImagePtr im, int instyle, int incolor, int inhatch) (Function)
Returns 1 for success, 0 for failure. cdSetShapeFillAttrib sets the attributes for the interior of closed area elements. The drawing functionsaffected are 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. cdSetFillStyle with instyle to set the interior style (solid, hatch, empty), cdSetFillColor with incolor to set the interior color (used if instyle is solid or hatch), and cdSetFillHatch with inhatch 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.
int cdSetShapeEdgeAttrib(cdImagePtr im, int edtype, int edwidth, int edcolor, int edvis) (Function)
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 drawing functionsaffected are 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. cdSetEdgeType with edtype to set the edge type (solid, dashed, etc), cdSetEdgeWidth with edwidth to set the width of the line around the perimeter, cdSetEdgeColor with edcolor to set the color of the line around the perimeter, and cdSetEdgeVis with edvis to determine if the line around the perimeter is visible. You may also call any of the four functions individually if you like.
int cdSetMarkerAttrib(cdImagePtr im, int mtype, int mwidth, int mcolor ) (Function)
Returns 1 for success, 0 for failure. cdSetMarkerAttrib sets the attributes for markers The drawing functionsaffected are 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.) cdSetMarkerAttrib calls three functions. cdSetMarkerType with mtype to set the marker type (point, cross, etc), cdSetMarkerSize with msize to set the size of each marker, and cdSetMarkerColor with mcolor to set the color of the marker. You may also call any of the three functions individually if you like.
int cdSetLineType(cdImagePtr im, int lntype) (Function)
Attribute: Line Type; Elem Class 5; Elem ID 2
Returns 1 for success, 0 for failure. lntype is the line type which is an integer with possible values of: lntype must be one of these values or the function will fail. See cdSetLineAttrib for more information on this and related functions.
int cdSetLineWidth(cdImagePtr im, int lnwidth) (Function)
Attribute: Line Width; Elem Class 5; Elem ID 3
Returns 1 for success, 0 for failure. lnwidth 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 cdSetLineAttrib for more information on this and related functions.
int cdSetLineColor(cdImagePtr im, int lncolor) (Function)
Attribute: Line Colour; Elem Class 5; Elem ID 4
Returns 1 for success, 0 for failure. Sets the line color to lncolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetLineAttrib for more information on this and related functions.
int cdSetFillStyle(cdImagePtr im, int instyle) (Function)
Attribute: Interior Style; Elem Class 5; Elem ID 22
Returns 1 for success, 0 for failure. Sets the style of the interior of filled area elements. instyle is the interior style which is an integer with possible values of: instyle 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 cdSetShapeFillAttrib for more information on this and related functions.
int cdSetFillColor(cdImagePtr im, int incolor) (Function)
Attribute: Fill Colour; Elem Class 5; Elem ID 23
Returns 1 for success, 0 for failure. Sets the fill color to incolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetShapeFillAttrib for more information on this and related functions.
int cdSetFillHatch(cdImagePtr im, int inhatch) (Function)
Attribute: Hatch Index; Elem Class 5; Elem ID 24
Returns 1 for success, 0 for failure. Sets the hatch pattern for the interior of filled-area elements to inhatch. The fill style must be set to hatch for this to have an effect. the value for inhatch is the hatch style, which is an integer with possible values of: lntype must be one of these values or the function will fail. See cdSetShapeFillAttrib for more information on this and related functions.
int cdSetEdgeType(cdImagePtr im, int edtype) (Function)
Attribute: Edge Type; Elem Class 5; Elem ID 27
Returns 1 for success, 0 for failure. edtype is the edge type which is an integer with possible values of: edtype must be one of these values or the function will fail. See cdSetShapeEdgeAttrib for more information on this and related functions.
int cdSetEdgeWidth(cdImagePtr im, int edwidth) (Function)
Attribute: Edge Width; Elem Class 5; Elem ID 28
Returns 1 for success, 0 for failure. edwidth 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 cdSetShapeEdgeAttrib for more information on this and related functions.
int cdSetEdgeColor(cdImagePtr im, int edcolor) (Function)
Attribute: Edge Color; Elem Class 5; Elem ID 29
Returns 1 for success, 0 for failure. Sets the color of the perimeter lines to edcolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetShapeEdgeAttrib for more information on this and related functions.
int cdSetEdgeVis(cdImagePtr im, int edvis) (Function)
Attribute: Edge Visibility; Elem Class 5; Elem ID 30
Returns 1 for success, 0 for failure. edvis is an integer that can have one of the following values. 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 cdSetShapeEdgeAttrib for more information on this and related functions.
int cdSetMarkerType(cdImagePtr im, int mtype) (Function)
Attribute: Marker Type; Elem Class 5; Elem ID 6
Returns 1 for success, 0 for failure. mtype is the marker type which is an integer with possible values of: mtype must be one of these values or the function will fail. See cdSetMarkerAttrib for more information on this and related functions.
int cdSetMarkerSize(cdImagePtr im, int msize) (Function)
Attribute: Marker Width; Elem Class 5; Elem ID 7
Returns 1 for success, 0 for failure. msize is an integer giving the size of markers. If you just want to note a point, the default size of 1 is probably sufficient. Larger sizes make larger markers. See cdSetMarkerAttrib for more information on this and related functions.
int cdSetMarkerColor(cdImagePtr im, int mcolor) (Function)
Attribute: Marker Colour; Elem Class 5; Elem ID 8
Returns 1 for success, 0 for failure. Sets the marker color to mcolor. This should be an integer which is an index into the color table that you have previously allocated. See cdSetMarkerAttrib for more information on this and related functions.

Color handling functions

int cdImageColorAllocate(cdImagePtr im, int r, int g, int b) (Function)
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.

In the event that all cdMaxColors 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.)

cdImageColorAllocate does not check for existing colors that match your request, you might want to use cdImageColorExact prior to calling this function to keep from defining multiple indexes with the same color. If color alocation fails, use cdImageColorClosest to find the nearest matching color.

int cdImageColorClosest(cdImagePtr im, int r, int g, int b) (Function)
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.)

If no colors have yet been allocated in the image, gdImageColorClosest returns -1.

This function is most useful as a backup method for choosing a drawing color when an image already contains cdMaxColors (256) colors and no more can be allocated. See cdImageColorExact for a method of locating exact matches only.

int cdImageColorExact(cdImagePtr im, int r, int g, int b) (Function)
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 cdImageColorClosest for a way to find the color closest to the color requested.
int cdImageColorsTotal(cdImagePtr im) (Macro)
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.
int cdImageColorRed(cdImagePtr im, int c) (Macro)
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.
int cdImageColorGreen(cdImagePtr im, int c) (Macro)
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.
int cdImageColorBlue(cdImagePtr im, int c) (Macro)
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.

Expert Functions

Most people will never have to use these functions. Don't use them unless you know what you are doing, and can't do it any other way. These functions are in a special group because using them adds considerable complexity to your program. All these functions deal with attributes which must be set before the picture is initialized, so you can't use cdImageCreate and use these functions as well. You must use these image creation functions if you set any of these "expert" attributes.

cdImagePtr cdImageStartCgm() (Expert Function)

Sets up the initial CGM state. Does not open a picture. this should be the first function you call.

int cdCgmHeader(cdImagePtr im) (Expert Function)

After you have changed any expert defaults you are going to, call this function. Only change the defaults that are marked as "expert" If you try to change things like line, marker, or shape attributes, you will end up with a bad CGM file.

int cdCgmPic(cdImagePtr im) (Expert Function)

This function actually starts a new picture in a CGM. Use this right after calling cdCgmHeader. If you have multiple pictures in the file, this can be used to start subsequent pictures, after the current one is closed.

int cdImageEndPic(cdImagePtr im) (Expert Function)

Closes a picture (but not the CGM) Useful if you are writing multiple picture CGM files and want to change the "expert" defaults between pictures. If all you want to do is start a new picture, it is easier to just call cdCgmNewPic with the sticky bit set to 1 (to keep your changes and the color table) or 2 (to keep your changes but not the color table.) if it is the last image of the CGM, you can then call cdImageEndCgm to finalize the CGM, but it is probably easier to call cdImageCgm instead of this function and cdImageEndCgm. Of course, if you set the output file at the begining, you have to close the CGM with these two functions.

int cdEndCgm(cdImagePtr im) (Expert Function)

Finalizes the CGM, writes any buffered data to the output stream that was set by cdImageSetOutput. See cdImageEndPic for more details.

int cdImageSetSize(cdImagePtr im, int x, int y) (Expert Function)

Sets the size of a CGM file. Can be called before the first picture is opened, or in a multi-picture CGM, it can be called between pictures.

int cdImageSetOutput(cdImagePtr im, FILE *output) (Expert Function)

Sets the output stream. The file must be opened prior to calling this function.

int cdImageClearFonts(cdImagePtr im) (Expert Function)

Clears the font list. You may only call this before the first picture is opened. If you are going to use all your own fonts instead of the pre-defined ones, you can clear out the old ones with this, then your fonts (added with cdAddFont will be numbered starting with 1. If you do not have any text in your file, you can call this to save about 150 bytes in the output file.

int cdImageAddFont(cdImagePtr im, char *fontname) (Expert Function)

Adds a new font. you may only call this before the first picture is opened. Returns the font index you need to use to access this font from within your picture.

int cdImageSetDefaults(cdImagePtr im) (Expert Function)

This is mostly useful for multi-picture CGM's. Between cdImageEndPic and cdImagePic you can call this function to reset the attributes to the standard defaults.

int cdImageSetLineSpec(cdImagePtr im, int specmode) (Expert Function)

Sets the Line Width Specification Mode. The options are:

This function can be called before the first picture is opened, or between pictures in a CGM.

int cdImageSetMarkerSpec(cdImagePtr im, int specmode) (Expert Function)

Sets the Marker Size Specification Mode. The options are:

This function can be called before the first picture is opened, or between pictures in a CGM.

int cdImageSetEdgeSpec(cdImagePtr im, int specmode) (Expert Function)

Sets the Edge Width Specification Mode. The options are:

This function can be called before the first picture is opened, or between pictures in a CGM.

Constants

cdMaxColors Constant
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 maximum 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.
CDSTARTLISTSIZE Constant
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 CDGROWLISTSIZE. 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.
CDGROWLISTSIZE Constant
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 CDSTARTLISTSIZE 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. I wouldn't make it smaller than about 1024.

Using cd instead of gd

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. cdImageLine takes the same parameters as gdImageLine and will draw a solid line of the color specified. cdImageRectangle 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 cdLine and cdRectangle instead of these, but they are there if you want them.

Please tell us you're using cd!

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.

G. Edward Johnson
lorax@nist.gov