/* Basic 1D plotting routines for multiscale talk. */
/* Last edited on 2012-12-11 23:20:48 by stolfilocal */

#ifndef plot1d_mscale_H
#define plot1d_mscale_H

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

#include <pswr.h>
    
#include <figtools_mscale.h>

typedef int8_t plot_1d_axis_t; 
  /* Axis of plot: 0 = horizontal, 1 = vertical. */

/* 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 plot_1d_logY_graph_decoration
  ( PSStream *ps,
    plot_options_t *o,
    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. */
    double mag[],     /* Function scales (one function unit in client units). */
    interval_t win[], /* Plotting area (client units). */
    double scale      /* Plot scale (one client unit in mm). */
  );
  /* Draws the coordinate axes, tick marks, etc for a set of one or
    more function graphs. Assumes Y coordinates are log 
    scaled in base 10. The tick marks on axis {i} and associated
    coord lines span the range {fr[i]} with steps {tstep[i]} (major)
    and {sstep[i]} (minor).
    
    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,
    plot_options_t *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,
    plot_options_t *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,
    plot_options_t *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,
    plot_options_t *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