GPIGuide - Clipping and Boundary Determination

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

GPI Guide and Reference

How to Use the GPI Guide and Reference Graphics Functions Data Types Graphics Orders Graphics Orders Data Types Errors Area and Polygon Primitives Bit Maps Creating and Drawing Retained Graphics Character String Primitives Clipping and Boundary Determination Color and Mix Attributes Correlation Coordinate Spaces and Transformations Editing Retained Graphics and Graphics Segments Fonts Graphics Attributes Line and Arc Primitives Marker Primitives Matrix Multiplication Metafiles Print Job Submission and Manipulation Presentation Spaces and Device Contexts Paths Regions Notices Glossary

Clipping and boundary determination are graphics operations that limit the amount of graphics information transferred between coordinate spaces. Related topics include:

• Presentation spaces and device contexts
• Coordinate spaces and transformations
• Regions
• Paths

About Clipping

Clipping allows the Presentation Manager (PM) to discard parts of a picture outside a specified clipping boundary. The enclosed parts form the clipping area, which can be a single rectangle or a complex shape depending on the definition method.

Note: In this context, area refers to the shape used for clipping, not an area primitive.

If an application draws outside the clipping area, the operating system ensures the output does not appear on the drawing surface. For example, a triangular clipping area would discard text outside the triangle, even if a full page of text is defined (see img34.bmp: Triangular Clip Path).

Clipping boundaries are application-defined. The PM automatically clips graphics to fit client window areas or hardcopy device output areas.

Types of Clipping Areas

The PM assembles graphics output through up to five coordinate spaces in the viewing pipeline. Clipping can occur at each stage, affecting objects in world, model, page, or device spaces. Multiple clipping areas across spaces combine into a single area defined by their intersection. Clipping is performed in one operation in device space.

The following table summarizes clipping areas and their coordinate spaces:

Clipping Areas and Coordinate Space Summary

Clipping Area	Coordinate Space	Description
Clip path	World space	Always inclusive/inclusive Clipping area can have curved edges Clipping area can be rotated.
Viewing limit	Model space	Always a rectangular clipping boundary Always inclusive/inclusive Rotating results in larger rectangle.
Graphics field	Page space	Always a rectangular clipping boundary Always inclusive/inclusive Rotation impossible. Cannot specify device transform with rotation.
Clip region	Device space	Can be a single or multiple rectangles (overlapping or separate) Always inclusive/exclusive Rotation impossible.

Note: Inclusive/inclusive includes the bottom, left, top, and right edges of the rectangle in the clipping area. Inclusive/exclusive includes the bottom and left edges but excludes the top and right edges (see img35.bmp: Inclusive/Inclusive and Inclusive/Exclusive Clipping).

The Clip Path

The clip path defines the clipping boundary in world coordinate space. Paths, described in Paths, serve multiple purposes, including clipping. The recommended sequence for creating a clip path is:

• GpiBeginPath: Begins the path definition.
• Line and arc GPIs: Define the path shape.
• GpiEndPath: Ends the path definition.
• GpiModifyPath: Optional modification (see below).
• GpiSetClipPath: Converts the path to a clip path.

Before conversion, GpiModifyPath can convert the path to a geometric (wide) line using current geometric width, line join, and line end attributes, defining the clip path’s shape. GpiSetClipPath accepts two path identifiers:

• 1SCP_RESET (default): Resets the clip path to infinity (no clipping), discarding the current definition.
• 0SCP_AND: Redefines the clip path as the intersection of the stored and current path definitions.

To set the clip path to the current path after a previous GpiSetClipPath call, use SCP_RESET followed by SCP_AND. For example, a triangle defined as a clip path clips a subsequently drawn filled box to the triangle (see img36.bmp: The Clipping Path).

Clip paths are ideal for irregular or integral clipping boundaries. GpiSetClipPath also accepts construction options:

• SCP_ALTERNATE (default)
• SCP_WINDING (required if path modified)

Drawing clipped to the clip path follows alternate or winding rules (see Paths in Alternate Mode and Paths in Winding Mode). Boundary points are considered within the path and not clipped. To end clipping, call GpiSetClipPath with identifier 0 to set the clip path to infinity. Clip paths may be deselected automatically in some cases.

Clip path definitions can be stored in retained segments and recreated when redrawn. In DM_DRAWANDRETAIN mode, the clip path is created during segment construction; in DM_RETAIN mode, it is created when the segment is first drawn.

The Viewing Window

The viewing window defines a rectangular clipping boundary in model space, set with GpiSetViewingLimits, using model coordinates for the lower-left and upper-right corners. Primitives outside the window are clipped, while boundary points are included. By default, the viewing window performs no clipping, transforming all model space output (see img37.bmp: The Viewing Window).

For example, a viewing window outlining an aircraft’s tail in model space clips the rest of the aircraft during transformation to presentation-page space.

The Graphics Field

The graphics field defines a rectangular clipping area in the presentation page, set with GpiSetGraphicsField before drawing begins. Specify its size in presentation page coordinates. Only output within the graphics field is visible in device space. By default, it is infinitely large (no clipping). Boundary points are included, and primitives outside are clipped (see img38.bmp: The Graphics Field).

For example, an aircraft tail outside a smaller graphics field is clipped. The graphics field’s picture is displayed or printed; without a defined field, the entire presentation page is used, potentially showing graphics outside its boundary.

The Current Clipping Region

Clipping regions are defined in device coordinates as one or more rectangles, avoiding rounding errors, making them ideal for redrawing parts of a picture (e.g., after scrolling with BitBlt). Select a region as the clipping region with GpiSetClipRegion. By default, the clipping region matches the drawing surface’s size. Only one clipping region exists at a time. Deselect it with a NULL region handle, retaining prior changes for reselection (see img39.bmp: Screen Repairing).

Selecting a new clipping region replaces the previous one, reverting it to a normal region with its handle returned. Clip regions are faster to create than clip paths, aiding performance in screen repairs. GpiSetClipRegion does not add graphics orders to segments, so clip region variations must not construct the picture.

Region-related GPI functions are unavailable for the clipping region. Instead, use functions operating in world coordinates, subject to transformations:

• GpiQueryClipBox: Returns the smallest rectangle enclosing all clipping boundaries (clip path, viewing window, graphics field, clipping region, and visible window region).
• GpiIntersectClipRectangle: Redefines the clipping region to its intersection with a specified rectangle (similar to CRGN_AND in GpiCombineRegion).
• GpiExcludeClipRectangle: Excludes a rectangle from the clipping region (similar to CRGN_DIFF in GpiCombineRegion).
• GpiOffsetClipRegion: Moves the clipping region.
• GpiPtVisible: Checks if a world-coordinate point is visible within all clipping boundaries and the window’s visible region.
• GpiRectVisible: Checks if a world-coordinate rectangle intersects all clipping boundaries and the window’s visible region.

How Clipping Is Implemented

The PM implements clipping with these rules:

• Primitives completely outside the clipping boundary are discarded.
• Primitives crossing a boundary have outside parts discarded and inside parts retained.
• For clip paths, viewing windows, or graphics fields, boundary points are included.
• For clipping regions, top or right boundary points are discarded; bottom or left boundary points (not also on top or right) are included.

Redrawing Nondynamic Graphics

Interactive graphics applications allow picture changes, often using dynamic segments (see Editing Retained Graphics and Graphics Segments). For nonretained graphics, repair the picture using a clipping region. For example, moving a circle in a picture with a hexagon (see img40.bmp: A Hexagon and Circle) involves:

1. Determine the smallest rectangle containing the circle in its current position using boundary determination. 2. Disable DCTL_DISPLAY in GpiSetDrawControl, apply a translation, and redraw the circle in its new position. 3. Determine the smallest rectangle for the new position. 4. Convert model-space coordinates to device-space using GpiConvert. 5. Create a region from the two rectangles’ device-space coordinates and select it as the clipping region. 6. Enable DCTL_DISPLAY in GpiSetDrawControl. 7. Call GpiErase (or set erase-before-draw) to clear the clipping region. 8. Redraw the picture with the circle in its new position, affecting only the clipping region (see img41.bmp: Defining a Clipping Region).

The hexagon outside the clipping region remains unaffected.

About Boundary Determination

Boundary determination computes the smallest rectangle enclosing a graphics output in model space, useful for repairing affected screen parts when objects move or change. Dynamic segments are excluded. Enable boundary data collection by setting the DCTL_BOUNDARY flag in GpiSetDrawControl. If not set and needed later:

1. Enable DCTL_BOUNDARY and disable the display flag in GpiSetDrawControl. 2. Redraw the object to collect boundary data without altering it.

For retained graphics, boundary data is available after each GpiDrawSegment, GpiDrawFrom, or GpiDrawChain call, requested via GpiQueryDeviceBitmapFormats. Data is reset before each operation.

For nonretained graphics, boundary data accumulates for each GpiPutData or primitive drawing function, retrievable with GpiQueryBoundaryData. Data persists until reset with GpiResetBoundaryData.

Boundary data returns four model-space coordinates: the lowest and highest (x,y) positions of the bounding rectangle (see img42.bmp: The Bounding Rectangle).

Using Clipping and Boundary Determination

This section covers using clipping functions to:

• Create a clip path or clip region
• Exclude a rectangular area from a clip region
• Add a rectangular area to a clip region
• Set the clip region to an intersection with a rectangle
• Determine the smallest rectangle surrounding all clipping areas

Creating a Clip Path

For curved clipping edges in CAD applications, use a clip path in world coordinates. Due to high memory and processing costs, prefer clip regions, graphics fields, or viewing limits when possible. Steps:

1. Determine the clip path’s shape and size in world coordinates. 2. Call GpiBeginPath to start the path definition. 3. Create the path. 4. Close the path with GpiEndPath. 5. Convert to a clip path with GpiSetClipPath.

Example creating an elliptical clip path:

#define INCL_GPIPATHS
#include <os2.h>
void fncCLIP01(void) {
    HPS hps; /* Presentation-space handle */
    POINTL ptl1; /* Point structure */
    FIXED fxArc; /* Multiplier for arc */
    LONG idPath; /* Path identifier */
    /* Load ptl1 with coordinates of clip path. */
    idPath = 1;
    GpiBeginPath(hps, idPath); /* Begins path */
    GpiMove(hps, &ptl1); /* Sets current position */
    fxArc = MAKEFIXED(50, 0); /* Sets arc multiplier */
    GpiFullArc(hps, DRO_OUTLINE, fxArc); /* Defines ellipse */
    GpiEndPath(hps); /* Ends path */
    GpiSetClipPath(hps, idPath, SCP_ALTERNATE | SCP_AND);
} /* fncCLIP01 */

Creating a Clip Region

Determine the clip region’s size and shape in device coordinates, load rectangle coordinates into an array of RECTL structures, create the region with GpiCreateRegion, and set it as a clip region with GpiSetClipRegion.

Example:

#include <os2.h>
void fncCLIP02(void) {
    HPS hps;
    HRGN hrgn;
    RECTL arcl[3];
    /* Load array of RECTL structures with coordinates. */
    hrgn = GpiCreateRegion(hps, sizeof(arcl) / sizeof(RECTL), arcl);
    GpiSetClipRegion(hps, hrgn, NULL);
} /* fncCLIP02 */

Excluding a Rectangular Area from a Clip Region

To protect existing output in multi-stage applications (e.g., word processing with added bitmaps), exclude an area from a clip region. Determine the smallest rectangle in device coordinates surrounding the area to exclude, then call GpiExcludeClipRectangle.

Example:

#include <os2.h>
void fncCLIP03(void) {
    HPS hps;
    RECTL rcl;
    /* Set rectangle coordinates here. */
    GpiExcludeClipRectangle(hps, &rcl);
} /* fncCLIP03 */

Adding a Rectangular Area to a Clip Region

To extend a clip region (e.g., for a desktop publishing column), follow these steps:

1. Determine the rectangular area’s dimensions in device coordinates. 2. Release the current clip region with GpiSetClipRegion (required before combining regions). 3. Create a second region with GpiCreateRegion for the new rectangle. 4. Create a third region with GpiCreateRegion as the destination. 5. Combine the original and new regions with GpiCombineRegion. 6. Set the combined region as the clip region with GpiSetClipRegion.

Example:

#define INCL_GPIREGIONS
#include <os2.h>
void fncCLIP04(void) {
    HPS hps;
    RECTL rcl1, rcl2, rcl3;
    HRGN hrgn1, hrgn2, hrgn3;
    hrgn1 = GpiCreateRegion(hps, sizeof(rcl1) / sizeof(RECTL), &rcl1);
    GpiSetClipRegion(hps, hrgn1, NULL); /* Creates first clipping region */
    /* Compute coordinates of second region here. */
    GpiSetClipRegion(hps, NULLHANDLE, NULL); /* Releases first clipping region */
    hrgn2 = GpiCreateRegion(hps, sizeof(rcl2) / sizeof(RECTL), &rcl2);
    hrgn3 = GpiCreateRegion(hps, sizeof(rcl3) / sizeof(RECTL), &rcl3);
    GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
    GpiSetClipRegion(hps, hrgn3, NULL); /* Creates second clipping region */
} /* fncCLIP04 */

Setting the Clip Region to a Region Intersection

To set the clip region to the intersection of the current clip region and a rectangle, use GpiIntersectClipRectangle.

Example:

#include <os2.h>
void fncCLIP05(void) {
    RECTL rcl;
    HPS hps;
    /* Load rcl with coordinates of rectangle to intersect. */
    GpiIntersectClipRectangle(hps, &rcl);
} /* fncCLIP05 */

Determining the Size of a Clipping Area

To find the smallest rectangle surrounding the intersection of a clip path (world space), viewing limit (model space), graphics field (page space), clip region (device space), and visible region, use GpiQueryClipBox, which returns dimensions in world coordinates.

Example:

#include <os2.h>
void fncCLIP06(void) {
    HPS hps;
    RECTL rclClip;
    GpiQueryClipBox(hps, &rclClip);
} /* fncCLIP06 */