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
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:190
void setStorageStrategy(StorageStrategy s)
Specify when and how to reuse an existing attribute.
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.
GLsizeiptr size
Definition: glcorearb.h:663
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:42
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:48
GLenum src
Definition: glcorearb.h:1792