/* Tools for generating figures for IA/AA papers. */
/* Last edited on 2007-12-27 02:28:09 by stolfi */

#ifndef figtools_H
#define figtools_H

#include <dg_grid.h>
#include <dg_pulse.h>
#include <dg_tree.h>
#include <bz_basic.h>
#include <bz_patch.h>
#include <pswr.h>
#include <stdio.h>
#include <values.h>

#ifndef INF
#define INF INFINITY
  /* Infinity in double format. */
#endif

/* An RGB color value; */
typedef struct Color { double c[3]; } Color;
   
/* A generic function from {R^d} to {R^n}, for plotting */
typedef void Field(double x[], double fx[]); 

/* General plot options: */
typedef struct PlotOptions
  { char *outName;    /* Prefix for output file names. */
    bool_t eps;         /* TRUE for Encapsulated Postscript. */
    char *paperSize;  /* TRUE for Encapsulated Postscript. */
    bool_t color;       /* TRUE uses colors, FALSE uses only grays. */
    Color fill;       /* Fill color (RGB [0_1]). */
    double scale;     /* Figure scale factor (client to mm). */
    double margin[2]; /* X and Y extra margin (in mm). */
    double meshSize;  /* Nominal plot step size (in mm). */
  } PlotOptions;

/* Essential parameters for a "function graph" figure: */
typedef struct GraphData
  { 
    char *tag;       /* Function name (for output file names). */
    char *title;     /* Function description. */
  } GraphData;
  
extern PSStream *ps;
  /* "The" Postscript file for single-document plotting. */
  
void start_document(PlotOptions *o);
  /* IF {o->eps} is FALSE, sets {ps} to a new Postscript document
    whose filename is "{o->outName}.ps".  If {o->eps} is TRUE,
    has no effect. */

void start_figure
  ( PlotOptions *o,
    char *figTag,
    char *title,
    interval_t bbox[2],    /* Client plot window. */
    double scale            /* Plot scale (mm per client unit). */
  );
  /* If {o->eps} is true, {ps} must be NULL; opens a new Encapsulated
    Postscript file, with name "{o->outName}-{figTag}.eps", and
    initializes it. Otherwise {ps} must be non-NULL and initialized,
    as by {start_document}; starts a new page with the figure centered
    on it, with {title} as the caption.
    
    In either case the nominal client plot window is {bbox}, plus a 
    safety margin {o->margin}. */

void finish_figure(PlotOptions *o);
  /* Finalizes the current figure written to file {ps}.
    If {o->eps} is true, closes the file and returns NULL.
    Otherwise simply terminates the current page. */

void finish_document(PlotOptions *o);
  /* If {o->eps} is true, {ps} must be NULL and the call is 
    a no-op.  Otherwise {ps} must be a plain Postscript file;
    finalizes and closes it. */

void hatch_rectangle(PSStream *ps, interval_t B[], double hstep);
  /* Draws hatch-lines across the cell {B}, spaced {hstep} in client
    units, with the current pen. */

void persp_project
  ( double x, double y, double z, 
    double *xp, double *yp, double *zp,
    double vdist
  );
  /* Computes the perspective projection {(xp,yp,zp)} of the point
    {(x,y,z)}. If {vdist == 0}, uses parallel projection; if {vdist >
    0}, uses conical perspective for an observer at distance {vdist}
    from the screen (in client units) along the direction
    {(1,1,1)}. */

void print_1d_cell(FILE *wr, interval_t cell);
void print_2d_cell(FILE *wr, interval_t cell[]);
void print_3d_cell(FILE *wr, interval_t cell[]);
  /* Prints the cell ranges along each axis. */

bool_t check_pulse_index(dg_pulse_family_t *fam, dg_pulse_mother_index_t pix);
  /* If the pulse index {pix} is valid for the family {fam},
    returns TRUE; otherwise prints a warning message and returns FALSE. */

/* 
  VALUE RANGES FOR PULSES */

interval_t get_pulse_range
  ( dg_pulse_kind_t pkind, /* Kind of mother spline. */
    dg_cont_t c,           /* Continuity class of spline. */
    dg_degree_t g,         /* Degree of spline. */
    dg_pulse_mother_index_t pix,  /* Puse index. */
    dg_grid_size_t gsz      /* Num of cells in grid. */
  );
  /* Returns an interval that encloses the values of the 
    pulse with parameters {pkind,c,g,pix} on a periodic grid
    with {gsz} intervals. */

interval_t get_common_pulse_range
  ( dg_pulse_kind_t pkind,  /* Pulse kind. */
    dg_cont_t c,           /* Continuity class of spline. */
    dg_degree_t gmax,      /* Max degree to consider. */
    dg_grid_size_t gsz      /* Num of cells in grid. */
  );
  /* Returns an interval that encloses the values of a pulse of kind
    {pkind} and continuity class {c}, with any valid degree {g} up to
    {gmax}, and any pulse index {pix}, on a periodic grid with {gsz}
    intervals. */

interval_t multiply_ranges (interval_t *x, interval_t *y);
  /* Computes the product of the two intervals {x,y}.
    Beware - does not worry about infinities and 
    roundoff errors. */


#endif