Jump to content

GpiCorrelateSegment: Difference between revisions

From EDM2
← Older editNewer edit →
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Line 1: Line 1:
This function performs a correlate operation on a specified segment.  
This function performs a correlate operation on a specified segment.


==Syntax==
==Syntax==
<PRE>
  GpiCorrelateSegment(hps, lSegment, lType, pptlPick, lMaxHits, lMaxDepth, alSegTag)
#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);
</PRE>


==Parameters==
==Parameters==
;hps (HPS) - input : Presentation-space handle.
;hps (HPS) - input: Presentation-space handle.
;lSegment (LONG) - input : Identifier of the segment to be correlated.
;lSegment (LONG) - input: Identifier of the segment to be correlated.
:It must be greater than 0.
:It must be greater than 0.
;lType (LONG) - input : Type of segments on which correlation is to be performed.
;lType (LONG) - input: Type of segments on which correlation is to be performed.
:PICKSEL_VISIBLE
::PICKSEL_VISIBLE: Only visible and detectable segments with nonzero identifiers are correlated.
::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.
:PICKSEL_ALL
;pptlPick (PPOINTL) - input: Pick position.
::All segments with nonzero identifiers are correlated, regardless of the detectability and visibility attributes of the segments.
:The position of the center of the pick aperture, in presentation page units.
;pptlPick (PPOINTL) - input : Pick position.
;lMaxHits (LONG) - input: Maximum hits.
: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.
: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.
;lMaxDepth (LONG) - input: Number of pairs.
:Number of segment/tag pairs to be returned by each hit. It must be greater than 0.
:Number of segment/tag pairs to be returned by each hit. It must be greater than 0.
;alSegTag (PLONG) - output : Segment identifiers and tags.
;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.
: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==
==Return Code==
;lNumHits (LONG) - returns : Number of hits and error indicators.
;lNumHits (LONG) - returns : Number of hits and error indicators.
>=0                 Number of hits that occurred
::>=0 - Number of hits that occurred
GPI_ALTERROR       Error.
::GPI_ALTERROR - Error.


===Errors===
===Errors===
Line 47: Line 29:
;PMERR_INV_HPS (0x207F):An invalid presentation-space handle was specified.
;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_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_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_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_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_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_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_FOUND (0x2100):The specified segment identifier did not exist.
Line 56: Line 38:


==Example Code==
==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.
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''.
<PRE>
<PRE>
#define INCL_GPICORRELATION    /* GPI Correlation functions    */
#define INCL_GPICORRELATION    /* GPI Correlation functions    */

Revision as of 20:24, 2 March 2020

This function performs a correlate operation on a specified segment.

Syntax

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
Retrieved from "https://www.edm2.com/index.php?title=GpiCorrelateSegment&oldid=72370"