1 01/16/84 graphic_macros_, gmc_ 2 3 This module provides a user of the graphic system with the ability to 4 easily create common graphic objects which are not directly 5 representable as primitive graphic elements. All entities created 6 are two-dimensional figures, at the position and in the orientation 7 specified by the user. Each entrypoint returns a graphic node value 8 which consists of an array of vectors. 9 10 This info file contains most of the documentation on graphic_macros_ 11 ultimately planned for the Graphics Reference Manual, and is quite 12 long. A short section on programming hints is followed by a 13 description of each entrypoint. 14 15 16 Programming hints: 17 Declarations for all the user-callable entry points in graphic_macros_ 18 are contained in the PL/I include file "gmc_entry_dcls.incl.pl1". 19 Users may include this file (using the PL/I "%include" facility) in 20 their source programs to save typing and syntax errors. 21 22 Each of the figures produced originates at the current graphic 23 position. The current graphic position is left at the termination 24 point of the figure. For the simple closed curves (polygons, circles, 25 ellipses, boxes) this will be the same as the point of origin. For 26 the other figures (arcs, partial ellipses) it will not. 27 28 29 Entry points in graphic_macros_: 30 (list is generated by the help command) 31 32 33 :Entry: box: 01/16/84 graphic_macros_$box 34 35 Function: creates a rectangular box. 36 37 38 Syntax: 39 declare graphic_macros_$box entry (float bin, float bin, 40 fixed bin (35)) returns (fixed bin (18)); 41 node = graphic_macros_$box (x_side, y_side, code); 42 43 44 Arguments: 45 node 46 is the returned graphic node. (Output) 47 x_side 48 is the X dimension of the box desired. (Input) 49 y_side 50 is the Y dimension of the box desired. (Input) 51 code 52 is a standard system error code. (Output) 53 54 55 Notes: The first two vectors of the box created are a horizontal line 56 of length (x_side) and a vertical line of length (y_side). Therefore, 57 for example, if x_side and y_side are both negative, the box will be 58 drawn to the left and down from the current graphic position. 59 60 61 :Entry: circle: 01/16/84 graphic_macros_$circle 62 63 Function: creates a circle. The rim of the circle originates at the 64 current graphic position. The radius and orientation of the circle is 65 determined by the given distances to the desired centerpoint of the 66 circle. 67 68 69 Syntax: 70 declare graphic_macros_$circle entry (float bin, float bin, 71 fixed bin (35)) returns (fixed bin (18)); 72 node = graphic_macros_$circle (x_dist, y_dist, code); 73 74 75 Arguments: 76 node 77 is the returned graphic node. (Output) 78 x_dist 79 is the X dimension of the relative distance from the current 80 graphic position to the desired center of the circle. (Input) 81 y_dist 82 is the Y dimension of the relative distance from the current 83 graphic position to the desired center of the circle. (Input) 84 code 85 is a standard system error code. (Output) 86 87 88 :Entry: arc: 01/16/84 graphic_macros_$arc 89 90 Function: creates an arc, using the same criteria used by the circle 91 entrypoint. 92 93 94 Usage 95 declare graphic_macros_$arc entry (float bin, float bin, 96 float bin, fixed bin (35)) returns (fixed bin (18)); 97 node = graphic_macros_$arc (x_dist, y_dist, fraction, code); 98 99 100 Arguments: 101 node 102 is the returned graphic node. (Output) 103 x_dist 104 is the X dimension of the relative distance from the current 105 graphic position to the desired center of the circle. (Input) 106 y_dist 107 is the Y dimension of the relative distance from the current 108 graphic position to the desired center of the circle. (Input) 109 fraction 110 represents the fraction of a complete circle desired. If 111 fraction = 1e0, a complete circle will be drawn. (Input) 112 code 113 is a standard system error code. (Output) 114 115 116 Notes: Arcs are drawn counterclockwise, in the direction of increasing 117 angle. If a clockwise arc is desired, a negative value for fraction 118 may be used. 119 120 121 :Entry: polygon: 01/16/84 graphic_macros_$polygon 122 123 Function: creates N-sided polygons. 124 125 126 Syntax: 127 declare graphic_macros_$polygon entry (float bin, float bin, 128 fixed bin, fixed bin (35)) returns (fixed bin (18)); 129 node = graphic_macros_$polygon (x_dist, y_dist, n_sides, code); 130 131 132 Arguments: 133 node 134 is the returned graphic node. (Output) 135 x_dist 136 is the X dimension of the relative distance from the current 137 graphic position to the desired center of the circle. (Input) 138 y_dist 139 is the Y dimension of the relative distance from the current 140 graphic position to the desired center of the circle. (Input) 141 n_sides 142 is the number of sides desired. (Input) 143 code 144 is a standard system error code. (Output) 145 146 147 Notes: One vertex of the polygon will locate itself at the current 148 graphic position. 149 150 151 :Entry: ellipse: 01/16/84 graphic_macros_$ellipse 152 153 Function: creates an ellipse, given the location of its epicenter, and 154 information about its eccentricity. 155 156 157 Syntax: 158 declare graphic_macros_$ellipse entry (float bin, float bin, 159 float bin, fixed bin, float bin, fixed bin (35)) 160 returns (fixed bin (18)); 161 node = graphic_macros_$ellipse (x_dist, y_dist, eccentricity, 162 eccentricity_angle, fraction, code); 163 164 165 Arguments: 166 node 167 is the returned graphic node. (Output) 168 x_dist 169 is the X dimension of the distance from the current graphic 170 position to the epicenter (geographical center) of the desired 171 ellipse. (Input) 172 y_dist 173 is the Y dimension of the distance from the current graphic 174 position to the epicenter (geographical center) of the desired 175 ellipse. (Input) 176 eccentricity 177 is the desired ratio of major axis to minor axis. (Input) 178 179 180 eccentricity_angle 181 is the desired angle between the normal X-axis and the major axis 182 of the ellipse. (Input) 183 fraction 184 represents the fraction of the ellipse desired. If fraction = 1e0, 185 an entire ellipse is drawn. (Input) 186 code 187 is a standard system error code. (Output) 188 189 190 Notes: Like arcs, fractional ellipses are drawn counterclockwise. 191 If a clockwise portion of an ellipse is desired, a negative value 192 for fraction may be used. 193 194 Fractional ellipses are computed on the basis of angle subtended by 195 the elliptical portion, not by circumferential meas- urement. 196 Therefore, depending on the location of the current graphic position 197 and the angle of eccentricity, fractions such as 0.25e0 and 0.75e0 may 198 not produce the intuitive result. 199 200 Note that the definition of eccentricity presented does not bear any 201 relation with the mathematical property also called eccentricity by 202 which ellipses are sometimes described. 203 204 205 :Entry: ellipse_by_foci: 01/16/84 graphic_macros_$ellipse_by_foci 206 207 Function: creates an ellipse given the locations of its two foci with 208 respect to the current graphic position. 209 210 211 Syntax: 212 declare graphic_macros_$ellipse_by_foci entry (float bin, 213 float bin, float bin, float bin, float bin, fixed bin (35)) 214 returns (fixed bin (18)); 215 node = graphic_macros_$ellipse_by_foci (x_dist1, y_dist1, 216 x_dist2, y_dist2, fraction, code); 217 218 219 Arguments: 220 node 221 is the returned graphic node. (Output) 222 x_dist1 223 is the X dimension of the distance between the current graphic 224 position and the first focus of the desired ellipse. (Input) 225 y_dist1 226 is the Y dimension of the distance between the current graphic 227 position and the first focus of the desired ellipse. (Input) 228 x_dist2 229 is the X dimension of the distance between the current graphic 230 position and the second focus of the desired ellipse. (Input) 231 y_dist2 232 is the Y dimension of the distance between the current graphic 233 position and the second focus of the desired ellipse. (Input) 234 235 236 fraction 237 represents the fraction of a complete ellipse desired. If 238 fraction = 1e0, a complete ellipse is drawn. (Input) 239 code 240 is a standard system error code. (Output) 241 242 243 Notes: The interpretation of fraction is described in the notes for 244 entrypoint graphic_macros_$ellipse.