NAME

       plshades - Shade regions on the basis of value

SYNOPSIS

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

DESCRIPTION

       Shade regions on the basis of value.  This is the high-level routine for making continuous
       color  shaded  plots  with  cmap1 while plshade(3plplot) should be used to plot individual
       shaded regions using either cmap0 or cmap1. examples/;<language>/x16*  shows  how  to  use
       plshades(3plplot) for each of our supported languages.

       Redacted  form:  General: plshades(a, defined, xmin, xmax, ymin, ymax, clevel, fill_width,
       cont_color, cont_width, fill, rectangular, pltr, pltr_data)

       This function is used in examples 16, 21, and 22.

ARGUMENTS

       a (PLFLT_MATRIX(3plplot), input)
              A matrix containing function values to plot.  Should have dimensions of nx by ny.

       nx (PLINT(3plplot), input)
              First dimension of matrix "a".

       ny (PLINT(3plplot), input)
              Second dimension of matrix "a".

       defined (PLDEFINED_callback(3plplot), input)
              Callback function specifying the region that should be plotted in the  shade  plot.
              This  function  accepts x and y coordinates as input arguments and must return 1 if
              the point is to be included in the shade plot and 0 otherwise.  If you want to plot
              the entire shade plot (the usual case), this argument should be set to NULL.

       xmin, xmax, ymin, ymax (PLFLT(3plplot), input)
              See  the  discussion  of  pltr below for how these arguments are used (only for the
              special case when the callback function pltr is not supplied).

       clevel (PLFLT_VECTOR(3plplot), input)
              A vector containing the data levels corresponding  to  the  edges  of  each  shaded
              region  that  will be plotted by this function.  To work properly the levels should
              be monotonic.

       nlevel (PLINT(3plplot), input)
              Number of shades plus 1 (i.e., the number of shade edge values in clevel).

       fill_width (PLFLT(3plplot), input)
              Defines the line width used by the fill pattern.

       cont_color (PLINT(3plplot), input)
              Defines cmap0 pen color used for contours defining edges of  shaded  regions.   The
              pen color is only temporary set for the contour drawing.  Set this value to zero or
              less if no shade edge contours are wanted.

       cont_width (PLFLT(3plplot), input)
              Defines line width used for contours defining edges of shaded regions.  This  value
              may  not  be  honored  by  all drivers. The pen width is only temporary set for the
              contour drawing.  Set this value to zero or less if  no  shade  edge  contours  are
              wanted.

       fill (PLFILL_callback(3plplot), input)
              Callback routine used to fill the region.  Use plfill(3plplot) for this purpose.

       rectangular (PLBOOL(3plplot), input)
              Set   rectangular  to  true  if  rectangles  map  to  rectangles  after  coordinate
              transformation with pltrl.  Otherwise, set rectangular to false. If rectangular  is
              set  to  true,  plshade  tries  to  save  time  by  filling large rectangles.  This
              optimization  fails  if  the  coordinate  transformation  distorts  the  shape   of
              rectangles.  For example a plot in polar coordinates has to have rectangular set to
              false.

       pltr (PLTRANSFORM_callback(3plplot), input)
              A callback function that defines the transformation between the zero-based  indices
              of  the  matrix  a  and world coordinates. If pltr is not supplied (e.g., is set to
              NULL in the C case), then the x indices of a are mapped to the range  xmin  through
              xmax  and  the  y  indices of a are mapped to the range ymin through ymax.For the C
              case, transformation functions are provided in the PLplot  library:  pltr0(3plplot)
              for  the  identity  mapping,  and  pltr1(3plplot)  and pltr2(3plplot) for arbitrary
              mappings respectively defined by vectors and matrices.   In  addition,  C  callback
              routines  for  the  transformation  can  be supplied by the user such as the mypltr
              function in  examples/c/x09c.c  which  provides  a  general  linear  transformation
              between  index  coordinates  and  world  coordinates.For languages other than C you
              should  consult  the  PLplot  documentation  for   the   details   concerning   how
              PLTRANSFORM_callback(3plplot)  arguments  are  interfaced.  However,  in general, a
              particular pattern of callback-associated arguments such as  a  tr  vector  with  6
              elements; xg and yg vectors; or xg and yg matrices are respectively interfaced to a
              linear-transformation routine similar to the above mypltr function; pltr1(3plplot);
              and  pltr2(3plplot).  Furthermore,  some  of  our more sophisticated bindings (see,
              e.g., the PLplot documentation) support  native  language  callbacks  for  handling
              index  to  world-coordinate  transformations.  Examples of these various approaches
              are      given      in      examples/<language>x09*,       examples/<language>x16*,
              examples/<language>x20*,  examples/<language>x21*, and examples/<language>x22*, for
              all our supported languages.

       pltr_data (PLPointer(3plplot), input)
              Extra  parameter  to  help  pass  information  to  pltr0(3plplot),  pltr1(3plplot),
              pltr2(3plplot), or whatever routine that is externally supplied.

AUTHORS

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

SEE ALSO

       PLplot documentation at http://plplot.org/documentation.php.

                                            June, 2022                          PLSHADES(3plplot)