/* Basic 1D plotting routines for the dygrid papers. */
/* Last edited on 2007-04-16 18:40:49 by stolfi */

#ifndef plot1d_H
#define plot1d_H

#include <stdio.h>
#include <stdint.h>

#include <pswr.h>

#include <basis1d.h>

#include <figtools.h>
    
typedef int8_t plot_1d_axis_t; 
  /* Axis of plot: 0 = horizontal, 1 = vertical. */

/* ELEMENT RANGE ESTIMATION */

void compute_1d_element_ranges
  ( b1d_kind_t bkind,       /* Kind of basis. */
    b1d_cont_t c,           /* Continuity class. */
    b1d_degree_t g,         /* Degree. */
    b1d_grid_size_t gsz,    /* Num of intervals in grid period. */
    double wd,              /* Width of root interval. */
    interval_t fr[]         /* (OUT) X- and value ranges (rounded). */
  );
  /* Computes the nominal domain range {fr[0]} and value range {fr[1]}
    suitable for plotting a standard dyadic element of kind {pkind}, continuity {c}
    degree {g}, and any index, assuming a periodic grid with {gsz} intervals and
    root inertval width {wd}. */

void compute_1d_common_element_ranges
  ( b1d_cont_t c,          /* Continuity class of spline. */
    b1d_grid_size_t gsz,   /* Num of intervals in grid period. */
    double wd,            /* Width of root interval. */
    interval_t fr[]       /* (OUT)  X- and value ranges (rounded). */
  );
  /* Computes the nominal domain range {fr[0]} and value range {fr[1]}
    suitable for plotting standard dyadic elements with continuity class
    {c}, of any kind, degree, and index, assuming a periodic grid with
    {gsz} intervals and root interval width {wd}. */

/* SCALE ADJUSTMENT */

/* For the following procedures, the {XXXmag} parameters are
  extra scale factors to be applied to the argument value {x} and the
  function value {y = f(x)} (`function coordinates') to turn them into
  coordinates for plotting (`client coordinates'). These scale factors
  affect the size of the plot and the spacing of ticks and coordinate
  lines, but not the actual arguments passed to the function,
  or the label attached to tick marks. */

void compute_1d_plot_scales
  ( PSStream *ps,
    PlotOptions *o,
    interval_t fr[],   /* (IN) Nominal graph range. */
    double scale,       /* Plot scale (one client unit in mm). */
    double  mag[],      /* Graph scaling factors (function to client). */
    interval_t gr[],   /* (OUT) Range of function coords for plot. */
    interval_t win[]   /* (OUT) Plot window in client coords. */
  );
  /* Computes the nominal function domain/range {fr}, the graphing
    range {gr}, and the plot window {win} suitable for a mother 
    spline of the given {kind}, with domain period {gsz}. */
    
/* PLOTTING */

void plot_1d_function
  ( PSStream *ps,
    PlotOptions *o,
    double func (double x),
    double xstep,
    interval_t xr,
    double xmag,
    interval_t yr,
    double ymag
  );
  /* Draws the graph of {func(x)}. The argument {x} ranges in {xr}
    with step {xstep}, and the function value is clipped to {yr}. For
    plotting, the {x} and {y} values are scaled by {xmag} and
    {ymag}. */
    
void plot_1d_graph_decoration
  ( PSStream *ps,
    PlotOptions *o,
    double scale,
    double mag[],
    interval_t fr[],  /* Function domain and range, for ticks &c. */
    double tstep[],    /* Space between major (labeled) ticks/coordlines. */
    double sstep[],    /* Space between minor (unlabeled) ticks/coordlines. */
    interval_t gr[],  /* Function domain and range for graph/clip. */
    interval_t win[]  /* Plotting area (client units). */
  );
  /* Draws the coordinate axes, tick marks, etc for a set of one or
    more function graphs. The tick marks on axis {i} and associated
    coord lines span the range {fr[i]} with steps {tstep[i]} (major)
    and {sstep[i]} (minor). The function is evaluated over the
    interval {gr[0]} and its graph is clipped to the Y range {gr[1]}.
    
    Arguments {tstep}, {sstep}, and {gr} should be given in function
    coordinates, which are scaled by {mag[0..1]} to yield the plotting
    (client) coords. */
    
void plot_1d_axes
  ( PSStream *ps,
    PlotOptions *o,
    interval_t *xr,
    double xmag,
    interval_t *yr,
    double ymag
  );
  /* Draws the parts of the coordinates axes that lie
    in the specified rectangle. The ranges {xr} and {yr}
    are in function coordinates; for plotting, they
    are scaled by {xmag} and {ymag}. */

void plot_1d_coord_lines
  ( PSStream *ps,
    PlotOptions *o,
    plot_1d_axis_t ax,  /* Axis PERPENDICULAR to the lines. */
    int nsteps,         /* Number of steps (num of lines minus 1) */
    interval_t *nr,     /* Cordinate range along axis {ax}  */
    double nmag,        /* Extra scale factor along axis {ax}. */
    interval_t *tr,     /* Range along the lines. */
    double tmag         /* Extra scale factor along the lines. */
  );
  /* Draws {nsteps+1} cordinate lines perpendicular to axis {ax},
    spanning the range {nr} on that axis. (If {nsteps == 0}, plots a
    single line at mid-range.) The lines extend over the range {tr}
    along axis {1-ax}.
    
    The parameters {nr} and {tr} are in function coordinates; for
    plotting, they are scaled by {nmag} and {tmag}. */

void plot_1d_ticks_and_lines
  ( PSStream *ps,
    PlotOptions *o,
    plot_1d_axis_t ax,       /* Axis along which ticks are to be placed. */
    double hsize,     /* Half-length of tick marks (client units). */
    double step,      /* Spacing between ticks (func units). */
    bool_t labeled,     /* TRUE to print label at left/under each tick. */
    bool_t lines,       /* TRUE draws coord lines at tick positions. */
    interval_t *cr,  /* Only place ticks within this coordinate range. */
    double cmag,      /* Extra scale factor along axis {ax}. */
    interval_t *gr,  /* Trim coordlines to this coordinate range. */
    double gmag,      /* Extra scale factor across axis {ax}. */
    interval_t win[] /* Plot window in client units. */
  );
  /* Draws tick marks along axis {ax}, spanning the range {cr}, spaced
    {step} units apart.  If {labeled} is TRUE, also writes the
    coordinate value, with an appropriate format. If {lines} is TRUE,
    also draws a coordinate line at the tick position.  
    
    The tick marks extend {hsize} units on each side of the axis.
    Marks that lie outside the {win} rectangle, or too close to the
    boundary, or too close to the origin are supressed.  Coord lines
    span the range {gr} along the other axis.
    
    The tick spacing {step} and the ranges {cr} and {gr} are in
    function coordinates, which are scaled by {cmag}, {cmag} and
    {gmag}, respectively, before plotting. The argument {hsize} is in
    *client* units, irrespective of {cmag} and {gmag}. */

void plot_1d_ticks
  ( PSStream *ps,
    PlotOptions *o,
    plot_1d_axis_t ax, /* Axis along which ticks are to be placed. */
    double hsize,      /* Half-length of tick marks (client units). */
    char *fmt,         /* Format for tick labels, or NULL, */
    int nsteps,        /* Number of tick steps in {cr}. */
    interval_t *cr,    /* Only place ticks within this coordinate range. */
    double mag,        /* Scale fator from func units to client units. */
    interval_t win[]   /* Plot window in client units. */
  );
  /* Draws {nsteps+1} tick marks along axis {ax}, spanning the range
    {cr}. (If {nsteps == 0}, plots a single tick at mid-range.) If
    {fmt} is not null, also writes the coordinate value, with that
    format. The tick marks extend {hsize} units on each side of
    the axis. Marks that lie outside the {win} rectangle, or too close
    to the boundary, or too close to the origin are supressed.
    
    The range {cr} is in function coordinates, which are scaled by
    {mag} for plotting. The arguments {hsize} and {win} are in
    *client* units, irrespective of {mag}. */
 
char *plot_1d_tick_format(double step, interval_t *fr);
  /* Selects a good format for tick labels, given the tick spacing 
    {step} and the function argument/value coordinate range {fr}.  */

#endif