### 15.3.623  src/lib/x-kit/draw/region.api

`## region.api`

`# Compiled by:`
`#     `src/lib/x-kit/draw/xkit-draw.sublib

`# Api for regions.`

`###                     "There is no unhappiness like the`
`###                      misery of sighting land (and work)`
`###                      again after a cheerful, careless voyage."`
`###`
`###                                    -- Mark Twain,`
`###                                       Letter to Will Bowen`
`###                                       (prior to sailing on Quaker City)`

`stipulate`
`    package g2d =  geometry2d;          # Geometry2d    is from   `src/lib/std/2d/geometry2d.api
`herein`

`    api Region {`

`        Fill_Rule = EVEN_ODD ``| WINDING;`

`        Box_Overlap = BOX_OUT ``| BOX_IN | BOX_PART;`

`        Region;`

`        empty:  Region;`

`        # Return list of rectangles composing the region.`
`        # The rectangles are YX banded. Specifically, the rectangles`
`        # are listed in non-decreasing y coordinates. Two rectangles`
`        # with the same y coordinate are listed in increasing x coordinate.`
`        # Additionally, if the y projections of any two rectangles overlap,`
`        # then the projections are equal. (The rectangles lie in non-overlapping`
`        # bands.) Within a band, the rectangles are non-contiguous.`
`        #`
`        boxes_of:  Region -> List( g2d::Box );`

`        box:  g2d::Box -> Region;`
`            #`
`            # Construct a region corresponding to the given rectangle.`

`        polygon:  (List( g2d::Point ), Fill_Rule) -> Region;`
`            #`
`            # Construct a region corresponding to the polygon described by`
`            # the list of points and the fill rule. `

`        offset:  (Region, g2d::Point) -> Region;`
`            #`
`            #  Translate a region by the given vector. `

`        shrink:  (Region, g2d::Point) -> Region;`
`            #`
`            # shrink (r, PT { x, y } ) strips a band x pixels horizontally`
`            # and y pixels vertically from the boundary of r. If x or y are `
`            # negative, pixels are added rather than stripped in that dimension.`

`        clip_box:  Region -> g2d::Box;`
`            #`
`            #  Return the smallest rectangle containing the region. `

`        # Return the region corresponding to the given set operation`
`        # applied to two argument regions.`
`        #`
`        intersect:  (Region, Region) -> Region;`
`        union:      (Region, Region) -> Region;`
`        subtract:   (Region, Region) -> Region;`
`        xor:        (Region, Region) -> Region;`

`        is_empty:  Region -> Bool;`
`            #`
`            # TRUE iff the region is empty. `

`        equal:  (Region, Region) -> Bool;`
`            #`
`            # TRUE iff the two regions are equal. `

`        overlap:  (Region, Region) -> Bool;`
`            #`
`            # TRUE iff the two regions have non-empty intersection. `

`        point_in:  (Region, g2d::Point) -> Bool;`
`            #`
`            # TRUE iff the point lies within the region. `

`        box_in:  (Region, g2d::Box) -> Box_Overlap;`
`            #`
`            # Returns RECTANGLE_IN if the rectangle is entirely contained in the region.`
`            # Returns RECTANGLE_OUT if the rectangle is entirely outside the region.`
`            # Returns RECTANGLE_PART if the rectangle is partly in and partly out of the region.`
`    };`
`end;`

`## COPYRIGHT (c) 1994 by AT&T Bell Laboratories`
`## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,`
`## released per terms of SMLNJ-COPYRIGHT.`