NCL Home > Documentation > HLUs > User Guide

Mixing HLUs and LLUs

Some of the utilities of Version 3.2 have not yet been converted to HLUs (missing are histograms, 3-D wireframe surfaces and isosurfaces, weather maps, and polypack). Moreover, the wide range of flexibility available at the low level can never be fully implemented in a high level interface.

Thus, there may be situations for some time in which you will want to directly call routines in the low level libraries. Consequently, it is important to learn how to mix LLU calls with HLUs in an HLU program.

Some major considerations are:

In a C program, you need to include the GKS library and the LLU C-binding library.
```
#include <ncarg/gks.h>
#include <ncarg/ncargC.h>
```
These libraries are automatically loaded for Fortran programs.

The GKS output connection for low level output and HLU output must be the same.

To accomplish this, you must retrieve the workstation id used by the HLU program and assign it to the LLU workstation. In Fortran, the calls would look like this:

C
C Activate the GKS workstation using the HLU workstation id, gkswid.
C
      call NhlFRLClear(grlist)
      call NhlFRLGetinteger(grlist,'wkGksWorkId',gkswid,ierr)
      call NhlFGetValues(wid,grlist,ierr)
      call gacwk(gkswid)

Then issue the LLU calls you want to make. Then deactivate the GKS workstation with the call:

      call gdawk(gkswid)

In a C program, these calls would look like:

/*
 * Activate the GKS workstation using the HLU workstation id, gkswid.
 */
    NhlRLClear(grlist);
    NhlRLGetInteger(grlist,NhlNwkGksWorkId,&gkswid);
    NhlGetValues(wid,grlist);
    gactivate_ws(gkswid);

/*
 *  Add your LLU codes here.
 */

    gdeactivate_ws(gkswid);

The viewport and transformations must be synchronized.

In example cn11f.f (which you can copy into your local directory and execute using ng4ex), a call is made to the LLU contouring utility Conpack. The viewport and transformation are set with a call to the LLU set routine. The code is:

C     
C  The following are calls to the low level ncar graphics library to
C  draw labeled contour lines
C  
      call gacwk(gkswid)
      call cpseti('set',0)
      call cpsetr('xc1',-90.0)
      call cpsetr('xcm',90.0)
      call cpsetr('yc1',0.0)
      call cpsetr('ycn',9.0)
      call cpsetr('cis',5.0)
      call cpsetr('dps',.02)
      call cpseti('lis',2)
C  
C  Note that y axis user coordinates are set to grid coordinates 
C  rather than data coordinates. this is done because the input 
C  data is irregularly spaced in the y direction. This 'tricks'
C  Conpack into thinking the grid points are evenly spaced.
C  
      call set(0.2,0.8,0.2,0.8,-90.0,90.0,0.0,9.0,1)
      call cprect(t,73,73,10,rwrk,5000,iwrk,1000)
      call cpcldr(t,rwrk,iwrk)
      call gdawk(gkswid)
C  
C  End of NCAR Graphics section. Note deactivation of gks workstation
C

You can retrieve and execute the equivalent C example by issuing the command ng4ex cn11c.

Watch out for automatic frame advances in the LLUs.
Some LLU codes automatically advance the frame before returning. In such cases, you will want to issue an HLU draw before the LLU call.

Mixing HLUs and LLUs

See also: