GpiCorrelateSegment

This function performs a correlate operation on a specified segment.

Syntax

 * 1) define INCL_GPICORRELATION /* Or use INCL_GPI, INCL_PM, */
 * 2) include 

HPS       hps;        /*  Presentation-space handle. */ LONG      lSegment;   /*  Identifier of the segment to be correlated. */ LONG      lType;      /*  Type of segments on which correlation is to be performed. */ PPOINTL   pptlPick;   /*  Pick position. */ LONG      lMaxHits;   /*  Maximum hits. */ LONG      lMaxDepth;  /*  Number of pairs. */ PLONG     alSegTag;   /*  Segment identifiers and tags. */ LONG      lNumHits;   /*  Number of hits and error indicators. */

lNumHits = GpiCorrelateSegment(hps, lSegment,            lType, pptlPick, lMaxHits, lMaxDepth,             alSegTag); 

Parameters

 * hps (HPS) - input : Presentation-space handle.
 * lSegment (LONG) - input : Identifier of the segment to be correlated.
 * It must be greater than 0.


 * lType (LONG) - input : Type of segments on which correlation is to be performed.
 * PICKSEL_VISIBLE
 * Only visible and detectable segments with nonzero identifiers are correlated.
 * PICKSEL_ALL
 * All segments with nonzero identifiers are correlated, regardless of the detectability and visibility attributes of the segments.


 * pptlPick (PPOINTL) - input : Pick position.
 * The position of the center of the pick aperture, in presentation page units.


 * lMaxHits (LONG) - input : Maximum hits.
 * The maximum number of hits that can be returned in the alSegTag parameter. It must be greater than 0.


 * lMaxDepth (LONG) - input : Number of pairs.
 * Number of segment/tag pairs to be returned by each hit. It must be greater than 0.


 * alSegTag (PLONG) - output : Segment identifiers and tags.
 * An array consisting of segment identifiers and primitive tags in alternate elements. For each hit, a set of lMaxDepth segment identifiers and tag pairs is returned.

Return Code
>=0                Number of hits that occurred GPI_ALTERROR       Error.
 * lNumHits (LONG) - returns : Number of hits and error indicators.

Errors
Possible returns from WinGetLastError
 * PMERR_INV_HPS (0x207F):An invalid presentation-space handle was specified.
 * PMERR_PS_BUSY (0x20F4):An attempt was made to access the presentation space from more than one thread simultaneously.
 * PMERR_INV_CORRELATE_TYPE (0x205D):An invalid type parameter was specified with GpiCorrelateSegment, GpiCorrelateFrom, or GpiCorrelateChain.
 * PMERR_INV_COORDINATE (0x205B):An invalid coordinate value was specified.
 * PMERR_INV_MAX_HITS (0x209C):An invalid maxhits parameter was specified with GpiCorrelateSegment, GpiCorrelateFrom, or GpiCorrelateChain.
 * PMERR_INV_CORRELATE_DEPTH (0x205C):An invalid maxdepth parameter was specified with GpiCorrelateSegment, GpiCorrelateFrom, or GpiCorrelateChain.
 * PMERR_INV_MICROPS_FUNCTION (0x20A1):An attempt was made to issue a function that is invalid in a micro presentation space.
 * PMERR_SEG_NOT_FOUND (0x2100):The specified segment identifier did not exist.
 * PMERR_INV_SEG_NAME (0x20C8):An invalid segment identifier was specified.

Example Code
This example uses GpiCorrelateSegment to correlate, using an aperture of default size and centered at (200,200), on a visible and detectable segment and requests one intersection (or hit) and one segment/tag pair for that hit to be returned. The segment will have been previously defined and created using GpiSetInitialSegmentAttrs and GpiOpenSegment/GpiCloseSegment. 
 * 1) define INCL_GPICORRELATION    /* GPI Correlation functions    */
 * 2) include 

BOOL    fSuccess;      /* success indicator                    */ SIZEL   psizlSize;     /* size of pick aperture                */ LONG    lNumHits;      /* number of hits or error              */ HPS     hps;           /* Presentation-space handle            */ LONG    lSegment;      /* segment to be correlated             */ LONG    lLastSegment;  /* Specifies the last segment to be                           correlated                           */ POINTL  pptlPick = {200L,200L}; /* Pick (center of aperture) position  */ LONG    lMaxHits;      /* Maximum hits to be returned          */ LONG    lMaxDepth;     /* Number of pairs to be returned       */ LONG    alSegTag;      /* Segment identifiers and tags         */

fSuccess = GpiSetPickAperturePosition(hps, &pptlPick);

/* set aperture size (use default) */ fSuccess = GpiSetPickApertureSize(hps, PICKAP_DEFAULT, &psizlSize);

/* define segment */ lSegment = 1;

/* return only one hit */ lMaxHits = 1L;

/* return only one segment/tag pair per hit */ lMaxDepth = 1L;

/* correlate on visible, detectable segments */ lNumHits = GpiCorrelateSegment(hps, lSegment, PICKSEL_VISIBLE,                              &pptlPick, lMaxHits, lMaxDepth,                               &alSegTag); 

Related Functions

 * GpiCallSegmentMatrix
 * GpiCloseSegment
 * GpiCorrelateChain
 * GpiCorrelateFrom
 * GpiDeleteSegment
 * GpiDeleteSegments
 * GpiDrawSegment
 * GpiErrorSegmentData
 * GpiOpenSegment
 * GpiQueryInitialSegmentAttrs
 * GpiQuerySegmentAttrs
 * GpiQuerySegmentNames
 * GpiQuerySegmentPriority
 * GpiSetDrawControl
 * GpiSetInitialSegmentAttrs
 * GpiSetPickAperturePosition
 * GpiSetPickApertureSize
 * GpiSetSegmentAttrs
 * GpiSetSegmentPriority