XCircuit PostScript Reference



Introduction

XCircuit uses PostScript as its file format for input and output. There are several reasons for this:
  1. PostScript is an ASCII format, so results can be hand-edited when necessary, and source can be viewed in detail.
  2. PostScript is a platform-independent format
  3. PostScript is an interpreted language, so it contains enough features to handle much more than just drawing. It is easy to create a set of definitions to cover the needs of a particular problem, like circuit drawing, and easy to expand that set when necessary in a way that is backwardly-compatible with earlier versions.
  4. PostScript is a printer language, so the same format used to save the files is used to print the files, cutting down on overhead.
  5. Encapsulated PostScript is convenient for embedding XCircuit output in other documents.
  6. Well-written PostScript is both easy to read and efficient on space. XCircuit output tends to be much smaller than equivalent files produced by any other drawing or schematic capture package.
Because PostScript is an interpreted language, XCircuit files can be read like a program. Of course, conventional use of PostScript encourages massive use of macro definitions. Often the use of macros begins to look like some kind of compression coding, where macros are used to keep the size of the file small and can be virtually unreadable. XCircuit tries to maintain a balance between coding efficiency and readability, tending to fall on the side of readability because circuit diagrams tend not to be very big to begin with, and contain their own coding efficiency in the form of circuit hierarchy.

There is enough coding efficiency in XCircuit output, however, that parts of the output are non-intuitive (e.g., XCircuit encodes drawing styles as a bitmask, and label parts read in backwards order due to the stack nature of the PostScript interpreter). User-induced changes to an XCircuit output file will almost certainly fail to read back into XCircuit properly unless the format is strictly adhered to. XCircuit's PostScript reading routine is neither general-purpose nor particularly robust (i.e., deviations from the format can cause XCircuit to crash).

So, with all the above caveats, here is the XCircuit output format in detail.

Overall Structure

XCircuit generally conforms to the Adobe PostScript ``Document Structuring Conventions'' (DSC) Version 3.0 (see the PostScript reference manual for details). Actually, it conforms exactly, but there is enough slop in the DSC definition that some instantiations of it can get a little confused by xcircuit files, especially when trying to back up several pages.

The overal file structure is the following:

  1. Header
  2. Prolog
  3. Optional Definitions
  4. Page structure:
    1. Definition of objects used on the next page and possible subsequent pages
    2. Page Header
    3. Page Body
    4. Page Trailer
  5. Trailer
XCircuit library files (.lps) have a different structure:
  1. Library Header
  2. Definition of objects in the library
  3. Library Trailer
Because library files do not contain a prolog defining the macros used, library files are not, strictly speaking, PostScript. For this reason, I give them a different suffix (.lps instead of .ps). However, each object in the library used the same set of definitions defined in the PostScript prolog.

Header

The XCircuit header is always at the top of the output file. It looks something like the following:
%!PS-Adobe-3.0
%%Title: examples/FlareLED
%%Creator: Xcircuit v2.3
%%CreationDate: Mon Jul  2 14:17:57 2001
%%Pages: 1
%%BoundingBox: -319 -124 931 916
%%DocumentNeededResources: font Helvetica font Helvetica-Bold font Times-Roman
%%+ font Times-RomanISO font Symbol
%%EndComments
All of these lines are generated on the fly by xcircuit at the time of file output. XCircuit understands the following keywords in this section:
%!PS-Adobe
This is the first line of the file. If the line contains the word ``EPSF'', the page type will be assumed to be Encapsulated Postscript. Multiple-page files should NOT be encapsulated.
%%Pages:
Indicates the total number of pages in the file.
%%BoundingBox:
Indicates the bounding box of the whole file, in PostScript units of 1/72 inch. This information is not strictly necessary for XCircuit, as it will recompute the bounding box from the data.
XCircuit
This keyword appears in the ``%%Creator:'' line of the header. It is followed by a version number. This documentation corresponds to the syntax of version v2.3.
All other header lines are used by DSC but ignored by XCircuit. Their presence is optional.

Prolog

The prolog portion of the output is pre-defined, and is dropped into place when the output is written. The source for the prolog is the file xcircps2.pro, found in the xcircuit lib directory (e.g., /usr/local/lib/xcircuit-2.3/xcircps2.pro). It contains all of the definitions used by the xcircuit format.

The prolog follows the header and is everything between the lines

%%BeginProlog
and
%%EndProlog

Optional Definitions

XCircuit may define a few extra definitions after the prolog. Generally this is restricted to font definitions needed to declare ISO-encoded fonts and slanted fonts in font types which normally do not have an italic version (such as Symbol). These definitions are ignored by the xcircuit file reader, and are regenerated as needed whenever output is re-written.

Object Definitions

Objects are defined outside of the page definition where they are used, in keeping with the internal structure of xcircuit. Each object is a PostScript definition. Objects with no parameters take the form
/object_name {
% llx lly urx ury bbox
begingate
  .
  .
  .
endgate
} def
while objects with parameters take the form
/object_name {
% llx lly urx ury bbox
(string1) (string2) . . . (stringn) n beginparm
  .
  .
  .
endgate
} def
The bounding box position llx lly urx ury is given in xcircuit coordinates (integers), as are all the internal elements of the object definition. n is the number of parameters, which must be preceded by n different parameter default values. A simple string appears in parentheses ``()'', and a string with multiple parts is written exactly like a label definition (see below) and appears in braces ``{}''. For symbols in circuit schematic drawings, an optional line may appear after the ``bbox'' line, declaring a page (schematic) which is associated with the symbol. The syntax of this line takes the form:
% page_name is_schematic
In the page named page_name, there will be a corresponding statement making the association from the page to the object (see directly below for page header syntax).

Page Definition

Each page begins with a page header which looks like the following:
%%Page: 1 1
%%PageOrientation: Portrait
/pgsave save def bop
% 1688 848 offsets
1.0000 inchscale
2.6000 setlinewidth 
All of these lines are required. In detail:
%%Page: pnum pname
pnum is the page number (starting at 1), and pname is the page name as it appears in xcircuit. A PostScript viewer may get confused if pnum is not in order, but pname is generally unrestricted.
%%PageOrientation: type
type is either the keyword ``Portrait'' or ``Landscape''. A ``Landscape'' keyword is accompanied by a rotate line.
/pgsave save def bop
Always written exactly as shown.
% ox oy offsets
Lower left-hand corner offset, in xcircuit units. Determines the viewport in xcircuit, but is otherwise unimportant.
scale scaletype
scale is a floating-point number defining the scale relative to xcircuit's idea of ``normal'' scale, defined at 1.0. scaletype determines the units used by all internal measurements on the page, and is one of inchscale (inches) or cmscale (centimeters).
width setlinewidth
width is a floating-point value which sets the default line width of lines drawn on the page. For obscure historic reasons, the default value is 2.6.
In circuit schematic drawings, one additional line may appear after the ``/pgsave save def bop'' line. This declares an association of the schematic to a symbol defined elsewhere in the PostScript file. The line has the following syntax:
% symbol_name is_symbol
There will be a corresponding line in the symbol definition declaring the page to be the associated schematic.

The page body is a set of one or more lines of xcircuit elements, as defined below. Each page ends with a page trailer, which is exactly the line

pgsave restore showpage

Trailer

The trailer to the whole XCircuit output file is exactly the following:
%%Trailer
XCIRCsave restore
%%EOF
Nothing should appear after the trailer.

Libraries

As mentioned above, libraries have a different format, although the objects defined in the library follow the same format as listed in the sections below. The main difference in libraries is that there are no page definitions, and the header and trailer are specific to the library file type.

The header for library files looks something like the following:

%! PostScript set of library objects for XCircuit
%  Version: 2.3
%  Library name is: analog
%  Author: R. Timothy Edwards 

% XCircuitLib library built-in objects
The name of the library on the third line is the name selected when the library file was saved. The author name and information will be taking from the USER environment variable, so as to automatically give credit where credit is due.

The four header lines are PostScript comments. However, XCircuit parses them for these keywords:

% Version:
Must be followed by the (floating-point) version number which matches the output format. The format described in this documentation matches version 2.3.
% Library:
Followed by the library name. The name will be reported on the library page, unless this library is appended to a library page which already contains objects and has a name.
% XCircuitLib
This line assures xcircuit that it is looking at a library file. It must appear after the header and before all of the object definitions.
All other PostScript comments (lines beginning with `%') will be ignored.

The trailer for library files is exactly the following line:

% EndLib
Any text after this line will be ignored.

Macros for XCircuit elements

XCircuit elements are used for the page body, and the body of each object definition (for both regular and library files). The definitions are as follows:
R G B scb
Set the current color to the RGB definition defined by R G B (floating-point, 0 to 1 inclusive).
sce
End the current color setting, returning to default.
x y insertion (deprecated!)
Begin insertion of an encapsulated PostScript section at position x y (see below for behavior in current version).
r x y s psinsertion
Begin insertion of an encapsulated PostScript section at position x y, rotation r, and scale s. The PostScript is generic PostScript (does not have to be in xcircuit format) and continues until the keyword end_insert is read. The insertion is drawn as the background of the xcircuit window by rendering in ghostscript. The old form ``x y insertion'' is deprecated since xcircuit version 2.5.3 (rev. 1), as the new behavior corrects for output scaling and orientation.
end_insert
Defines the end of an encapsulated PostScript rendered background.
style linewidth x1 y1 x2 y2 [. . . xn yn ] n polygon
Draw a polygon. style (integer) defined below. Linewidth (floating-point) is scale relative to page-defined linewidth. Points defined in (x,y) pairs. n is the number of points. Closed figures should be closed using the style bit for closed figures, not by repeating the first point.
style linewidth xc yc r a1 a2 xcarc
Draw an arc. Arc is centered at xc yc with radius r. Arc segment begins at angle a1 and ends at angle a2. a1, a2, and style are floating-point; all other values are integers. style values are described below.
style linewidth x y rx ry a1 a2 ellipse
Draw an ellipse. This follows the same convention as ``xcarc'' except that the radius is split into major (rx) and minor (ry) components (both integer values).
style linewidth x1 y1 x2 y2 x3 y3 x4 y4 spline
Draw a bezier cubic curve defined by the endpoints x1 y1 and x4 y4 and the control points x2 y2 and x3 y3. style values are described below. linewidth is a floating-point value; all other values are integer.
x y beginpath
Defines a path made of xcircuit objects. These may be polygons, splines, arcs, or ellipses. However, in paths, the direction in which each element is drawn, and the last point of some elements must equal the start point of the next element, so these elements have slightly different syntax inside the path. x y defines the starting point of the path. Subsequent points in the path are determined by the elements defined in the path:
x2 y2 ... xm ym n polyc
Defines a polygon starting at the current point, and passing through all the defined points in order. n is the number of points, where n = m - 1.
x2 y2 x3 y3 x4 x4 curveto
``curveto'' is the actual PostScript definition. Using the current point as an endpoint, defines a bezier curve with other endpoint x4 y4 and control points x2 y2 and x3 y3.
xc yc r a1 a2 arc
``arc'' is the actual PostScript definition. Uses the same definitions as ``xcarc'', except that the arc is always drawn counterclockwise, and a line is drawn from the current point to the first point on the arc, to maintain the path.
xc yc r a1 a2 arcn
``arcn'' is the actual PostScript definition. It is defined exactly like ``arc'' except that the arc is drawn in the clockwise direction.
xc yc rx ry a1 a2 pellip
Defined much like ``arc'' except for the separation of the radius into major (rx) and minor (ry) components.
xc yc rx ry a1 a2 nellip
Defined much like ``arcn'' except for the separation of the radius into major (rx) and minor (ry) components.

style linewidth endpath
Ends a path definition, giving it a line style style (integer) and relative linewidth linewidth (floating-point) with which to stroke the path.
{proc} (string) [...] parts just rotate scale x y label
Defines a label at position x y (integer), justified according to the bitmask just (integer), rotated by rotate (integer) degrees and scaled by a factor of scale (floating-point) relative to XCircuit's default scale (1.0 is about 14 points in a page scale of 1.0). The just bitmask is more easily drawn this way:
3 1 0
7 5 4
15 13 12
Bit 5 of the just value, if set, declares the label to be ``flip-invariant''. That is, if the text is inside an object which is flipped, the text does not flip along with the object but remains in a readable orientation. This is true for both the x and y directions. If text is rotated more than 90 degrees, it is flipped so that the text is oriented upright (within 90 degrees) with respect to the horizontal.

As of XCircuit version 2.3.6, bit 6 of the just value, if set, declares the label to be visible on all levels of the hierarchy. This only has an effect on pin labels, which by default cannot be seen on any level in the hierarchy above the object containing the pin.

Label parts can be one of the following:

(text)
Insert string text into the label output. May contain non-ASCII characters as octal codes, following the PostScript notation.

{proc}
Execute procedure proc at this point in the label output. Valid procedures understood by xcircuit are defined below.

vnumber
Insert parameter number number into the label at this point. If a value is defined in the call to the object instance, it takes precedence. Otherwise, the default value in the object definition is used.

Note that label parts read backwards from the order they appear in the label, although text inside a string label part reads forwards with respect to the label output.

The following procedures are defined for labels in xcircuit:

{ul}
Underline following text string.
{ol}
Overline following text string.
{}
Stop any over/underlining (null procedure; separates text strings).
{Ts}
Define a tab stop at the current location.
{Tf}
Tab forward to first tab stop on the right.
{Tb}
Tab backward to first tab stop on the left.
{qS}
Insert quarter space
{hS}
Insert half space
{ss}
Begin subscript
{Ss}
Begin superscript
{ns}
Cancel sub- or superscript (normal script)
{CR}
Insert embedded carriage-return
{kx ky Kn}
Offset text by kx ky values (integer)
{R G B scb}
Change text color to the given R G B values (floating-point, 0 to 1 inclusive)
{scb}
Revert to original text color
{/fontname cf}
Switch to new font named fontname
{/fontname scale cf}
Switch to new font named fontname at scale scale (floating-point).
{proc} (string) [...] parts just rotate scale x y pinlabel
Same syntax as ``label'' but defines a label for a schematic-type pin. The label only shows up when the defined object is on the top-level page, and the label is offset slightly from the point of origin.
{proc} (string) [...] parts just rotate scale x y infolabel
Same syntax as ``label'' but defines a label for declaring schematic output. See the schematic tutorial pages for the meaning of ``infolabel'' content.
mark {proc} (string) vn [...] ctmk just rotate scale x y label | pinlabel | infolabel
Alternative form of the ``label'' definition for use with parameters. Parameters are written v1, v2, etc., with the number order matching that in the current object's parameter list. If any parameter is inserted into a string, the number of parts is unknown. By using the syntax above, the PostScript interpreter can use the mark to automatically determine the number of parts in the string after parameters are substituted.
scale rotation x y object_name
Draw a defined object. Object name is object_name, which must have been defined before instantiation. rotation is an integer angle of rotation. scale (floating-point) is the overall scale of the object, defined relative to the size at which the object was drawn. x y (integer) is the position of the object (the origin of the object is positioned at this coordinate).

Style bitmask

For each type declaring style in the above list, the style value is a bitmask with the following parts:
bit(s) values use
0 0, 1 border closed if 0, open if 1
1-2 0, 2, 4, 6 border line is solid if 0, dashed if 2, dotted if 4
3 0, 8 draw border if 8
4 0, 16 area enclosed filled if 16, unfilled if 0
5-7 0 to 224 modulus 32 area filled with grayscale stipple
9 0, 256 area enclosed is opaque if 256
10 0, 512 border is a bounding box if 512

For More Information. . .

PostScript is a registered trademark of Adobe, Inc.

For more information on the PostScript language, click here for the PostScript Language Reference Manual, third edition
(PDF file, 7.4MB (!), 912 pages).

Back to the xcircuit home page. . .

email: tim@bach.ece.jhu.edu