View source for GpiCorrelateChain

This function performs a correlate operation on the retained segment chain. It returns data for each tagged primitive that intersects the current aperture, as set by GpiSetPickApertureSize.

==Syntax==
 GpiCorrelateChain(hps, lType, pptlPick, lMaxHits, lMaxDepth, pl2)

==Parameters==
;hps ([[HPS]]) - input : Presentation-space handle.
;lType ([[LONG]]) - input : Segment type.
:Type of segment 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.
:Maximum number of hits that can be returned in the pl2 parameter. It must be greater or equal to 0.
;lMaxDepth (LONG) - input : Number of pairs.
:Number of segment and tag pairs to be returned by each hit. It must be greater or equal to 0.
;pl2 ([[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_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_INV_CORRELATE_TYPE (0x205D) An invalid type parameter was specified with GpiCorrelateSegment, GpiCorrelateFrom, or GpiCorrelateChain.

==Remarks==
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 that segment. This is repeated until either the root segment is reached or lMaxDepth segment and tag pairs are returned.

Only primitives with a nonzero tag in segments with a nonzero identifier are correlated using this function. Primitives in segments called (to any depth in the hierarchy) from an unnamed segment 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 pl2 parameter returned. The lNumHits parameter, therefore, returns this distinct number of hits. Hits are returned in the reverse order of their occurrence.

pl2 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 function, 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 pl2 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 function.

It may be necessary to ensure that attributes, model transform, current position, and viewing limits are reset to their default values, before processing the chain. This can be done by either ensuring that the first segment to be correlated does not have the ATTR_FASTCHAIN attribute (see GpiSetInitialSegmentAttrs), or by issuing GpiResetPS before the GpiCorrelateChain. 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.

Examples
<PRE>
Start segment 1
  Tag 10
  Call 2
End segment 1

Start segment 2
  Tag 20                      Pick Aperture
  Call 3
  Tag 21                    ┌───────────────┐
  ......        ───────────────Hit 1        │
  ......                    │               │
End segment 2               │               │
                            │               │
Start segment 3             │               │
  Tag 30                    │               │
  ......        ───────────────Hit 2        │
  ......                    ────────────────┘
End segment 3

For lMaxHits = 1 at lMaxDepth = 2:

segment        tag
   2            21
   1            10

Returned lNumHits = 2.

For lMaxHits = 2 at lMaxDepth = 4:

segment        tag
   2            21       hit1.1
   1            10       hit1.2
   0            0        hit1.3
   0            0        hit1.4
   3            30       hit2.1
   2            20       hit2.2
   1            10       hit2.3
   0            0        hit2.4

Returned lNumHits = 2. 
</PRE>

==Example Code==
This example uses GpiCorrelateChain to correlate, using an aperture of default size and centered at (200,200), on visible and detectable segments and 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.
<PRE>
#define INCL_GPICORRELATION     /* GPI Correlation functions    */
#include <os2.h>

BOOL     fSuccess;      /* success indicator                    */
SIZEL    psizlSize={0L,0L}; /* size of pick aperture            */
LONG     lNumHits;      /* number of hits or error              */
HPS      hps;           /* Presentation-space handle            */
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);

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

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

/* correlate on visible, detectable segment chains */
lNumHits = GpiCorrelateChain(hps, PICKSEL_VISIBLE, &pptlPick, lMaxHits,
                                   lMaxDepth, &alSegTag);
</PRE>

==Related Functions==
*[[GpiCorrelateFrom]]
*[[GpiCorrelateSegment]]
*[[GpiSetDrawControl]]
*[[GpiSetPickAperturePosition]]
*[[GpiSetPickApertureSize]]

[[Category:Gpi]]