Provided by: radiance_4R0+20110410-1build1_amd64 bug

NAME

       metafile - graphics command interface, similar to plot(5)

DESCRIPTION

       The  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.

       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.

       "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.

       The metafile commands are as follows:

       F  end of file:  no arguments.
          When end of file is reached, all processing stops.

       E  end of page:  no arguments.
          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.

       P  pause:  arguments specify the message to be printed.
          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.

       D  draw global:  no arguments.
          This global forces flushing of output and updating of device.

       I  include file:  arg0 TRUE if standard file.
          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.

       S  set:  arg0 specifies what to set (from meta.h):
          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.
          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.

       U  unset:  arg0 specifies what to unset (from meta.h):
          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.
          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.

       R  reset:  arg0 specifies what to reset (from meta.h):
          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.
          The  reset  command  returns  a variable to its default setting.  The reset all command
          returns all variables to their initial state.

       O  open segment:  arguments specify segment name.
          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.

       C  close segment:  no arguments.
          The current segment is closed, which completes its usable definition.

       l  line segment:  fields of arg0 are:
          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.

       r  rectangle fill:  fields of arg0 are:
          100:  toggle:  OR fill, XOR fill.
          014:  pattern:  choice of 4 (see set).
          003:  color:  black, red, green, blue.
          Fills the given extent with the  specified  pattern.   Toggle  (XOR)  fill  allows  the
          reversal of previous fills to an area.

       t  triangle fill:  fields of arg0 are:
          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.
          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.

       p  polygon fill:  fields of arg0 are:
          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.
          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.

       m  matrix string:  fields of arg0 are:
          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.
          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.

       v  vector string:  fields of arg0 are:
          060:  orientation:  right, up, left, down.
          014:  thickness:  0, 12, 24, 48, 96 units.
          003:  color:  black, red, green, blue.
          The string specified following the command will be made to fit within the given extent.

       s  print segment:  fields of arg0 are:
          060:  orientation:  right, up, left, down.
          014:  thickness:  0, 12, 24, 48, 96 units.
          003:  color:  black, red, green, blue.
          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.

       The metafile has two basic formats.  The first format is meant to be  user  readable,  and
       has the form:

           c arg0 xmin ymin xmax ymax `args

       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 ('#').

       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).

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.

BUGS

       The command for line segment ('l') is awkward at best.

AUTHOR

       Greg Ward

SEE ALSO

       cv(1), meta(3), pexpand(1), primout(3), psort(1)