NAME

cxPyrActive - flag as active/inactive the elements at a specified pyramid layer

C SPECIFICATION

#include <cx/Pyramid.h>

char *cxPyrActive(cxPyramid *pyr, long layer)

FORTRAN SPECIFICATION

integer function cxPyrActive( pyr, layer )
integer pyr
integer layer

PARAMETERS

pyr: Input pyramid structure for which computations are to be performed.
layer: Input layer of active elements (1-based value).

FUNCTION RETURN VALUE

Returns a pointer to a byte array indicating which elements are active in layer layer, given that all elements are active in the top layer. Returns a NULL if its input is malformed, if an allocation error occurs, or if the destination layer is in a compressed region. Returns a list of active vertices if layer is zero, even in the presence of compression.

DESCRIPTION

cxPyrActive computes which subordinate elements are active at the layer layer, assuming that all elements are active in the top layer of the pyramid. Position i of the returned byte array holds a 0 if element i of the layer is inactive, a 1 if the element is active and contained within only one parent element, or a 2 if the element is active and contained within more than one parent element.

cxPyrActive is useful in circumstances where only the active elements at a given level are to be manipulated. This is the approved way of determining the pyramid elements which should be manipulated or displayed in any pyramid-based module (the alternative method of displaying all elements available at a given level is not correct).

The returned indicator array is considered to be owned by the caller of cxPyrActive and should be freed (with free(3C)) after use.