1 |
.\" RCSid "$Id$" |
2 |
.TH METAFILE 5 10/23/98 RADIANCE |
3 |
.SH NAME |
4 |
metafile - graphics command interface, similar to plot(5) |
5 |
.SH DESCRIPTION |
6 |
The |
7 |
.I metafile |
8 |
graphics format was designed with the primary |
9 |
goal of serving as a temporary file for routines which |
10 |
output to dot-matrix and other line-at-a-time devices. |
11 |
As a result, all of the "primitives" are completely self-contained |
12 |
to facilitate sorting. |
13 |
.PP |
14 |
A primitive is a command which can itself be plotted. |
15 |
Into this catagory fall line segments, rectangle and triangle fills, |
16 |
matrix and vector strings. |
17 |
Every primitive has a zeroeth argument which contains bundled attribute |
18 |
information, and an extent. |
19 |
The extent gives the x and y minimum and maximum values which enclose |
20 |
the primitive. |
21 |
The extent is used in sorting, and typically also in describing |
22 |
the primitive. |
23 |
For example, a line segment will be described completely by its |
24 |
enclosing rectangle and attributes including specification |
25 |
of which diagonal the segment falls on. |
26 |
Other primitives will have additional arguments, such as vector string, |
27 |
which must specify the string to be output within its extent. |
28 |
.PP |
29 |
"Global" commands separate the primitives |
30 |
and allow functions which affect all commands. |
31 |
These are commands such as end of page, pause, open and close segment, |
32 |
set, unset and reset, and a special global, end of file. |
33 |
The end of file command is included to facilitate finding the end of |
34 |
file on systems which do not keep track exactly. |
35 |
Global commands sometimes have arguments. |
36 |
The open command, for instance, specifies the name of the segment. |
37 |
Global commands never have extents. |
38 |
.PP |
39 |
The metafile commands are as follows: |
40 |
.TP 3 |
41 |
.B F |
42 |
end of file: no arguments. |
43 |
.br |
44 |
When end of file is reached, all processing stops. |
45 |
.TP |
46 |
.B E |
47 |
end of page: no arguments. |
48 |
.br |
49 |
This causes the device to advance to the next screen or page. |
50 |
If the output device is a terminal, it will beep and wait |
51 |
for the user to hit return before clearing the screen. |
52 |
.TP |
53 |
.B P |
54 |
pause: arguments specify the message to be printed. |
55 |
.br |
56 |
This causes output to be flushed and the controlling terminal |
57 |
to be opened. |
58 |
The user is then prompted with the specified string followed by |
59 |
the message "- (hit return to continue)". |
60 |
If no string is specified, the bell is sounded without a message. |
61 |
After the user hits return, output continues. |
62 |
This command is useful when the user is required for some part of |
63 |
the output, such as changing paper or pens. |
64 |
.TP |
65 |
.B D |
66 |
draw global: no arguments. |
67 |
.br |
68 |
This global forces flushing of output and updating of device. |
69 |
.TP |
70 |
.B I |
71 |
include file: arg0 TRUE if standard file. |
72 |
.br |
73 |
The include global causes the contents of the named file to be |
74 |
substituted in the include command's location. |
75 |
If arg0 is 1 (TRUE), a standard location is searched if the |
76 |
file is not found in the working directory. |
77 |
If arg0 is 0 (FALSE), the file must be in the working directory. |
78 |
Include files can be nested to the number of allowed open files. |
79 |
.TP |
80 |
.B S |
81 |
set: arg0 specifies what to set (from meta.h): |
82 |
.nf |
83 |
SALL: place context mark on current settings. |
84 |
SPAT0: set pattern 0 to the specified value. |
85 |
SPAT1: set pattern 1 to the specified value. |
86 |
SPAT2: set pattern 2 to the specified value. |
87 |
SPAT3: set pattern 3 to the specified value. |
88 |
.fi |
89 |
The set command is used to globally affect certain attributes. |
90 |
The zeroeth argument specifies the variable to set, and the |
91 |
arguments following specify the value. |
92 |
Pattern values can have two forms. |
93 |
The first form begins with the letter 'P', immediately followed |
94 |
by an integer between 0 and 11. |
95 |
This selects one from the following patterns: solid, |
96 |
thick \\\\\\, thin \\\\\\, mixed \\\\\\, |
97 |
thick ///, thin ///, mixed ///, crisscross, web. |
98 |
The default pattern settings are: 0=P0, 1=P1, 2=P2, 3=P3. |
99 |
The second form gives the explicit values for a pattern. |
100 |
The set all command makes a context mark with the current settings. |
101 |
All settings which follow can be undone with the unset all command. |
102 |
.TP |
103 |
.B U |
104 |
unset: arg0 specifies what to unset (from meta.h): |
105 |
.nf |
106 |
SALL: return to previous context. |
107 |
SPAT0: set pattern 0 to the previous value. |
108 |
SPAT1: set pattern 1 to the previous value. |
109 |
SPAT2: set pattern 2 to the previous value. |
110 |
SPAT3: set pattern 3 to the previous value. |
111 |
.fi |
112 |
The unset command returns a variable to its previous value. |
113 |
The unset all command returns the settings to the values they had in |
114 |
the previous context. |
115 |
If no context has been marked by set all, variables are returned to |
116 |
their default values. |
117 |
.TP |
118 |
.B R |
119 |
reset: arg0 specifies what to reset (from meta.h): |
120 |
.nf |
121 |
SALL: reset all variables. |
122 |
SPAT0: set pattern 0 to the default value. |
123 |
SPAT1: set pattern 1 to the default value. |
124 |
SPAT2: set pattern 2 to the default value. |
125 |
SPAT3: set pattern 3 to the default value. |
126 |
.fi |
127 |
The reset command returns a variable to its default setting. |
128 |
The reset all command returns all variables to their initial state. |
129 |
.TP |
130 |
.B O |
131 |
open segment: arguments specify segment name. |
132 |
.br |
133 |
The commands following up to a C (close segment) are not to be output, |
134 |
but are to be stored in the named segment. |
135 |
Segment names can contain any ascii character (except newline) |
136 |
in any sequence of reasonable length. |
137 |
Segment definitions are local to the enclosing segment. |
138 |
Side effects should |
139 |
be avoided in segments by balancing calls to set and unset. |
140 |
A segment cannot reference itself. |
141 |
.TP |
142 |
.B C |
143 |
close segment: no arguments. |
144 |
.br |
145 |
The current segment is closed, which completes its usable definition. |
146 |
.TP |
147 |
.B l |
148 |
line segment: fields of arg0 are: |
149 |
.nf |
150 |
100: orientation: positive slope, negative slope. |
151 |
060: type: solid, dashed, dotted, dotted-dashed. |
152 |
014: width: 0, 12, 24, 48, 96 units. |
153 |
003: color: black, red, green, blue. |
154 |
.fi |
155 |
.TP |
156 |
.B r |
157 |
rectangle fill: fields of arg0 are: |
158 |
.nf |
159 |
100: toggle: OR fill, XOR fill. |
160 |
014: pattern: choice of 4 (see set). |
161 |
003: color: black, red, green, blue. |
162 |
.fi |
163 |
Fills the given extent with the specified pattern. |
164 |
Toggle (XOR) fill allows the reversal of previous fills to an area. |
165 |
.TP |
166 |
.B t |
167 |
triangle fill: fields of arg0 are: |
168 |
.nf |
169 |
100: toggle: OR fill, XOR fill. |
170 |
060: orientation: right (& down), up, left, down. |
171 |
014: pattern: choice of 4 (see set). |
172 |
003: color: black, red, green, blue. |
173 |
.fi |
174 |
Fills the given half-rectangle with the specified pattern. |
175 |
A triangle is oriented to the right if the the area between the |
176 |
positive-sloped diagonal and the lower right corner of the |
177 |
extent is filled. |
178 |
Rotating this triangle ccw successively yields up, left and down |
179 |
triangles. |
180 |
Toggle (XOR) fill allows the reversal of previous fills to an area. |
181 |
.TP |
182 |
.B p |
183 |
polygon fill: fields of arg0 are: |
184 |
.nf |
185 |
100: border: no border, line border. |
186 |
060: orientation: right (& down), up, left, down. |
187 |
014: pattern: choice of 4 (see set). |
188 |
003: color: black, red, green, blue. |
189 |
.fi |
190 |
The argument string gives a blank separated list of the polygon |
191 |
vertices in the form: "x0 y0 x1 y1 x2 y2 ... ". |
192 |
The coordinates must be integers ranging between 0 and 16383. |
193 |
The bounding box and orientation will be used to fit the original polygon |
194 |
into a scaled and rotated position. |
195 |
The last vertex will be connected to the first, and the polygon |
196 |
will be filled in with the specified pattern. |
197 |
If a border is requested, one will be drawn of solid black zero width |
198 |
lines. |
199 |
All polygon fills will toggle, therefore other polygon and toggled |
200 |
triangle and rectangle fills will affect the final appearance of the |
201 |
image. |
202 |
For example, a polygon drawn inside another polygon of the same |
203 |
pattern will make a hole. |
204 |
.TP |
205 |
.B m |
206 |
matrix string: fields of arg0 are: |
207 |
.nf |
208 |
100: strike: single, double. |
209 |
060: density: 10 cpi, 12 cpi, 17 cpi, 20 cpi. |
210 |
014: size: normal, double width, double height, double both. |
211 |
003: color: black, red, green, blue. |
212 |
.fi |
213 |
The upper left corner of the extent is used to place the beginning of |
214 |
the string specified after the command. |
215 |
More sophisticated drivers will use the extent for clipping, |
216 |
but the size of the characters will not be altered. |
217 |
.TP |
218 |
.B v |
219 |
vector string: fields of arg0 are: |
220 |
.nf |
221 |
060: orientation: right, up, left, down. |
222 |
014: thickness: 0, 12, 24, 48, 96 units. |
223 |
003: color: black, red, green, blue. |
224 |
.fi |
225 |
The string specified following the command will be made to fit |
226 |
within the given extent. |
227 |
.TP |
228 |
.B s |
229 |
print segment: fields of arg0 are: |
230 |
.nf |
231 |
060: orientation: right, up, left, down. |
232 |
014: thickness: 0, 12, 24, 48, 96 units. |
233 |
003: color: black, red, green, blue. |
234 |
.fi |
235 |
The segment whose name is specified in the arguments will be oriented |
236 |
according to arg0 and made to fit in the given extent. |
237 |
The thickness and color of the lines in the segment will be changed |
238 |
also according to arg0. |
239 |
In the case of area fill, it is the pattern rather than the width |
240 |
which will change. |
241 |
The segment must have been previously defined using the open segment |
242 |
global. |
243 |
Note that matrix strings will not transfer well since they cannot |
244 |
be oriented or scaled. |
245 |
.PP |
246 |
The metafile has two basic formats. |
247 |
The first format is meant to be user readable, and has the form: |
248 |
.nf |
249 |
|
250 |
c arg0 xmin ymin xmax ymax `args |
251 |
|
252 |
.fi |
253 |
Where c is the single letter command, arg0 is the octal value for |
254 |
arg0, xmin ymin xmax ymax are the extent (ranging from 0 to 16283), |
255 |
and the optional args following the backquote are additional arguments, |
256 |
terminated by a newline. |
257 |
If the command is a global, the extent is not present. |
258 |
If the global has no arg0, 0200 is appropriate. |
259 |
Any global which has a following string must have a value for |
260 |
arg0 (< 0200). |
261 |
Comments are permitted on lines beginning with a pound sign ('#'). |
262 |
.PP |
263 |
The second format is roughly equivalent, but packs the extrema into |
264 |
two bytes each. |
265 |
It takes between one quarter and one third as much space, and much |
266 |
less processing to use this type of file, hence it is the default |
267 |
format for all of the programs. |
268 |
Conversion between formats is accomplished with cv(1). |
269 |
.SH FILES |
270 |
The standard location for metafiles used by the programs |
271 |
is /usr/lib/meta/, but can be changed by setting the environment |
272 |
variable MDIR. |
273 |
This is useful for systems where the owner does not have |
274 |
access to the /usr/lib/ directory. It also allows the user |
275 |
to create his own metafiles for vector characters and other symbols. |
276 |
.SH BUGS |
277 |
The command for line segment ('l') is awkward at best. |
278 |
.SH AUTHOR |
279 |
Greg Ward |
280 |
.SH "SEE ALSO" |
281 |
cv(1), meta(3), pexpand(1), primout(3), psort(1) |