HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_ReuseStrategy.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_ReuseStrategy.h ( GA Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __GA_ReuseStrategy__
12 #define __GA_ReuseStrategy__
13 
14 #include "GA_API.h"
15 #include "GA_Types.h"
16 
17 class GA_Attribute;
18 class GA_Defaults;
20 
21 class UT_Options;
22 class UT_StringRef;
23 
24 
25 /// @brief Specify when and how to reuse an existing attribute.
26 ///
27 /// When attempting to create a new attribute, we may encounter an existing
28 /// attribute with the same name. The @c GA_ReuseStrategy settings specify
29 /// when and how to reuse the existing attribute instead of creating the new
30 /// one.
31 ///
33 {
34 public:
35  /// The high level strategy for resolving a name collision with an
36  /// existing attribute.
38  {
39  /// Fail immediately on the collision, and resolve using the set
40  /// FailureStrategy.
42 
43  /// Attempt to recycle the existing attribute, failing only if the
44  /// attempt fails, at which point, resolve using the FailureStrategy.
45  /// The existing attribute may be partially changed on failure, so
46  /// be careful when combining with FAILURE_RETURN_MISMATCH or even
47  /// FAILURE_RETURN_INVALID.
49 
50  COLLISION_DEFAULT = COLLISION_RECYCLE
51  };
52 
53  /// This enum specifies how to deal with a failure when applying the
54  /// CollisionStrategy.
56  {
57  /// Return the conflicting attribute
59  /// Return an invalid result (NULL pointer or invalid reference)
61  /// Replace the conflicting attribute
63  /// Replace the conflicting attribute and attempt to copy data
64  /// values to the new attribute.
66 
67  FAILURE_DEFAULT = FAILURE_REPLACE_AND_COPY
68  };
69 
70  /// Typically a type mismatch will result in the existing attribute being
71  /// replaced when an attribute type is explicitly requested, but when the
72  /// only criteria is that the existing attribute support some expected
73  /// interface, we can be less restrictive.
75  {
76  /// Disallow mis-matched type
78  /// Allow mis-matched type if compatible (only possible in generic
79  /// methods like addFloatTuple(), addStringTuple(), etc where type
80  /// is only implied).
82 
83  TYPE_DEFAULT = TYPE_KEEP_COMPATIBLE
84  };
85 
86  /// For attributes which have storage, this enum specifies what to do if
87  /// there is a mismatch.
89  {
90  /// Disallow mis-matched storage
92  /// Keep existing storage (if compatible)
94  /// Reduce existing storage to that desired
96  /// Use storage with greatest precision (float > int)
98 
99  STORAGE_DEFAULT = STORAGE_USE_BEST
100  };
101 
102  /// For attributes which have a tuple size, this enum specifies what to do
103  /// if there is a mis-match.
105  {
106  /// Disallow mis-matched tuple sizes
108  /// Set the new tuple size to be no larger than the old size.
110  /// Use the larger of the two tuple sizes
112 
113  TUPLE_SIZE_DEFAULT = TUPLE_SIZE_USE_BEST
114  };
115 
116  /// This enum specifies what to do with the attribute options passed to the
117  /// creation method in the event that we're going to reuse an attribute.
119  {
120  /// Keep existing attribute's options
122  /// Replace existing attribute's options entirely
124  /// Overwrite existing attribute's options so that options unique to
125  /// the existing attribute are not lost
127  /// Keep any existing options, but merge in any missing options
129 
130  OPTIONS_DEFAULT = OPTIONS_MERGE_MISSING
131  };
132 
133  /// This enum specifies whether or not we attempt to copy values from the
134  /// existing attribute in the event that we fail to reuse it.
136  {
139 
140  DATACOPY_DEFAULT = DATACOPY_TRUE
141  };
142 
143  /// This enum specifies how we deal with name collisions across the point
144  /// and vertex dictionaries.
146  {
147  /// Ignore the attribute in the other dictionary.
149  /// Destroy the attribute in the other dictionary.
151  /// Inherit the values from the attribute in the other dictionary, and
152  /// then destroy it.
154 
155  PT_VTX_COLLISION_DEFAULT = PT_VTX_COLLISION_INHERIT_VALUES_AND_DESTROY
156  };
157 
158 
159  GA_ReuseStrategy(FailureStrategy fail_strategy = FAILURE_DEFAULT,
160  TypeStrategy type_strategy = TYPE_DEFAULT,
161  StorageStrategy storage_strategy = STORAGE_DEFAULT,
162  TupleSizeStrategy size_strategy = TUPLE_SIZE_DEFAULT,
163  OptionsStrategy opts_strategy = OPTIONS_DEFAULT)
164  : myCollisionStrategy(COLLISION_RECYCLE),
165  myFailureStrategy(fail_strategy),
166  myTypeStrategy(type_strategy), myStorageStrategy(storage_strategy),
167  myTupleSizeStrategy(size_strategy), myOptionsStrategy(opts_strategy),
168  myPointVertexCollisionStrategy(PT_VTX_COLLISION_DEFAULT)
169  { }
171 
173  { return myCollisionStrategy; }
175  { myCollisionStrategy = s; }
176 
178  { return myFailureStrategy; }
180  { myFailureStrategy = s; }
181 
183  { return myTypeStrategy; }
185  { myTypeStrategy = s; }
186 
188  { return myStorageStrategy; }
190  { myStorageStrategy = s; }
191 
193  { return myTupleSizeStrategy; }
195  { myTupleSizeStrategy = s; }
196 
198  { return myOptionsStrategy; }
200  { myOptionsStrategy = s; }
201 
202 
204  { return myCollisionStrategy == COLLISION_RECYCLE; }
205  bool getReplaceOnFailure() const
206  {
207  return myFailureStrategy == FAILURE_REPLACE ||
208  myFailureStrategy == FAILURE_REPLACE_AND_COPY;
209  }
210 
212  { return myPointVertexCollisionStrategy; }
215  {
216  myPointVertexCollisionStrategy = s;
217  }
218 
219 
220  /// Attempt to bring the attribute to compliance as per the strategy. Our
221  /// TypeStrategy determines whether we care about an exact type match or
222  /// can work with a tuple AIF.
223  ///
224  /// Returns true on success and false on failure. It is expected that the
225  /// attribute will be replaced on failure as it may be partially modified
226  /// by this method.
227  bool applyStrategiesForTuples(
228  GA_Attribute &attrib, GA_Storage requested_storage,
229  int requested_tuple_size,
230  const GA_Defaults *requested_defaults,
231  const UT_Options *requested_creation_options,
232  const GA_AttributeOptions *requested_attribute_options,
233  const UT_StringRef &requested_type) const;
234 
235  /// Attempt to bring the attribute to compliance as per the strategy. Our
236  /// TypeStrategy determines whether we care about an exact type match
237  ///
238  /// Returns true on success and false on failure. It is expected that the
239  /// attribute will be replaced on failure as it may be partially modified
240  /// by this method.
241  bool applyStrategiesForArrays(
242  GA_Attribute &attrib, GA_Storage requested_storage,
243  int requested_tuple_size,
244  const UT_Options *requested_creation_options,
245  const GA_AttributeOptions *requested_attribute_options,
246  const UT_StringRef &requested_type) const;
247 
248  /// Only call this method if getReplaceOnFailure() returns true. Returns
249  /// true if the copy was successful, or was not needed. False otherwise.
250  bool applyDataCopyStrategy(
251  GA_Attribute *dest,
252  const GA_Attribute *src) const;
253 
254  /// @{
255  /// Helper methods for COLLISION_RECYCLE
256  ///
257  /// Applies getTupleSizeStrategy() to return the new tuple size for the
258  /// attribute, or -1 if no resolution is possible.
259  int computeTupleSize(int old_size,
260  int requested_size) const;
261 
262  /// Applies getStorageStrategy() to return the new numeric storage for the
263  /// attribute or GA_STORE_INVALID if no resolution is possible. Note that
264  /// GA_STORE_BOOL is considered a numeric storage type for these purposes.
265  GA_Storage computeNumericStorage(GA_Storage old_storage,
266  GA_Storage requested_storage)
267  const;
268 
269  /// Compare two defaults objects for equality.
270  static bool areEqual(const GA_Defaults &a_defaults,
271  const GA_Defaults &b_defaults,
272  GA_Storage storage, int size);
273 
274  /// Apply getOptionsStrategy().
275  void applyOptionsStrategy(
276  const GA_AttributeOptions *requested_options,
277  GA_AttributeOptions &current_options) const;
278 
279  /// @}
280  //
281  /// Returns the dictionary that should be checked for a cross dictionary
282  /// collision (GA_ATTRIB_VERTEX for GA_ATTRIB_POINT and vice versa) and
283  /// GA_ATTRIB_INVALID when no check is needed.
285  GA_AttributeOwner dict) const
286  {
287  if (myPointVertexCollisionStrategy != PT_VTX_COLLISION_IGNORE)
288  {
289  if (dict == GA_ATTRIB_POINT)
290  return GA_ATTRIB_VERTEX;
291  if (dict == GA_ATTRIB_VERTEX)
292  return GA_ATTRIB_POINT;
293  }
294  return GA_ATTRIB_INVALID;
295  }
296 
297  /// Only call this method if getPointVertexCollisionDict() does not return
298  /// GA_ATTRIB_GLOBAL. Returns true if the copy was successful, or was not
299  /// needed. False otherwise.
300  bool applyPointVertexCollisionDataCopyStrategy(
301  GA_Attribute *dest, bool replacement,
302  const GA_Attribute *src) const;
303 
304 private:
305  CollisionStrategy myCollisionStrategy;
306  FailureStrategy myFailureStrategy;
307  TypeStrategy myTypeStrategy;
308  StorageStrategy myStorageStrategy;
309  TupleSizeStrategy myTupleSizeStrategy;
310  OptionsStrategy myOptionsStrategy;
311  PointVertexCollisionStrategy myPointVertexCollisionStrategy;
312 };
313 
314 #endif
GLdouble s
Definition: glew.h:1390
OptionsStrategy getOptionsStrategy() const
Destroy the attribute in the other dictionary.
TupleSizeStrategy getTupleSizeStrategy() const
GA_ReuseStrategy(FailureStrategy fail_strategy=FAILURE_DEFAULT, TypeStrategy type_strategy=TYPE_DEFAULT, StorageStrategy storage_strategy=STORAGE_DEFAULT, TupleSizeStrategy size_strategy=TUPLE_SIZE_DEFAULT, OptionsStrategy opts_strategy=OPTIONS_DEFAULT)
Definition of a geometry attribute.
Definition: GA_Attribute.h:196
void setStorageStrategy(StorageStrategy s)
Specify when and how to reuse an existing attribute.
GLsizeiptr size
Definition: glew.h:1681
GLenum src
Definition: glew.h:2410
Return the conflicting attribute.
void setOptionsStrategy(OptionsStrategy s)
Set the new tuple size to be no larger than the old size.
Replace the conflicting attribute.
Disallow mis-matched storage.
Class which stores the default values for a GA_Attribute.
Definition: GA_Defaults.h:35
Keep existing storage (if compatible)
CollisionStrategy getCollisionStrategy() const
Keep existing attribute's options.
bool getRecycleOnCollision() const
Disallow mis-matched tuple sizes.
Ignore the attribute in the other dictionary.
#define GA_API
Definition: GA_API.h:12
Keep any existing options, but merge in any missing options.
GA_AttributeOwner getPointVertexCollisionDict(GA_AttributeOwner dict) const
Reduce existing storage to that desired.
void setCollisionStrategy(CollisionStrategy s)
Disallow mis-matched type.
StorageStrategy getStorageStrategy() const
FailureStrategy getFailureStrategy() const
PointVertexCollisionStrategy getPointVertexCollisionStrategy() const
TypeStrategy getTypeStrategy() const
bool getReplaceOnFailure() const
void setTupleSizeStrategy(TupleSizeStrategy s)
void setPointVertexCollisionStrategy(PointVertexCollisionStrategy s)
Use storage with greatest precision (float > int)
void setFailureStrategy(FailureStrategy s)
Use the larger of the two tuple sizes.
GA_AttributeOwner
Definition: GA_Types.h:33
A map of string to various well defined value types.
Definition: UT_Options.h:84
void setTypeStrategy(TypeStrategy s)
getOption("OpenEXR.storage") storage
Definition: HDK_Image.dox:276
Replace existing attribute's options entirely.
Return an invalid result (NULL pointer or invalid reference)
GA_Storage
Definition: GA_Types.h:49