PLplot  5.10.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
plctrl.c File Reference
#include "plplotP.h"
#include "mt19937ar.h"

Go to the source code of this file.

Macros

#define DEBUG
#define NEED_PLDEBUG
#define BUFFER_SIZE   256
#define COLLEN   30
#define PALLEN   160
#define MSGLEN   1024
#define FUZZ_EPSILON   1.e-4
#define PLLIBDEV   "/usr/local/plplot/lib"
#define color_def(i, r, g, b, a, n)   if ( i >= imin && i <= imax ) color_set( i, r, g, b, a, n );
#define fuzzy_range_check(value, min, max, fuzz, err_number)
#define MAX_NUM_TRIES   10

Functions

static void color_set (PLINT i, U_CHAR r, U_CHAR g, U_CHAR b, PLFLT a, const char *name)
static void strcat_delim (char *dirspec)
static void plcmap0_def (int imin, int imax)
static void plcmap1_def (void)
static PLFLT value (double n1, double n2, double hue)
static char * read_line (char *buffer, int length, FILE *fp)
static void cmap0_palette_read (const char *filename, int *number_colors, unsigned int **r, unsigned int **g, unsigned int **b, double **a)
void c_plcol0 (PLINT icol0)
void c_plcol1 (PLFLT col1)
void c_plscolbg (PLINT r, PLINT g, PLINT b)
void c_plscolbga (PLINT r, PLINT g, PLINT b, PLFLT alpha)
void c_plgcolbg (PLINT *r, PLINT *g, PLINT *b)
void c_plgcolbga (PLINT *r, PLINT *g, PLINT *b, PLFLT *alpha)
void c_plscol0 (PLINT icol0, PLINT r, PLINT g, PLINT b)
void c_plscol0a (PLINT icol0, PLINT r, PLINT g, PLINT b, PLFLT alpha)
void c_plgcol0 (PLINT icol0, PLINT *r, PLINT *g, PLINT *b)
void c_plgcol0a (PLINT icol0, PLINT *r, PLINT *g, PLINT *b, PLFLT *alpha)
void c_plscmap0 (const PLINT *r, const PLINT *g, const PLINT *b, PLINT ncol0)
void c_plscmap0a (const PLINT *r, const PLINT *g, const PLINT *b, const PLFLT *alpha, PLINT ncol0)
void c_plscmap1 (const PLINT *r, const PLINT *g, const PLINT *b, PLINT ncol1)
void c_plscmap1a (const PLINT *r, const PLINT *g, const PLINT *b, const PLFLT *alpha, PLINT ncol1)
void c_plscmap1l (PLINT itype, PLINT npts, const PLFLT *intensity, const PLFLT *coord1, const PLFLT *coord2, const PLFLT *coord3, const PLINT *alt_hue_path)
void c_plscmap1la (PLINT itype, PLINT npts, const PLFLT *intensity, const PLFLT *coord1, const PLFLT *coord2, const PLFLT *coord3, const PLFLT *alpha, const PLINT *alt_hue_path)
void plcmap1_calc (void)
void c_plscmap1_range (PLFLT min_color, PLFLT max_color)
void c_plgcmap1_range (PLFLT *min_color, PLFLT *max_color)
void c_plscmap0n (PLINT ncol0)
void c_plscmap1n (PLINT ncol1)
void c_plscolor (PLINT color)
void c_plhlsrgb (PLFLT h, PLFLT l, PLFLT s, PLFLT *p_r, PLFLT *p_g, PLFLT *p_b)
void c_plrgbhls (PLFLT r, PLFLT g, PLFLT b, PLFLT *p_h, PLFLT *p_l, PLFLT *p_s)
void c_plspal0 (const char *filename)
void c_plspal1 (const char *filename, PLBOOL interpolate)
void plwarn (const char *errormsg)
void plabort (const char *errormsg)
void plsabort (void(*handler)(const char *))
void plexit (const char *errormsg)
void plsexit (int(*handler)(const char *))
void c_plgra (void)
void c_plxormod (PLINT mode, PLINT *status)
void c_plsdrawmode (PLINT mode)
PLINT c_plgdrawmode (void)
void c_pltext (void)
 Switches to text screen.
void pl_cmd (PLINT op, void *ptr)
char * plFindCommand (const char *fn)
FILE * plLibOpen (const char *fn)
PDFstrmplLibOpenPdfstrm (const char *fn)
int plFindName (char *p)
void plGetName (const char *dir, const char *subdir, const char *filename, char **filespec)
void plcol_interp (PLStream *pls, PLColor *newcolor, int i, int ncol)
void plOpenFile (PLStream *pls)
void plCloseFile (PLStream *pls)
void plP_getmember (PLStream *pls)
void plP_sfnam (PLStream *pls, const char *fnam)
void plFamInit (PLStream *pls)
void plGetFam (PLStream *pls)
void plRotPhy (PLINT orient, PLINT xmin, PLINT ymin, PLINT xmax, PLINT ymax, PLINT *px, PLINT *py)
PLDevplAllocDev (PLStream *pls)
void plGinInit (PLGraphicsIn *gin)
PLINT plGetInt (const char *s)
PLFLT plGetFlt (const char *s)
char PLDLLIMPEXPplstrdup (const char *src)
int plsnprintf (char *buffer, int n, const char *format,...)
int plsnscanf (const char *buffer, int n, const char *format,...)
void c_plseed (unsigned int seed)
PLFLT c_plrandd (void)
char * plsave_set_locale (void)
void plrestore_locale (char *saved_lc_numeric_locale)

Variables

char PLDLLIMPEXPplplotLibDir = 0
static int(* exit_handler )(const char *errormsg)
static void(* abort_handler )(const char *errormsg)

Detailed Description

Part 1: Color map routines. Part 2: "A grab-bag of various control routines".

Definition in file plctrl.c.

Macro Definition Documentation

#define BUFFER_SIZE   256

Definition at line 64 of file plctrl.c.

#define COLLEN   30

Definition at line 65 of file plctrl.c.

#define color_def (   i,
  r,
  g,
  b,
  a,
 
)    if ( i >= imin && i <= imax ) color_set( i, r, g, b, a, n );

Definition at line 1005 of file plctrl.c.

#define DEBUG

Definition at line 37 of file plctrl.c.

#define FUZZ_EPSILON   1.e-4

Definition at line 71 of file plctrl.c.

#define fuzzy_range_check (   value,
  min,
  max,
  fuzz,
  err_number 
)
Value:
if ( value < ( min - fuzz ) || value > ( max + fuzz ) ) { \
snprintf( msgbuf, MSGLEN, "Unrecognized cmap1 format data line. Error number is %d. Line is %s\n", err_number, color_info ); \
plwarn( msgbuf ); \
err = 1; \
break; \
} else if ( value < min ) { \
value = min; \
} else if ( value > max ) { \
value = max; \
}

This code fragment used a lot in plspal1 to deal with floating-point range checking of a value and the adjustment of that value when close to the range when there is floating-point errors.

Parameters
valueThe value to range check.
minThe minimum allowable value.
maxThe maximum allowable value.
fuzzAmount of slop to allow beyond the range defined by min & max.
err_numberThe error number.

Definition at line 1584 of file plctrl.c.

#define MAX_NUM_TRIES   10

Opens file for output, prompting if not set. Prints extra newline at end to make output look better in batch runs. A file name of "-" indicates output to stdout.

Parameters
plsA plot stream structure.

Definition at line 2553 of file plctrl.c.

#define MSGLEN   1024

Definition at line 67 of file plctrl.c.

#define NEED_PLDEBUG

Definition at line 39 of file plctrl.c.

#define PALLEN   160

Definition at line 66 of file plctrl.c.

#define PLLIBDEV   "/usr/local/plplot/lib"

Definition at line 125 of file plctrl.c.

Function Documentation

void c_plcol0 ( PLINT  icol0)

Set color, map 0. Argument is a integer between 0 and plsc->ncol0.

Parameters
icol0The index of the color map 0 color to use as the current color. (0 - plsc->ncol0).

Definition at line 143 of file plctrl.c.

void c_plcol1 ( PLFLT  col1)

Set color, map 1. Argument is a float between 0. and 1.

Parameters
col1The index of the color map 1 color to use as the current color. (0.0 - 1.0)

Definition at line 177 of file plctrl.c.

void c_plgcmap1_range ( PLFLT min_color,
PLFLT max_color 
)

Get the color map 1 value range used in continuous color plots.

Parameters
min_colorSpecifies the minimum color used.
max_colorSpecifies the maximum color used.

Definition at line 916 of file plctrl.c.

void c_plgcol0 ( PLINT  icol0,
PLINT r,
PLINT g,
PLINT b 
)

Returns 8 bit RGB values for given color from color map 0 Values are negative if an invalid color id is given

Parameters
icol0Index of the color to be return (0 - plsc->ncol0).
rCurrent red value of the color.
gCurrent green value of the color.
bCurrent blue value of the color.

Definition at line 361 of file plctrl.c.

void c_plgcol0a ( PLINT  icol0,
PLINT r,
PLINT g,
PLINT b,
PLFLT alpha 
)

Returns 8 bit RGB values for given color from color map 0 and alpha value Values are negative if an invalid color id is given

Parameters
icol0Index of the color to be return (0 - plsc->ncol0).
rCurrent red value of the color.
gCurrent green value of the color.
bCurrent blue value of the color.
alphaCurrent alpha value of the color.

Definition at line 398 of file plctrl.c.

void c_plgcolbg ( PLINT r,
PLINT g,
PLINT b 
)

Returns the background color (cmap0[0]) by 8 bit RGB value

Parameters
rCurrent red value of the background color.
gCurrent green value of the background color.
bCurrent blue value of the background color.

Definition at line 251 of file plctrl.c.

void c_plgcolbga ( PLINT r,
PLINT g,
PLINT b,
PLFLT alpha 
)

Returns the background color (cmap0[0]) by 8 bit RGB value and alpha value

Parameters
rCurrent red value of the background color.
gCurrent green value of the background color.
bCurrent blue value of the background color.
alphaCurrent alpha value of the background color.

Definition at line 267 of file plctrl.c.

PLINT c_plgdrawmode ( void  )

Get drawing mode (depends on device support!)

Returns
Current drawing mode

Definition at line 2063 of file plctrl.c.

void c_plgra ( void  )

Switches to graphics screen.

Here and in pltext() it's a good idea to return silently if plinit() hasn't yet been called, since plwarn() calls pltext() and plgra(), and plwarn() may be called at any time.

Definition at line 1995 of file plctrl.c.

void c_plhlsrgb ( PLFLT  h,
PLFLT  l,
PLFLT  s,
PLFLT p_r,
PLFLT p_g,
PLFLT p_b 
)

Convert HLS color to RGB color. Bounds on HLS (input): hue [0., 360.] degrees lightness [0., 1.] magnitude saturation [0., 1.] magnitude

Hue is always mapped onto the interval [0., 360.] regardless of input. Bounds on RGB (output) is always [0., 1.]. Convert to RGB color values by multiplying by 2**nbits (nbits typically 8).

Parameters
hhue in HLS color scheme (0.0 - 360.0)
llightness in HLS color scheme (0.0 - 1.0)
ssaturation in HLS color scheme (0.0 - 1.0)
p_rred value of the HLS color
p_ggreen value of the HLS color
p_bblue value of the HLS color

Definition at line 1253 of file plctrl.c.

PLFLT c_plrandd ( void  )
Returns
A random number on [0,1]-interval.

Definition at line 3065 of file plctrl.c.

void c_plrgbhls ( PLFLT  r,
PLFLT  g,
PLFLT  b,
PLFLT p_h,
PLFLT p_l,
PLFLT p_s 
)

Convert RGB color to HLS color. Bounds on RGB (input) is always [0., 1.]. Bounds on HLS (output): hue [0., 360.] degrees lightness [0., 1.] magnitude saturation [0., 1.] magnitude

Parameters
rred in RGB color scheme (0.0 - 1.0)
ggreen in RGB color scheme (0.0 - 1.0)
bblue in RGB color scheme (0.0 - 1.0)
p_hhue value of the RGB color.
p_llightness value of the RGB color.
p_ssaturation value of the RGB color.

Definition at line 1286 of file plctrl.c.

void c_plscmap0 ( const PLINT r,
const PLINT g,
const PLINT b,
PLINT  ncol0 
)

Set color map 0 colors by 8 bit RGB values. This sets the entire color map – only as many colors as specified will be allocated.

Parameters
rArray of red values.
gArray of green values.
bArray of blue values.
ncol0Total number of RGB values.

Definition at line 436 of file plctrl.c.

void c_plscmap0a ( const PLINT r,
const PLINT g,
const PLINT b,
const PLFLT alpha,
PLINT  ncol0 
)

Set color map 0 colors by 8 bit RGB and alpha value. This sets the entire color map – only as many colors as specified will be allocated.

Parameters
rArray of red values.
gArray of green values.
bArray of blue values.
alphaArray of alpha values.
ncol0Total number of RGBA values.

Definition at line 478 of file plctrl.c.

void c_plscmap0n ( PLINT  ncol0)

Set number of colors in cmap 0, (re-)allocate cmap 0, and fill with default values for those colors not previously allocated (and less than index 15, after that you just get grey).

The driver is not guaranteed to support all of these.

Parameters
ncol0Total number of colors.

Definition at line 934 of file plctrl.c.

void c_plscmap1 ( const PLINT r,
const PLINT g,
const PLINT b,
PLINT  ncol1 
)

Set color map 1 colors by 8 bit RGB values This also sets the number of colors.

Parameters
rArray of red values.
gArray of green values.
bArray of blue values.
ncol1Total number of RGB values.

Definition at line 520 of file plctrl.c.

void c_plscmap1_range ( PLFLT  min_color,
PLFLT  max_color 
)

Set the color map 1 value range to use in continuous color plots.

Parameters
min_colorSpecifies the minimum color to use. A value of 0.0 or less indicates that the range should start at the lowest color map 1 value available.
max_colorSpecifies the maximum color to use. A value of 1.0 or greater indicates that the range should exten to the highest color map 1 value available.

If min_color > max_color or min_color is greater than 1.0 or max_color is less than 0.0 then no change is made.

Definition at line 887 of file plctrl.c.

void c_plscmap1a ( const PLINT r,
const PLINT g,
const PLINT b,
const PLFLT alpha,
PLINT  ncol1 
)

Set color map 1 colors by 8 bit RGB and alpha values This also sets the number of colors.

Parameters
rArray of red values.
gArray of green values.
bArray of blue values.
alphaArray of alpha values.
ncol1Total number of RGBA values.

Definition at line 561 of file plctrl.c.

void c_plscmap1l ( PLINT  itype,
PLINT  npts,
const PLFLT intensity,
const PLFLT coord1,
const PLFLT coord2,
const PLFLT coord3,
const PLINT alt_hue_path 
)

Set color map 1 colors using a piece-wise linear relationship between position in the color map (from 0 to 1) and position in HLS or RGB color space. May be called at any time.

The idea here is to specify a number of control points that specify the mapping between HLS (or RGB or CMY) and palette 1 value. Between these points, linear interpolation is used. By mapping position in the color map to function value, this gives a smooth variation of color with intensity. Any number of control points may be specified, located at arbitrary positions (intensities), although typically 2 - 4 are enough. Another way of stating this is that we are traversing a given number of lines through HLS (or RGB) space as we move through cmap 1 entries. The control points at the minimum and maximum intensity (0 and 1) must always be specified. By adding more control points you can get more variation. One good technique for plotting functions that vary about some expected average is to use an additional 2 control points in the center (intensity ~= 0.5) that are the same color as the background (typically white for paper output, black for crt), and same hue as the boundary control points. This allows the highs and lows to be very easily distinguished.

Each control point must specify the position in cmap 1 as well as three coordinates in HLS or RGB space. The first point MUST correspond to position = 0, and the last to position = 1.

Every change in hue from one control point to the next can be linearly interpolated in two ways. The usual (alt_hue_path[i] false) method for the ith interval uses the dh = h[i+1] - h[i] interval for interpolation. The alternate (alt_hue_path true) method for the ith interval uses the dh = (h[i+1] - h[i]) - 360 if (h[i+1] - h[i]) is positive or dh = 360 - (h[i+1] - h[i]) if (h[i+1] - h[i]) is negative interval for the interpolation. Thus, alt_hue_path true interpolation intervals always include hue = 0. Specifying alt_hue_path=NULL is equivalent to setting alt_hue_path[]=false for every control point.

Bounds on RGB coordinates: R,G,B [0, 1] magnitude

Bounds on HLS coordinates: hue [0, 360] degrees lightness [0, 1] magnitude saturation [0, 1] magnitude

The inputs are:

Parameters
itype0: HLS, 1: RGB
nptsnumber of control points
intensity[]intensity index for each control point
coord1[]first coordinate for each control point
coord2[]second coordinate for each control point
coord3[]third coordinate for each control point
alt_hue_path[]if true, use alternative hue interpolation path for the associated interval.

Definition at line 643 of file plctrl.c.

void c_plscmap1la ( PLINT  itype,
PLINT  npts,
const PLFLT intensity,
const PLFLT coord1,
const PLFLT coord2,
const PLFLT coord3,
const PLFLT alpha,
const PLINT alt_hue_path 
)

This is the same as plscmap1l, but also allows alpha value interpolation.

Parameters
itype0: HLS, 1: RGB
nptsnumber of control points
intensity[]intensity index for each control point
coord1[]first coordinate for each control point
coord2[]second coordinate for each control point
coord3[]third coordinate for each control point
alpha[]alpha value for each control point
alt_hue_path[]if true, use alternative hue interpolation path for the associated interval.

Definition at line 729 of file plctrl.c.

void c_plscmap1n ( PLINT  ncol1)

Set number of colors in cmap 1, (re-)allocate cmap 1, and set default values if this is the first allocation.

Note that the driver is allowed to disregard this number. In particular, most use fewer than we use internally.

Parameters
ncol1The number of colors in cmap1.

Definition at line 1059 of file plctrl.c.

void c_plscol0 ( PLINT  icol0,
PLINT  r,
PLINT  g,
PLINT  b 
)

Set a given color from color map 0 by 8 bit RGB value Does not result in any additional cells to be allocated.

Parameters
icol0index of the color to set (0 - plsc->ncol0)
rRed value of the color (0 - 255).
gGreen value of the color (0 - 255).
bBlue value of the color (0 - 255).

Definition at line 284 of file plctrl.c.

void c_plscol0a ( PLINT  icol0,
PLINT  r,
PLINT  g,
PLINT  b,
PLFLT  alpha 
)

Set a given color from color map 0 by 8 bit RGB value and alpha value. Does not result in any additional cells to be allocated.

Parameters
icol0index of the color to set (0 - plsc->ncol0)
rRed value of the color (0 - 255).
gGreen value of the color (0 - 255).
bBlue value of the color (0 - 255).
alphaAlpha value of the color (0.0 - 1.0).

Definition at line 320 of file plctrl.c.

void c_plscolbg ( PLINT  r,
PLINT  g,
PLINT  b 
)

Set the background color (cmap0[0]) by 8 bit RGB value

Parameters
rRed value of the background color (0 - 255).
gGreen value of the background color (0 - 255).
bBlue value of the background color (0 - 255).

Definition at line 217 of file plctrl.c.

void c_plscolbga ( PLINT  r,
PLINT  g,
PLINT  b,
PLFLT  alpha 
)

Set the background color (cmap0[0]) by 8 bit RGB value and alpha value

Parameters
rRed value of the background color (0 - 255).
gGreen value of the background color (0 - 255).
bBlue value of the background color (0 - 255).
alphaAlpha (transparency) value of the background color (0.0 - 1.0).

Definition at line 236 of file plctrl.c.

void c_plscolor ( PLINT  color)

Used to globally turn color output on/off

Parameters
color0 = no color, Not zero = color.

Definition at line 1194 of file plctrl.c.

void c_plsdrawmode ( PLINT  mode)

Set drawing mode (depends on device support!)

Parameters
modeThis determines which drawing mode to use.

Definition at line 2040 of file plctrl.c.

void c_plseed ( unsigned int  seed)

Set the seed for the random number generator included.

Parameters
seedThe random number generator seed value.

Definition at line 3052 of file plctrl.c.

void c_plspal0 ( const char *  filename)

Set the palette for color map 0 using a cmap0*.pal format file. filename: the name of the cmap0*.pal file to use.

Parameters
filenamename of the cmap0 palette file.

Definition at line 1550 of file plctrl.c.

void c_plspal1 ( const char *  filename,
PLBOOL  interpolate 
)

Set the palette for color map 1 using a cmap1*.pal format file. filename: the name of the cmap1*.pal file to use.

Parameters
filenamename of the cmap1 palette file.
interpolateinterpolate between control points.

Definition at line 1606 of file plctrl.c.

void c_pltext ( void  )

Switches to text screen.

Definition at line 2092 of file plctrl.c.

void c_plxormod ( PLINT  mode,
PLINT status 
)

Set xor mode? FIXME: Not really sure what this function does.

Parameters
modeBoolean.
status1 if successful, 0 otherwise.

Definition at line 2010 of file plctrl.c.

void cmap0_palette_read ( const char *  filename,
int *  number_colors,
unsigned int **  r,
unsigned int **  g,
unsigned int **  b,
double **  a 
)
static

Read and check r, g, b, a data from a cmap0*.pal format file. The caller must free the returned malloc'ed space for r, g, b, and a.

Parameters
filenamename of the cmap0 palette file.
number_colorsnumber of color found in the palette file.
rred value of each color in the palette file.
ggreen value of each color in the palette file.
bblue value of each color in the palette file.
aalpha value of each color in the palette file.

Definition at line 1401 of file plctrl.c.

void color_set ( PLINT  i,
U_CHAR  r,
U_CHAR  g,
U_CHAR  b,
PLFLT  a,
const char *  name 
)
static

Initializes color table 0 entry by RGB values.

Parameters
iIndex of the color.
rRed value of the color.
gGreen value of the color.
bBlue value of the color.
aAlpha value of the color.
nameThe name of the color.

Definition at line 996 of file plctrl.c.

void pl_cmd ( PLINT  op,
void ptr 
)

Front-end to driver escape function. In principle this can be used to pass just about anything directly to the driver.

Parameters
opA PLESC command to pass to the driver.
ptrData associated with the op command.

Definition at line 2110 of file plctrl.c.

void plabort ( const char *  errormsg)

Much the same as plwarn(), but appends ", aborting operation" to the error message. Helps to keep source code uncluttered and provides a convention for error aborts.

If cleanup needs to be done in the main program, the user should write his/her own exit handler and pass it in via plsabort().

Parameters
errormsgThe error message.

Definition at line 1886 of file plctrl.c.

PLDev* plAllocDev ( PLStream pls)

Allocates a standard PLDev structure for device-specific data, stores the address in pls->dev, and returns the address as well.

Parameters
plsA plot stream structure.
Returns
A PLDev *

Definition at line 2850 of file plctrl.c.

void plCloseFile ( PLStream pls)

Closes output file unless it is associated with stdout.

Parameters
plsA plot stream structure.

Definition at line 2619 of file plctrl.c.

void plcmap0_def ( int  imin,
int  imax 
)
static

Initializes specified color map 0 color entry to its default for index range from imin to imax.

Parameters
iminIndex of the first color to set to its default.
imaxIndex of the last color to set to its default.

Definition at line 1018 of file plctrl.c.

void plcmap1_calc ( void  )

Bin up cmap 1 space and assign colors to make inverse mapping easy. Always do interpolation in HLS space.

Definition at line 806 of file plctrl.c.

void plcmap1_def ( void  )
static

Initializes color map 1.

The default initialization uses 6 control points in HLS space, the inner ones being very close to one of the vertices of the HLS double cone. The vertex used (black or white) is chosen to be the closer to the background color. The 6 points were chosen over the older 4 points in order to make weaker structures more easily visible, and give more control through the palette editor. If you don't like these settings.. change them!

Definition at line 1120 of file plctrl.c.

void plcol_interp ( PLStream pls,
PLColor newcolor,
int  i,
int  ncol 
)

Initializes device cmap 1 entry by interpolation from pls->cmap1 entries. Returned PLColor is supposed to represent the i_th color out of a total of ncol colors in the current color scheme.

Parameters
plsA plot stream structure.
newcolorA color structure to store the color in.
iIndex of the desired color.
ncolTotal number of colors (supported by the device?).

Definition at line 2514 of file plctrl.c.

void plexit ( const char *  errormsg)

In case of an abort this routine is called. It just prints out an error message and tries to clean up as much as possible. It's best to turn off pause and then restore previous setting before returning.

If cleanup needs to be done in the main program, the user should write his/her own exit handler and pass it in via plsexit(). This function should should either call plend() before exiting, or simply return.

Parameters
errormsgThe error message.

Definition at line 1950 of file plctrl.c.

void plFamInit ( PLStream pls)

Initializes family file parameters.

Parameters
plsA plot stream structure.

Definition at line 2735 of file plctrl.c.

char* plFindCommand ( const char *  fn)

Looks for the specified executable file. Search path: if command invoked in the build tree: build_tree/tk (plserver lies there - needed for the tk driver) source_tree/scripts (plpr lies there - needed for the tk driver) else PLPLOT_BIN_ENV = current directory PLPLOT_HOME_ENV/bin = /bin BIN_DIR

The caller must free the returned pointer (points to malloc'ed memory) when finished with it.

Parameters
fnName of the executable(?).
Returns
The location of the executable file.

Definition at line 2137 of file plctrl.c.

int plFindName ( char *  p)

Authors: Paul Dubois (LLNL), others? This function is in the public domain.

Given a pathname, determine if it is a symbolic link. If so, continue searching to the ultimate terminus - there may be more than one link. Use the error value to determine when the terminus is reached, and to determine if the pathname really exists. Then stat it to determine whether it's executable. Return 0 for an executable, errno otherwise. Note that 'p' must have at least one '/' character - it does by construction in this program. The contents of the array pointed to by 'p' are changed to the actual pathname if findname is successful.

This function is only defined under Unix for now.

Parameters
pName of the executable to find.
Returns
0 if p is found & is an executable.

Definition at line 2423 of file plctrl.c.

void plGetFam ( PLStream pls)

Starts new member file of family file set if necessary.

Note each member file is a complete graphics file (can be printed individually), although 'plrender' will treat a family as a single logical file if given the family name instead of the member name.

Parameters
plsA plot stream structure.

Definition at line 2764 of file plctrl.c.

PLFLT plGetFlt ( const char *  s)

Prompts human to input a float in response to given message.

Parameters
sThe prompt message.
Returns
The PLFLT the human entered.

Definition at line 2929 of file plctrl.c.

PLINT plGetInt ( const char *  s)

Prompts human to input an integer in response to given message.

Parameters
sThe prompt message.
Returns
The PLINT the human entered.

Definition at line 2894 of file plctrl.c.

void plGetName ( const char *  dir,
const char *  subdir,
const char *  filename,
char **  filespec 
)

Gets search name for file by concatenating the dir, subdir, and file name, allocating memory as needed. The appropriate delimiter is added after the dir specification as necessary. The caller is responsible for freeing the malloc'ed memory.

Parameters
dirThe directory name.
subdirThe sub-directory name.
filenameThe file name.
filespecThe result of concatenating dir, subdir and filename.

Definition at line 2444 of file plctrl.c.

void plGinInit ( PLGraphicsIn gin)

Just fills in the PLGraphicsIn with appropriate initial values.

Parameters
ginA plot graphics input (i.e. keypress or mouseclick) structure.

Definition at line 2871 of file plctrl.c.

FILE* plLibOpen ( const char *  fn)

Return file pointer to library file (such as a colormap palette). Locations checked: PLPLOT_LIB_ENV = current directory PLPLOT_HOME_ENV/lib = /lib DATA_DIR PLLIBDEV

Parameters
fnName of the file.
Returns
A open file pointer (if successful).

Definition at line 2220 of file plctrl.c.

PDFstrm* plLibOpenPdfstrm ( const char *  fn)

Return file PDFstrm * to a file (originally used for loading fonts?). Locations checked: PLPLOT_LIB_ENV = current directory PLPLOT_HOME_ENV/lib = /lib DATA_DIR PLLIBDEV

Parameters
fnName of the file.
Returns
A open PDFstrm file pointer (if successful)

Definition at line 2254 of file plctrl.c.

void plOpenFile ( PLStream pls)

Definition at line 2555 of file plctrl.c.

void plP_getmember ( PLStream pls)

Sets up next file member name (in pls->FileName), but does not open it.

Parameters
plsA plot stream structure.

Definition at line 2641 of file plctrl.c.

void plP_sfnam ( PLStream pls,
const char *  fnam 
)

Sets up file name (with "%n" removed if present) & family stem name. Reserve some extra space (10 chars) to hold an optional member number.

Parameters
plsA plot stream.
fnamThe base file name of the plot files.

Definition at line 2684 of file plctrl.c.

void plrestore_locale ( char *  saved_lc_numeric_locale)

Restore LC_NUMERIC locale string that was determined by plsave_set_locale with the pointer to that string as the argument. Also, free the memory for that string.

Parameters
saved_lc_numeric_localeThe saved numeric locale..

Definition at line 3129 of file plctrl.c.

void plRotPhy ( PLINT  orient,
PLINT  xmin,
PLINT  ymin,
PLINT  xmax,
PLINT  ymax,
PLINT px,
PLINT py 
)

Rotates physical coordinates if necessary for given orientation. Each time orient is incremented, the plot is rotated 90 deg clockwise. Note: this is now used only to rotate by 90 degrees for devices that expect portrait mode.

Parameters
orientNew plot orientation (0-3)
xminCurrent plot x minimum?
yminCurrent plot y minimum?
xmaxCurrent plot x maximum?
ymaxCurrent plot y maximum?
pxOld x coordinate mapped to new x coordinate.
pyOld y coordinate mapped to new y coordinate.

Definition at line 2808 of file plctrl.c.

void plsabort ( void(*)(const char *)  handler)

Sets an optional user abort handler.

Parameters
handlerA function that takes a const char * argument that will be called in the event of a abort.

Definition at line 1930 of file plctrl.c.

char* plsave_set_locale ( void  )

Save LC_NUMERIC locale in a string. The pointer to that string is returned. Then set LC_NUMERIC to "C" locale. n.b. plsave_set_locale and plrestore_locale should always be used as a pair to surround PLplot code that absolutely requires the LC_NUMERIC "C" locale to be in effect. It is one of plrestore_locale's responsibilities to free the memory allocated here for the locale string.

Returns
The LC_NUMERIC locale.

Definition at line 3085 of file plctrl.c.

void plsexit ( int(*)(const char *)  handler)

Sets an optional user exit handler.

Parameters
handlerA function that takes a const char * argument that will will be called in the event of a exit.

Definition at line 1979 of file plctrl.c.

int plsnprintf ( char *  buffer,
int  n,
const char *  format,
  ... 
)

Dummy function for snprintf(). This function just calls the unsafe function ignoring the string size. This function will rarely be needed if ever.

Parameters
bufferString output buffer.
nSize of buffer.
formatThe format string.
...The values that go in the format string (...)
Returns
The length of buffer that is actually used.

Definition at line 2997 of file plctrl.c.

int plsnscanf ( const char *  buffer,
int  n,
const char *  format,
  ... 
)

Dummy function for snscanf(). This function just calls the unsafe function ignoring the string size. This function will rarely be needed if ever.

Parameters
bufferString output buffer.
nSize of buffer.
formatThe format string.
...The values that go in the format string (...)
Returns
The length of buffer that is actually used.

Definition at line 3029 of file plctrl.c.

char PLDLLIMPEXP* plstrdup ( const char *  src)

A replacement for strdup(), which isn't portable. Caller responsible for freeing the allocated memory.

Parameters
srcThe string to duplicate.
Returns
A copy of the string src.

Definition at line 2969 of file plctrl.c.

void plwarn ( const char *  errormsg)

A handy way to issue warnings, if need be.

Parameters
errormsgThe error message.

Definition at line 1855 of file plctrl.c.

static char * read_line ( char *  buffer,
int  length,
FILE *  fp 
)
static

Read a complete line and fill the buffer with its contents up to capacity. Then sanitize the string - no control characters, no trailing blanks

Parameters
bufferstorage for the line of text.
lengthsize of the buffer.
fpopen file pointer from which the line of text should be read.
Returns
The sanitized line from the file.

Definition at line 1344 of file plctrl.c.

void strcat_delim ( char *  dirspec)
static

Append path name deliminator if necessary (does not add one if one's there already, or if dealing with a colon-terminated device name).

Parameters
dirspecString to add the appropriate delimiter too.

Definition at line 2485 of file plctrl.c.

PLFLT value ( double  n1,
double  n2,
double  hue 
)
static

Auxiliary function used by c_plhlsrgb().

Parameters
n1Lightness/saturation value 1.
n2Lightness/saturation value 2.
huehue (0.0 - 360.0).

Definition at line 1211 of file plctrl.c.

Variable Documentation

void( * abort_handler)(const char *errormsg)
static

Definition at line 88 of file plctrl.c.

int( * exit_handler)(const char *errormsg)
static

Definition at line 85 of file plctrl.c.

char PLDLLIMPEXP* plplotLibDir = 0

Definition at line 76 of file plctrl.c.