NAME

       STREAM - Plots a streamline representation of field flow data, based on conditions
       established by STINIT and the current values of a set of user-modifiable internal
       parameters associated with the Streamlines utility.

SYNOPSIS

       CALL STREAM (U,V,P,IAM,STUMSL,WRK)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_stream(float *u, float *v, float *p, int *iam,
                     int (*stumsl_)( float *xcs, float *ycs,
                     int *ncs, int *iai, int *iag, int *nai),
                     float *wrk)

DESCRIPTION

       U           (REAL 2 dimensional array, dimensioned as specified in last call to STINIT,
                   input): By default, assumed to contain the first dimensional axis components
                   of the vector field.  However, if PLR is non-zero, it is treated as containing
                   the vector magnitudes.

       V           (REAL 2 dimensional array, dimensioned as specified in last call to STINIT,
                   input): By default, assumed to contain the second dimensional axis components
                   of the vector field.  However, if PLR is non-zero, it is treated as containing
                   the vector angles.

       P           (REAL, input, DUMMY): This argument is currently ignored.  May be assigned a
                   dummy value.

       IAM         (INTEGER array, unknown dimension, input): Area map array previously
                   established by calls to routines in the Areas utility. It is checked to see
                   that the number of area groups is within the limits allowed by Streamlines,
                   then simply passed through to an Areas routine for further processing.
                   Required only if MSK is set to a non-zero value; otherwise it is ignored and
                   may be assigned a dummy value.

       STUMSL      (EXTERNAL subroutine, input): User-definable masked drawing subroutine.
                   Required only if MSK is set to a non-zero value; otherwise it is ignored and
                   may be assigned a dummy value.

       WRK         (REAL array, dimensioned as specified in last call to STINIT, input/output):
                   Work array used to store normalized values of the U and V vector components
                   while the streamlines are calculated. It also holds bit flags indicating
                   whether a grid location is eligible for starting a streamline or placing a
                   directional arrowhead.

C-BINDING DESCRIPTION

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

USAGE

       A call to STINIT must precede the first call to STREAM, and is again required any time the
       vector array data changes or any of the coordinate space control parameters are modified.
       However, you may modify certain rendering control parameters between multiple invocations
       of STREAM. See the streamlines_params man page for more information.

       Arguments to STINIT establish the sizes of the vector component arrays and the WRK array.
       STINIT places these values into common block variables where they become available to
       STREAM.  Therefore no size arguments need appear in the STREAM argument list.  When area
       masking is not enabled, the third, fourth and fifth arguments to STREAM may all have dummy
       values and the invocation would be something like:

               CALL STREAM(U,V,IDM,IDM,IDM,WRK)

       where IDM is an arbitrary variable that need not have been initialized.

       The masking capability supported by Streamlines allows you to overlay streamlines on
       graphics produced by other utilities, such as Conpack contour plots, without encroaching
       on areas, like label boxes, that should appear in the foreground. Normally the area map
       should be generated and used in the normal way (as described in the Areas and Conpack
       documentation) before calling any routines in the Streamlines utility. When the parameter
       MSK has a non-zero value, masking is enabled and a previously created area map must be
       passed to STREAM. STREAM examines the map, returning an error if the map appears to be
       invalid or the number of area groups is beyond the range it can handle (currently 64).
       Otherwise, it only uses the map as an argument to the Areas utility subroutine, ARDRLN.
       The user must also pass in a user-definable masked drawing subroutine. A simple version of
       this subroutine, named (like the argument) STUMSL, is supplied with the Streamlines
       utility, and may suffice for basic masked drawing operations. See the stumsl man page for
       more information.

       The P array argument is intended for future enhancement of the Streamlines utility and is
       not currently used or examined in any way.  You may pass it an uninitialized dummy
       argument.

EXAMPLES

       Use the ncargex command to see the following relevant examples: ffex00, ffex01, ffex03,
       ffex04, fstream, stex01, stex02, stex03, stex03.

ACCESS

       To use STREAM or c_stream, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c,
       preferably in that order.

MESSAGES

       See the streamlines man page for a description of all Streamlines error messages and/or
       informational messages.

SEE ALSO

       Online: stgetc, stgeti, stgetr, stinit, streamlines, streamlines_params, strset, stsetc,
       stseti, stsetr, stuixy, stumsl, stumta, stumxy, ncarg_cbind.

       Hardcopy: NCAR Graphics Fundamentals, UNIX Version

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research
       The use of this Software is governed by a License Agreement.