PLplot: plctrl.c File Reference

PLplot 5.15.0

Macros | Functions | Variables
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 | limit_rgba_range (PLCHAR_VECTOR message, PLINT_NC_SCALAR r, PLINT_NC_SCALAR g, PLINT_NC_SCALAR b, PLFLT_NC_SCALAR alpha)
static void | color_set (PLINT i, U_CHAR r, U_CHAR g, U_CHAR b, PLFLT a, PLCHAR_VECTOR 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 (PLCHAR_VECTOR 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 (PLINT_VECTOR r, PLINT_VECTOR g, PLINT_VECTOR b, PLINT ncol0)
void | c_plscmap0a (PLINT_VECTOR r, PLINT_VECTOR g, PLINT_VECTOR b, PLFLT_VECTOR alpha, PLINT ncol0)
void | c_plscmap1 (PLINT_VECTOR r, PLINT_VECTOR g, PLINT_VECTOR b, PLINT ncol1)
void | c_plscmap1a (PLINT_VECTOR r, PLINT_VECTOR g, PLINT_VECTOR b, PLFLT_VECTOR alpha, PLINT ncol1)
void | c_plscmap1l (PLINT itype, PLINT npts, PLFLT_VECTOR intensity, PLFLT_VECTOR coord1, PLFLT_VECTOR coord2, PLFLT_VECTOR coord3, PLINT_VECTOR alt_hue_path)
void | c_plscmap1la (PLINT itype, PLINT npts, PLFLT_VECTOR intensity, PLFLT_VECTOR coord1, PLFLT_VECTOR coord2, PLFLT_VECTOR coord3, PLFLT_VECTOR alpha, PLINT_VECTOR alt_hue_path)
void | plcmap1_calc (void)
| Bin up cmap 1 space and assign colors to make inverse mapping easy. More...
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 (PLCHAR_VECTOR filename)
void | c_plspal1 (PLCHAR_VECTOR filename, PLBOOL interpolate)
void | plwarn (PLCHAR_VECTOR errormsg)
void | plabort (PLCHAR_VECTOR errormsg)
void | plsabort (void(*handler)(PLCHAR_VECTOR))
void | plexit (PLCHAR_VECTOR errormsg)
void | plsexit (int(*handler)(PLCHAR_VECTOR))
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. More...
void | pl_cmd (PLINT op, void *ptr)
char * | plFindCommand (PLCHAR_VECTOR fn)
FILE * | plLibOpen (PLCHAR_VECTOR fn)
PDFstrm * | plLibOpenPdfstrm (PLCHAR_VECTOR fn)
PLINT | plFindName (char *p)
void | plGetName (PLCHAR_VECTOR dir, PLCHAR_VECTOR subdir, PLCHAR_VECTOR 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, PLCHAR_VECTOR 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)
PLDev * | plAllocDev (PLStream *pls)
void | plGinInit (PLGraphicsIn *gin)
PLINT | plGetInt (PLCHAR_VECTOR s)
PLFLT | plGetFlt (PLCHAR_VECTOR s)
char PLDLLIMPEXP * | plstrdup (PLCHAR_VECTOR src)
int | plsnprintf (char *buffer, int n, PLCHAR_VECTOR format,...)
int | plsnscanf (PLCHAR_VECTOR buffer, int n, PLCHAR_VECTOR 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 PLDLLIMPEXP * | plplotLibDir = 0
static int(* | exit_handler )(PLCHAR_VECTOR errormsg)
static void(* | abort_handler )(PLCHAR_VECTOR 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

## ◆ BUFFER_SIZE

#define BUFFER_SIZE 256

Definition at line 72 of file plctrl.c.

## ◆ COLLEN

#define COLLEN 30

Definition at line 73 of file plctrl.c.

## ◆ color_def

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

Definition at line 1013 of file plctrl.c.

## ◆ DEBUG

#define DEBUG

Definition at line 45 of file plctrl.c.

## ◆ FUZZ_EPSILON

#define FUZZ_EPSILON 1.e-4

Definition at line 79 of file plctrl.c.

## ◆ fuzzy_range_check

#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; \
}
min
int min(int a, int b)
Definition: plplot_octaveOCTAVE_wrap.cxx:2496
value
static PLFLT value(double n1, double n2, double hue)
Definition: plctrl.c:1219
max
int max(int a, int b)
Definition: plplot_octaveOCTAVE_wrap.cxx:2492
MSGLEN
#define MSGLEN
Definition: plctrl.c:75

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

  value | The value to range check.
  min | The minimum allowable value.
  max | The maximum allowable value.
  fuzz | Amount of slop to allow beyond the range defined by min & max.
  err_number | The error number.

Definition at line 1592 of file plctrl.c.

## ◆ MAX_NUM_TRIES

#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

  pls | A plot stream structure.

Definition at line 2569 of file plctrl.c.

## ◆ MSGLEN

#define MSGLEN 1024

Definition at line 75 of file plctrl.c.

## ◆ NEED_PLDEBUG

#define NEED_PLDEBUG

Definition at line 47 of file plctrl.c.

## ◆ PALLEN

#define PALLEN 160

Definition at line 74 of file plctrl.c.

## ◆ PLLIBDEV

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

Definition at line 136 of file plctrl.c.

## Function Documentation

## ◆ c_plcol0()

void c_plcol0 | ( | PLINT | icol0 | ) |

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

Parameters

  icol0 | The index of the color map 0 color to use as the current color. (0 - plsc->ncol0).

Definition at line 154 of file plctrl.c.

## ◆ c_plcol1()

void c_plcol1 | ( | PLFLT | col1 | ) |

Set color for cmap1. Argument is a float between MIN_PLFLT_CMAP1 and MAX_PLFLT_CMAP1

Parameters

  col1 | The index of the color map 1 color to use as the current color. (MIN_PLFLT_CMAP1 - MAX_PLFLT_CMAP1)

Definition at line 188 of file plctrl.c.

## ◆ c_plgcmap1_range()

void c_plgcmap1_range | ( | PLFLT * | min_color,
|  | PLFLT * | max_color
| ) |  |

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

Parameters

  min_color | Specifies the minimum color used.
  max_color | Specifies the maximum color used.

Definition at line 924 of file plctrl.c.

## ◆ c_plgcol0()

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

  icol0 | Index of the color to be return (0 - plsc->ncol0).
  r | Current red value of the color.
  g | Current green value of the color.
  b | Current blue value of the color.

Definition at line 359 of file plctrl.c.

## ◆ c_plgcol0a()

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

  icol0 | Index of the color to be return (0 - plsc->ncol0).
  r | Current red value of the color.
  g | Current green value of the color.
  b | Current blue value of the color.
  alpha | Current alpha value of the color.

Definition at line 396 of file plctrl.c.

## ◆ c_plgcolbg()

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

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

Parameters

  r | Current red value of the background color.
  g | Current green value of the background color.
  b | Current blue value of the background color.

Definition at line 263 of file plctrl.c.

## ◆ c_plgcolbga()

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

  r | Current red value of the background color.
  g | Current green value of the background color.
  b | Current blue value of the background color.
  alpha | Current alpha value of the background color.

Definition at line 279 of file plctrl.c.

## ◆ c_plgdrawmode()

PLINT c_plgdrawmode | ( | void |  | ) |

Get drawing mode (depends on device support!)

Returns
  Current drawing mode

Definition at line 2071 of file plctrl.c.

## ◆ c_plgra()

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 2003 of file plctrl.c.

## ◆ c_plhlsrgb()

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

  h | hue in HLS color scheme (0.0 - 360.0)
  l | lightness in HLS color scheme (0.0 - 1.0)
  s | saturation in HLS color scheme (0.0 - 1.0)
  p_r | red value of the HLS color
  p_g | green value of the HLS color
  p_b | blue value of the HLS color

Definition at line 1261 of file plctrl.c.

## ◆ c_plrandd()

PLFLT c_plrandd | ( | void |  | ) |

Returns
  A random number on [0,1]-interval.

Definition at line 3081 of file plctrl.c.

## ◆ c_plrgbhls()

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

  r | red in RGB color scheme (0.0 - 1.0)
  g | green in RGB color scheme (0.0 - 1.0)
  b | blue in RGB color scheme (0.0 - 1.0)
  p_h | hue value of the RGB color.
  p_l | lightness value of the RGB color.
  p_s | saturation value of the RGB color.

Definition at line 1294 of file plctrl.c.

## ◆ c_plscmap0()

void c_plscmap0 | ( | PLINT_VECTOR | r,
|  | PLINT_VECTOR | g,
|  | PLINT_VECTOR | 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

  r | Array of red values.
  g | Array of green values.
  b | Array of blue values.
  ncol0 | Total number of RGB values.

Definition at line 434 of file plctrl.c.

## ◆ c_plscmap0a()

void c_plscmap0a | ( | PLINT_VECTOR | r,
|  | PLINT_VECTOR | g,
|  | PLINT_VECTOR | b,
|  | PLFLT_VECTOR | 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

  r | Array of red values.
  g | Array of green values.
  b | Array of blue values.
  alpha | Array of alpha values.
  ncol0 | Total number of RGBA values.

Definition at line 472 of file plctrl.c.

## ◆ c_plscmap0n()

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

  ncol0 | Total number of colors.

Definition at line 942 of file plctrl.c.

## ◆ c_plscmap1()

void c_plscmap1 | ( | PLINT_VECTOR | r,
|  | PLINT_VECTOR | g,
|  | PLINT_VECTOR | b,
|  | PLINT | ncol1
| ) |  |

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

Parameters

  r | Array of red values.
  g | Array of green values.
  b | Array of blue values.
  ncol1 | Total number of RGB values.

Definition at line 513 of file plctrl.c.

## ◆ c_plscmap1_range()

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_color | Specifies the minimum cmap1 index to use. A value of MIN_PLFLT_CMAP1 or less indicates that the range should start at MIN_PLFLT_CMAP1, the lowest valid cmap1 index available.
  max_color | Specifies the maximum cmap1 index to use. A value of MAX_PLFLT_CMAP1 or greater indicates that the range should finish at MAX_PLFLT_CMAP1, the highest valid cmap1 index available.

If the specified range is completely invalid (i.e., min_color >= max_color or max_color < MIN_PLFLT_CMAP1, or min_color > MAX_PLFLT_CMAP1), then min_color = MIN_PLFLT_CMAP1 and max_color = MAX_PLFLT_CMAP1 is used.

Definition at line 892 of file plctrl.c.

## ◆ c_plscmap1a()

void c_plscmap1a | ( | PLINT_VECTOR | r,
|  | PLINT_VECTOR | g,
|  | PLINT_VECTOR | b,
|  | PLFLT_VECTOR | alpha,
|  | PLINT | ncol1
| ) |  |

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

Parameters

  r | Array of red values.
  g | Array of green values.
  b | Array of blue values.
  alpha | Array of alpha values.
  ncol1 | Total number of RGBA values.

Definition at line 551 of file plctrl.c.

## ◆ c_plscmap1l()

void c_plscmap1l | ( | PLINT | itype,
|  | PLINT | npts,
|  | PLFLT_VECTOR | intensity,
|  | PLFLT_VECTOR | coord1,
|  | PLFLT_VECTOR | coord2,
|  | PLFLT_VECTOR | coord3,
|  | PLINT_VECTOR | 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 and last points MUST correspond to cmap1 coordinates MIN_PLFLT_CMAP1 and MAX_PLFLT_CMAP1.

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

  itype | 0: HLS, 1: RGB
  npts | number 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 632 of file plctrl.c.

## ◆ c_plscmap1la()

void c_plscmap1la | ( | PLINT | itype,
|  | PLINT | npts,
|  | PLFLT_VECTOR | intensity,
|  | PLFLT_VECTOR | coord1,
|  | PLFLT_VECTOR | coord2,
|  | PLFLT_VECTOR | coord3,
|  | PLFLT_VECTOR | alpha,
|  | PLINT_VECTOR | alt_hue_path
| ) |  |

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

Parameters

  itype | 0: HLS, 1: RGB
  npts | number 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 703 of file plctrl.c.

## ◆ c_plscmap1n()

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

  ncol1 | The number of colors in cmap1.

Definition at line 1067 of file plctrl.c.

## ◆ c_plscol0()

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

  icol0 | index of the color to set (0 - plsc->ncol0)
  r | Red value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  g | Green value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  b | Blue value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).

Definition at line 296 of file plctrl.c.

## ◆ c_plscol0a()

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

  icol0 | index of the color to set (0 - plsc->ncol0)
  r | Red value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  g | Green value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  b | Blue value of the color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  alpha | Alpha value of the color (MIN_PLFLT_ALPHA - MAX_PLFLT_ALPHA).

Definition at line 326 of file plctrl.c.

## ◆ c_plscolbg()

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

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

Parameters

  r | Red value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  g | Green value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  b | Blue value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).

Definition at line 229 of file plctrl.c.

## ◆ c_plscolbga()

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

  r | Red value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  g | Green value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  b | Blue value of the background color (MIN_PLINT_RGB - MAX_PLINT_RGB).
  alpha | Alpha (transparency) value of the background color (MIN_PLFLT_ALPHA - MAX_PLFLT_ALPHA).

Definition at line 248 of file plctrl.c.

## ◆ c_plscolor()

void c_plscolor | ( | PLINT | color | ) |

Used to globally turn color output on/off

Parameters

  color | 0 = no color, Not zero = color.

Definition at line 1202 of file plctrl.c.

## ◆ c_plsdrawmode()

void c_plsdrawmode | ( | PLINT | mode | ) |

Set drawing mode (depends on device support!)

Parameters

  mode | This determines which drawing mode to use.

Definition at line 2048 of file plctrl.c.

## ◆ c_plseed()

void c_plseed | ( | unsigned int | seed | ) |

Set the seed for the random number generator included.

Parameters

  seed | The random number generator seed value.

Definition at line 3068 of file plctrl.c.

## ◆ c_plspal0()

void c_plspal0 | ( | PLCHAR_VECTOR | 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

  filename | name of the cmap0 palette file.

Definition at line 1558 of file plctrl.c.

## ◆ c_plspal1()

void c_plspal1 | ( | PLCHAR_VECTOR | 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

  filename | name of the cmap1 palette file.
  interpolate | interpolate between control points.

Definition at line 1614 of file plctrl.c.

## ◆ c_pltext()

void c_pltext | ( | void |  | ) |

Switches to text screen.

Definition at line 2100 of file plctrl.c.

## ◆ c_plxormod()

void c_plxormod | ( | PLINT | mode,
|  | PLINT * | status
| ) |  |

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

Parameters

  mode | Boolean.
  status | 1 if successful, 0 otherwise.

Definition at line 2018 of file plctrl.c.

## ◆ cmap0_palette_read()

static void cmap0_palette_read | ( | PLCHAR_VECTOR | 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

  filename | name of the cmap0 palette file.
  number_colors | number of color found in the palette file.
  r | red value of each color in the palette file.
  g | green value of each color in the palette file.
  b | blue value of each color in the palette file.
  a | alpha value of each color in the palette file.

Definition at line 1409 of file plctrl.c.

## ◆ color_set()

static void color_set | ( | PLINT | i,
|  | U_CHAR | r,
|  | U_CHAR | g,
|  | U_CHAR | b,
|  | PLFLT | a,
|  | PLCHAR_VECTOR | name
| ) |  |
| static

Initializes color table 0 entry by RGB values.

Parameters

  i | Index of the color.
  r | Red value of the color.
  g | Green value of the color.
  b | Blue value of the color.
  a | Alpha value of the color.
  name | The name of the color.

Definition at line 1004 of file plctrl.c.

## ◆ limit_rgba_range()

static void limit_rgba_range | ( | PLCHAR_VECTOR | message,
|  | PLINT_NC_SCALAR | r,
|  | PLINT_NC_SCALAR | g,
|  | PLINT_NC_SCALAR | b,
|  | PLFLT_NC_SCALAR | alpha
| ) |  |
| static

Definition at line 3165 of file plctrl.c.

## ◆ pl_cmd()

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

  op | A PLESC command to pass to the driver.
  ptr | Data associated with the op command.

Definition at line 2118 of file plctrl.c.

## ◆ plabort()

void plabort | ( | PLCHAR_VECTOR | 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

  errormsg | The error message.

Definition at line 1894 of file plctrl.c.

## ◆ plAllocDev()

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

  pls | A plot stream structure.

Returns
  A PLDev *

Definition at line 2866 of file plctrl.c.

## ◆ plCloseFile()

void plCloseFile | ( | PLStream * | pls | ) |

Closes output file unless it is associated with stdout.

Parameters

  pls | A plot stream structure.

Definition at line 2635 of file plctrl.c.

## ◆ plcmap0_def()

static 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

  imin | Index of the first color to set to its default.
  imax | Index of the last color to set to its default.

Definition at line 1026 of file plctrl.c.

## ◆ plcmap1_calc()

void plcmap1_calc | ( | void |  | ) |

Bin up cmap 1 space and assign colors to make inverse mapping easy.

Definition at line 764 of file plctrl.c.

## ◆ plcmap1_def()

static 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 1128 of file plctrl.c.

## ◆ plcol_interp()

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

  pls | A plot stream structure.
  newcolor | A color structure to store the color in.
  i | Index of the desired color.
  ncol | Total number of colors (supported by the device?).

Definition at line 2530 of file plctrl.c.

## ◆ plexit()

void plexit | ( | PLCHAR_VECTOR | 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

  errormsg | The error message.

Definition at line 1958 of file plctrl.c.

## ◆ plFamInit()

void plFamInit | ( | PLStream * | pls | ) |

Initializes family file parameters.

Parameters

  pls | A plot stream structure.

Definition at line 2751 of file plctrl.c.

## ◆ plFindCommand()

char* plFindCommand | ( | PLCHAR_VECTOR | 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

  fn | Name of the executable(?).

Returns
  The location of the executable file.

Definition at line 2146 of file plctrl.c.

## ◆ plFindName()

PLINT 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

  p | Name of the executable to find.

Returns
  0 if p is found & is an executable.

Definition at line 2432 of file plctrl.c.

## ◆ plGetFam()

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

  pls | A plot stream structure.

Definition at line 2780 of file plctrl.c.

## ◆ plGetFlt()

PLFLT plGetFlt | ( | PLCHAR_VECTOR | s | ) |

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

Parameters

  s | The prompt message.

Returns
  The PLFLT the human entered.

Definition at line 2945 of file plctrl.c.

## ◆ plGetInt()

PLINT plGetInt | ( | PLCHAR_VECTOR | s | ) |

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

Parameters

  s | The prompt message.

Returns
  The PLINT the human entered.

Definition at line 2910 of file plctrl.c.

## ◆ plGetName()

void plGetName | ( | PLCHAR_VECTOR | dir,
|  | PLCHAR_VECTOR | subdir,
|  | PLCHAR_VECTOR | 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

  dir | The directory name.
  subdir | The sub-directory name.
  filename | The file name.
  filespec | The result of concatenating dir, subdir and filename.

Definition at line 2453 of file plctrl.c.

## ◆ plGinInit()

void plGinInit | ( | PLGraphicsIn * | gin | ) |

Just fills in the PLGraphicsIn with appropriate initial values.

Parameters

  gin | A plot graphics input (i.e. keypress or mouseclick) structure.

Definition at line 2887 of file plctrl.c.

## ◆ plLibOpen()

FILE* plLibOpen | ( | PLCHAR_VECTOR | 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

  fn | Name of the file.

Returns
  A open file pointer (if successful).

Definition at line 2229 of file plctrl.c.

## ◆ plLibOpenPdfstrm()

PDFstrm* plLibOpenPdfstrm | ( | PLCHAR_VECTOR | 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

  fn | Name of the file.

Returns
  A open PDFstrm file pointer (if successful)

Definition at line 2263 of file plctrl.c.

## ◆ plOpenFile()

void plOpenFile | ( | PLStream * | pls | ) |

Definition at line 2571 of file plctrl.c.

## ◆ plP_getmember()

void plP_getmember | ( | PLStream * | pls | ) |

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

Parameters

  pls | A plot stream structure.

Definition at line 2657 of file plctrl.c.

## ◆ plP_sfnam()

void plP_sfnam | ( | PLStream * | pls,
|  | PLCHAR_VECTOR | 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

  pls | A plot stream.
  fnam | The base file name of the plot files.

Definition at line 2700 of file plctrl.c.

## ◆ plrestore_locale()

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_locale | The saved numeric locale..

Definition at line 3145 of file plctrl.c.

## ◆ plRotPhy()

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

  orient | New plot orientation (0-3)
  xmin | Current plot x minimum?
  ymin | Current plot y minimum?
  xmax | Current plot x maximum?
  ymax | Current plot y maximum?
  px | Old x coordinate mapped to new x coordinate.
  py | Old y coordinate mapped to new y coordinate.

Definition at line 2824 of file plctrl.c.

## ◆ plsabort()

void plsabort | ( | void(*)(PLCHAR_VECTOR) | handler | ) |

Sets an optional user abort handler.

Parameters

  handler | A function that takes a PLCHAR_VECTOR argument that will be called in the event of a abort.

Definition at line 1938 of file plctrl.c.

## ◆ plsave_set_locale()

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 3101 of file plctrl.c.

## ◆ plsexit()

void plsexit | ( | int(*)(PLCHAR_VECTOR) | handler | ) |

Sets an optional user exit handler.

Parameters

  handler | A function that takes a PLCHAR_VECTOR argument that will will be called in the event of a exit.

Definition at line 1987 of file plctrl.c.

## ◆ plsnprintf()

int plsnprintf | ( | char * | buffer,
|  | int | n,
|  | PLCHAR_VECTOR | 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

  buffer | String output buffer.
  n | Size of buffer.
  format | The format string.
  ... | The values that go in the format string (...)

Returns
  The length of buffer that is actually used.

Definition at line 3013 of file plctrl.c.

## ◆ plsnscanf()

int plsnscanf | ( | PLCHAR_VECTOR | buffer,
|  | int | n,
|  | PLCHAR_VECTOR | 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

  buffer | String output buffer.
  n | Size of buffer.
  format | The format string.
  ... | The values that go in the format string (...)

Returns
  The length of buffer that is actually used.

Definition at line 3045 of file plctrl.c.

## ◆ plstrdup()

char PLDLLIMPEXP* plstrdup | ( | PLCHAR_VECTOR | src | ) |

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

Parameters

  src | The string to duplicate.

Returns
  A copy of the string src.

Definition at line 2985 of file plctrl.c.

## ◆ plwarn()

void plwarn | ( | PLCHAR_VECTOR | errormsg | ) |

A handy way to issue warnings, if need be.

Parameters

  errormsg | The error message.

Definition at line 1863 of file plctrl.c.

## ◆ read_line()

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

  buffer | storage for the line of text.
  length | size of the buffer.
  fp | open file pointer from which the line of text should be read.

Returns
  The sanitized line from the file.

Definition at line 1352 of file plctrl.c.

## ◆ strcat_delim()

static 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

  dirspec | String to add the appropriate delimiter too.

Definition at line 2501 of file plctrl.c.

## ◆ value()

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

Auxiliary function used by c_plhlsrgb().

Parameters

  n1 | Lightness/saturation value 1.
  n2 | Lightness/saturation value 2.
  hue | hue (0.0 - 360.0).

Definition at line 1219 of file plctrl.c.

## Variable Documentation

## ◆ abort_handler

void( * abort_handler) (PLCHAR_VECTOR errormsg)
| static

Definition at line 99 of file plctrl.c.

## ◆ exit_handler

int( * exit_handler) (PLCHAR_VECTOR errormsg)
| static

Definition at line 96 of file plctrl.c.

## ◆ plplotLibDir

char PLDLLIMPEXP* plplotLibDir = 0

Definition at line 82 of file plctrl.c.