1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
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>
|
