Region composition in CLIM is the process in which two regions are combined in some way (such as union or intersection) to produce a third region.
Since all regions in CLIM are closed, region composition is not always equivalent to simple set operations. Instead, composition attempts to return an object that has the same dimensionality as one of its arguments. If this is not possible, then the result is defined to be an empty region, which is canonicalized to +nowhere+ . (The exact details of this are specified with each function.)
Sometimes composition of regions can produce a result that is not a simple contiguous region. For example, region-union of two rectangular regions might not be rectangular. In order to support cases like this, CLIM has the concept of a region set , an object that represents one or more region objects related by some region operation, usually a union.
region-set [Protocol Class]
Summary: The protocol class that represents a region set; a subclass of region and bounding-rectangle .
Members of this class are immutable.
region-set-p [Function]
Summary: Returns t if object is a region set; otherwise, it returns nil .
Summary: This instantiable subclass of region-set and bounding-rectangle represents the union of several axis-aligned rectangles.
Summary: These three instantiable classes respectively implement the union, intersection, and differences of regions.
Region sets that are composed entirely of axis-aligned rectangles must be canonicalized into either a single rectangle or a union of rectangles. Furthermore, the rectangles in the union must not overlap each other.
The following generic functions comprise the region composition protocol. All classes that are subclasses of region must implement methods for these generic functions.
The methods for region-union , region-intersection , and region-difference will typically specialize both the region1 and region2 arguments.
region-set-regions [Generic Function]
Arguments: region
&key
normalize
Summary: Returns a sequence of the regions in the region set region . region can be either a region set or a "simple" region, in which case the result is simply a sequence of one element: region .
This function returns objects that reveal CLIM's internal state; do not modify these objects.
For the case of region sets that are unions of axis-aligned rectangles, the rectangles returned by region-set-regions are guaranteed not to overlap.
If normalize is supplied, it must be either :x-banding or :y-banding . If it is :x-banding and all the regions in region are axis-aligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the x direction. If it is :y-banding and all the regions in region are rectangles, the result is normalized with banding done in the y direction. Normalizing a region set that is not composed entirely of axis-aligned rectangles using x- or y-banding causes CLIM to signal the region-set-not-rectangular error.
map-over-region-set-regions [Generic Function]
Arguments: function region
&key
normalize
Summary: Calls function on each region in the region set region . This is often more efficient than calling region-set-regions . function is a function of one argument, a region; it has dynamic extent. region can be either a region set or a "simple" region, in which case function is called once on region itself. normalize is as for region-set-regions .
region-union [Generic Function]
Summary: Returns a region that contains all points that are in either of the regions region1 or region2 (possibly with some points removed in order to satisfy the dimensionality rule). The result of region-union always has dimensionality that is the maximum dimensionality of region1 and region2 . For example, the union of a path and an area produces an area; the union of two paths is a path.
region-union will return either a simple region or a member of the class standard-region-union .
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
region-intersection [Generic Function]
Summary: Returns a region that contains all points that are in both of the regions region1 and region2 (possibly with some points removed in order to satisfy the dimensionality rule). The result of region-intersection has dimensionality that is the minimum dimensionality of region1 and region2 , or is +nowhere+ . For example, the intersection of two areas is either another area or +nowhere+ ; the intersection of two paths is either another path or +nowhere+ ; the intersection of a path and an area produces the path clipped to stay inside of the area.
region-intersection will return either a simple region or a member of the class standard-region-intersection .
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
region-difference [Generic Function]
Summary: Returns a region that contains all points in the region region1 that are not in the region region2 (possibly plus additional boundary points to make the result closed). The result of region-difference has the same dimensionality as region1 , or is +nowhere+ . For example, the difference of an area and a path produces the same area; the difference of a path and an area produces the path clipped to stay outside of the area.
region-difference will return either a simple region, a region set, or a member of the class standard-region-difference .
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
Common Lisp Interface Manager 2.0 User's Guide - 7 Aug 2017