HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros 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();
54  /// @}
55 
56  /// @{
57  /// Default iterator
58  GA_Iterator begin() const;
59  GA_Iterator end() const;
60  /// @}
61 
62  /// Determine whether a range is empty
63  bool empty() const
64  { return myRange->isEmpty(); }
65 
66  /// @{
67  /// Classes used to differentiate between different constructors
68  class pointref {};
69  class ordered {};
70  class primitiveref {};
71  class emptyrange {};
73  class safedeletions {};
74  class enditerator {};
75  class ignore_order {};
76  /// @}
77 
78  /// @{
79  /// Interface for making another range into an ordered range.
80  /// @param descending If true, the index order is going to be in
81  /// a descending order. If false, it's ascending.
82  GA_Range(const GA_Range &src, ordered, bool descending = false);
83  /// @}
84  //
85  /// @{
86  /// Interface for making another range into one where deletions
87  /// are safe to perform during the traversal.
89  /// @}
90 
91  /// @{
92  /// An empty range.
93  GA_Range(const GA_IndexMap &map, emptyrange);
94  /// @}
95 
96  /// @{
97  /// Convenience constructor to construct an offset range
98  /// The range includes @c start, but doesn't include @c end.
99  /// @see GA_RTIOffset
100  explicit GA_Range(const GA_IndexMap &map);
102  /// @}
103 
104  /// @{
105  /// Convenience constructor to construct an index range
106  /// @see GA_RTIIndex
109  GA_Size step, ordered);
110  /// @}
111 
112 
113  /// Constructor to create a range containing the offsets in the given list.
114  /// If end < 0, it will be set to the @c offsetlist.entries()
115  /// @see GA_RTIOffsetList
116  GA_Range(const GA_IndexMap &map, const GA_OffsetList &offsetlist,
117  GA_Size start=0, GA_Size end=-1);
118 
119  /// Construct a range of the elements in a given group
120  /// @see GA_RTIElementGroup
121  explicit GA_Range(const GA_ElementGroup &group,
122  bool complement=false);
123 
124  /// Construct a range of the elements in a given group
125  /// @see GA_RTIElementGroup
126  GA_Range(const GA_IndexMap &map, const GA_ElementGroup *group,
127  bool complement=false);
128 
129  /// Construct a range of the elements in a given group, ignoring its order
130  /// even if it is ordered.
131  /// @see GA_RTIElementGroup
132  /// @{
133  GA_Range(const GA_ElementGroup &group, ignore_order, bool complement=false);
134  GA_Range(const GA_IndexMap &map, const GA_ElementGroup *group,
135  ignore_order, bool complement=false);
136  /// @}
137 
138  /// Construct a range of all the elements referencing a given point. The
139  /// harden argument determines whether it is safe to use this range after
140  /// the point has been deleted. If the point will exist for the lifetime
141  /// of the range, harden can be false and thus more efficient.
142  ///
143  /// For example, to find all the vertices which reference point number 3:
144  /// @code
145  /// GA_Range(geo, 3, GA_ATTRIB_VERTEX, GA_Range::pointref, false);
146  /// @endcode
147  /// @see GA_RTIPointRef
148  GA_Range(const GA_Detail &geo, GA_Offset point, GA_AttributeOwner owner,
149  pointref, bool harden);
150 
151  /// Construct a range of all primitives/vertices referenced by the points
152  /// in the given range. The harden argument determines whether it is safe
153  /// to use this range after the point has been deleted. If the point will
154  /// exist for the lifetime of the range, harden can be false and thus more
155  /// efficient.
156  /// @code
157  /// GA_Range(geo, geo.getPointRange(), GA_ATTRIB_PRIMITIVE, false);
158  /// GA_Range(geo, geo.getPointRange(), GA_ATTRIB_VERTEX, false);
159  /// @endcode
160  /// @see GA_RTIPointComprehension
161  GA_Range(const GA_Detail &geo, const GA_Range &point_range,
162  GA_AttributeOwner type, pointref, bool harden);
163 
164 
165  /// Construct a range of all the elements used by a given primitive. The
166  /// harden argument determines whether it is safe to use this range after
167  /// the primitive has been deleted. If the primitive will exist for the
168  /// lifetime of the range, harden can be false, and thus more efficient.
169  /// If vertices are added or removed during traversal and harden is true,
170  /// only the original vertices will be traversed, but behaviour is
171  /// undefined if harden is false.
172  ///
173  /// For example, to find all the points which referenced by primitive 3:
174  /// @code
175  /// GA_Range(geo, 3, GA_ATTRIB_VERTEX, GA_Range::primitiveref);
176  /// @endcode
177  /// @see GA_RTIPrimitiveRef
178  GA_Range(const GA_Detail &geo, GA_Offset prim, GA_AttributeOwner owner,
179  primitiveref, bool harden);
180 
181  /// Construct a range of all points/vertices referenced by the primitives
182  /// in the given range. The harden argument determines whether it is safe
183  /// to use this range after the primitive has been deleted. If the
184  /// primitive will exist for the lifetime of the range, harden can be false
185  /// and thus more efficient.
186  /// @code
187  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_POINT);
188  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_VERTEX);
189  /// @endcode
190  /// @see GA_RTIPrimitiveComprehension
191  GA_Range(const GA_Detail &geo, const GA_Range &primitive_range,
192  GA_AttributeOwner type, primitiveref, bool harden);
193 
194  /// Construct a range of all points/vertices referenced by the primitives
195  /// in the given range. The harden argument determines whether it is safe
196  /// to use this range after the primitive has been deleted. If the
197  /// primitive will exist for the lifetime of the range, harden can be false
198  /// and thus more efficient.
199  ///
200  /// This version delivers the points/vertices in the order imposed by the
201  /// @c primitive_range. This is equivalent to traversing the vertices of
202  /// each primitive with a GA_Primitive::const_iterator as it is visited.
203  /// @code
204  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_POINT);
205  /// GA_Range(geo, geo.getPrimitiveRange(), GA_ATTRIB_VERTEX);
206  /// @endcode
207  /// @see GA_RTIPrimitiveComprehension
208  GA_Range(const GA_Detail &geo, const GA_Range &primitive_range,
209  GA_AttributeOwner type, primitiveref, ordered, bool harden);
210 
211  /// Iterate over all elements in the index map, including any temporary
212  /// elements. This should be used within ATI's when changing data for all
213  /// elements (including temporaries).
215 
216  /// @{
217  /// Operators
219  {
220  setRange(src.myRange);
221  return *this;
222  }
223  bool operator==(const GA_Range &src) const;
224  /// @}
225 
226  /// Take ownership of the given GA_RangeTypeInterface. This is used to
227  /// avoid unnecessary calls to GA_RangeTypeInterface::copy().
228  void adopt(GA_RangeTypeInterface *r) { setRange(r); }
229 
230  /// Check whether range is valid (i.e. has an implementation)
231  bool isValid() const { return myRange != NULL; }
232 
233  /// Query type of element
234  GA_AttributeOwner getOwner() const { return myRange->getOwner(); }
235 
236  /// Check whether the range is empty
237  bool isEmpty() const { return myRange->isEmpty(); }
238 
239  /// Get an upper bound on the range
240  GA_Size getMaxEntries() const { return myRange->getMaxEntries(); }
241  /// Get an accurate count of the entries in the range
242  GA_Size getEntries() const { return myRange->getEntries(); }
243 
244  /// Query if it is safe to delete an element during traversal. If not,
245  /// you can build an equivalent range by calling:
246  /// GA_Range(initial_range, GA_Range::safedeletions)
248  {
249  return !getRTI() ||
250  getRTI()->areTraversalDeletionsSafe();
251  }
252 
253  /// Query if the range contains duplicates. If it cannot, then
254  /// optimizations can be made assuming that there are no duplicates in the
255  /// range. This defaults to true.
256  bool canContainDuplicates() const
257  { return myRange->canContainDuplicates(); }
258 
259 
260  /// Allocate an object for testing the membership of individual elements
261  /// to this range. The caller is responsible for deleting this object,
262  /// which should not outlive the allocating range.
263  ///
264  /// Behaviour of this object is undefined for any elements that have been
265  /// deleted or moved since its creation.
266  const GA_RangeMemberQuery *allocMemberQuery() const;
267 
268  /// @cond INTERNAL
269  /// Interface used by iterators to perform iteration
270  void iterateCreate(GA_IteratorState &state) const
271  { myRange->iterateCreate(state); }
272  void iterateDestroy(GA_IteratorState &state) const
273  { myRange->iterateDestroy(state); }
274  void iterateRewind(GA_IteratorState &state,
275  GA_Offset &start, GA_Offset &end) const
276  { myRange->iterateRewind(state, start, end); }
277  void iterateNext(GA_IteratorState &state,
278  GA_Offset &start, GA_Offset &end) const
279  { myRange->iterateNext(state, start, end); }
280  void iterateCopy(GA_IteratorState &dest,
281  const GA_IteratorState &src) const
282  { myRange->iterateCopy(dest, src); }
283  /// @endcond
284 
285  /// Accessor for RTI
286  const GA_RangeTypeInterface *getRTI() const { return myRange; }
287 
288 private:
289  void setRange(GA_RangeTypeInterface *r)
290  {
291  if (r != myRange)
292  {
293  if (r)
294  r->incref();
295  if (myRange)
296  myRange->decref();
297  myRange = r;
298  }
299  }
300  GA_RangeTypeInterface *myRange;
301 
302  friend class GA_RangeTypeInterface; // For splitting
303  friend class GA_SplittableRange; // For splitting
304 };
305 
306 #endif
A class to manage an ordered array which has fixed offset handles.
Definition: GA_IndexMap.h:63
GLenum GLint * range
Definition: glcorearb.h:1924
Iteration over a range of elements.
Definition: GA_Iterator.h:28
GA_Iterator const_iterator
Definition: GA_Range.h:45
GLuint start
Definition: glcorearb.h:474
bool isValid() const
Check whether range is valid (i.e. has an implementation)
Definition: GA_Range.h:231
bool areTraversalDeletionsSafe() const
Definition: GA_Range.h:247
#define GA_API
Definition: GA_API.h:12
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:211
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:617
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
bool canContainDuplicates() const
Definition: GA_Range.h:256
GLuint GLuint end
Definition: glcorearb.h:474
GA_Size getMaxEntries() const
Get an upper bound on the range.
Definition: GA_Range.h:240
const GA_RangeTypeInterface * getRTI() const
Accessor for RTI.
Definition: GA_Range.h:286
GA_Size GA_Index
Define the strictness of GA_Offset/GA_Index.
Definition: GA_Types.h:611
Abstract implementation of a range.
bool isEmpty() const
Check whether the range is empty.
Definition: GA_Range.h:237
bool empty() const
Determine whether a range is empty.
Definition: GA_Range.h:63
const GA_Range & operator=(const GA_Range &src)
Definition: GA_Range.h:218
GA_AttributeOwner
Definition: GA_Types.h:33
GA_Size getEntries() const
Get an accurate count of the entries in the range.
Definition: GA_Range.h:242
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
Container class for all geometry.
Definition: GA_Detail.h:96
void adopt(GA_RangeTypeInterface *r)
Definition: GA_Range.h:228
GA_AttributeOwner getOwner() const
Query type of element.
Definition: GA_Range.h:234
GLboolean r
Definition: glcorearb.h:1221
GLenum src
Definition: glcorearb.h:1792