home *** CD-ROM | disk | FTP | other *** search
/ Education Sampler 1992 [NeXTSTEP] / Education_1992_Sampler.iso / Programming / Source / HippoDraw / hippo / hippo.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-04-28  |  24.9 KB  |  844 lines
  1. #ifndef _HIPPO_H_        /* only include once */
  2. #define _HIPPO_H_
  3.  
  4. /*
  5.  * hippo.h - histogramming package in C. 
  6.  * originally by jonas karlsson, at SLAC, August 1990
  7.  * much modified since by Gravina, Kunz, Pavel, Rensing
  8.  *
  9.  * Copyright (C)  1991  The Board of Trustees of The Leland Stanford
  10.  * Junior University.  All Rights Reserved.
  11.  *
  12.  * $Id: hippo.h,v 3.13 1992/04/24 01:12:47 rensing Rel $
  13.  */
  14.  
  15. #ifdef THINK_C
  16. #define const
  17. #define malloc(A) malloc((size_t)(A))
  18. #define realloc(A,B) realloc((A),(size_t)(B))
  19. #endif
  20.  
  21. /* for IBM AIX workstations */
  22. #if defined(_IBMR2) && !defined(_BSD)
  23. #define _BSD 1
  24. #include <sys/select.h>
  25. #endif
  26.  
  27. #include <stdarg.h>        /* needed for variable arguments */
  28. #include <stdio.h>        /* needed for FILE definition */
  29.  
  30. /* 
  31.  * pick up the RPC header
  32.  */
  33. #ifdef VM            
  34. #include <rpc.h>
  35. #else
  36. #if defined(_IBMR2) || defined(VAXC)
  37. #define malloc old_malloc
  38. #endif
  39. #ifdef THINK_C
  40. #include "rpctypes.h"
  41. #include "rpcxdr.h"
  42. #else
  43. #include <rpc/rpc.h>
  44. #endif
  45. #if defined(_IBMR2) || defined(VAXC)
  46. #undef malloc
  47. #endif
  48. #endif
  49.  
  50. #ifndef __STDC__
  51. #define const 
  52. #endif
  53.  
  54. /* 
  55.  * for VMS, add noshare to externals so hippo can be sharable library
  56.  */
  57. #ifdef VMS
  58. #define GLOB_QUAL noshare
  59. #else
  60. #define GLOB_QUAL
  61. #endif
  62.  
  63. #define HIPPO_H_RCSID "$Id: hippo.h,v 3.13 1992/04/24 01:12:47 rensing Rel $"
  64.  
  65. /*
  66.  * enum types for options
  67.  */
  68.  
  69. /*
  70.  * graphtype - type of plot
  71.  * SCATTERPLOT - 2D scatter plot
  72.  * LEGOPLOT    - 2D binned Lego plot
  73.  * COLORPLOT   - 2D binned grayscale/colorscale plot
  74.  *               If drawtype COLOR bit is set, tries to use color scale
  75.  * XYPLOT      - Plot of y versus x
  76.  * STRIPCHART  - Like XYPLOT, but ntuple is considered as circular buffer, 
  77.  *                start is tuple with smallest x value.
  78.  * HISTOGRAM   - 1D binned histogram
  79.  */
  80. typedef enum { SCATTERPLOT, LEGOPLOT, COLORPLOT, XYPLOT, 
  81.             STRIPCHART, HISTOGRAM } graphtype_t;
  82.  
  83. /*
  84.  * drawtype - drawing options
  85.  * BOX      - for HISTOGRAM, draw the histogram box-type line
  86.  * POINT    - draw points
  87.  * LINE     - connect points with straight lines
  88.  * ERRBAR   - plot error bars when appropriate
  89.  * COLOR    - for COLORPLOT, try to use full color spectrum
  90.  */
  91. typedef enum {
  92.      NONE = 0, BOX = 1, POINT = 2, LINE = 4, ERRBAR = 8, COLOR = 16
  93. } drawtype_t;
  94.  
  95. /*
  96.  * plot drivers
  97.  * NEXT     - NeXT Display PostScript and NeXT library calls
  98.  * UNIXPLOT - device-independent UNIXPlot calls
  99.  * LPR      - line printer; same as calling h_print
  100.  * XIVPLOT  - Interviews X-windows calls
  101.  * MAC      - Macintosh QuickDraw
  102.  * X11PLOT  - basic X-windows (R4) driver
  103.  * PSPLOT   - PostScript to file
  104.  * EPSPLOT  - EPS to file (same as PSPLOT for now)
  105.  */
  106. typedef enum { NEXT, UNIXPLOT, LPR, XIVPLOT, MAC, X11PLOT, 
  107.             PSPLOT, EPSPLOT } plotdrvr_t;
  108.  
  109. typedef enum { SOLID, DASH, DOT, DOTDASH } linestyle_t;
  110. typedef enum { SQUARE, SOLIDSQUARE, PLUS, TIMES } plotsymbol_t;
  111. typedef enum { XAXIS, YAXIS, ZAXIS, WEIGHT, XERROR, YERROR } binding_t;
  112.  
  113. /*
  114.  * plot locations - used for axis labels and ticks.
  115.  */
  116. typedef enum { PLOTLEFT=1, PLOTRIGHT=2, PLOTTOP=4, PLOTBOTTOM=8 } plotloc_t;
  117.  
  118.      
  119. /*
  120.  * structure definitions.
  121.  */
  122. #ifdef VM
  123. #include "hshrtnm.h"
  124. #include "h_struct.h"
  125. #else
  126. #include "hippostruct.h"
  127. #endif
  128.  
  129.  
  130. /*-----------------------------------------------------------------------*/
  131.  
  132. /*
  133.  * Function Prototypes
  134.  */
  135.  
  136. #ifdef __cplusplus        /* do not leave open across includes */
  137. extern "C" {            /* for C++ V2.0 */
  138. #endif
  139.  
  140. /*
  141.  * ----------- ntuple functions  -----------------
  142.  */
  143.  
  144. /*
  145.  * h_new - returns a new ntuple, with ndim dimensions.
  146.  *    returns NULL on error.
  147.  */
  148. ntuple h_new(int ndim);
  149.  
  150. /*
  151.  * h_freeNt - frees all memory associated with the n-tuple.
  152.  *    returns 0.
  153.  */
  154. int h_freeNt( ntuple nt );
  155.  
  156. /*
  157.  * h_clrNt - Clear all data points from the n-tuple, 
  158.  *  and reallocs memory for data to default size.
  159.  *    returns -1 on error, 0 on success.
  160.  */
  161. int h_clrNt( ntuple nt );
  162.  
  163. /*
  164.  * h_fill - add one entry to the end of the ntuple data list.
  165.  *          There must be ndim float parameters after the first parameter,
  166.  *          where ndim is the ntuple's dimension.
  167.  *
  168.  * h_arrayFill - add an n-tuple, getting data from an array
  169.  *
  170.  *    return -1 on error, 0 otherwise.
  171.  */
  172. int h_fill(ntuple nt,  ...);
  173. int h_arrayFill(ntuple nt, float *data );
  174.  
  175. /*
  176.  * h_setNtTitle - set title of ntuple data set.
  177.  * h_setNtLabel - set label on ntuple dimension dim.
  178.  * h_setAllNtLabels - set labels on all ntuple dimensions.
  179.  *                There must be ndim strings in the array.
  180.  *
  181.  *   return 0 if successful, -1 if failed.
  182.  */
  183. int h_setNtTitle( ntuple nt, const char *title );
  184. int h_setNtLabel( ntuple nt, int dim, const char *label );
  185. int h_setAllNtLabels( ntuple nt, const char *label[] );
  186.  
  187. /*
  188.  * h_getNtDim - return the dimension of the n-tuple.
  189.  */
  190. #define h_getNtDim(nt) ((int) (nt)->ndim)
  191.  
  192. /*
  193.  * h_getNtTitle - return the title of the ntuple.
  194.  * h_getNtLabel - return the label associated with dimension dim of 
  195.  *                the ntuple. Returns NULL on error.
  196.  */
  197. #define h_getNtTitle(nt) ((const char *)(nt)->title)
  198. const char *h_getNtLabel( ntuple nt, int dim );
  199.  
  200. /*
  201.  * h_getNtNdata - return number of ntuples in nt.
  202.  *  returns -1 on error.
  203.  */
  204. #define h_getNtNdata(nt) ((nt)->ndata)
  205.  
  206. /*
  207.  * h_getNtAllData - return pointer to all the data in specified ntuple. 
  208.  *          Tuples are stored consecutively in the array, first all
  209.  *          columns for the first row, then subsequent rows.
  210.  *          Do NOT attempt to modify the data.
  211.  *
  212.  * h_getNtData - returns a pointer to a particular row in the data.
  213.  *          The first row is numbered 0. Do NOT attempt to modify the data.
  214.  *          Returns NULL on error.
  215.  */
  216. #define h_getNtAllData(nt) ((const float *) (nt)->data)
  217. const float *h_getNtData( ntuple nt, int i_nt );
  218.  
  219. /*
  220.  * h_getNtColumn - get array data for a particular variable in ntuple.
  221.  *          Use h_getNtNdata as number of points returned.
  222.  *          This data is a copy of the data in the ntuple and it is 
  223.  *          therefore the user's responsibility to free the memory
  224.  *          when done.
  225.  *          Returns NULL on error.
  226.  */
  227. float *h_getNtColumn( ntuple nt, int dim );
  228.  
  229. /*
  230.  * h_getNtLow - returns array of lower limits of each column of the ntuple.
  231.  *              ie. f = h_getNtLow( nt); then
  232.  *               f[1] is the lowest value of the 2nd variable of the ntuple.
  233.  *
  234.  * h_getNtHigh - returns array of upper limits.
  235.  *
  236.  *        Do NOT attempt to modify the data.
  237.  */
  238. #define h_getNtHigh(nt) ((const float *) (nt)->nhigh)
  239. #define h_getNtLow(nt) ((const float *) (nt)->nlow)
  240.  
  241.  
  242. /*
  243.  * h_replData - replace the specified row in the ntuple.
  244.  *    i_nt, which is the index of the row to replace (starting from 0),
  245.  *    must be within the existing range of data.
  246.  *    There must be ndim floats after i_nt, where ndim is the dimension
  247.  *    of the ntuple. After calling this routine, the low/high limits of
  248.  *    the ntuple dimensions may be wrong. The flag extremeBad will be set.
  249.  *
  250.  * h_arrayReplData - replace specified tuple from a float array.
  251.  *    Array must contain ndim floats.
  252.  *
  253.  * Return -1 on error, 0 otherwise.
  254.  */
  255. int h_arrayReplData( ntuple nt, int i_nt, float *data );
  256. int h_replData( ntuple nt, int i_nt, ... );
  257.  
  258.  
  259. /*
  260.  * h_getExtremeBad - get flag extremeBad from ntuple.
  261.  *     extremeBad is set if the upper/lower limits may be wrong.
  262.  */
  263. #define h_getExtremeBad(nt) ((nt)->extremeBad)
  264.  
  265. /*
  266.  * h_ntSize - the number of bytes needed to write out a given ntuple.
  267.  *      Some slop is included.
  268.  */
  269. int h_ntSize( ntuple nt );
  270.  
  271.  
  272. /*
  273.  * ---------- Display routines -------------------------------------
  274.  */
  275.  
  276. /*
  277.  * h_newDisp - creates a new display of the type specified.
  278.  *      Sets most fields of the display to reasonable defaults.
  279.  *
  280.  *    Returns NULL on error.
  281.  */
  282. display h_newDisp(graphtype_t type);
  283.  
  284. /*
  285.  * h_copyDisp - create a new display and copy the old one into it.
  286.  *
  287.  *  Returns NULL on error.
  288.  */
  289. display h_copyDisp(display olddisp);
  290.  
  291. /*
  292.  * h_freeDisp - free all memory accosiated with display.
  293.  *    Returns 0.
  294.  */
  295. int h_freeDisp( display disp );
  296.  
  297. /*
  298.  * h_dispSize - calculate the number of bytes needed to 
  299.  *        write out a given display. Some slop is included.
  300.  */
  301. int h_dispSize( display disp );
  302.  
  303.  
  304. /*
  305.  * h_setDispType - sets the plot type.
  306.  *       Returns -1 on error.
  307.  *
  308.  * h_getDispType - fetch the current plot type.
  309.  */
  310. int h_setDispType( display disp, graphtype_t type);
  311. #define h_getDispType(d) ((d)->graphtype)
  312.  
  313. /*
  314.  * h_setDrawType - set the what should be drawn for the data;
  315.  *                 eg. histogram bars, points...
  316.  *
  317.  * h_orDrawType - do a logical OR of draw bits; means the 
  318.  *                given options will be added to list of things
  319.  *                to plot.
  320.  *  Return -1 on error.
  321.  * 
  322.  * h_getDrawType - fetch the current draw type.
  323.  */
  324. int h_setDrawType(display disp, drawtype_t type);
  325. int h_orDrawType(display disp, drawtype_t type);
  326. #define h_getDrawType(d) ((d)->drawtype)
  327.  
  328. /*
  329.  * h_bindNtuple - binds a ntuple to a display
  330.  *    Returns -1 on error.
  331.  *
  332.  * h_getNtuple - fetch the currently bound ntuple.
  333.  */
  334. int h_bindNtuple(display disp, ntuple nt);
  335. #define h_getNtuple(d) ((d)->ntuple)
  336.  
  337. /*
  338.  * h_setNtByRef - set/clear flag to indicate ntuple is access 
  339.  *      "by reference". This means that when written out, a display with
  340.  *      an ntuple "by reference" will NOT cause that ntuple to be
  341.  *      written out as well. When read back in, it is the application's
  342.  *      responsibility to re-establish the connection between the
  343.  *      display and its ntuple.
  344.  *    The third argument is a string which should indicate where the 
  345.  *      ntuple comes from, ie. which file. This is intended to help
  346.  *      with portability.
  347.  *
  348.  * h_getNtByRef - fetch the "by reference" flag.
  349.  *
  350.  * h_getNtFile - get the filename for the ntuple if by reference
  351.  */
  352. int h_setNtByRef(display disp, int flag, const char *filename);
  353. #define h_getNtByRef(d) ((d)->flags.ntByReference)
  354. #define h_getNtFile(d) ((d)->ntFile)
  355.  
  356.  
  357. /*
  358.  * h_bind - binds the ntuple column dataDim to the display quantity.
  359.  *    The ntuple columns are numbered starting from 0.
  360.  *    Returns -1 on error, 0 otherwise.
  361.  *  
  362.  * h_getBinding - fetch the current binding in the display.
  363.  */
  364. int h_bind(display disp, binding_t q, int dataDim);
  365. int h_getBinding( display disp, binding_t q );
  366.  
  367.  
  368. /*
  369.  * h_bindMany - binds specified number (n) of plot variables to 
  370.  *      n-tuple variables. Variable arguments must come in pairs
  371.  *      of  binding_t q, int dataDim. 
  372.  *    Returns -1 on error, 0 otherwise.
  373.  */
  374. int h_bindMany(display disp, int n, ...);
  375.  
  376.  
  377. /*
  378.  * h_setBinWidth - sets the width of bins along the specified axis.
  379.  *    The axis' upper limit is adjusted to be consistent with the lower
  380.  *      limit, the given bin width, and the number of bins.
  381.  *    Returns -1 on error, 0 otherwise.
  382.  *
  383.  * h_getBinWidth - fetch the bin width for the specifed axis.
  384.  */
  385. int h_setBinWidth(display disp, binding_t axis, float width);
  386. float h_getBinWidth( display disp, binding_t axis );
  387.  
  388.  
  389. /*
  390.  * h_setBinNum - set the number of bins along the specified axis.
  391.  *    Returns -1 on error, 0 otherwise.
  392.  *
  393.  * h_getBinNum - return number of bins along the axis.
  394.  *    Return -1 on error.
  395.  */
  396. int h_setBinNum(display disp, binding_t axis, int n);
  397. int h_getBinNum( display disp, binding_t axis );
  398.  
  399. /*
  400.  * h_setLogAxis - switch logarithmic axes (base 10) on or off.
  401.  *        Log axis does not have any meaning for a binned axis.
  402.  * 
  403.  * h_getLogAxis - fetch log axis flag for specified axis.
  404.  */
  405. int h_setLogAxis(display disp, binding_t axis, int onOff);
  406. int h_getLogAxis(display disp, binding_t axis);
  407.  
  408. /*
  409.  * h_setAutoScale - turn on or off autoscaling for an axis.
  410.  *
  411.  * h_getAutoScale - fetch autoscale flag for an axis.
  412.  *
  413.  * h_autoScale - force autoscaling immediately for axes with flag set.
  414.  */
  415. int h_setAutoScale(display disp, binding_t axis, int onOff);
  416. int h_getAutoScale(display disp, binding_t axis);
  417. void h_autoScale( display );
  418.  
  419. /* 
  420.  * h_setRange - set the lower and upper limit along an axis.
  421.  *    Returns -1 on error, 0 otherwise.
  422.  *
  423.  * h_getRange - fetch the lower and upper limits along an axis.
  424.  *     If the axis is autoscaled, this will be the numbers used
  425.  *     once an h_plot (or h_bin for a binned axis) has been done.
  426.  */
  427. int h_setRange(display disp, binding_t axis, float low, float high);
  428. int h_getRange(display disp, binding_t axis, float *low, float *high);
  429.  
  430.  
  431. /*
  432.  * h_setTitle - sets the title of the display.
  433.  *    Possible printf format-like strings which pick up quantities from
  434.  *     the ntuple are:
  435.  *      %t   the ntuple's title
  436.  *      %x   the label for the ntuple column bound to the x-axis
  437.  *      %y         "              "          "            y-axis
  438.  *      %z         "              "          "            z-axis
  439.  *      %w         "              "          "            weight
  440.  *
  441.  *    Returns -1 on error, 0 otherwise.
  442.  *
  443.  * h_getTitle - fetch the display's title.
  444.  */
  445. int h_setTitle(display disp, const char *title);
  446. #define h_getTitle(d) ((const char *)(d)->title)
  447.  
  448. /*
  449.  * h_setAxisLabel - set the label for the specified axis.
  450.  *    The format-like strings discussed for h_setTitle are valid.
  451.  *   Returns -1 on error, 0 otherwise.
  452.  * 
  453.  * h_getAxisLabel - return pointers to label for specified axis.
  454.  *   Returns NULL on error.
  455.  */
  456. int h_setAxisLabel( display disp, binding_t axis, const char *label );
  457. const char *h_getAxisLabel( display disp, binding_t axis );
  458.  
  459. /*
  460.  * h_expandLabel - Function to expand labels which include hippo 
  461.  *  "format" specifiers. The valid "format" symbols are: 
  462.  *    %t   - title of the ntuple
  463.  *    %x   - label of ntuple column bound to x-axis
  464.  *    %y   - label of ntuple column bound to y-axis
  465.  *    %z   - label of ntuple column bound to z-axis
  466.  *    %w   - label of ntuple column bound to weight
  467.  *    %ex  - label of ntuple column bound to x error
  468.  *    %ey  - label of ntuple column bound to y error
  469.  *    %dx  - width of bins in x-axis direction
  470.  *    %dy  - width of bins in y-axis direction
  471.  *
  472.  *  dest is destination string, src is source string, max is maximum number 
  473.  *  of characters in dest, and disp is the relevant display.
  474.  *  Returns pointer to dest.
  475.  */
  476. char *h_expandLabel( char *dest, const char *src, int max, display disp );
  477.  
  478.  
  479. /*
  480.  * h_setPlotSymbol - set the plot symbol used when plotting the
  481.  *    data. Plot symbols can be one of those defined by plotsymbol_t
  482.  * 
  483.  * h_getPlotSymbol - fetch the current plot symbol.
  484.  */
  485. #define h_setPlotSym(d,s) ((d)->plotSymbol = (s))
  486. #define h_getPlotSym(d) ((d)->plotSymbol)
  487.  
  488. /*
  489.  * h_setSymSize - set the size of the plot symbol. Size is in points.
  490.  *         (ie. 1/72 inch)
  491.  *
  492.  * h_getSymSize - fetch the current plot symbol size.
  493.  */
  494. #define h_setSymSize(d,s) ((d)->symbolSize = (s))
  495. #define h_getSymSize(d) ((d)->symbolSize)
  496.  
  497. /*
  498.  * h_setLineStyle - set the line style used when connecting points.
  499.  *         Line styles are defined by linestyle_t above.
  500.  *
  501.  * h_getLineStyle - fetch the current line style.
  502.  */
  503. #define h_setLineStyle(d,s) ((d)->lineStyle = (s))
  504. #define h_getLineStyle(d) ((d)->lineStyle)
  505.  
  506. /*
  507.  *----------- Display actions ----------------------
  508.  */
  509.  
  510.  
  511. /*
  512.  * h_plot - Plots the ntuple using the current plot driver.
  513.  *      
  514.  *    The optional parameters are used by some plot drivers:
  515.  *     eg. XPLOT passes the painter and canvas as optional parameters.
  516.  */
  517. int h_plot(display disp, ...);
  518.  
  519. /*
  520.  * h_setPlotDrvr - select device for plotting.
  521.  *    Valid plot drivers are specified by the enum type plotdrvr_t.
  522.  *    Optional parameters are used by:
  523.  *     UNIXPLOT - optional parameter a C FILE pointer, to which
  524.  *          output is sent (does not work at present).
  525.  */
  526. int h_setPlotDrvr( plotdrvr_t drvr, ... );
  527.  
  528. /*
  529.  * h_endPlotDrvr - do any cleanup needed before a driver is closed
  530.  */
  531. int h_endPlotDrvr( void );
  532.  
  533. /*
  534.  * h_endPage - end a page for a plot driver.
  535.  */
  536. int h_endPage( void );
  537.  
  538.  
  539. /*
  540.  * h_print - Prints an ASCII representation of the histogram to stdout.
  541.  * h_fprint - h_print to given file.
  542.  */
  543. void h_fprint(display disp, FILE *file);
  544. #define h_print(x) h_fprint(x,stdout)
  545.  
  546. /*
  547.  * h_bin - perform binning on the display, but don't plot.
  548.  *    Returns -1 on error, 0 otherwise
  549.  */
  550. int h_bin(display disp);
  551.  
  552. /* 
  553.  * h_getBins - get a pointer to the array of bin values.
  554.  * h_getVariance - get a pointer to the array of bin variances (ie. error^2)
  555.  *    h_getBinNum will give number of data points.
  556.  *
  557.  *  Do NOT attempt to modify this data.
  558.  */
  559. #define h_getBins(d) ((const float *) (d)->bins.data)
  560. #define h_getVariance(d) ((const float *) (d)->bins.variance)
  561.  
  562. /*
  563.  * h_getBinExtreme - get minimum and maximum bin value.
  564.  *  return 0 if normal, -1 on error.
  565.  */
  566. int h_getBinExtreme( display disp, float *min, float *max );
  567.  
  568. /*
  569.  * h_getTotal - get the (weighted) sums of events inside/outside
  570.  *   the plot. i is for x-axis, j for y-axis. 0 means below lower limit,
  571.  *   1 is inside plot's range, 2 is above range.
  572.  */
  573. #define h_getTotal(d,i,j) ((const float) (d)->bins.totals[i][j])
  574.  
  575. /*
  576.  * h_setDrawTitles - set/clear flag to plot the display title and labels
  577.  *    during h_plot.
  578.  *
  579.  * h_getDrawTitles - fetch the flag indicating whether to draw titles.
  580.  */
  581. #define h_setDrawTitles(d,f) ((d)->flags.drawTitles = (f))
  582. #define h_getDrawTitles(d) ((d)->flags.drawTitles)
  583.  
  584. /*
  585.  * h_setDrawAxes - set/clear flag to plot the display axes during h_plot
  586.  *                (w/ ticks and scales).
  587.  *
  588.  * h_getDrawAxes - fetch the flag indicating whether to draw the axes.
  589.  */
  590. #define h_setDrawAxes(d,f) ((d)->flags.drawAxes = (f))
  591. #define h_getDrawAxes(d) ((d)->flags.drawAxes)
  592.  
  593. /*
  594.  * h_setFixedBins - set/clear flag to indicate bins are fixed.
  595.  *    This means that h_bin and h_plot will not preform any rebinning
  596.  *    and the bin contents will be written on output.
  597.  *
  598.  * h_getFixedBins - fetch the flag indicating whether bins are fixed.
  599.  */
  600. #define h_setFixedBins(d,f) ((d)->bins.flags.fixed = (f))
  601. #define h_getFixedBins(d) ((d)->bins.flags.fixed)
  602.  
  603. /*
  604.  *----------- auxiliary functions ------------------
  605.  */
  606.  
  607. /*
  608.  * h_binVal - returns the value of the bin specified by the arguments
  609.  *    There must be as many arguments as the dimensionality of the display.
  610.  *    (1, 2, or 3).
  611.  *    Returns -1 on error.
  612.  */
  613. float h_binVal(display disp, ...);
  614.  
  615.  
  616. /*
  617.  * h_ptToBin - returns the bin number containing 'f' on the axis 'axis'.
  618.  *    Returns -1 on error.
  619.  */
  620. int h_ptToBin(display disp, float f, binding_t axis);
  621.  
  622.  
  623. /*
  624.  * h_setDrawRect - set the rectangle in which the plot is drawn. 
  625.  *      Units are points (1/72 inch).
  626.  *
  627.  * h_getDrawRect - get a copy of the rectangle which defines the 
  628.  *     location and size of the plot.
  629.  *
  630.  *  Return -1 on error, 0 otherwise.
  631.  */
  632. int h_setDrawRect(display disp, rectangle *rect );
  633. int h_getDrawRect(display disp, rectangle *rect );
  634.  
  635. /*
  636.  * h_setMarginRect - set the rectangle which defines the location of the
  637.  *      axes. Units are points (1/72 inch). The margin rectangle is in
  638.  *      the same co-ordinates as the draw rectangle.
  639.  *
  640.  * h_getMarginRect - get a copy of the rectangle which defines the 
  641.  *      location of the axes.
  642.  *
  643.  *  Return -1 on error, 0 otherwise.
  644.  */
  645. int h_setMarginRect(display disp, rectangle *rect );
  646. int h_getMarginRect(display disp, rectangle *rect );
  647.  
  648.  
  649. /*
  650.  * h_wPtTogPt - convert a number in window co-ordinates (ie. same as
  651.  *     draw rectangle) to graph co-ordinates (ie. same a axis scale).
  652.  *
  653.  * h_gPtTowPt - convert from graph to window co-ordinates.
  654.  */
  655. float h_wPtTogPt(display disp, float wPt, binding_t axis);
  656. float h_gPtTowPt(display disp, float gPt, binding_t axis);
  657.  
  658. /*
  659.  * set the dirty flag in a display.
  660.  * The bins of a display are dirty if a quantity which affects the bins
  661.  *  has been changed.
  662.  * Please, think 5 times before using this routine. It should not be used
  663.  *  in hippo code (the display should know automatically if it is dirty).
  664.  * The only valid use is when a user cut is changed.
  665.  */
  666. #define h_setDirty(d) ((d)->bins.flags.dirty = 1)
  667.  
  668.  
  669. /*
  670.  *----------- drawing functions ---------------
  671.  */
  672. /*
  673.  * h_shade - shade a region of the plot along the x-axis. The shaded region
  674.  *      runs from the lower to the upper limits along the y-axis and
  675.  *      from low to high along the x-axis, but does not go past the
  676.  *      x-axis' limits.
  677.  */
  678. int h_shade(display disp, float low, float high);
  679.  
  680.  
  681. /*
  682.  * --------------- IO functions ----------------------------------
  683.  */
  684.  
  685. /*
  686.  * h_fileParse - create an ntuple from a text file.
  687.  *   If oldnt is NULL, will create a new ntuple; else, will append
  688.  *   data to the ntuple specified. 
  689.  *   If verbose is true, will print lots of messages.
  690.  *   Returns the ntuple it created or modified.
  691.  */
  692. ntuple h_fileParse(FILE* ifile, ntuple oldnt, int verbose);
  693.  
  694. /*
  695.  * h_nt2text - write an ntuple as a text file (suitable for h_fileParse)
  696.  */
  697. int h_nt2text( FILE *outfile, ntuple nt );
  698.  
  699. /*
  700.  * h_writeStream, h_readStream - write/read list of displays and
  701.  *       ntuple to a file stream. Both lists of displays and ntuples
  702.  *       are NULL terminated. 
  703.  *
  704.  *   On read, pass in a pointer to pointer to a display or ntuple, 
  705.  *    and routine allocates space for list.
  706.  *
  707.  *      eg. FILE *myfile;
  708.  *          display *d_list;
  709.  *          ntuple *nt_list;
  710.  *          h_readStream( myfile, &d_list, &nt_list );
  711.  * 
  712.  *   On write, either list may be a NULL, meaning you don't care.
  713.  *    The write routine adds any ntuples used by displays in the list,
  714.  *    but which you didn't specify, to the list you do specify.
  715.  * 
  716.  *      eg. h_writeStream( myfile, d_list, NULL);
  717.  *      writes out all the displays in d_list and all the ntuples
  718.  *      that those displays refer to.
  719.  * 
  720.  * Returns -1 on error, 0 otherwise.
  721.  */
  722. int h_writeStream(FILE *outfile, display dlist[], ntuple ntlist[] );
  723. int h_readStream(FILE *infile, display **dlist, ntuple **ntlist );
  724.  
  725.  
  726. /*
  727.  * h_write, h_read  - write/read displays and ntuples from named file.
  728.  *      See h_writeStream for more information.
  729.  */
  730. int h_write(const char *filenm, display dlist[], ntuple ntlist[] );
  731. int  h_read(const char *filenm, display **dlist, ntuple **ntlist );
  732.  
  733. /*
  734.  * h_writeMem, h_readMem - write/read displays and ntuples from
  735.  *      provided memory buffer.
  736.  *   len is length of buffer in bytes.
  737.  *
  738.  *  See h_writeStream for more information.
  739.  */
  740. int h_writeMem(char *buf, int len, display dlist[], ntuple ntlist[] );
  741. int h_readMem(char *buf, int len, display **dlist, ntuple **ntlist );
  742.  
  743. /*
  744.  * h_writeXDR, h_readXDR -  write/read displays and ntuples from
  745.  *            provided XDR stream. XDR stream should be opened
  746.  *            with appropriate ENCODE/DECODE code.
  747.  *
  748.  *  See h_writeStream for more information.
  749.  */
  750. int h_writeXDR(XDR *xdrs, display dlist[], ntuple ntlist[] );
  751. int h_readXDR(XDR *xdrs, display **dlist, ntuple **ntlist );
  752.  
  753. /*
  754.  * ---------------- Cuts and Plot Functions --------------------
  755.  */
  756.  
  757. /*
  758.  * h_funcReg - register a function in the "registry".
  759.  *   The registry keeps track of function pointers and names
  760.  *     so that they can be reconnected after save/restore of a file.
  761.  */
  762. #define h_funcReg(x) h_func_reg( #x, x )
  763. int h_func_reg(const char *fn, void *func);
  764.  
  765. /*
  766.  * h_addCut -  adds a hippo-supported cut to a display.
  767.  *  Supported cuts are:
  768.  *     "h_cut_le", "h_cut_lt", "h_cut_ge", "h_cut_gt",
  769.  *     "h_cut_inside", "h_cut_in_incl", "h_cut_outside",
  770.  *     and "h_cut_out_incl".
  771.  *  The first 4 require 1 parameter, the other 4, 2 parameters.
  772.  *  When there are 2 parameters, the first is the lesser.
  773.  *
  774.  *  Returns pointer to cut structure, or NULL on error.
  775.  */
  776. func_id h_addCut( display disp, const char *cutfunc, int cut_dim, 
  777.          double val1, ... );
  778.  
  779. /*
  780.  * h_changeCut - changes the cutting parameters. Requires the func_id 
  781.  *    returned by h_addCut. Requires the same number of parameters as
  782.  *    h_addCut, depending on the type of cut.
  783.  *
  784.  *  Returns -1 on error.
  785.  */
  786. int h_changeCut( display disp, func_id cut, double val1, ... );
  787.  
  788. /*
  789.  * h_addUserCut - adds a user-supported cut to a display.
  790.  *   The user passes a function name, a pointer to a parameter block *
  791.  *   (all doubles), and the size of the parameter block (number of *
  792.  *   doubles). It is the responsibility of the user to maintain the *
  793.  *   parameters; if they are changed, one should call h_forceReBin
  794.  *   (not * necessary if display is not binned) on the display. hippo
  795.  *   maintains * a pointer to the parameter block, so it should not be
  796.  *   moved.
  797.  *
  798.  * Returns func_id or NULL on error.
  799.  */
  800. func_id h_addUserCut( display disp, const char *cutfunc,
  801.              double *param_blk, int nParam);
  802.  
  803. /*
  804.  * h_deleteCut removes a cut from a display. Requires func_id returned
  805.  *  by h_addCut.
  806.  * Returns -1 on error.
  807.  */
  808. int h_deleteCut( display disp, func_id cut );
  809.  
  810. /*
  811.  * h_nextCut returns the next func_id used in a display.
  812.  *  If thiscut equals NULL, it returns the first func_id.
  813.  *
  814.  * Returns NULL if there are no more cuts.
  815.  */
  816. func_id h_nextCut( display disp, func_id thiscut );
  817.  
  818. /*
  819.  * h_addPlotFunc - add a function to be plotted to the display.
  820.  *     Function is similar to h_addUserCut.
  821.  */
  822. func_id h_addPlotFunc(display disp, const char *plotfunc, double *paramBlk,
  823.               int nParam, linestyle_t ls );
  824.  
  825. /*
  826.  * h_nextPlotFunc - traverse the list of plot functions.
  827.  *     Function is similar to h_nextCut.
  828.  */
  829. func_id h_nextPlotFunc( display disp, func_id thispfunc );
  830.  
  831. /*
  832.  * h_deletePlotFunc - remove a plot function from the list.
  833.  *     Function is similar to h_deleteCut.
  834.  */
  835. int h_deletePlotFunc( display disp, func_id pfunc );
  836.  
  837.  
  838. #ifdef __cplusplus
  839. }                                               /* for C++ V2.0 */
  840. #endif
  841.  
  842.  
  843. #endif                /* end of ifndef _HIPPO_H_ */
  844.