HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_AIFMerge.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_AIFMerge.h ( GA Library, C++)
7  *
8  * COMMENTS: Attribute Interface for merging
9  */
10 
11 #ifndef __GA_AIFMerge__
12 #define __GA_AIFMerge__
13 
14 #include "GA_API.h"
15 
16 
17 class GA_Attribute;
18 class GA_MergeMap;
19 
20 
21 /// @brief Attribute Interface for merging attribute data between details
22 ///
23 /// This class provides an interface used to copy attribute data from one
24 /// detail to another detail. The @b source detail is const and contains the
25 /// geometry which will be merged into the @b destination detail.
26 ///
27 /// Merging is done in stages:
28 /// @li Initially, the attributes on the source detail (the one being merged
29 /// into the destination) are iterated over and if there's a matching
30 /// "destination" attribute, the @c destroyDestination() method is called.<br>
31 /// This gives the merging interface a chance to destroy any attributes on the
32 /// destination (depending on the options in the GA_MergeMap). The method
33 /// will be called once for each attribute on the source detail.<br>
34 /// This provides the opportunity to delete attributes on the detail prior to
35 /// the re-allocation of attribute arrays.
36 ///
37 /// @li If @c map.getMergeStrategy() is not @c
38 /// GA_MergeOptions::MERGE_INTERLEAVE, then, the @c growArray() method is
39 /// called. By default, this will simply call @c
40 /// GA_Attribute::setArraySize() with the new size. However, this method
41 /// provides the opportunity to perform optimizations in copying data from
42 /// the source.
43 ///
44 /// @li After the destination arrays have been resized to accommodate new
45 /// elements, (or modify) attributes on the destination attribute, the
46 /// @c addDestination() method will be called to create new attributes
47 /// on the desintion detail. The method will be called for each attribute on
48 /// the source detail.
49 ///
50 /// @li The last stage of a merge is the @c copyArray() method. At this point,
51 /// the attribute should have all the storage allocated and it should be as
52 /// simple as using the source and destination iterators to copy the data.
53 /// If optimizations are made in the @c growArray() method, you will most
54 /// likely have to alter behaviour based on the @c map.getMergeStrategy().
55 ///
57 {
58 public:
59  GA_AIFMerge();
60  virtual ~GA_AIFMerge();
61 
62  /// The @c destroyDestination() method is used to delete attributes on the
63  /// destination (dattrib). These are attributes which will not
64  /// survive the merge.
65  ///
66  /// @param map The merge options
67  /// @param dattrib NULL or the existing destination attribute
68  /// @param sattrib The source attribute
69  virtual void destroyDestination(const GA_MergeMap &map,
70  GA_Attribute *dattrib,
71  const GA_Attribute &sattrib) const = 0;
72 
73  /// The @c addDestination() method is used to either @b create or @b modify
74  /// attributes on the destination. For example, this method can be used to
75  /// change storage, tuple size, etc. on an attribute, or to create an
76  /// entirely new attribute.
77  /// The dattrib parameter will be set to point to an existing
78  /// attribute on the destination detail.
79  /// @param map The merge options
80  /// @param dattrib NULL or the existing destination attribute
81  /// @param sattrib The source attribute
82  virtual GA_Attribute *addDestination(const GA_MergeMap &map,
83  GA_Attribute *dattrib,
84  const GA_Attribute &sattrib) const = 0;
85 
86  /// The @c growArray() method is responsible for growing the array. The
87  /// default behaviour is to call @c GA_Attribute::setArraySize(). This
88  /// method is only called if the merge strategy is not set to
89  /// @c GA_MergeOptions::MERGE_INTERLEAVE. It may be possible to perform
90  /// optimizations depending on how data is stored.
91  /// @param map The merge options
92  /// @param dattrib NULL or the existing destination attribute
93  /// @param sattrib The source attribute
94  ///
95  /// The default behaviour is to call: @code
96  /// dattrib.setArraySize( map.getDestCapacity(dattrib.getOwner()) );
97  /// @endcode
98  virtual void growArray(const GA_MergeMap &map,
99  GA_Attribute &dattrib,
100  const GA_Attribute *sattrib) const;
101 
102  /// The @c copyArray() method is responsible for copying the data from the
103  /// source to the destination attribute. The @c GA_MergeMap provides
104  /// all the information necessary for mapping the source data to the
105  /// destination.
106  ///
107  /// Note: The destination attribute's AIFMerge is used, and it's possible
108  /// that the source attribute is NULL (indicating that there's no data to
109  /// copy).
110  /// @code
111  /// bool
112  /// Example::mergeAppend(GA_MergeMap &map, const GA_Attribute *src)
113  /// {
114  /// if (src) {
115  /// // Copy data from the src array to my array
116  /// const GA_Range &di = map.getDestIterator(getOwner());
117  /// const GA_Range &si = map.getSourceIterator(getOwner());
118  /// copyArray(*this, di, src, si);
119  /// }
120  /// }
121  ///
122  /// bool
123  /// ExampleMergeAIF::copyArray(GA_MergeMap &map, GA_Attribute &d, const GA_Attribute *s) const {
124  /// Example *da = dynamic_cast<Example *>(&d);
125  /// if (da)
126  /// da->mergeAppend(map, s);
127  /// }
128  /// @endcode
129  /// @param map The merge options
130  /// @param dattrib NULL or the existing destination attribute
131  /// @param sattrib The source attribute
132  virtual bool copyArray(const GA_MergeMap &map,
133  GA_Attribute &dattrib,
134  const GA_Attribute *sattrib) const = 0;
135 
136  /// The @c destroyMismatchedType() function is a convenience function to
137  /// use the options in GA_MergeMap to handle attributes of different types.
138  ///
139  /// The method should only be called if the dest and src
140  /// attributes are different.
141  ///
142  /// This should only be called from within @c destroyDestination()
143  ///
144  /// @code
145  /// void
146  /// ExampleMergeAIF::destroyDestination(GA_MergeMap &map, GA_Attribute *dest, const GA_Attribute &s) const {
147  /// Example *da = dynamic_cast<Example *>(dest);
148  /// if (!da)
149  /// GA_AIFMerge::destroyMismatchedType(map, dest, s);
150  /// }
151  /// @endcode
152  ///
153  /// @b Note: It's possible for dest to be NULL.
154  /// @param map The merge options
155  /// @param dest NULL or the existing destination attribute
156  /// @see GA_MergeOptions
157  static bool destroyMismatchedType(const GA_MergeMap &map,
158  GA_Attribute *dest);
159 
160  /// The @c addMismatchedType() function is a convenience function to use
161  /// the options in GA_MergeMap to handle attributes of different types.
162  /// There are three possible types of return values:
163  /// @li The original mis-matched attribute. This will happen if the dest
164  /// attribute passed in is a different type than the source attribute,
165  /// but the merge options specify to keep the original attribute.
166  /// @li A new attribute of the same type as the source. This should only
167  /// really happen if the dest parameter was NULL.
168  /// @li A NULL pointer. This will happen if it wasn't possible to call @c
169  /// clone() on the source attribute.
170  ///
171  /// The method should only be called if the dest and src attributes are
172  /// different.
173  ///
174  /// This should only be called from within @c addDestination()
175  ///
176  /// @code
177  /// GA_Attribute *
178  /// ExampleMergeAIF::addDestination(GA_MergeMap &map, GA_Attribute *dest, const GA_Attribute &s) const {
179  /// Example *da = dynamic_cast<Example *>(dest);
180  /// if (!da)
181  /// {
182  /// dest = GA_AIFMerge::addMismatchedType(map, dest, s);
183  /// da = dynamic_cast<Example *>(dest);
184  /// return da;
185  /// }
186  /// return da;
187  /// }
188  /// @endcode
189  ///
190  /// @b Note: It's possible for dest to be NULL.
191  /// @param map The merge options
192  /// @param dest NULL or the existing destination attribute
193  /// @param src The source attribute
194  /// @see GA_MergeOptions
195  static GA_Attribute *addMismatchedType(const GA_MergeMap &map,
196  GA_Attribute *dest,
197  const GA_Attribute &src);
198 
199  /// Convenience function to deal with changing tuple sizes (based on
200  /// merging strategy)
201  /// The function returns true if the tuple storage match, false if there's
202  /// an irreconcilable difference.
203  /// This should be called from within @c addDestination(). If the function
204  /// returns false, then no attribute should be returned from @c
205  /// addDestination() (indicating no merging).
206  /// @param map The merge options
207  /// @param dest The existing destination attribute
208  /// @param src The source attribute
209  /// @see GA_MergeOptions
210  static bool checkTupleStorage(const GA_MergeMap &map,
211  GA_Attribute &dest,
212  const GA_Attribute &src);
213 
214  /// Convenience function to deal with changing tuple storage (based on
215  /// merging strategy).
216  /// The function returns true if the tuple sizes match, false if there's an
217  /// irreconcilable difference.
218  /// This should be called from within @c addDestination(). If the function
219  /// returns false, then no attribute should be returned from @c
220  /// addDestination() (indicating no merging).
221  /// @param map The merge options
222  /// @param dest The existing destination attribute
223  /// @param src The source attribute
224  /// @see GA_MergeOptions
225  static bool checkTupleSize(const GA_MergeMap &map,
226  GA_Attribute &dest,
227  const GA_Attribute &src);
228 };
229 
230 #endif
Definition of a geometry attribute.
Definition: GA_Attribute.h:190
The merge map keeps track of information when merging details.
Definition: GA_MergeMap.h:53
#define GA_API
Definition: GA_API.h:12
Attribute Interface for merging attribute data between details.
Definition: GA_AIFMerge.h:56
GLenum src
Definition: glcorearb.h:1792