man/man5/metafile.5

.\" RCSid "$Id$"
.TH METAFILE 5 10/23/98 RADIANCE
.SH NAME
metafile - graphics command interface, similar to plot(5)
.SH DESCRIPTION
The
.I metafile
graphics format was designed with the primary
goal of serving as a temporary file for routines which
output to dot-matrix and other line-at-a-time devices.
As a result, all of the "primitives" are completely self-contained
to facilitate sorting.
.PP
A primitive is a command which can itself be plotted.
Into this catagory fall line segments, rectangle and triangle fills,
matrix and vector strings.
Every primitive has a zeroeth argument which contains bundled attribute
information, and an extent.
The extent gives the x and y minimum and maximum values which enclose
the primitive.
The extent is used in sorting, and typically also in describing
the primitive.
For example, a line segment will be described completely by its
enclosing rectangle and attributes including specification
of which diagonal the segment falls on.
Other primitives will have additional arguments, such as vector string,
which must specify the string to be output within its extent.
.PP
"Global" commands separate the primitives
and allow functions which affect all commands.
These are commands such as end of page, pause, open and close segment,
set, unset and reset, and a special global, end of file.
The end of file command is included to facilitate finding the end of
file on systems which do not keep track exactly.
Global commands sometimes have arguments.
The open command, for instance, specifies the name of the segment.
Global commands never have extents.
.PP
The metafile commands are as follows:
.TP 3
.B F
end of file:  no arguments.
.br
When end of file is reached, all processing stops.
.TP
.B E
end of page:  no arguments.
.br
This causes the device to advance to the next screen or page.
If the output device is a terminal, it will beep and wait
for the user to hit return before clearing the screen.
.TP
.B P
pause:  arguments specify the message to be printed.
.br
This causes output to be flushed and the controlling terminal
to be opened.
The user is then prompted with the specified string followed by
the message "- (hit return to continue)".
If no string is specified, the bell is sounded without a message.
After the user hits return, output continues.
This command is useful when the user is required for some part of
the output, such as changing paper or pens.
.TP
.B D
draw global:  no arguments.
.br
This global forces flushing of output and updating of device.
.TP
.B I
include file:  arg0 TRUE if standard file.
.br
The include global causes the contents of the named file to be
substituted in the include command's location.
If arg0 is 1 (TRUE), a standard location is searched if the
file is not found in the working directory.
If arg0 is 0 (FALSE), the file must be in the working directory.
Include files can be nested to the number of allowed open files.
.TP
.B S
set:  arg0 specifies what to set (from meta.h):
.nf
SALL:  place context mark on current settings.
SPAT0:  set pattern 0 to the specified value.
SPAT1:  set pattern 1 to the specified value.
SPAT2:  set pattern 2 to the specified value.
SPAT3:  set pattern 3 to the specified value.
.fi
The set command is used to globally affect certain attributes.
The zeroeth argument specifies the variable to set, and the
arguments following specify the value.
Pattern values can have two forms.
The first form begins with the letter 'P', immediately followed
by an integer between 0 and 11.
This selects one from the following patterns:  solid, 
thick \\\\\\, thin \\\\\\, mixed \\\\\\,
thick ///, thin ///, mixed ///, crisscross, web.
The default pattern settings are:  0=P0, 1=P1, 2=P2, 3=P3.
The second form gives the explicit values for a pattern.
The set all command makes a context mark with the current settings.
All settings which follow can be undone with the unset all command.
.TP
.B U
unset:  arg0 specifies what to unset (from meta.h):
.nf
SALL:  return to previous context.
SPAT0:  set pattern 0 to the previous value.
SPAT1:  set pattern 1 to the previous value.
SPAT2:  set pattern 2 to the previous value.
SPAT3:  set pattern 3 to the previous value.
.fi
The unset command returns a variable to its previous value.
The unset all command returns the settings to the values they had in
the previous context.
If no context has been marked by set all, variables are returned to
their default values.
.TP
.B R
reset:  arg0 specifies what to reset (from meta.h):
.nf
SALL:  reset all variables.
SPAT0:  set pattern 0 to the default value.
SPAT1:  set pattern 1 to the default value.
SPAT2:  set pattern 2 to the default value.
SPAT3:  set pattern 3 to the default value.
.fi
The reset command returns a variable to its default setting.
The reset all command returns all variables to their initial state.
.TP
.B O
open segment:  arguments specify segment name.
.br
The commands following up to a C (close segment) are not to be output,
but are to be stored in the named segment.
Segment names can contain any ascii character (except newline)
in any sequence of reasonable length.
Segment definitions are local to the enclosing segment.
Side effects should
be avoided in segments by balancing calls to set and unset.
A segment cannot reference itself.
.TP
.B C
close segment:  no arguments.
.br
The current segment is closed, which completes its usable definition.
.TP
.B l
line segment:  fields of arg0 are:
.nf
100:  orientation:  positive slope, negative slope.
060:  type:  solid, dashed, dotted, dotted-dashed.
014:  width:  0, 12, 24, 48, 96 units.
003:  color:  black, red, green, blue.
.fi
.TP
.B r
rectangle fill:  fields of arg0 are:
.nf
100:  toggle:  OR fill, XOR fill.
014:  pattern:  choice of 4 (see set).
003:  color:  black, red, green, blue.
.fi
Fills the given extent with the specified pattern.
Toggle (XOR) fill allows the reversal of previous fills to an area.
.TP
.B t
triangle fill:  fields of arg0 are:
.nf
100:  toggle:  OR fill, XOR fill.
060:  orientation:  right (& down), up, left, down.
014:  pattern:  choice of 4 (see set).
003:  color:  black, red, green, blue.
.fi
Fills the given half-rectangle  with the specified pattern.
A triangle is oriented to the right if the the area between the
positive-sloped diagonal and the lower right corner of the
extent is filled.
Rotating this triangle ccw successively yields up, left and down
triangles.
Toggle (XOR) fill allows the reversal of previous fills to an area.
.TP
.B p
polygon fill:  fields of arg0 are:
.nf
100:  border:  no border, line border.
060:  orientation:  right (& down), up, left, down.
014:  pattern:  choice of 4 (see set).
003:  color:  black, red, green, blue.
.fi
The argument string gives a blank separated list of the polygon
vertices in the form:  "x0 y0 x1 y1 x2 y2 ... ".
The coordinates must be integers ranging between 0 and 16383.
The bounding box and orientation will be used to fit the original polygon
into a scaled and rotated position.
The last vertex will be connected to the first, and the polygon
will be filled in with the specified pattern.
If a border is requested, one will be drawn of solid black zero width
lines.
All polygon fills will toggle, therefore other polygon and toggled
triangle and rectangle fills will affect the final appearance of the
image.
For example, a polygon drawn inside another polygon of the same
pattern will make a hole.
.TP
.B m
matrix string:  fields of arg0 are:
.nf
100:  strike:  single, double.
060:  density:  10 cpi, 12 cpi, 17 cpi, 20 cpi.
014:  size:  normal, double width, double height, double both.
003:  color:  black, red, green, blue.
.fi
The upper left corner of the extent is used to place the beginning of
the string specified after the command.
More sophisticated drivers will use the extent for clipping,
but the size of the characters will not be altered.
.TP
.B v
vector string:  fields of arg0 are:
.nf
060:  orientation:  right, up, left, down.
014:  thickness:  0, 12, 24, 48, 96 units.
003:  color:  black, red, green, blue.
.fi
The string specified following the command will be made to fit
within the given extent.
.TP
.B s
print segment:  fields of arg0 are:
.nf
060:  orientation:  right, up, left, down.
014:  thickness:  0, 12, 24, 48, 96 units.
003:  color:  black, red, green, blue.
.fi
The segment whose name is specified in the arguments will be oriented
according to arg0 and made to fit in the given extent.
The thickness and color of the lines in the segment will be changed
also according to arg0.
In the case of area fill, it is the pattern rather than the width
which will change.
The segment must have been previously defined using the open segment
global.
Note that matrix strings will not transfer well since they cannot
be oriented or scaled.
.PP
The metafile has two basic formats.
The first format is meant to be user readable, and has the form:
.nf

    c arg0 xmin ymin xmax ymax `args

.fi
Where c is the single letter command, arg0 is the octal value for
arg0, xmin ymin xmax ymax are the extent (ranging from 0 to 16283),
and the optional args following the backquote are additional arguments,
terminated by a newline.
If the command is a global, the extent is not present.
If the global has no arg0, 0200 is appropriate.
Any global which has a following string must have a value for
arg0 (< 0200).
Comments are permitted on lines beginning with a pound sign ('#').
.PP
The second format is roughly equivalent, but packs the extrema into
two bytes each.
It takes between one quarter and one third as much space, and much
less processing to use this type of file, hence it is the default
format for all of the programs.
Conversion between formats is accomplished with cv(1).
.SH FILES
The standard location for metafiles used by the programs 
is /usr/lib/meta/, but can be changed by setting the environment
variable MDIR.
This is useful for systems where the owner does not have
access to the /usr/lib/ directory.  It also allows the user
to create his own metafiles for vector characters and other symbols.
.SH BUGS
The command for line segment ('l') is awkward at best.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cv(1), meta(3), pexpand(1), primout(3), psort(1)
Revision:	1.2
Committed:	Tue Dec 9 15:59:07 2003 UTC (20 years, 5 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R2, rad4R2P2, rad5R0, rad5R1, rad3R7P2, rad3R7P1, rad4R2, rad4R1, rad4R0, rad3R6, rad3R6P1, rad3R8, rad3R9, rad4R2P1, rad5R3, HEAD
Changes since 1.1:	+1 -1 lines
Log Message:	Fixed RCSid specification
#	User	Rev	Content
1	greg	1.2	.\" RCSid "$Id$"
2	greg	1.1	.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)