HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_Range.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: GA_Range.h ( GA Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __GA_Range__
12 #define __GA_Range__
13 
14 #include "GA_API.h"
15 #include "GA_OffsetList.h"
16 #include "GA_RangeTypeInterface.h"
17 #include "GA_Types.h"
18 
19 #include <stddef.h>
20 
21 
22 class GA_Detail;
23 class GA_ElementGroup;
24 class GA_IndexMap;
25 class GA_Iterator;
26 class GA_IteratorState;
29 
30 
31 /// @brief A range of elements in an index-map
32 ///
33 /// A range specifies a selection/collection of elements in an index map
34 /// for iteration. The membership state of individual elements can also
35 /// be queried (@see allocMemberQuery()).
36 ///
37 /// Iteration over a range, performed by instantiating a GA_Iterator, does
38 /// not affect the range object itself. The begin() method can be used to
39 /// initialize a basic iterator.
40 ///
41 /// Custom range types are implemented by subclassing GA_RangeTypeInterface.
43 {
44 public:
47 
48  /// @{
49  /// Constructor/destructors
50  GA_Range();
52  GA_Range(const GA_Range &src);
53  GA_Range(GA_Range &&src) noexcept;
54  ~GA_Range();
55  /// @}
56 
58 
59  /// Default iterator
60  /// @{
61  GA_Iterator begin() const;
62  enditerator end() const { return enditerator(); }
63  /// @}
64 
65  /// Determine whether a range is empty
66  bool empty() const
67  { return myRange->isEmpty(); }
68 
69  /// @{
70  /// Classes used to differentiate between different constructors
71  class pointref {};
72  class ordered {};
73  class primitiveref {};
74  class emptyrange {};
76  class safedeletions {};
77  class ignore_order {};
78  /// @}
79 
80  /// @{
81  /// Interface for making another range into an ordered range.
82  /// @param descending If true, the index order is going to be in
83  /// a descending order. If false, it's ascending.
84  GA_Range(const GA_Range &src, ordered, bool descending = false);
85  /// @}
86  //
87  /// @{
88  /// Interface for making another range into one where deletions
89  /// are safe to perform during the traversal.
91  /// @}
92 
93  /// @{
94  /// An empty range.
95  GA_Range(const GA_IndexMap &map, emptyrange);
96  /// @}
97 
98  /// @{
99  /// Convenience constructor to construct an offset range
100  /// The range includes @c start, but doesn't include @c end.
101  /// @see GA_RTIOffset
102  explicit GA_Range(const GA_IndexMap &map);
104  /// @}
105 
106  /// @{
107  /// Convenience constructor to construct an index range
108  /// @see GA_RTIIndex
111  GA_Size step, ordered);
112  /// @}
113 
114 
115  /// Constructor to create a range containing the offsets in the given list.
116  /// If end < 0, it will be set to the @c offsetlist.entries()
117  /// @see GA_RTIOffsetList
118  GA_Range(const GA_IndexMap &map, const GA_OffsetList &offsetlist,
119  GA_Size start=0, GA_Size end=-1);
120 
121  /// Construct a range of the elements in a given group
122  /// @see GA_RTIElementGroup
123  explicit GA_Range(const GA_ElementGroup &group,
124  bool complement=false);
125 
126  /// Construct a range of the elements in a given group
127  /// @see GA_RTIElementGroup
128  GA_Range(const GA_IndexMap &map, const GA_ElementGroup *group,
129  bool complement=false);
130 
131  /// Construct a range of the elements in a given group, ignoring its order
132  /// even if it is ordered.
133  /// @see GA_RTIElementGroup
134  /// @{
135  GA_Range(const GA_ElementGroup &group, ignore_order, bool complement=false);
136  GA_Range(const GA_IndexMap &map, const GA_ElementGroup *group,
137  ignore_order, bool complement=false);
138  /// @}
139 
140  /// Construct a range of all the elements referencing a given point. The
141  /// harden argument determines whether it is safe to use this range after
142  /// the point has been deleted. If the point will exist for the lifetime
143  /// of the range, harden can be false and thus more efficient.
144  ///
145  /// For example, to find all the vertices which reference point number 3:
146  /// @code
147  /// GA_Range(geo, 3, GA_ATTRIB_VERTEX, GA_Range::pointref, false);
148  /// @endcode
149  /// @see GA_RTIPointRef
150  GA_Range(const GA_Detail &geo, GA_Offset point, GA_AttributeOwner owner,
151  pointref, bool harden);
152 
153  /// Construct a range of all primitives/vertices referenced by the points
154  /// in the given range. The harden argument determines whether it is safe
155  /// to use this range after the point has been deleted. If the point will
156  /// exist for the lifetime of the range, harden can be false and thus more
157  /// efficient.
158  /// @code
159  /// GA_Range(geo, geo.getPointRange(), GA_ATTRIB_PRIMITIVE, false);
160  /// GA_Range(geo, geo.getPointRange(), GA_ATTRIB_VERTEX, false);
161  /// @endcode
162  /// @see GA_RTIPointComprehension
163  GA_Range(const GA_Detail &geo, const GA_Range &point_range,
164  GA_AttributeOwner type, pointref, bool harden);
165 
166 
167  /// Construct a range of all the elements used by a given primitive. The
168  /// harden argument determines whether it is safe to use this range after
169  /// the primitive has been deleted. If the primitive will exist for the
170  /// lifetime of the range, harden can be false, and thus more efficient.
171  /// If vertices are added or removed during traversal and harden is true,
172  /// only the original vertices will be traversed, but behaviour is
173  /// undefined if harden is false.
174  ///
175  /// For example, to find all the points which referenced by primitive 3:
176  /// @code
177  /// GA_Range(geo, 3, GA_ATTRIB_VERTEX, GA_Range::primitiveref);
178  /// @endcode
179  /// @see GA_RTIPrimitiveRef
180  GA_Range(const GA_Detail &geo, GA_Offset prim, GA_AttributeOwner owner,
181  primitiveref, bool harden);
182 
183  /// Construct a range of all points/vertices referenced by the primitives
184  /// in the given range. The harden argument determines whether it is safe
185  /// to use this range after the primitive has been deleted. If the
186  /// primitive will exist for the lifetime of the range, harden can be false
187  /// and thus more efficient.
188  /// @code
189  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_POINT);
190  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_VERTEX);
191  /// @endcode
192  /// @see GA_RTIPrimitiveComprehension
193  GA_Range(const GA_Detail &geo, const GA_Range &primitive_range,
194  GA_AttributeOwner type, primitiveref, bool harden);
195 
196  /// Construct a range of all points/vertices referenced by the primitives
197  /// in the given range. The harden argument determines whether it is safe
198  /// to use this range after the primitive has been deleted. If the
199  /// primitive will exist for the lifetime of the range, harden can be false
200  /// and thus more efficient.
201  ///
202  /// This version delivers the points/vertices in the order imposed by the
203  /// @c primitive_range. This is equivalent to traversing the vertices of
204  /// each primitive with a GA_Primitive::const_iterator as it is visited.
205  /// @code
206  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_POINT);
207  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_VERTEX);
208  /// @endcode
209  /// @see GA_RTIPrimitiveComprehension
210  GA_Range(const GA_Detail &geo, const GA_Range &primitive_range,
211  GA_AttributeOwner type, primitiveref, ordered, bool harden);
212 
213  /// Iterate over all elements in the index map, including any temporary
214  /// elements. This should be used within ATI's when changing data for all
215  /// elements (including temporaries).
217 
218  /// @{
219  /// Operators
221  {
222  setRange(src.myRange);
223  return *this;
224  }
225  const GA_Range &operator=(GA_Range &&src) noexcept
226  {
227  if (myRange)
228  myRange->decref();
229  myRange = src.myRange;
230  src.myRange = nullptr;
231  return *this;
232  }
233  bool operator==(const GA_Range &src) const;
234  /// @}
235 
236  /// Take ownership of the given GA_RangeTypeInterface. This is used to
237  /// avoid unnecessary calls to GA_RangeTypeInterface::copy().
238  void adopt(GA_RangeTypeInterface *r) { setRange(r); }
239 
240  /// Check whether range is valid (i.e. has an implementation)
241  bool isValid() const { return myRange != NULL; }
242 
243  /// Query type of element
244  GA_AttributeOwner getOwner() const { return myRange->getOwner(); }
245 
246  /// Check whether the range is empty
247  bool isEmpty() const { return myRange->isEmpty(); }
248 
249  /// Get an upper bound on the range
250  GA_Size getMaxEntries() const { return myRange->getMaxEntries(); }
251  /// Get an accurate count of the entries in the range
252  GA_Size getEntries() const { return myRange->getEntries(); }
253 
254  /// Query if it is safe to delete an element during traversal. If not,
255  /// you can build an equivalent range by calling:
256  /// GA_Range(initial_range, GA_Range::safedeletions)
258  {
259  return !getRTI() ||
260  getRTI()->areTraversalDeletionsSafe();
261  }
262 
263  /// Query if the range contains duplicates. If it cannot, then
264  /// optimizations can be made assuming that there are no duplicates in the
265  /// range. This defaults to true.
266  bool canContainDuplicates() const
267  { return myRange->canContainDuplicates(); }
268 
269 
270  /// Allocate an object for testing the membership of individual elements
271  /// to this range. The caller is responsible for deleting this object,
272  /// which should not outlive the allocating range.
273  ///
274  /// Behaviour of this object is undefined for any elements that have been
275  /// deleted or moved since its creation.
276  const GA_RangeMemberQuery *allocMemberQuery() const;
277 
278  /// @cond INTERNAL
279  /// Interface used by iterators to perform iteration
280  void iterateCreate(GA_IteratorState &state) const
281  { myRange->iterateCreate(state); }
282  void iterateDestroy(GA_IteratorState &state) const
283  { myRange->iterateDestroy(state); }
284  void iterateRewind(GA_IteratorState &state,
285  GA_Offset &start, GA_Offset &end) const
286  { myRange->iterateRewind(state, start, end); }
287  void iterateNext(GA_IteratorState &state,
288  GA_Offset &start, GA_Offset &end) const
289  { myRange->iterateNext(state, start, end); }
290  void iterateCopy(GA_IteratorState &dest,
291  const GA_IteratorState &src) const
292  { myRange->iterateCopy(dest, src); }
293  /// @endcond
294 
295  /// Accessor for RTI
296  const GA_RangeTypeInterface *getRTI() const { return myRange; }
297 
298 private:
299  void setRange(GA_RangeTypeInterface *r)
300  {
301  if (r != myRange)
302  {
303  if (r)
304  r->incref();
305  if (myRange)
306  myRange->decref();
307  myRange = r;
308  }
309  }
310  GA_RangeTypeInterface *myRange;
311 
312  friend class GA_RangeTypeInterface; // For splitting
313  friend class GA_SplittableRange; // For splitting
314 };
315 
316 #endif
A class to manage an ordered array which has fixed offset handles.
Definition: GA_IndexMap.h:63
GLenum GLint * range
Definition: glcorearb.h:1925
Iteration over a range of elements.
Definition: GA_Iterator.h:29
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:623
GA_Iterator const_iterator
Definition: GA_Range.h:45
GLuint start
Definition: glcorearb.h:475
bool isValid() const
Check whether range is valid (i.e. has an implementation)
Definition: GA_Range.h:241
bool areTraversalDeletionsSafe() const
Definition: GA_Range.h:257
enditerator end() const
Definition: GA_Range.h:62
#define GA_API
Definition: GA_API.h:14
Abstract base class for a range membership query object.
exint GA_Size
Defines the bit width for index and offset types in GA.
Definition: GA_Types.h:236
void incref() const
A range of elements in an index-map.
Definition: GA_Range.h:42
GA_Iterator iterator
Definition: GA_Range.h:46
GA_Size GA_Offset
Definition: GA_Types.h:646
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
bool canContainDuplicates() const
Definition: GA_Range.h:266
GLuint GLuint end
Definition: glcorearb.h:475
GA_Size getMaxEntries() const
Get an upper bound on the range.
Definition: GA_Range.h:250
const GA_RangeTypeInterface * getRTI() const
Accessor for RTI.
Definition: GA_Range.h:296
GA_Size GA_Index
Define the strictness of GA_Offset/GA_Index.
Definition: GA_Types.h:640
Abstract implementation of a range.
bool isEmpty() const
Check whether the range is empty.
Definition: GA_Range.h:247
bool empty() const
Determine whether a range is empty.
Definition: GA_Range.h:66
const GA_Range & operator=(const GA_Range &src)
Definition: GA_Range.h:220
GA_AttributeOwner
Definition: GA_Types.h:35
const GA_Range & operator=(GA_Range &&src) noexcept
Definition: GA_Range.h:225
GA_Size getEntries() const
Get an accurate count of the entries in the range.
Definition: GA_Range.h:252
Container class for all geometry.
Definition: GA_Detail.h:96
void adopt(GA_RangeTypeInterface *r)
Definition: GA_Range.h:238
GA_AttributeOwner getOwner() const
Query type of element.
Definition: GA_Range.h:244
GLboolean r
Definition: glcorearb.h:1222
type
Definition: core.h:1059
GLenum src
Definition: glcorearb.h:1793
PcpNodeRef_ChildrenIterator begin(const PcpNodeRef::child_const_range &r)
Support for range-based for loops for PcpNodeRef children ranges.
Definition: node.h:558