1STUMXY(3NCARG)                   NCAR GRAPHICS                  STUMXY(3NCARG)
2
3
4

NAME

6       STUMXY - Maps a single point on the streamline from data to user
7       coordinate space.
8

SYNOPSIS

10       CALL STUMXY(XDA,YDA,XUS,YUS,IST)
11

DESCRIPTION

13       XDA         (REAL, input): The X coordinate of a point on the
14                   streamline in data coordinate space.
15
16       YDA         (REAL, input): The Y coordinate of a point on the
17                   streamline in data coordinate space.
18
19       XUS         (REAL, output): The X coordinate of the point in user
20                   coordinate space.
21
22       YUS         (REAL, output): The Y coordinate of the point in user
23                   coordinate space.
24
25       IST         (REAL, output) Status of the mapping operation: 0 indicates
26                   success, negative values indicate that the mapping failed;
27                   positive values are reserved and should not be used by the
28                   implementor of a mapping routine.
29

USAGE

31       STUMXY is a user-modifiable routine provided to support custom mappings
32       of the data coordinate space. The user does not invoke it directly.
33       Instead, whenever the parameter MAP specifies a mapping not handled by
34       Streamlines internally (i.e., when MAP is set to a value other than 0,
35       1, or 2), Streamlines calls STUMXY as needed during the process of
36       creating a streamline. The default version of STUMXY simply performs an
37       identity mapping. In order to implement a custom mapping, you must pick
38       a unique mapping code (a positive integer greater than 2), and then
39       modify each of the three routines, STUMXY, STUIXY, and STUMTA to
40       recognize and respond consistently to the chosen code. In the standard
41       distribution of NCAR Graphics, these three routines reside in a single
42       file, ´stumxy.f´.  STUMXY maps a point from data to user coordinate
43       space, STUIXY inversely maps a point from user to data coordinate
44       space, and STUMTA, which is likely to be the most difficult to
45       implement, finds the tangent angle of the streamline at a point in NDC
46       space.
47
48       STUMXY has access to a common block called STMAP that contains a number
49       of variables used to record the current transformation state. In order
50       to accommodate a variety of mapping implementations, STMAP provides
51       more information than normally required. Consider the values stored in
52       STMAP as strictly read-only. One essential member of this common block
53       is IMAP, which contains the value currently assigned to the MAP
54       parameter.
55
56       In STUMXY, the implementor of a custom mapping needs to add code of the
57       form:
58
59            IF (IMAP .EQ. <chosen_map_code>) THEN
60
61                ...map XDA to XUS
62
63                ...map YDA to YUS
64
65                ...if error, set IST to a negative value
66
67                RETURN
68
69            ENDIF
70
71       Note that after the return from STUMXY, Streamlines checks to ensure
72       that XUS and YUS are within the current boundaries of the user
73       coordinate system.
74
75       When implementing a custom mapping, you may wish to look at the coding
76       of the pre-defined mappings (0, identity mapping; 1, Ezmap projections;
77       and 2, polar coordinate mapping) in the file ´stmpxy.f´. For these
78       mappings, the subroutine STMPXY is the equivalent of STUMXY; it has an
79       identical interface and may serve as a model for your implementation.
80

ACCESS

82       To use STUMXY, load the NCAR Graphics libraries ncarg, ncarg_gks, and
83       ncarg_c, preferably in that order.
84

SEE ALSO

86       Online: stgetc, stgeti, stgetr, stinit, stream, streamlines,
87       streamlines_params, strset, stsetc, stseti, stsetr, stuixy, stumsl,
88       stumta, stumxy, ncarg_cbind.
89
90       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
91

93       Copyright (C) 1987-2007
94       University Corporation for Atmospheric Research
95
96       This documentation is free software; you can redistribute it and/or
97       modify it under the terms of the GNU General Public License as
98       published by the Free Software Foundation; either version 2 of the
99       License, or (at your option) any later version.
100
101       This software is distributed in the hope that it will be useful, but
102       WITHOUT ANY WARRANTY; without even the implied warranty of
103       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
104       General Public License for more details.
105
106       You should have received a copy of the GNU General Public License along
107       with this software; if not, write to the Free Software Foundation,
108       Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
109
110
111
112UNIX                              April 1993                    STUMXY(3NCARG)
Impressum