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

NAME

6       VVECTR - Manages the coordinate system mapping, color setting,
7       auxiliary text output, and drawing of the vector field plot, according
8       to the specifications established by the parameter setting routines and
9       the initialization routine, VVINIT.
10

SYNOPSIS

12       CALL VVECTR (U,V,P,IAM,VVUDMV,WRK)
13

C-BINDING SYNOPSIS

15       #include <ncarg/ncargC.h>
16
17       void c_vvectr(float *u, float *v, float *p, int *iam,
18                     int (*vvudmv_)(float *xcs, float *ycs,
19                     int *ncs, int *iai, int *iag, int *nai),
20                     float *wrk)
21

DESCRIPTION

23       U           (REAL 2 dimensional array, dimensioned as specified in last
24                   call to VVINIT, input): By default, assumed to contain the
25                   first dimensional axis components of the vector field.
26                   However, if PLR is non-zero, it is treated as containing
27                   the vector magnitudes.
28
29       V           (REAL 2 dimensional array, dimensioned as specified in last
30                   call to VVINIT, input): By default, assumed to contain the
31                   second dimensional axis components of the vector field.
32                   However, if PLR is non-zero, it is treated as containing
33                   the vector angles.
34
35       P           (REAL 2 dimensional array, dimensioned as specified in last
36                   call to VVINIT, input): Array of scalar data that may be
37                   used to color the vectors. The grid points are assumed to
38                   coincide with the grid points of the U and V arrays.
39                   Required only if CTV has an absolute value of 2; otherwise
40                   this argument is ignored and may be assigned a dummy value.
41
42       IAM         (INTEGER array, unknown dimension, input): Area map array
43                   previously established by calls to routines in the Areas
44                   utility. It is not examined or modified by Vectors.
45                   Required only if MSK is set to a non-zero value; otherwise
46                   it is ignored and may be assigned a dummy value.
47
48       VVUDMV      (EXTERNAL subroutine, input): User-definable masked drawing
49                   subroutine. See the man page vvudmv for a discussion of the
50                   usage and argument list required for this subroutine.
51                   Required only if MSK is set to a non-zero value; otherwise
52                   it is ignored and may be assigned a dummy value.
53
54       WRK         (REAL array, dimensioned as specified in last call to
55                   VVINIT, input/output): Work array required only if the
56                   parameter VMD is set to a value greater than 0.0. Otherwise
57                   may be set to a dummy value.
58
59

C-BINDING DESCRIPTION

61       The C-binding argument descriptions are the same as the FORTRAN
62       argument descriptions.
63

USAGE

65       A call to VVINIT must precede the first call to VVECTR, and is again
66       required any time the vector or scalar array data changes, any of the
67       coordinate control parameters are modified, or the number of color
68       threshold levels is modified when Vectors is given the responsibility
69       of setting up the color threshold value array. However, the user may
70       modify text elements or any of the rendering control parameters, and if
71       assuming responsibility for setting up the color threshold array, may
72       also modify the color array parameters, in between multiple invocations
73       of VVECTR.
74
75       Arguments to VVINIT establish the sizes of the two or three data
76       arrays, as well as the possible work array. VVINIT places these values
77       into common block variables where they become available to VVECTR.
78       Therefore no size arguments need appear in the VVECTR argument list.
79       When there is no scalar data array, area masking is not enabled, and
80       VMD is less than or equal to 0.0, all but the first two arguments to
81       VVECTR may have dummy values and the invocation would be something
82       like:
83
84               CALL VVECTR(U,V,IDM,IDM,IDM,IDM)
85
86       where IDM is an arbitrary variable, INTEGER or REAL, that need not have
87       been initialized.  However, any time the color threshold control
88       parameter, CTV has an absolute value of 2, the auxiliary scalar data
89       array is expected, and the P scalar array variable needs to be
90       specified.
91
92       The masking capability supported by Vectors allows the user to overlay
93       vector fields on top of graphics produced by other utilities, such as
94       Conpack contour plots, without encroaching on areas, like label boxes,
95       that should appear in the foreground. Normally the area map should be
96       generated and used in the normal way (as described in the Areas and
97       Conpack documentation) before calling any routines in the Vectors
98       utility. When the parameter MSK has a non-zero value, masking is
99       enabled and a previously created area map must be passed to VVECTR.
100       VVECTR examines the map, returning an error if it determines that it is
101       an invalid map or contains more area maps that it can handle, currently
102       64. Otherwise its only use of the map is as a member of the argument
103       list when invoking one of the Areas routines, ARDRLN or ARGTAI.  The
104       user must also pass in a user-definable masked drawing subroutine.  A
105       simple version of this subroutine, named VVUDMV, is supplied with the
106       Vectors utility, and may suffice for basic masked drawing operations.
107       See the vvudmv man page for more information.
108
109       The last argument in the calling sequence, WRK, is used only when the
110       parameter VMD (Vector Minimum Distance) is given a value greater than
111       0.0. In this case, Vectors uses the array to keep track of the location
112       of each vector in NDC space so that the distances between vectors can
113       be compared. Based on these comparisons, Vectors eliminates some
114       vectors such that the remaining vectors are separated by at least the
115       specified distance.  Otherwise the WRK argument is ignored, and may be
116       passed a dummy argument value.
117

EXAMPLES

119       Use the ncargex command to see the following relevant examples: bnchmk,
120       fcover, ffex00, ffex01, ffex02, ffex05, stex02, stex03, vvex01, vvex02.
121

ACCESS

123       To use VVECTR or c_vvectr, load the NCAR Graphics libraries ncarg,
124       ncarg_gks, and ncarg_c, preferably in that order.
125

MESSAGES

127       See the vectors man page for a description of all Vectors error
128       messages and/or informational messages.
129

SEE ALSO

131       Online: vectors, vectors_params, vvgetc, vvgeti, vvgetr, vvinit,
132       vvrset, vvsetc, vvseti, vvsetr, vvudmv, vvumxy, ncarg_cbind.
133
134       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
135
137       Copyright (C) 1987-2009
138       University Corporation for Atmospheric Research
139       The use of this Software is governed by a License Agreement.
140
141
142
143UNIX                              April 1993                    VVECTR(3NCARG)
Impressum