1// Copyright 2005 Google Inc. All Rights Reserved.
2
3#ifndef UTIL_GEOMETRY_S2REGION_H_
4#define UTIL_GEOMETRY_S2REGION_H_
5
6#include "s2.h"
7
8class Decoder;
9class Encoder;
10
11class S2Cap;
12class S2Cell;
13class S2LatLngRect;
14
15// An S2Region represents a two-dimensional region over the unit sphere.
16// It is an abstract interface with various concrete subtypes.
17//
18// The main purpose of this interface is to allow complex regions to be
19// approximated as simpler regions. So rather than having a wide variety
20// of virtual methods that are implemented by all subtypes, the interface
21// is restricted to methods that are useful for computing approximations.
22class S2Region {
23 public:
24 virtual ~S2Region();
25
26 // Return a deep copy of this region. If you want to narrow the result to a
27 // specific known region type, use down_cast<T*> from basictypes.h.
28 // Subtypes return pointers to that subtype from their Clone() methods.
29 virtual S2Region* Clone() const = 0;
30
31 // Return a bounding spherical cap. This is not guaranteed to be exact.
32 virtual S2Cap GetCapBound() const = 0;
33
34 // Return a bounding latitude-longitude rectangle that contains the region.
35 // The bounds are not guaranteed to be tight.
36 virtual S2LatLngRect GetRectBound() const = 0;
37
38 // If this method returns true, the region completely contains the given
39 // cell. Otherwise, either the region does not contain the cell or the
40 // containment relationship could not be determined.
41 virtual bool Contains(S2Cell const& cell) const = 0;
42
43 // If this method returns false, the region does not intersect the given
44 // cell. Otherwise, either region intersects the cell, or the intersection
45 // relationship could not be determined.
46 virtual bool MayIntersect(S2Cell const& cell) const = 0;
47
48 // Return true if and only if the given point is contained by the region.
49 // The point 'p' is generally required to be unit length, although some
50 // subtypes may relax this restriction.
51 // NOTE: If you will be calling this function on one specific subtype only,
52 // or if performance is a consideration, please use the non-virtual
53 // method Contains(S2Point const& p) declared below!
54 virtual bool VirtualContainsPoint(S2Point const& p) const = 0;
55
56 // Use encoder to generate a serialized representation of this region.
57 // Assumes that encoder can be enlarged using calls to Ensure(int).
58 //
59 // The representation chosen is left up to the sub-classes but it should
60 // satisfy the following constraints:
61 // - It should encode a version number.
62 // - It should be deserializable using the corresponding Decode method.
63 // - Performance, not space, should be the chief consideration. Encode() and
64 // Decode() should be implemented such that the combination is equivalent
65 // to calling Clone().
66 virtual void Encode(Encoder* const encoder) const = 0;
67
68 // Reconstruct a region from the serialized representation generated by
69 // Encode(). Note that since this method is virtual, it requires that a
70 // Region object of the appropriate concrete type has already been
71 // constructed. It is not possible to decode regions of unknown type.
72 //
73 // Whenever the Decode method is changed to deal with new serialized
74 // representations, it should be done so in a manner that allows for
75 // older versions to be decoded i.e. the version number in the serialized
76 // representation should be used to decide how to decode the data.
77 //
78 // Returns true on success.
79 virtual bool Decode(Decoder* const decoder) = 0;
80
81 // Provide the same functionality as Decode, except that decoded regions are
82 // allowed to point directly into the Decoder's memory buffer rather than
83 // copying the data. This method can be much faster for regions that have
84 // a lot of data (such as polygons), but the decoded region is only valid
85 // within the scope (lifetime) of the Decoder's memory buffer.
86 // Default implementation just calls Decode.
87 virtual bool DecodeWithinScope(Decoder* const decoder);
88
89 /////////////////////////////////////////////////////////////////////////
90 // The following are NON-VIRTUAL methods (for efficiency reasons) that
91 // happen to be implemented by all subclasses. You cannot call these
92 // methods unless you have an object of a particular subtype.
93 //
94 // bool Contains(S2Point const& p) const;
95 //
96 // Return true if and only if the given point is contained by the region.
97 // The point 'p' is generally required to be unit length, although some
98 // subtypes may relax this restriction.
99};
100
101#endif // UTIL_GEOMETRY_S2REGION_H_
102