3.1 General Regions
A region is an object that denotes a set of mathematical points in the plane. Regions include their boundaries, that is, they are closed. Regions have infinite resolution. [annotate]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← A Glossary]
[region, Concept← 16.4.1 The Output Recording Stream Protocol, stream-replay]
[region, Concept← 16.2.2 The Output Record "Database" Protocol, map-over-output-records-overlapping-region]
[region, Concept← 8.4.1 Repaint Protocol Functions, repaint-sheet]
[region, Concept← 7.3.1 Sheet Geometry Functions, children-overlapping-region]
[region, Concept← 5.3.3 Applying Transformations, transform-region]
[region, Concept← 5.3.3 Applying Transformations]
[region, Concept← 3.1.2 Region Composition Protocol, region-difference]
[region, Concept← 3.1.2 Region Composition Protocol, region-difference]
[region, Concept← 3.1.1 The Region Predicate Protocol, region-contains-position-p]
[region, Concept← 3.1.1 The Region Predicate Protocol, region-contains-region-p]
[region, Concept← 3.1.1 The Region Predicate Protocol, region-contains-region-p]
[region, Concept← 3.1 General Regions, regionp]
A bounded region is a region that contains at least one point and for which there exists a number, d, called the region's diameter, such that if p1 and p2 are points in the region, the distance between p1 and p2 is always less than or equal to d. [annotate]
An unbounded region either contains no points or contains points arbitrarily far apart. [annotate]
Another way to describe a region is that it maps every (x,y) pair into either true or false (meaning member or not a member, respectively, of the region). Later, in Chapter 14, we will generalize a region to something called a design that maps every point (x,y) into color and opacity values. [annotate]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← A Glossary]
[design, Concept← 14.5 Arbitrary Designs, draw-design]
[design, Concept← 14.3 Tiling, make-rectangular-tile]
[design, Concept← 14.1 The Compositing Protocol, compose-out]
[design, Concept← 14.1 The Compositing Protocol, compose-out]
[design, Concept← 14.1 The Compositing Protocol, compose-in]
[design, Concept← 14.1 The Compositing Protocol, compose-in]
[design, Concept← 14.1 The Compositing Protocol, compose-over]
[design, Concept← 14.1 The Compositing Protocol, compose-over]
[design, Concept← 13.2 Basic Designs, designp]
The protocol class that corresponds to a set of points. This includes both bounded and unbounded regions. This is a subclass of design (see Chapter 13). [annotate] If you want to create a new class that behaves like a region, it should be a subclass of region. All instantiable subclasses of region must obey the region protocol. [annotate] Note: The spec mentions the "region predicate protocol" and the "region composition protocol", but there seems to be no explicit mention of "the region protocol". Should we assume that the "region protocol" is the union of those two protocols? [edit]-- Robert Strandh 2007-08-23 08:57Z There is no general constructor called make-region because of the impossibility of a uniform way to specify the arguments to such a function. [annotate] [← 14.4 Regions as Designs] [← 10.2 Drawing Option Binding Forms, :clipping-region] [← 5.3.3 Applying Transformations] [← 4.1.1 The Bounding Rectangle Protocol] [← 4.1 Bounding Rectangles, bounding-rectangle] [← 3.2.1 Points, point] [← 3.1.2 Region Composition Protocol, standard-region-union] [← 3.1.2 Region Composition Protocol, region-set] [← 3.1.2 Region Composition Protocol] [← 3.1.1 The Region Predicate Protocol] [← 3.1 General Regions, area] [← 3.1 General Regions, path] [← 2.4 Immutability of Objects] |
Returns true if object is a region, otherwise returns false. [annotate] |
The protocol class path denotes bounded regions that have dimensionality 1 (that is, have length). It is a subclass of region and bounding-rectangle. If you want to create a new class that behaves like a path, it should be a subclass of path. All instantiable subclasses of path must obey the path protocol. [annotate] Constructing a path object with no length (via make-line*, for example) may canonicalize it to +nowhere+. [annotate] Some rendering models support the constructing of areas by filling a closed path. In this case, the path needs a direction associated with it. Since CLIM does not currently support the path-filling model, paths are directionless. [annotate] |
Returns true if object is a path, otherwise returns false. [annotate] Note that constructing a path object with no length (such as calling make-line with two coincident points), for example) may canonicalize it to +nowhere+. [annotate] |
The protocol class area denotes bounded regions that have dimensionality 2 (that is, have area). It is a subclass of region and bounding-rectangle. If you want to create a new class that behaves like an area, it should be a subclass of area. All instantiable subclasses of area must obey the area protocol. [annotate] Note that constructing an area object with no area (such as calling make-rectangle with two coincident points), for example) may canonicalize it to +nowhere+. [annotate] |
Returns true if object is an area, otherwise returns false. [annotate] |
The type that represents a coordinate. This must either be t, or a subtype of real. CLIM implementations may use a more specific subtype of real, such as single-float, for reasons of efficiency. [annotate] All of the specific region classes and subclasses of bounding-rectangle will use this type to store their coordinates. However, the constructor functions for the region classes and for bounding rectangles must accept numbers of any type and coerce them to coordinate. [annotate] |
Coerces the number n to be a coordinate. [annotate] |
+everywhere+ is the region that includes all the points on the two-dimensional infinite drawing plane. +nowhere+ is the empty region, the opposite of +everywhere+. [annotate] [← 16.2.1 The Basic Output Record Protocol, replay-output-record] [← 10.2 Drawing Option Binding Forms, :clipping-region] [← 8.3.1 Output Properties, medium-clipping-region] [← 14.5 Arbitrary Designs, draw-pattern*] [← 14.5 Arbitrary Designs, draw-design] [← 13.7 Flipping Ink, make-flipping-ink] [← 3.1.2 Region Composition Protocol, region-difference] [← 3.1.2 Region Composition Protocol, region-intersection] [← 3.1.2 Region Composition Protocol] [← 3.1.1 The Region Predicate Protocol, region-intersects-region-p] [← 3.1 General Regions, area] [← 3.1 General Regions, pathp] [← 3.1 General Regions, path] |
3.1.1 The Region Predicate Protocol
The following generic functions comprise the region predicate protocol. All classes that are subclasses of region must either inherit or implement methods for these generic functions. [annotate]
The methods for region-equal, region-contains-region-p, and region-intersects-region-p will typically specialize both the region1 and region2 arguments. [annotate]
Returns true if the two regions region1 and region2 contain exactly the same set of points, otherwise returns false. [annotate] |
Returns true if all points in the region region2 are members of the region region1, otherwise returns false. [annotate] |
Returns true if the point at (x,y) is contained in the region region, otherwise returns false. Since regions in CLIM are closed, this must return true if the point at (x,y) is on the region's boundary. CLIM implementations are permitted to return different non-nil values depending on whether the point is completely inside the region or is on the border. [annotate] region-contains-position-p is a special case of region-contains-region-p in which the region is the point (x,y). [annotate] |
Returns false if region-intersection of the two regions region1 and region2 would be +nowhere+, otherwise returns true. [annotate] |
3.1.2 Region Composition Protocol
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.) [annotate]
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 a single rectangle. In order to support cases like this, CLIM has the concept of a region set, which is an object that represents one or more region objects related by some region operation, usually a union. CLIM provides standard classes to cover the cases of region union, intersection, and difference. [annotate]
[region set, Concept← A Glossary]
[region set, Concept← 3.1.2 Region Composition Protocol, map-over-region-set-regions]
[region set, Concept← 3.1.2 Region Composition Protocol, map-over-region-set-regions]
[region set, Concept← 3.1.2 Region Composition Protocol, region-set-regions]
[region set, Concept← 3.1.2 Region Composition Protocol, region-set-regions]
[region set, Concept← 3.1.2 Region Composition Protocol, region-set-p]
Some CLIM implementations might only implement a subset of full region composition. Because of the importance of rectangular regions and region sets that are the union of rectangular regions, every CLIM implementation is required to fully support all functions that use regions for those cases. (For example, CLIM implementations must be able do clipping and repainting on region sets composed entirely of axis-aligned rectangles.) If a CLIM implementation does not support some functions on non-rectangular region sets (for example, clipping), it must signal an error when an unsupported case is encountered; the exact details of this depend on the particular CLIM implementation. [annotate]
The protocol class that represents a region set; a subclass of region and bounding-rectangle. [annotate] In addition to the three classes below, there may be other instantiable subclasses of region-set that represent special cases, for instance, some implementations might have a standard-rectangle-set class that represents the union of several axis-aligned rectangles. [annotate] Members of this class are immutable. [annotate] |
Returns true if object is a region set, otherwise returns false. [annotate] |
These three instantiable classes respectively implement the union, intersection, and differences of regions. Implementations may, but are not required to, take advantage of the commutativity and associativity of union and intersection in order to "collapse" complicated region sets into simpler ones. [annotate] 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. [annotate] The following generic functions comprise the region composition protocol. All classes that are subclasses of region must implement methods for these generic functions. [annotate] The methods for region-union, region-intersection, and region-difference will typically specialize both the region1 and region2 arguments. [annotate] |
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 those objects. [annotate] 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. [annotate] 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. [annotate] |
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. [annotate] Note: The function can safely be allocated on the stack instead of the heap, as with the dynamic-extent declaration. [edit]-- Elijah Malaby 2016-09-04 15:03Z  Figure 3.1: Normalization of rectangular region sets. |
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. [annotate] region-union will return either a simple region, a region set, or a member of the class standard-region-union. [annotate] This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. [annotate] |
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. [annotate] region-intersection will return either a simple region or a member of the class standard-region-intersection. [annotate] This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. [annotate] |
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. [annotate] region-difference will return either a simple region, a region set, or a member of the class standard-region-difference. [annotate] This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. [annotate]  Figure 3.2: Examples of region union, intersection, and difference. |