(* Copyright (C) 1995 UNICAMP.  See notice at the end of this file.  *)

INTERFACE PSWrite;  (* Version 95-04-16-stolfi *)

(* Low-level tools to write Postscript files *)

IMPORT Wr;

(* All coordinates and lengths are in millimeters, except where noted. *)

TYPE
  LONG = LONGREAL;
  BOOL = BOOLEAN;
  Axis = {X, Y};

PROCEDURE EPSFileHeader(wr: Wr.T; xMin, xMax, yMin, yMax: LONG);
  (*
    Writes the standard header for an Encapsulated Postscript (EPS) file,
    including the "%%BoundingBox" comment.  The bounding box will be 
    the rectangle "[xMin_xMax]x[yMin_yMax]" (given in millimeters,
    converted internally to points).
    
    An EPS file is meant to be included in other documents;
    it contains a single figure, with no "%%Page" comments or
    "showpage" commands.  Be sure to call "EPSFileTrailer" below
    before closing the writer. *)
    
PROCEDURE EPSFileTrailer(wr: Wr.T);
  (*
    Writes the standard Encapsulated Postscript trailer. *)

PROCEDURE PSFileHeader(wr: Wr.T);
  (*
    Writes a standard Postscript header for non-encapsulated, possibly
    multipage documents.  The header includes a "%%Pages: (atend)" comment.
    Be sure to call "PSPageHeader" and "PSPageTrailer" around each page,
    and "PSFileTrailer" at the end of the document. *)

PROCEDURE PSFileTrailer(wr: Wr.T; pages: TEXT);
  (*
    Writes the standard Postscript trailer, including
    the "%%Pages:" comment. *)

PROCEDURE PSPageHeader(wr: Wr.T; page, foot: TEXT);
  (*
    Writes the "%%BeginPage" command, and prints the given
    footline at the bottom of the page.
    Valid only in plain Postscript files. *)

PROCEDURE PSPageTrailer(wr: Wr.T);
  (*
    Writes the "showpage" command, and the "%%EndPage" comment.
    Valid only in plain Postscript files. *)

PROCEDURE BeginDrawing(wr: Wr.T; xMin, xMax, yMin, yMax: LONG);
  (*
    Starts a new plot on the current page.
    The drawing area will be  "[xMin_xMax]x[yMin_yMax]",
    relative to the bottom left corner of the page.
    All drawing commands will be clipped to this
    rectangle.

    An Encapsulated Postscript file should contain only one drawing. *)
    
PROCEDURE EndDrawing(wr: Wr.T);
  (*
    Must be called at the end of each drawing that 
    was started with "BeginDrawing". *)

PROCEDURE Comment(wr: Wr.T; txt: TEXT);
  (*
    Writes "txt" as a comment to the Postscript file. *)
    
PROCEDURE SetLineColor(wr: Wr.T; r, g, b: REAL);
PROCEDURE SetLineWidth(wr: Wr.T; width: REAL);
PROCEDURE SetLineDashPattern(wr: Wr.T; READONLY pattern: ARRAY OF REAL; skip: REAL);
  (*
    Sets the pen parameters for "Segment" and figure outlines.
    The "width", "pattern", and "skip" parameters are in millimeters. *)
    
PROCEDURE SetFillColor(wr: Wr.T; r, g, b: REAL);
  (*
    Sets the color used by "Rectangle", "Circle", etc.
    when filling figures. *)
    
PROCEDURE RoundJoinAndCaps(wr: Wr.T);
  (*
    Sets the line join and cap style to "round" *)
    
PROCEDURE SetGridSize(wr: Wr.T; xN, yN: CARDINAL);
  (*
    Defines the number of grid cells for "Cell" and "GridLines". *)
    
(* 
  The following procedures assume the coordinates are in mm, relative
  to the lower left corner of the drawing area, except 
  where said otherwise.  
  
  If "fill=TRUE" the interior of the figure is painted using the
  current color; then if "draw=TRUE" the outline of the figure is
  drawn using the current pen.  *)

PROCEDURE Segment(wr: Wr.T; xa, ya, xb, yb: LONG);
  (*
    Draws a line segment from "(xa,ya)" to "(xb,yb)". *)
    
PROCEDURE Rectangle(wr: Wr.T; xlo, xhi, ylo, yhi: LONG; fill, draw: BOOL);
  (*
    Draws and/or fills the rectangle "[xlo_xhi]x[ylo_yhi]". *)
    
PROCEDURE Triangle(wr: Wr.T; xa, ya, xb, yb, xc, yc: LONG; fill, draw: BOOL);
  (*
    Draws and/or fills the triangle with corners "(xa,ya)",
    "(xb,yb)", "(xc,yc)". *)

PROCEDURE Circle(wr: Wr.T; xc, yc, radius: LONG; fill, draw: BOOL);
  (*
    Draws and/or fills the circle with center "(xc,yc)" and 
    given "radius". *)
    
PROCEDURE Ellipse(wr: Wr.T; xc, yc, xa, ya, xb, yb: LONG; fill, draw: BOOL);
  (*
    Draws and/or fills the ellipse that corresponds to the unit circle
    in the affine frame with origin "(xc,yc)" and axes "(xa,ya), (xb,yb)". *)
    
PROCEDURE GridCell(wr: Wr.T; xi, yi: CARDINAL; fill, draw: BOOL);
  (*
    Draws and/or fills the grid cell numbered "(xi,yi)".
    See "SetGrid" above. *)
    
PROCEDURE GridLines(wr: Wr.T);
  (*
    Draws the cell grid lines using the current pen. *)
    
PROCEDURE CoordLine(wr: Wr.T; axis: Axis; coord: LONG);
  (*
    Draws a line perpendicular to the given axis
    at the given coordinate, using the current pen. *)
    
PROCEDURE Frame(wr: Wr.T);
  (*
    Draws a frame around the drawing area, using the current pen. *)

PROCEDURE SetFont(wr: Wr.T; font: TEXT; size: REAL);
  (*
    Defines the font (family name and point size) to be used for the
    following "Label" commands.  
    
    The "name" must be a valid Postscript font family name,
    e.g. "Courier", "Times-Roman", "Times-Bold", "Helvetica-Oblique",
    "Times-BoldItalic", etc; "size" is the nominal font size in points. *)

PROCEDURE SetTextColor(wr: Wr.T; r, g, b: REAL);
  (*
    Sets the color of text, for "Label" commands. *)
    
PROCEDURE Label(
    wr: Wr.T; 
    txt: TEXT;
    x, y: LONG; 
    xAlign, yAlign: REAL := 0.0; 
    angle: REAL := 0.0;
  );
  (*
    Prints "txt" tilted by "angle" with its reference point at "(x,y)".
    The label is NOT clipped to the drawing area.

    The parameters "xAlign" and "yAlign" are the coordinates of the
    reference point relative to the text's bounding box: 
    "(0,0)" means the lower left corner, "(1,1)" the upper right
    corner, "(0.5,0.5)" the center, etc. The text should not
    contain embedded newline characters. *)

(*** VERY LOW LEVEL HACKS ***)

PROCEDURE PutString(psfile: Wr.T; text: TEXT; newline: TEXT);
  (*
    Writes "text" to the Postscript file, with the necessary escapes.
    Each "\n" character in "text" is replaced by the "newline"
    string.*)

END PSWrite.
(****************************************************************************)
(*                                                                          *)
(* Copyright (C) 1995 Universidade Estadual de Campinas (UNICAMP)           *)
(*                                                                          *)
(* Authors:                                                                 *)
(*   Jorge Stolfi        - CS Dept, UNICAMP <stolfi@dcc.unicamp.br>         *)
(*                                                                          *)
(* This file can be freely used, distributed, and modified, provided that   *)
(*   this copyright and authorship notice is included in every copy or      *)
(*   derived version.                                                       *)
(*                                                                          *)
(* DISCLAIMER: This software is offered ``as is'', without any guarantee    *)
(*   as to fitness for any particular purpose.  Neither the copyright       *)
(*   holder nor the authors or their employers can be held responsible for  *)
(*   any damages that may result from its use.                              *)
(*                                                                          *)
(****************************************************************************)