PLSHADES(3)                       PLplot API                       PLSHADES(3)



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(3)
       (or plshade1(3)) are used for individual shaded regions using either
       cmap0 or cmap1. examples/c/x16c.c shows a number of examples for using
       this function. See the following discussion of the arguments and the
       PLplot documentation for more information.

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


       This function is used in examples 16,21.

ARGUMENTS
       a (PLFLT **, input)
              Contains ** pointer to array to be plotted. The array must have
              been declared as PLFLT a[nx][ny].

       nx (PLINT, input)
              First dimension of array "a".

       ny (PLINT, input)
              Second dimension of array "a".

       defined (PLINT (*) (PLFLT, PLFLT), input)
              User function specifying regions excluded from the shading plot.
              This function accepts x and y coordinates as input arguments and
              must return 0 if the point is in the excluded region or 1
              otherwise. This argument can be NULL if all the values are
              valid.

       xmin (PLFLT, input)
              Defines the "grid" coordinates.  The data a[0][0] has a position
              of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so
              on.  (xmax,ymin)

       xmax (PLFLT, input)
              Defines the "grid" coordinates.  The data a[0][0] has a position
              of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so
              on.

       ymin (PLFLT, input)
              Defines the "grid" coordinates.  The data a[0][0] has a position
              of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so
              on.

       ymax (PLFLT, input)
              Defines the "grid" coordinates.  The data a[0][0] has a position
              of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin) and so
              on.

       clevel (PLFLT *, input)
              Pointer to array 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, input)
              Number of shades plus 1 (i.e., the number of shade edge values
              in clevel).

       fill_width (PLINT, input)
              Defines width used by the fill pattern.

       cont_color (PLINT, input)
              Defines 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 (PLINT, input)
              Defines pen 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 (void (*) (PLINT, PLFLT *, PLFLT *), input)
              Routine used to fill the region.  Use plfill(3).  Future version
              of PLplot may have other fill routines.

       rectangular (PLBOOL, 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 (void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer) , input)
              Pointer to function that defines transformation between indices
              in array z and the world coordinates (C only).  Transformation
              functions are provided in the PLplot library: pltr0(3) for
              identity mapping, and pltr1(3) and pltr2(3) for arbitrary
              mappings respectively defined by one- and two-dimensional
              arrays.  In addition, user-supplied routines for the
              transformation can be used as well.  Examples of all of these
              approaches are given in the PLplot documentation. The
              transformation function should have the form given by any of
              pltr0(3), pltr1(3), or pltr2(3).

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


AUTHORS
       Geoffrey Furnish and Maurice LeBrun wrote and maintain PLplot.  This
       man page was automatically generated from the DocBook source of the
       PLplot documentation, maintained by Alan W. Irwin and Rafael
       Laboissiere.

SEE ALSO
       PLplot documentation at http://plplot.sourceforge.net/resources.



                                November, 2007                     PLSHADES(3)
