At various times GINO needs to store information in memory. Normally these are of a known size and can therefore be declared internally as arrays.

However, there are facilities in GINO which possibly require large amounts of memory depending on the complexity of the users application. In such cases it is not sensible for GINO to pre-assign space as it is impossible to predict the requirement. These areas include polygon storage, area filling, internal point storage and the software display file.

GINO therefore provides a mechanism for the user to allocate a single block of memory for such purposes of a size defined by the user as required by the application. In fact such an area MUST be allocated by the user if these facilities are being used by an application program. GINO then provides a handler to manage this area, allocating a smaller amount of memory as and when required.

However, it should be noted that the mechanism for allocating this workspace differs in each of the C/C++ and Fortran 90 versions of GINO as described below.

Management of Workspace Area

While the same routine gSetWorkspaceLimit() is used to allocate the size of the workspace area in both the C/C++ and Fortran 90 versions of the GINO library, the location of the storage area and the number of arguments to this routine differ.

gSetWorkspaceLimit(n1[,n2])

In the C/C++ library the workspace area is allocated via the standard library routine malloc when gSetWorkspaceLimit() is called. The routine therefore only requires a single argument giving the total memory requirement for the workspace area:

gSetWorkspaceLimit(n1);

where n1 is the required size of the total workspace area.

In the Fortran 90 library the workspace area is allocated in an allocatable real array. For historical reasons, two arguments are required, but only the second is used:

call gSetWorkspaceLimit(n1, n2)

where n1 is ignored and n2 is the number of real words required in the workspace area.

It is important to free (deallocate) this memory at the end of an application but this is automatically achieved through the GINO routine gCloseGino().

Allocation of Workspace Area

For example:

[C/C++]
#include <gino-c.h>
main ()
{
/*  Initialize GINO */
     gOpenGino();
     .
     .
/*  Define workspace area */
     gSetWorkspaceLimit(6000);
     .
     .
/*  Free allocated workspace */
     gCloseGino();
}

[F90]
program work
use gino_f90

!  Initialize GINO 
     call gOpenGino
     .
     .
!  Define workspace area
     call gSetWorkspaceLimit(1,6000)
     .
     .
!  Free allocated workspace
     call gCloseGino
stop

would define a workspace area of 6000 words.

As only a single block of memory can be allocated for the workspace area, its total estimated size must be calculated before allocating the space. This can be achieved through studying the following sections.

The space within gSetWorkspaceLimit() is used for a number of different purposes and is allocated in continuous blocks as required and for as long as required. Three routines are provided to the user for specific allocation of space for polygon storage (gDefinePolygonWorkspace()), for internal point storage (gDefinePointWorkspace()) and for the software display file (gDefineSegWorkspace()) if this is required in memory. Other areas are allocated and returned internally by GINO for temporary workspace for area filling.

The workspace handler does its addressing and word counting in real words. The workspace area must be large enough for all the concurrent workspace needs of a given program. For example, an application where polygons will be stored, a software display file used and area filled, might have a workspace area which would appear as shown below.

Example Organisation of the Workspace Area

The total size of the workspace area depends upon the individual workspace needs found by consulting the sections given in the table below.

Space

Reference Section

Polygon Workspace

ADVANCED USE OF POLYGONS

Polygon List

ADVANCED USE OF POLYGONS

Polygonal Area Filling

ADVANCED USE OF POLYGONS

Software/Hardware Area Fill

ADVANCED USE OF POLYGONS

Polygonal Windowing / Masking

ADVANCED USE OF POLYGONS

Segment Workspace

SEGMENTS

Internal Point Storage Workspace

2D and 3D DRAWING

Areas allocated within gSetWorkspaceLimit() may be returned to the workspace by calling the appropriate routine gDefinePolygonWorkspace() or gDefineSegWorkspace() with an argument of 0.

The workspace area may be enlarged during an application program by calling gSetWorkspaceLimit() with a larger size. (i.e. no information is ever moved within the workspace). The workspace area cannot be reduced except by freeing the total area (in which case all information stored within it is lost) and allocating a smaller area.

Any workspace that has been allocated will be freed when GINO is closed through gCloseGino().

Enquiring about the Workspace Area

The routine gEnqWorkspaceLimit() may be called to enquire about the workspace area:

gEnqWorkspaceLimit(n [,n2])

Where n (and n2 in Fortran 90) returns the size of the workspace area as defined by the last call to gSetWorkspaceLimit(). If gSetWorkspaceLimit() has not been called, this routine returns zero in its arguments(s).

---