GpiCorrelateFrom
This function performs a correlate operation on a section of the retained segment chain.
Syntax
GpiCorrelateFrom(hps, lFirstSegment, lLastSegment, lType, pptlPick, lMaxHits, lMaxDepth, plSegTag)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lFirstSegment (LONG) - input
- Specifies the first segment to be correlated.
- It must be greater than 0.
- lLastSegment (LONG) - input
- Specifies the last 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 centre of the pick aperture, in presentation page units.
- lMaxHits (LONG) - input
- Maximum hits.
- Maximum number of hits that can be returned to the plSegTag parameter. It must be greater than 0.
- lMaxDepth (LONG) - input
- Number of pairs.
- Number of segment and tag pairs to be returned by each hit. It must be greater than 0.
- plSegTag (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_SEG_NOT_CHAINED (0x20FF) An attempt was made to issue GpiDrawFrom, GpiCorrelateFrom or GpiQuerySegmentPriority for a segment that was not chained.
- PMERR_INV_SEG_NAME (0x20C8) An invalid segment identifier was specified.
Remarks
The correlation operation starts at the segment identified by lFirstSegment and includes chained and called segments up to, and including, the segment identified by lLastSegment.
Data is returned for each tagged primitive that intersects the pick aperture. The data returned for each "hit" (or correlation) consists of a set of segment and tag pairs, starting with the correlated one and followed by the one that called the segment. This is repeated until the root segment is reached or lMaxDepth values are returned.
Only primitives with a nonzero tag (see GpiSetTag) in segments with a nonzero identifier are correlated using this function. Primitives in segments called (to any depth in the hierarchy) from a segment 0 are not eligible for correlation.
The depth value specifies the number of sets of segment and tag pairs to be returned for each hit. If the root segment is reached before lMaxDepth values, the remaining values are set to zero. If more than lMaxDepth values are available, only that number is returned.
The number of hits that occurred is returned in lNumHits.
A "hit" is an instance of a segment identifier and tag pair for which the primitives lie completely or partially within the specified aperture. Two different primitives in the same segment might have the same tag, and would therefore produce the same hit. This is counted as a single hit; the hit is recorded only once in the plSegTag parameter returned. The lNumHits parameter, therefore, returns this distinct number of hits. Hits are returned in reverse order of their occurrence.
plSegTag is set to the hits that are found, up to the maximum defined in the lMaxHits parameter. Corresponding pairs of elements form the hit pairs. The number returned by the call therefore contains the number of sets of lMaxDepth pairs set if the lMaxHits parameter is greater than the number of hits detected. The number of elements set in the plSegTag parameter is twice the number returned by the function (subject to a maximum of lMaxHits) multiplied by the lMaxDepth.
If the lNumHits value returned by the function is greater than that specified in lMaxHits, more hits occurred than could be returned. If all hits are important, specify an array that is large enough to contain the maximum number of sets of hits that are expected.
The draw controls (see GpiSetDrawControl) are ignored by this call.
It may be necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the segments. This can be done either ensuring that the first segment to be correlated does not have the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), or by issuing GpiResetPS before the GpiCorrelateFrom. The latter method also resets the clip path to no clipping.
If this function is followed by primitives or attributes, without first opening a segment, the processing is as described for GpiCloseSegment.
If lFirstSegment does not exist, or is not in the segment chain, an error is raised. If lLastSegment does not exist, or is not in the chain, or is chained before lFirstSegment, no error is raised and processing continues to the end of the chain.
Example Code
This example uses GpiCorrelateFrom to correlate, using an aperture of default size and centred at (200,200), on visible and detectable segments within the given chain of 2 segments. It requests one intersection (or hit) and one segment/tag pair for that hit to be returned. The segments 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 lFirstSegment; /* Specifies the first 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 chain of two segments (1 and 2) */
lFirstSegment = 1;
lLastSegment = 2;
/* return only one hit */
lMaxHits = 1L;
/* return only one segment/tag pair per hit */
lMaxDepth = 1L;
/* correlate on visible, detectable segments */
lNumHits = GpiCorrelateFrom(hps, lFirstSegment, lLastSegment,
PICKSEL_VISIBLE, &pptlPick, lMaxHits,
lMaxDepth, &alSegTag);