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.

UNIX                                               April 1993                                     STREAM(3NCARG)