/* Tools for generating figures for IA/AA papers. */
/* Last edited on 2024-12-21 14:02:27 by stolfi */

#ifndef figtools_mscale_H
#define figtools_mscale_H

#include <stdio.h>
#include <values.h>

#include <interval.h>
#include <frgb.h>
#include <pswr.h>

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

/* A generic function from {R^d} to {R^n}, for plotting */
typedef void Field(double x[], double fx[]); 

/* General plot options: */
typedef struct plot_options_t
  { 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. */
    frgb_t 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). */
  } plot_options_t;

/* Essential parameters for a "function graph" figure: */
typedef struct GraphData
  { 
    char *tag;       /* Function name (for output file names). */
    char *title;     /* Function description. */
  } GraphData;
  
void start_album(PSStream **psP, plot_options_t *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
  ( PSStream **psP,
    plot_options_t *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, and stores its address in {*ps}. Otherwise {*ps} must be non-NULL and initialized,
    as by {start_album}; 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(PSStream **psP, plot_options_t *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_album(PSStream **psP, plot_options_t *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)}. */

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