6.10 Vector Fields
 
                         S T M M O D

The routine STMMOD modifies the behaviour of streamlines.

The call is:  CALL STMMOD (CMOD, CKEY)         level 1, 2, 3 

CMOD          is a character string that defines a mode.
CKEY          is a character string that can have the values 
              'INTEGRATION', 'ARROWS' and 'CLOSED'. The 
              keyword 'INTEGRATION'  defines the integration
              method used for streamlines. For this keyword,
              CMOD can have the values  'EULER',  'RK2'  and
              'RK4'. 'RK2' and 'RK4' mean  Runke-Kutta inte-
              gration of second and fourth order.
              For the keywords  'ARROWS' and 'CLOSED',  COPT
              can have the values  'ON' and 'OFF'.  'ARROWS'
              enables arrows at streamlines and the  keyword
              'CLOSED' means that  DISLIN  tries  to  detect 
              closed streamlines.  A good integration method
              such as 'RK4' should be used for this mode.  
                           Defaults: ('RK2', 'INTEGRATION'),
                       ('OFF', 'ARROWS'), ('OFF', 'CLOSED').


                         S T M O P T

The routine STMOPT defines some streamline options.

The call is:  CALL STMOPT (N, CKEY)            level 1, 2, 3 

N             is an integer option.
CKEY          is a character string  containing  one  of the
              following keywords:
 = 'POINTS'   defines  the number  of points after  that the
              calculation of streamlines will be terminated.
              The default value is 1000 points.
 = 'ARROW'    specifies the form of arrows that can be plot-
              ted at streamlines.          Default: N = 1201
 = 'STREAMS'  defines  the number of starting points  around
              a seed point that  are  used  for  finding new 
              streamlines if automatic streamline generation
              is enabled for the routine STREAM3D. (N >= 4).
                                              Default: N = 4
 = 'HITS'     sets  the  number of minimal hits for the fast
              LIC algorithm that are required for each image
              pixel (N >= 1).                 Default: N = 1
 = 'LICL'     sets  the  filter  length for the fast LIC al-
              gorithm. The total filter length is: 2*N+1. 
                                             Default: N = 10
 = 'LICM'     defines the length of a  streamline in  points
              that  is  used  to  calculate  multiple  image 
              pixels in the fast LIC algorithm. 
                                            Default: N = 100

                         S T M V A L

The routine  STMVAL  defines some floating point options for
streamlines.

The call is:  CALL STMVAL (X, CKEY)            level 1, 2, 3 

X             is a floating point option.
CKEY          is a character string  containing  one  of the
              following keywords:
 = 'STEP'     defines the integration step.  The size of the
              integration step is X * (XPMAX - XPMIN), where 
              XPMIN and  XPMAX  are the  minimum and maximum 
              values of the array XPRAY in STREAM or STREAM-
              3D.            The default value is: X = 0.01.
 = 'DISTANCE' sets the distance of  streamlines  for evenly-
              spaced streamlines. The distance is calculated
              as  X * (XPMAX - XPMIN).  The  distance  value 
              should be greater than the integration step.
                                          Default: X = 0.02.
 = 'ARROWS'   defines  the  space between  arrows plotted at
              streamlines. The used space between arrows is:
              X * X-axis length.              Default: 0.25.
 = 'TEST'     defines a test value for evenly-spaced stream-
              lines.  The calculation of a new streamline is 
              stopped if the distance to any already  calcu-
              lated streamlines is lower than  X * distance,
              where distance  is the value  for  the keyword
              'DISTANCE'.                  Default: X = 0.5.
 = 'CLOSED'   sets a distance value for  detecting a  closed 
              streamline. The calculation of a streamline is
              terminated if the distance of a new seed point
              to  the  starting point  is  closer  than this 
              value. The used distance is  X *  (XPMAX - XP-
              MIN).                      Default: X = 0.005.
 = 'LICSTEP'  defines the  integration step  for streamlines
              that are calculated in the LIC algorithm  used
              by the routine LICPTS.
                                           Default: X = 0.5.     

                         L I C M O D

The routine  LICMOD modifies the behaviour of the Line Inte-
gral Convolution algorithm in the routine LICPTS.

The call is:  CALL LICMOD (CMOD, CKEY)         level 1, 2, 3 

CMOD          is a character string that can have the values
              'ON' and 'OFF'.
CKEY          is a character string that can have the values 
              'FAST' and 'SCALE'. The keyword 'FAST' enables
              or  disables the fast  LIC  algorithm  where a 
              single  streamline is used to calculate multi-
              ple image  pixels.  The image  pixels  can  be 
              scaled  with  the vectors lengths  if the key-
              word 'SCALE' is used with the mode 'ON'.
                                    Defaults: ('ON', 'FAST',
                                           ('OFF', 'SCALE').

6.11 Line Attributes

                      L I N E  S T Y L E S

The routines SOLID, DOT,  DASH,  CHNDSH, CHNDOT, DASHM, DOTL
and  DASHL  define  different  line styles.  They are called
without parameters.  The routine  LINTYP (NTYP)  can also be
used to set line styles where  NTYP  is an integer between 0
and 7 and corresponds to the line styles above.  The routine
MYLINE sets user-defined line styles.

                         M Y L I N E 

MYLINE defines a global line style.

The call is:  CALL MYLINE (NRAY, N)            level 1, 2, 3

NRAY          is an array  of positive  integers characteri-
              zing the line style.  Beginning with pen-down,
              a pen-down and pen-up will be done alternately
              according  to the  specified lengths in  NRAY.
              The lengths must be given in plot coordinates.
N             is the number of elements in NRAY (N <= 10).

Examples:     The values of  NRAY  for the  predefined  line
              styles  are given below:

              SOLID :        NRAY = {1} 
              DOT   :        NRAY = {1, 10} 
              DASH  :        NRAY = {10, 10} 
              CHNDSH:        NRAY = {30, 15, 10, 15} 
              CHNDOT:        NRAY = {1, 15, 15, 15} 
              DASHM :        NRAY = {20, 15} 
              DOTL  :        NRAY = {1, 20} 
              DASHL :        NRAY = {30, 20}


                         L I N C L R 

The routine  LINCLR  defines colour values for the pen-downs
in line styles. The colours are ignored for solid lines.

The call is:  CALL LINCLR (NRAY, N)            level 1, 2, 3

NRAY          is an array  of colour values.
N             is the number of  elements in NRAY  (N <= 10).
              The default  value  N = 0 disables colours for 
              line styles.

                         L I N W I D 

The routine LINWID sets the line width.

The call is:  CALL LINWID (NWIDTH)             level 1, 2, 3

NWIDTH        is the line width in plot coordinates.
                                         Default: NWIDTH = 1

Notes:      - To define smaller line widths than 1 (i.e. for
              PostScript files), the routine PENWID (XWIDTH)
              can be used where  XWIDTH has the same meaning
              as NWIDTH.
            - DISLIN tries to use hardware  features for the
              line width.  This  can  be  disabled  with the 
              option HWMODE ('OFF', 'LINE'). 
 
                         L N C A P 

The routine LNCAP sets the current line cap parameter.

The call is:  CALL LNCAP (CAP)                 level 1, 2, 3

CAP           is a character string defining the line cap.
  = 'ROUND'   defines rounded caps.
  = 'CUT'     defines square caps.
  = 'LONG'    defines square caps where stroke  ends will be
              continued equal to half the line width.
                                      Default: CAP = 'LONG'.

                         L N J O I N 

The routine LNJOIN sets the current line join parameter.

The call is:  CALL LNJOIN (CJOIN)              level 1, 2, 3

CJOIN         is  a  character  string  containing  the line
              join.
  = 'SHARP'   defines sharp corners between path segments.
  = 'TRUNC'   defines  truncated  corners  between path seg-
              ments.
                                   Default: CJOIN = 'TRUNC'.

                         L N M L T 

The routine  LNMLT  sets  the current miter limit parameter.
This  routine  can be  useful  if the  line join  is set  to
'SHARP'.

The call is:  CALL LNMLT (XFC)                 level 1, 2, 3

XFC           is a  floating point number  where  XFC * line
              width will  be used  as the  miter limit.  The
              miter length is the distance between the inner
              and outside edge of a path corner.
                                           Default: XFC = 2.

                         L I N M O D 

The routine LINMOD enables anti-aliased lines  in image for-
mats such as PNG, BMP and TIFF. True colour mode is required 
for anti-aliased lines (see IMGFMT).

The call is:  CALL LINWID (CMOD, CKEY)         level 1, 2, 3

CMOD          is a  character string  that  can  contain the 
              modes 'ON' and 'OFF'.
CKEY          is a character  string that can have the value 
              'SMOOTH'. 
                                 Default: ('OFF', 'SMOOTH').

6.12 Shading

                         S H D P A T 

SHDPAT  selects  shading patterns  used by  routines such as
SHDCRV and AREAF.

The call is:  CALL SHDPAT (IPAT)               level 1, 2, 3

IPAT     is an integer between 0 and 17. The predefined pat-
         terns  are shown in appendix B.

                          M Y P A T

MYPAT defines a global shading pattern.

The call is:  CALL MYPAT (IANGLE, ITYPE, IDENS, ICROSS)
                                               level 1, 2, 3

IANGLE        is the angle of shading lines (0 - 179).
ITYPE         defines the type of shading lines:
        = 0   no shading lines.
        = 1   equidistant lines.
        = 2   double shading lines.
        = 3   triple shading lines.
        = 4   thick shading lines.
        = 5   dotted lines.
        = 6   dashed lines.
        = 7   dashed-dotted lines.
IDENS         defines  the  distance  between  shading lines
              (0: small distance, 9: big distance).
ICROSS        indicates  whether  shading  lines are hatched
              (0: not hatched, 1: hatched).

Examples:     The following calls to  MYPAT  show the prede-
              fined shading patterns used by SHDPAT:

  IPAT = 0:   CALL MYPAT (  0, 0, 0, 0)
  IPAT = 1:   CALL MYPAT ( 45, 1, 5, 0)
  IPAT = 2:   CALL MYPAT (150, 4, 5, 0)
  IPAT = 3:   CALL MYPAT (135, 1, 5, 0)
  IPAT = 4:   CALL MYPAT ( 45, 4, 5, 0)
  IPAT = 5:   CALL MYPAT ( 45, 1, 5, 1)
  IPAT = 6:   CALL MYPAT (135, 2, 1, 0)
  IPAT = 7:   CALL MYPAT ( 45, 4, 5, 1)
  IPAT = 8:   CALL MYPAT ( 30, 1, 4, 0)
  IPAT = 9:   CALL MYPAT ( 45, 2, 1, 1)
  IPAT = 10:  CALL MYPAT (  0, 1, 5, 1)
  IPAT = 11:  CALL MYPAT ( 45, 3, 1, 0)
  IPAT = 12:  CALL MYPAT ( 70, 4, 7, 0)
  IPAT = 13:  CALL MYPAT ( 45, 3, 1, 1)
  IPAT = 14:  CALL MYPAT (  0, 4, 5, 1)
  IPAT = 15:  CALL MYPAT ( 45, 2, 1, 0)
  IPAT = 16:  CALL MYPAT (  0, 1, 0, 0)
  IPAT = 17:  CALL MYPAT (  0, 5, 5, 0)

                         N O A R L N 

With the routine  NOARLN  the outlines of shaded regions can
be suppressed.

The call is:  CALL NOARLN                      level 1, 2, 3

                         H W M O D E 

The routine HWMODE enables or disables hardware features for
the line width and for shading patterns.

The call is:  CALL HWMODE (CMOD, CKEY)         level 1, 2, 3

CMOD          is a character string that can have the values
              'ON' and 'OFF'.
CKEY          is a character string that can have the values
              'LINE' and 'SHADING'.
                                    Default: ('ON', 'LINE'),
                                          ('ON', 'SHADING').

                         S H D F A C 

The routine SHDFAC sets a scaling factor for the distance of
scan lines for software shading.  

The call is:  CALL SHDFAC (XFAC)               level 1, 2, 3

XFAC          is the scaling factor (> 0.0).
                                                Default: 1.0

6.13 Attribute Cycles

The attributes line style, colour and shading pattern can be
changed  automatically  by routines such as  CURVE,  SHDCRV,
BARS and PIEGRF according to a predefined cycle.

Line styles:  SOLID,  DOT, DASH, CHNDSH, CHNDOT, DASHM, DOTL
              and DASHL.
Colours:      WHITE/BLACK, RED, GREEN, YELLOW, BLUE, ORANGE,
              CYAN and MAGENTA.
Shading:      Pattern numbers from 0 to 17.

The following subroutines allow the redefining of cycles.

                         L I N C Y C 

LINCYC changes the line style cycle.

The call is:  CALL LINCYC (INDEX, ITYP)        level 1, 2, 3

INDEX         is an index between 1 and 30.
ITYP          is an integer between  0 and 7  containing the
              line style  (0 = SOLID,   1 = DOT,   2 = DASH,
              3 = CHNDSH,  4 = CHNDOT,  5 = DASHM, 6 = DOTL,
              7 = DASHL).

                         C L R C Y C 

CLRCYC changes the colour cycle.

The call is:  CALL CLRCYC (INDEX, ICLR)        level 1, 2, 3

INDEX         is an index between 1 and 30.
ICLR          is a colour value (see SETCLR).

                         P A T C Y C 

PATCYC changes the shading pattern cycle.

The call is:   CALL PATCYC (INDEX, IPAT)       level 1, 2, 3

INDEX          is an index between 1 and 30.
IPAT           is a pattern  number  between  0 and 17 or is
               determined by the formula  
               IANGLE * 1000 + ITYPE * 100 + IDENS * 10 +
                                                      ICROSS
               with the parameters described in MYPAT.

6.14 Base Transformations

The following  subroutines  create  a transformation  matrix
that  affects plot vectors  contained  within page  borders.
Vectors may be scaled, shifted and rotated and the transfor-
mations can be combined in any order.

                         T R F S H F 

TRFSHF affects the shifting of plot vectors.

The call is:    CALL TRFSHF (NXSHFT, NYSHFT)   level 1, 2, 3

NXSHFT, NYSHFT  are plot coordinates  that define the magni-
                tude of shifting in the X- and Y-direction.

                         T R F S C L 

TRFSCL affects the scaling of plot vectors.
 
The call is:  CALL TRFSCL (XSCL, YSCL)         level 1, 2, 3

XSCL, YSCL    are  scaling factors  for the  X- and Y-direc-
              tion.

                         T R F R O T 

TRFROT affects the rotation of plot vectors around a point.

The call is:  CALL TRFROT (XANG, NX, NY)       level 1, 2, 3

XANG          is the rotation angle measured in degrees in a
              counter-clockwise direction.
NX, NY        are  the  plot  coordinates  of  the  rotation
              point.

                         T R F R E S 

TRFRES resets base transformations.

The call is:  CALL TRFRES                      level 1, 2, 3

6.15 Shielded Regions

This section  describes how  to protect  regions  from being
overwritten.  Shielded regions can be defined  automatically
by  DISLIN  or explicitly by the user.  Shielded regions are
stored  in a  buffer  which can  then be manipulated  by the
user.

                         S H I E L D 

SHIELD  selects shielded regions which are set automatically
by DISLIN.

The call is:  CALL SHIELD (CAREA, CMODE)       level 1, 2, 3

CAREA         is a character string defining the regions:
  = 'MESSAG'  is used for text and numbers plotted by MESSAG
              and NUMBER.
  = 'SYMBOL'  will shield symbols.
  = 'BARS'    will shield bars plotted by BARS.
  = 'PIE'     will shield pie segments plotted by PIEGRF.
  = 'LEGEND'  will protect  legends.  All legend  attributes
              should be set before calling CURVE because the
              shielded region of a legend is defined by CUR-
              VE.  If there  is no legend  position  defined
              with  LEGPOS,  CURVE assumes  that the  legend
              lies  in the  upper right  corner  of the axis
              system.
CMODE         is a character string defining a status:
  = 'ON'      means that  the regions  defined above will be
              written  to the  shielding buffer and are pro-
              tected.
  = 'OFF'     means that regions will not be  written to the
              shielding  buffer.   Regions  that  are  still
              stored in the buffer will be shielded.
  = 'DELETE'  removes regions from the shielding buffer.
  = 'RESET'   is a  combination  of   'OFF'  and   'DELETE'.
              Regions are removed from and will not be writ-
              ten to the shielding buffer. To save computing
              time, this command should always be used  when
              shielding is no longer needed.
  = 'NOVIS'   The shielding of regions held in the shielding
              buffer is disabled. This is not valid for  re-
              gions newly written to the buffer.
  = 'VIS'     Disabled  regions will be  protected.  This is
              the default value for regions newly written to
              the buffer.

The following routines set user-defined regions:

The calls are: 

     CALL SHLREC  (NX, NY, NW, NH)          for rectangles
     CALL SHLRCT  (NX, NY, NW, NH, THETA)   for rotated 
                                            rectangles
     CALL SHLCIR  (NX, NY, NR)              for circles
     CALL SHLELL  (NX, NY, NA, NB, THETA)   for rotated
                                            ellipses
     CALL SHLPIE  (NX, NY, NR, ALPHA, BETA) for pie segments
     CALL SHLPOL  (NXRAY, NYRAY, N)         for polygons.

NX, NY       are  plot coordinates  of the upper left corner
             or the centre point.
NW, NH       are the width and height of rectangles.
NR, NA, NB   are radii in plot coordinates.
THETA        is a  rotation  angle  measured in degrees in a
             counter-clockwise direction.
ALPHA, BETA  are starting and ending angles for pie segments
             measured  in  degrees  in  a  counter-clockwise
             direction.
NXRAY, NYRAY are arrays  of the  dimension N containing  the
             corner points of a polygon.

                         S H L I N D 

The index of  shielded  regions  in the  buffer  can be  re-
quested with SHLIND. It returns the index of the region last
written to the buffer.

The call is:  CALL SHLIND (ID)                 level 1, 2, 3

ID            is the returned index.

                         S H L D E L 

SHLDEL removes entries from the shielding buffer.

The call is:  CALL SHLDEL (ID)                 level 1, 2, 3

ID            is the index of a shielded region. If ID is 0,
              all regions defined by the user  will be dele-
              ted.

                         S H L R E S 

SHLRES deletes regions last written to the shielding buffer.

The call is:  CALL SHLRES (N)                  level 1, 2, 3

N             is the number of regions to delete.

                         S H L V I S 

SHLVIS  disables or  enables shielded regions.  Disabled re-
gions  are no  longer protected  but are still  held  in the
shielding buffer.

The call is:  CALL SHLVIS (ID, CMODE)          level 1, 2, 3

ID            is the index of a shielded region. If ID is 0,
              all entries
              are disabled or enabled.
CMODE = 'ON'  enables shielded  regions. This is the default
              value for regions newly written to the buffer.
      = 'OFF' disables shielded regions.

Notes:     -  A frame  is plotted  around regions defined by
              the user.  The thickness  of frames can be set
              with FRAME.  Regions defined  automatically by
              DISLIN  are not enclosed by a frame but frames
              plotted  by  MESSAG  after  using  FRMESS  and
              shielded regions defined by MESSAG are identi-
              cal.
           -  Shielded regions can overlap each other. 
           -  The statement   CALL RESET  ('SHIELD')  resets
              shielding. All regions defined by  DISLIN  and
              the user are removed from the shielding buffer
              and no new regions will be written to the buf-
              fer.
           -  The number of shielded  regions is  limited to
              the size of the shielding buffer  which is set
              to  1000 words.  The number  of words  used by
              regions are: 
                  SHLREC = 6, SHLRCT = 7, SHLCIR = 5,
                  SHLELL = 7, SHLPIE = 7 and SHLPOL = 2*N+3.
           -  Shielding  of regions  is computer  intensive.
              Therefore, shielding should be used very care-
              fully  and shielded regions  should be deleted
              from the buffer when no longer needed.
           -  Base transformations  do not affect the  posi-
              tion of shielded regions.
           -  SHLPOL can be used between the routines GRFINI
              and GRFFIN.  The shielded  region will be pro-
              jected into  3-D space.  This is not valid for
              other shielded regions.

