1VVECTR(3NCARG) NCAR GRAPHICS VVECTR(3NCARG)
2
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
12 CALL VVECTR (U,V,P,IAM,VVUDMV,WRK)
13
15 #include <ncarg/ncargC.h>
16 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
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 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 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 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 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 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
61 The C-binding argument descriptions are the same as the FORTRAN
62 argument descriptions.
63
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 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 CALL VVECTR(U,V,IDM,IDM,IDM,IDM)
85 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 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 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
119 Use the ncargex command to see the following relevant examples: bnchmk,
120 fcover, ffex00, ffex01, ffex02, ffex05, stex02, stex03, vvex01, vvex02.
121
123 To use VVECTR or c_vvectr, load the NCAR Graphics libraries ncarg,
124 ncarg_gks, and ncarg_c, preferably in that order.
125
127 See the vectors man page for a description of all Vectors error
128 messages and/or informational messages.
129
131 Online: vectors, vectors_params, vvgetc, vvgeti, vvgetr, vvinit,
132 vvrset, vvsetc, vvseti, vvsetr, vvudmv, vvumxy, ncarg_cbind.
133 Hardcopy: NCAR Graphics Fundamentals, UNIX Version
135
137 Copyright (C) 1987-2007
138 University Corporation for Atmospheric Research
139 This documentation is free software; you can redistribute it and/or
141 modify it under the terms of the GNU General Public License as
142 published by the Free Software Foundation; either version 2 of the
143 License, or (at your option) any later version.
144 This software is distributed in the hope that it will be useful, but
146 WITHOUT ANY WARRANTY; without even the implied warranty of
147 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
148 General Public License for more details.
149 You should have received a copy of the GNU General Public License along
151 with this software; if not, write to the Free Software Foundation,
152 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
153UNIX April 1993 VVECTR(3NCARG)