/* © Copyright 1995 UNICAMP.  See the notice at the end of this file. */
/* Last edited on 1999-03-01 03:12:02 by stolfi */

/* Routines for writing PS (Encapsulated PostScript) files. */

#ifndef PS_H
#define PS_H

#include <stdio.h>

/*** ENCAPSULATED POSTSCRIPT FIGURES ***/

void ps_begin_figure (
    FILE *psfile,
    double xmin, double xmax,
    double ymin, double ymax,

    double hmin, double hmax,
    double vmin, double vmax,

    int xn, int yn
  );
  /* 
    Initializes an Encapsulated PostScript file.

    An Encapsulated PostScript file contains a single figure, with a
    BoundingBox comment, without an explicit "showpage" command;
    It is suitable for inclusion in TeX papers and such.  

    This procedure writes the preamble and bounding box, sets
    coordinate system, clip path, caption font, Postscript operators
    and constants, etc.

    Client coordinates will range over [xmin __ xmax] x [ymin __ ymax].
    Plotting area is [hmin __ hmax] x [vmin __ vmax] (in pt).
    The plotting scales dh/dx and dv/dy must be equal.

    The plotting area is divided implicitly into a grid of /xn/ by /yn/
    rectangular "cells".
  */

void ps_end_figure (FILE *psfile);
  /* Finalizes an Encapsulated PostScript file. */

/*** MULTI-PAGE POSTSCRIPT DOCUMENTS ***/

void ps_begin_document (FILE *psfile);
  /* 
    Initializes a (non-encapsulated, multi-page) PS file.
    
    A standard PostScript file contains a document with one or more pages,
    with explicit "show" commands at the end of each page, and no BoundingBox 
    comment.  It can be printed by itself.

    The procedure writes the file's preamble, with auxiliary
    Postscript operators.

    The client must call ps_begin_page and ps_end_page around each page.
    of the document.
  */

void ps_begin_page(
    FILE *psfile,
    int page,
    double xmin, double xmax,
    double ymin, double ymax,

    double hmin, double hmax,
    double vmin, double vmax,

    int xn, int yn
  );
  /* 
    Starts a new page of a PS document. 
    
    Sets coordinate system, clip path, dimension constants, etc.

    Client coordinates will range over [xmin __ xmax] x [ymin __ ymax].
    Plotting area is [hmin __ hmax] x [vmin __ vmax] (in pt).
    The plotting scales dh/dx and dv/dy must be equal.

    The plotting area is divided implicitly into a grid of /xn/ by /yn/ 
    rectangular "cells".
  */

void ps_end_page(FILE *psfile);
  /* 
    Finalizes a page: Writes page trailer line, etc. */

void ps_end_document (FILE *psfile, int npages);
  /* 
    Finalizes a multipage document.  The client must keep track 
    of the number of pages that were written to the file. */

/*** DRAWING COMMANDS ***/

void ps_begin_section (FILE *psfile, char *title);
  /* 
    Starts a new section of a plot. The title is a comment */

void ps_end_section (FILE *psfile);
  /* 
    Ends a section of a plot. */

void ps_set_pen (
    FILE *psfile,
    double gray,
    double width,
    double dashlength,
    double dashspace
  );
  /*
    Sets pen parameters and ink color for line drawing.
    Dimensions are in *millimeters* */

void ps_draw_segment(
    FILE *psfile,
    double xa, double ya,
    double xb, double yb
  );
  /* 
    Draws segment from (xa,ya) to (xb,yb) with current pen and gray */

void ps_draw_curve(
    FILE *psfile,
    double xa, double ya,
    double xb, double yb,
    double xc, double yc,
    double xd, double yd
  );
  /*
    Draws a Bezier arc with given control points, using the current pen and gray. */
  
void ps_draw_rectangle(
    FILE *psfile,
    double xlo, double xhi,
    double ylo, double yhi
  );
  /* 
    Draws the outline of the given rectangle using the current pen. */

void ps_fill_rectangle(
    FILE *psfile,
    double xlo, double xhi,
    double ylo, double yhi,
    double gray
  );
  /* Fills given rectangle with given gray color */

void ps_fill_and_draw_rectangle(
    FILE *psfile,
    double xlo, double xhi,
    double ylo, double yhi,
    double gray
  );
  /* 
    Fills rectangle with given gray, then
    draws its outline with current pen.
  */

void ps_fill_circle(
    FILE *psfile,
    double xc, double yc, double radius,
    double gray
  );
  /*
    Fills the circle with given center and radius, using the given gray. */
  
void ps_draw_circle(
    FILE *psfile,
    double xc, double yc, double radius
  );
  /* 
    Draws the circle with given center and radius, using the current pen and gray. */
  
void ps_fill_and_draw_circle(
    FILE *psfile,
    double xc, double yc, double radius,
    double gray
  );
  /* 
    Fills the circle with given center and radius, using the given gray,
    then draws its outline, using the current pen and gray. */

void ps_fill_and_draw_lune(
    FILE *psfile,
    double xc, double yc, double radius, double tilt,
    double gray
  );
  /* 
    Fills the lune with given center, radius, and tilt, using the given gray,
    then draws its outline, using the current pen and gray. */
  
void ps_fill_polygon(
    FILE *psfile,
    double x[], double y[],
    int n,
    double gray
  );
  /*
    Fills the polygon (x[1],y[1]),.. (x[n],y[n]) with the given gray level.
  */
  
void ps_draw_polygon(
    FILE *psfile,
    double x[], double y[],
    int n
  );
  /*
    Draws the contour of the polygon (x[1],y[1]),.. (x[n],y[n]) 
    using the current pen and gray.
  */
  
void ps_fill_and_draw_polygon(
    FILE *psfile,
    double x[], double y[],
    int n,
    double gray
  );
  /*
    Fills the polygon (x[1],y[1]),.. (x[n],y[n]) with the given gray level,
    then draws its contour using the current pen and gray.
  */
  
void ps_fill_triangle(
    FILE *psfile,
    double xa, double ya,
    double xb, double yb,
    double xc, double yc,
    double gray
  );
  /* Fills triangle /abc/ with given gray level. */

void ps_fill_grid_cell(FILE *psfile, int xi, int yi, double gray);
  /*
    Fills the given cell of the current cell grid with the given
    gray level.
  */

void ps_draw_coord_line (FILE *psfile, char axis, double coord);
  /* 
    Draws a reference line perpendicular to the given axis 
    at the given coordinate value.
  */

void ps_draw_grid_lines(FILE *psfile);
  /* 
    Draws the cell boundaries with the current pen and gray level. */

void ps_set_label_font(FILE *psfile, char *font, float size);
  /*
    Sets the name and point size of the font to be used by ps_put_label. */

void ps_put_label(
    FILE *psfile, 
    char *text, 
    double x, double y, 
    float xalign, float yalign
  );
  /*
    Prints "label" at point (x,y), using the current label font size. 
    The parameter "xalign" (resp. "yalign)" specifies which point of the string's 
    bounding box will end up at (x,y): 0.0 means the left (resp. bottom) side,
    1.0 means the right (resp. top) side.  Default is (0.5, 0.5), meaning 
    the box will be centered at (x,y). */

void ps_draw_frame (FILE *psfile);
  /* 
    Draws a frame around the plotting area. (The frame 
    will extend half a line width outside the nominal bounding box.) */

void ps_add_caption(FILE *psfile, char *txt);
  /*
    Adds a caption text below the drawing, *outside* the nominal
    bounding box. */

/*** LOW-LEVEL HACKS ***/

void ps_put_text(FILE *psfile, char *text, char *newline);
  /* 
    Writes a text string to /psfile/, in Postscript form,
    handling special chars and parentheses.
    
    Replaces any embedded '\n' by the given /newline/ string.
  */

#endif

/****************************************************************************/
/* (C) Copyright 1993 Universidade Estadual de Campinas (UNICAMP)           */
/*                    Campinas, SP, Brazil                                  */
/*                                                                          */
/* This file can be freely distributed, modified, and used for any          */
/*   non-commercial purpose, provided that this copyright and authorship    */
/*   notice be included in any copy or derived version of this file.        */
/*                                                                          */
/* 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.                              */
/****************************************************************************/