char *cxPyrActivePrev(cxPyramid *pyr, long curLayer, long dstLayer, char *flg, cxPyrPrevType switch)
integer function cxPyrActivePrev( pyr, curLayer, dstLayer, flg, switch) integer pyr integer curLayer integer dstLayer character*1 flg(*) integer switch
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_orIf 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 = 4Given 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.
This routine is used extensively in the ClipPyr, CropPyr, and CullPyr modules. It could form the basis of any other pyramid module in which elements are kept or excluded on the basis of their constituent vertex locations or values.