Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPICORRELATION
 
LONG GpiCorrelateSegment(hps, idSegment, lType, pptl, lMaxHits,
    lMaxDepth, alSegTag)
HPS hps;           /* presentation-space handle                       */
LONG idSegment;    /* segment to correlate                            */
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 GpiCorrelateSegment function correlates the specified segment,
identifying each tagged primitive that intersects the current aperture, as
set by the GpiSetPickApertureSize function.
 
The GpiCorrelateSegment function correlates a segment by searching for each
tagged primitive in the 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. The function also searches segments that are
called by the specified segment. After searching all segments,
GpiCorrelateSegment returns the number of hits it located.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idSegment  Specifies the segment to correlate. This value must be greater
           than zero.
 
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.
 
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_INV_SEG_NAME
     PMERR_PATH_INCOMPLETE
     PMERR_PS_BUSY
     PMERR_SEG_NOT_FOUND
 
Comments
 
GpiCorrelateSegment 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 records 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 subsequently called segments 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
 
GpiCorrelateChain, GpiCorrelateFrom, WinGetLastError, POINTL
 
                                      ♦