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.