1PLSHADES(3plplot)                 PLplot API                 PLSHADES(3plplot)
2
3
4

NAME

6       plshades - Shade regions on the basis of value
7

SYNOPSIS

9       plshades(a,  nx,  ny,  defined, xmin, xmax, ymin, ymax, clevel, nlevel,
10       fill_width, cont_color, cont_width, fill, rectangular, pltr, pltr_data)
11

DESCRIPTION

13       Shade regions on the basis of value.  This is  the  high-level  routine
14       for   making   continuous   color   shaded   plots   with  cmap1  while
15       plshade(3plplot) should be used to plot individual shaded regions using
16       either  cmap0  or  cmap1.  examples/;<language>/x16*  shows  how to use
17       plshades(3plplot) for each of our supported languages.
18
19       Redacted form: General: plshades(a, defined, xmin,  xmax,  ymin,  ymax,
20       clevel,  fill_width,  cont_color,  cont_width, fill, rectangular, pltr,
21       pltr_data)
22
23
24       This function is used in examples 16, 21, and 22.
25

ARGUMENTS

27       a (PLFLT_MATRIX(3plplot), input)
28              A matrix containing function values to plot.  Should have dimen‐
29              sions of nx by ny.
30
31       nx (PLINT(3plplot), input)
32              First dimension of matrix "a".
33
34       ny (PLINT(3plplot), input)
35              Second dimension of matrix "a".
36
37       defined (PLDEFINED_callback(3plplot), input)
38              Callback  function  specifying the region that should be plotted
39              in the shade plot.  This function accepts x and y coordinates as
40              input arguments and must return 1 if the point is to be included
41              in the shade plot and 0 otherwise.  If you want to plot the  en‐
42              tire shade plot (the usual case), this argument should be set to
43              NULL.
44
45       xmin, xmax, ymin, ymax (PLFLT(3plplot), input)
46              See the discussion of pltr below for  how  these  arguments  are
47              used  (only for the special case when the callback function pltr
48              is not supplied).
49
50       clevel (PLFLT_VECTOR(3plplot), input)
51              A vector containing the data levels corresponding to  the  edges
52              of each shaded region that will be plotted by this function.  To
53              work properly the levels should be monotonic.
54
55       nlevel (PLINT(3plplot), input)
56              Number of shades plus 1 (i.e., the number of shade  edge  values
57              in clevel).
58
59       fill_width (PLFLT(3plplot), input)
60              Defines the line width used by the fill pattern.
61
62       cont_color (PLINT(3plplot), input)
63              Defines  cmap0  pen  color  used  for contours defining edges of
64              shaded regions.  The pen color is only  temporary  set  for  the
65              contour  drawing.   Set  this  value to zero or less if no shade
66              edge contours are wanted.
67
68       cont_width (PLFLT(3plplot), input)
69              Defines line width used for contours defining  edges  of  shaded
70              regions.   This value may not be honored by all drivers. The pen
71              width is only temporary set for the contour drawing.   Set  this
72              value to zero or less if no shade edge contours are wanted.
73
74       fill (PLFILL_callback(3plplot), input)
75              Callback  routine  used to fill the region.  Use plfill(3plplot)
76              for this purpose.
77
78       rectangular (PLBOOL(3plplot), input)
79              Set rectangular to true if rectangles map  to  rectangles  after
80              coordinate  transformation with pltrl.  Otherwise, set rectangu‐
81              lar to false. If rectangular is set to true,  plshade  tries  to
82              save  time by filling large rectangles.  This optimization fails
83              if the coordinate transformation distorts the shape  of  rectan‐
84              gles.   For example a plot in polar coordinates has to have rec‐
85              tangular set to false.
86
87       pltr (PLTRANSFORM_callback(3plplot), input)
88              A callback function that defines the transformation between  the
89              zero-based  indices  of  the  matrix a and world coordinates. If
90              pltr is not supplied (e.g., is set to NULL in the C case),  then
91              the x indices of a are mapped to the range xmin through xmax and
92              the y indices of a are mapped to the range ymin through ymax.For
93              the  C case, transformation functions are provided in the PLplot
94              library:  pltr0(3plplot)   for   the   identity   mapping,   and
95              pltr1(3plplot) and pltr2(3plplot) for arbitrary mappings respec‐
96              tively defined by vectors and matrices.  In addition, C callback
97              routines for the transformation can be supplied by the user such
98              as the mypltr function in  examples/c/x09c.c  which  provides  a
99              general  linear  transformation  between  index  coordinates and
100              world coordinates.For languages other than C you should  consult
101              the PLplot documentation for the details concerning how PLTRANS‐
102              FORM_callback(3plplot) arguments  are  interfaced.  However,  in
103              general,  a  particular pattern of callback-associated arguments
104              such as a tr vector with 6 elements; xg and yg  vectors;  or  xg
105              and  yg  matrices are respectively interfaced to a linear-trans‐
106              formation  routine  similar  to  the  above   mypltr   function;
107              pltr1(3plplot);  and  pltr2(3plplot).  Furthermore,  some of our
108              more sophisticated bindings (see, e.g.,  the  PLplot  documenta‐
109              tion)  support  native  language callbacks for handling index to
110              world-coordinate transformations.  Examples of these various ap‐
111              proaches  are  given  in examples/<language>x09*, examples/<lan‐
112              guage>x16*,  examples/<language>x20*,   examples/<language>x21*,
113              and examples/<language>x22*, for all our supported languages.
114
115       pltr_data (PLPointer(3plplot), input)
116              Extra  parameter  to  help  pass  information to pltr0(3plplot),
117              pltr1(3plplot), pltr2(3plplot), or whatever routine that is  ex‐
118              ternally supplied.
119
120

AUTHORS

122       Many  developers  (who  are  credited at http://plplot.org/credits.php)
123       have contributed to PLplot over its long history.
124

SEE ALSO

126       PLplot documentation at http://plplot.org/documentation.php.
127
128
129
130                                 January, 2023               PLSHADES(3plplot)
Impressum