◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPICORRELATION
 
LONG GpiCorrelateChain(hps, lType, pptl, lMaxHits, lMaxDepth, alSegTag)
HPS hps;           /* presentation-space handle                       */
LONG lType;        /* segment type                                    */
PPOINTL pptl;      /* address of structure for aperture center        */
LONG lMaxHits;     /* maximum number of hits                          */
LONG lMaxDepth;    /* maximum number of segment/tag pairs to return   */
PLONG alSegTag;    /* address of array of segment and tag identifiers */
 
The GpiCorrelateChain function correlates the segment chain, identifying
each tagged primitive that intersects the current aperture, as set by the
GpiSetPickApertureSize function.
 
The GpiCorrelateChain function correlates a segment chain by searching for
each tagged primitive in each segment that lies completely or partially
within the aperture. Each instance of a tagged primitive in the aperture is
called a "hit." The function records a hit by copying the identifier of the
segment containing the primitive (along with the identifier for its tag) to
the array pointed to by alSegTag. After searching all segments in the chain,
GpiCorrelateChain returns the number of hits it located.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
lType      Specifies the type of segment to correlate. It can be one of the
           following values:
 
           Value            Meaning
           ─────────────────────────────────────────────────────────────────
           PICKSEL_ALL      Correlate all segments with nonzero identifiers
                            regardless of the detectability and visibility
                            attributes of the segments.
 
           PICKSEL_VISIBLE  Correlate visible and detectable segments with
                            nonzero identifiers.
 
pptl       Points to the POINTL structure that contains the position (in
           presentation page units) of the center of the aperture.
 
lMaxHits   Specifies the maximum number of hits to record.
 
lMaxDepth  Specifies the maximum number of segment/tag pairs to record for
           each hit.
 
alSegTag   Points to the array to receive the segment/tag pairs. The array
           must be large enough to receive 8 * lMaxHits * lMaxDepth bytes.
 
Return Value
 
The return value is the number of hits that occurred if the function is
successful or GPI_ERROR if an error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_AREA_INCOMPLETE
     PMERR_IMAGE_INCOMPLETE
     PMERR_INV_COORDINATE
     PMERR_INV_CORRELATE_DEPTH
     PMERR_INV_CORRELATE_TYPE
     PMERR_INV_CTYPE
     PMERR_INV_HPS
     PMERR_INV_MAX_HITS
     PMERR_INV_MICROPS_FUNCTION
     PMERR_INV_PICK_APERTURE_POSN
     PMERR_PATH_INCOMPLETE
     PMERR_PS_BUSY
 
Comments
 
GpiCorrelateChain may record more than one segment for each hit. It first
records the segment containing the hit, then the segment that called the
first segment, and so on until the function either records the original
segment in this chain or has recorded lMaxDepth segments. If the function
finds less than lMaxDepth segments for the hit, the function records zeros
so that exactly lMaxDepth records are copied for each hit. The function
records all hits up to lMaxHits, then continues to count the hits even
though it no longer records them. The return value specifies the complete
number of hits, not just those recorded.
 
The function searches only segments that have nonzero identifiers. If the
function encounters a segment with a zero identifier, it stops the search
even if subsequent segments in the chain have nonzero identifiers. During
the search, the function ignores primitives that do not have nonzero
identifiers. The function never records more than one hit for a tag in a
segment even if that tag is used with many primitives.
 
See Also
 
GpiCorrelateFrom, GpiCorrelateSegment, GpiSetPickApertureSize,
WinGetLastError, POINTL
 
                                      ♦