GpiCorrelateSegment

This function performs a correlate operation on a specified segment.

Syntax

#define INCL_GPICORRELATION /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

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

lNumHits (LONG) - returns: Number of hits and error indicators.

>=0                 Number of hits that occurred
GPI_ALTERROR        Error.

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.

#define INCL_GPICORRELATION     /* GPI Correlation functions    */
#include <os2.h>

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