XCircuit PostScript Reference

Introduction

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.

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

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

1. Library Header
2. Definition of objects in the library
3. Library Trailer

Header

%!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

%!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.

Prolog

The prolog follows the header and is everything between the lines

%%BeginProlog

%%EndProlog

Optional Definitions

Object Definitions

/object_name {
% llx lly urx ury bbox
begingate
  .
  .
  .
endgate
} def

/object_name {
% llx lly urx ury bbox
(string1) (string2) . . . (stringn) n beginparm
  .
  .
  .
endgate
} def

% page_name is_schematic

Page Definition

%%Page: 1 1
%%PageOrientation: Portrait
/pgsave save def bop
% 1688 848 offsets
1.0000 inchscale
2.6000 setlinewidth 

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

% symbol_name is_symbol

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

%%Trailer
XCIRCsave restore
%%EOF

Libraries

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

The trailer for library files is exactly the following line:

% EndLib

Macros for XCircuit elements

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