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. If find cd useful, please
+let us know.
+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 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.
+
+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.
+
+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.
+
+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.2.tar.gz
+tar -xf cd1.2.tar
+
+This will create the directory "cd1.2" 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. 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.
+
+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".
+
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
+ their first argument.
+
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.
+
Represents a collection of points in the coordinate space of the image;
+ used by cdPolygon and
+ by cdPolyLine.
+
+ 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.
+
+ 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.
+
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 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 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 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.
+
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.
+
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.)
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.)
+
+ 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.
+
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.
+
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
+
+
0 for right
+
1 for left
+
2 for up
+
3 for down
+
+ 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
+
+
0 right -- the direction of the character base vector
+
1 left -- 180 degrees from the direction of the character
+ base vector
+
2 up -- the direction of the character up vector
+
3 down -- 180 degrees from the direction of the character
+ up vector
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
+
+ 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.
+
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:
+
+
1 for Times
+
2 for Times Bold
+
3 for Times Italic
+
4 for Times Bold Italic
+
5 for Helvetica
+
6 for Helvetica Bold
+
7 for Helvetica Italic
+
8 for Helvetica Bold Italic
+
+ font must be one of these values or the function will fail.
+ See cdSetTextAttrib for more information
+ on this and related functions.
+
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.
+
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.
+
+ 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.
+
+ 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.
+
+ 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 three functions individually if you like.
+
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:
+
+
1 for a solid line
+
2 for a dashed line
+
3 for a dotted line
+
4 for a dash-dot line
+
5 for a dash-dot-dot line
+
+ lntype must be one of these values or the function will fail.
+ See cdSetLineAttrib for more information
+ on this and related functions.
+
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.
+
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.
+
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:
+
+
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
+
1 for solid. Fill the interior using the fill colour currently
+ selected
+
3 for hatch. Fill the interior using the fill colour and hatch index
+ currently selected.
+
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.
+
+ 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.
+
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.
+
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:
+
+
1 for horizontal lines
+
2 for vertcal lines
+
3 for positive slope parallel lines
+
4 for negative slope parallel lines
+
5 for horizontal/vertical crosshatch
+
6 for positive/negative slope crosshatch
+
+ lntype must be one of these values or the function will fail.
+ See cdSetShapeFillAttrib for more
+ information on this and related functions.
+
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:
+
+
1 for a solid line
+
2 for a dashed line
+
3 for a dotted line
+
4 for a dash-dot line
+
5 for a dash-dot-dot line
+
+ edtype must be one of these values or the function will fail.
+ See cdSetShapeEdgeAttrib for more
+ information on this and related functions.
+
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.
+
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.
+
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.
+
+
0 for invisible edges
+
1 for visible edges
+
+ 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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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, so I wouldn't
+ make it smaller than about 1024.
+
+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.
+
+
+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.
+