NAME

cxPyrActivePrev - flag as active/inactive the elements at the next higher pyramid layer

C SPECIFICATION

#include <cx/Pyramid.h>

char *cxPyrActivePrev(cxPyramid *pyr, long curLayer, long dstLayer,
                      char *flg, cxPyrPrevType switch)

FORTRAN SPECIFICATION

integer function cxPyrActivePrev( pyr, curLayer, dstLayer, flg, switch)
integer pyr
integer curLayer
integer dstLayer
character*1 flg(*)
integer switch

PARAMETERS

pyr: Input pyramid structure for which computations are to be performed.
curLayer: Input layer of currently active elements (1-based value).
dstLayer: Input layer of next active elements (1-based value).
flg: Input byte array indicating which elements are currently active in layer curLayer.
switch: Input selection of how to compute active status of an element from its connections.

FUNCTION RETURN VALUE

Returns a pointer to a byte array indicating (with non-zero value) which elements are active in layer dstLayer, given that the flg elements are active in layer curLayer. Returns a NULL if its input is malformed, if an allocation error occurs, or if the destination layer is in a compressed region.

DESCRIPTION

cxPyrActivePrev accepts a byte vector of indicators showing which elements are active in the pyramid pyr at a given layer, and from this information computes which predecessor elements are active at the higher layer dstLayer. If dstLayer is less than curLayer, the routine returns a NULL pointer.

An element at the higher level may be considered active if any or all of the flg entries are non-zero, if the bitwise and or or of the flg entries are non-zero, or if the flg entries indicate a plane-crossing, depending on the value of the switch argument.

Position i of the returned byte array holds the result of the computation specified in switch, which may be a Boolean operand (0 or 1), a bitwise operand (a char containing 0s and 1s), or a plane-crossing operand.

The switch argument may take as its value one of the cxPyrPrevType enumerated values, which are defined as

	cx_pyramid_prev_logical_and
	cx_pyramid_prev_logical_or
	cx_pyramid_prev_identical_on
	cx_pyramid_prev_intersect
	cx_pyramid_prev_bitwise_and
	cx_pyramid_prev_bitwise_or

If switch is one of the logical (Boolean) or bitwise enumerations, the ith byte in the output vector gives the result of the respective computation over all flg entries comprising the ith element. For instance, if element i at dstLayer refers to elements j, k, and l at curLayer and if switch has value cx_pyramid_prev_logical_or, then the ith output byte is non-zero if any of flg[j], flg[k], or flg[l] is non-zero.

The remaining two enumerations are used to detect plane crossings within a pyramid. These operations make use of the auxilliary macro definitions

	PLANE_FALSE     = 0
	PLANE_ON        = 1
	PLANE_PLUS      = 2
	PLANE_MINUS     = 4

Given flg inputs within this set and a switch of cx_pyramid_prev_identical_on, an element at the next higher layer is given the flag PLANE_TRUE if all of its subordinate elements are flagged as PLANE_PLUS or PLANE_ON, or if all of its subordinate elements are flagged as PLANE_MINUS or PLANE_ON. Otherwise, an element at the next higher layer is given the flag PLANE_FALSE, which indicates that some of its subordinate elements are flagged as PLANE_FALSE or that its subordinate elements contain both PLANE_PLUS and PLANE_MINUS flags.

Given flg inputs within this set and a switch of cx_pyramid_prev_intersect, an element at the next higher layer is given the flag PLANE_FALSE if any of its subordinate elements is flagged as PLANE_FALSE, if all of its subordinate elements are flagged as PLANE_PLUS, or if all of its subordinate elements are flagged as PLANE_MINUS. Otherwise, an element at the next higher layer is given the flag PLANE_ON, which indicates that some of its subordinate elements are flagged as PLANE_ON or that its subordinate elements contain both PLANE_PLUS and PLANE_MINUS flags.

cxPyrActivePrev is useful in circumstances where a subset of the elements at a given level are to be manipulated, and the caller wishes to identify their containing elements to manipulate at a higher level. This is the approved way of determining which pyramid elements should be manipulated or displayed in any pyramid-based module (the alternative method of displaying all elements available at a given level may not be correct).

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