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.

COPYRIGHT

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