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.