Correlating Nonretained Graphics

For the purposes of correlation, nonretained graphics are those graphics that are being correlated during the drawing process. Nonretained graphics can exist in nonretained graphic segments or completely outside any segment structure. Primitives outside segments are detectable when the applicable draw control is set.

Nonretained graphics, inside a segment bracket, can be created in either draw or draw-and-retain modes. If created in draw-and-retain mode, a segment, at first, is considered nonretained while the primitives in the segment are being drawn; then it is considered retained. To be correlated, nonretained segments must have unique, nonzero identifiers, and must be defined as detectable. The primitives within these segments can be tagged just as primitives in retained segments are. However, the tags do not influence the correlation process for nonretained graphics.

To get correlation data from the drawing of nonretained graphics, three steps must be performed- after creation of the presentation space but before drawing the primitives:

Call GpiSetDrawControl to switch on the correlation flag (DCTL_CORRELATE, DCTL_ON).
Call GpiSetPickApertureSize, if necessary, to change the size of the pick aperture.
Call GpiSetPickAperturePosition, if necessary, to explicitly position the aperture. As input to this function, you provide the coordinate position on which the pick aperture is to be centered, using presentation page coordinates.

Correlation is performed for the following functions:

Individual primitive-drawing requests, for example, GpiBox
Correlation is never performed for GpiErase
You detect correlation hits by examining the returned values from the GPI functions. If GpiLine, for example, draws a line that intersects the pick aperture, it returns a value of GPI_HITS to indicate a correlation hit. If the line does not intersect the pick aperture, GpiLine returns a value of GPI_OK, to indicate the successful drawing of a line without a correlation hit. GpiLine returns a value of GPI_ERROR if an error is detected.
If the line intersects the pick aperture, a correlation hit is returned even if the line style is LINETYPE_INVISIBLE. For other primitives, if the object is drawn in outline mode, a correlation hit is returned only if the pick aperture intersects the boundary. If the object is in fill mode, a correlation hit is returned if the pick aperture intersects or lies within the boundary.
The following figure is an example of primitives intersecting the pick aperture.
Correlating Nonretained Graphics
Each GPI function whose output intersects the pick aperture returns a hit (GPI_HIT). GpiBox, whose output does not intersect the pick aperture, returns GPI_OK.

[Back: About Correlation]
[Next: Correlating Retained Graphics]