HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_AIFEdit.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_AIFEdit.h ( GA Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __GA_AIFEdit__
12 #define __GA_AIFEdit__
13 
14 #include "GA_API.h"
15 #include "GA_Types.h"
16 
17 #include <UT/UT_VectorTypes.h>
18 
19 #include <SYS/SYS_Types.h>
20 
21 #include <stddef.h>
22 
23 
25 class GA_Attribute;
26 class GA_IndexMap;
27 class GA_Range;
28 
29 class UT_JSONParser;
30 class UT_JSONWriter;
31 class UT_String;
32 class UT_StringArray;
33 
34 
35 /// @brief Class for mapping between an index and an attribute data offset.
36 ///
37 /// GA_AIFEditDelta objects store element deltas by an ordered index, not
38 /// necessarily corresponding to the element's order in an GA_IndexMap.
39 /// This class maps between that index and the corresponding data offset
40 /// in a particular attribute.
41 ///
42 /// The simplest map is to use the ordered index from a GA_IndexMap as the
43 /// delta index.
44 /// TODO: Add a virtual getDeltaIndexTraverser which yields data offsets in
45 /// delta index order. This may be more efficient for
46 /// GA_AIFEditDelta::apply
47 
49 {
50 public:
51  virtual ~GA_AIFEditDeltaMap() {}
52 
53  virtual GA_Offset getDataOffset(GA_Index delta_index) const = 0;
54  virtual GA_Index getDeltaIndex(GA_Offset data_offset) const = 0;
55 };
56 
57 /// @brief Simple GA_AIFEditDeltaMap mapping data offset to element's ordered
58 // index.
59 
61 {
62 public:
64  : myIndexMap(index_map) {}
65 
66  GA_Offset getDataOffset(GA_Index delta_index) const override;
67  GA_Index getDeltaIndex(GA_Offset data_offset) const override;
68 private:
69  const GA_IndexMap &myIndexMap;
70 };
71 
72 /// @brief Base class for supplying coordinate frames.
73 ///
74 /// Coordinate frames are used to map between a delta relative to that
75 /// coordinate frame's local space and one relative to world space. A
76 /// coordinate frame will typically be stored for each index stored in
77 /// the GA_AIFEditDelta.
78 
80 {
81 public:
83 
84  virtual UT_Matrix3R getLocalToWorldTransform(GA_Index) const = 0;
85  virtual UT_Matrix3R getWorldToLocalTransform(GA_Index) const = 0;
86 };
87 
88 /// @brief Base class for specifying symmetry for operations.
89 ///
90 /// The symmetry class is used to generalize symmetry at the individual
91 /// element level.
92 
94 {
95 public:
96  virtual ~GA_AIFEditSymmetry() {}
97 
98  /// Return the delta index for the element symmetric to the element that
99  /// corresponds to the given input_delta_index, -1 if none. If symmetry
100  /// is found, xform will be set to the transform that will map the input
101  /// element's delta to the corresponding delta for the output element.
102  virtual GA_Index findSymmetry(GA_Index input_delta_index,
103  const GA_AIFEditDeltaMap &map,
104  UT_Matrix3R &xform) = 0;
105 };
106 
107 /// @brief Base class for storing snapshots during an edit operation.
108 ///
109 /// Opaque base class for snapshots of attribute values taken during an edit
110 /// operation.
111 
113 {
114 public:
115  virtual ~GA_AIFEditSnapshot() {}
116 };
117 
118 /// @brief Interface class for loading legacy tuple delta data.
119 ///
120 /// An interface class to allow a GA_AIFEditDelta implementation to load a
121 /// legacy stream without specific knowledge of the stream format.
123 {
124 public:
126 
127  virtual int getTupleSize() const = 0;
128  virtual GA_Size getDeltaCount() const = 0;
129 
130  /// @{
131  /// Extracting a delta will consume it, so these methods should be called
132  /// exactly getDeltaCount() times.
133  virtual bool extractDelta(GA_Index &index,
134  UT_Fpreal64Array &delta) = 0;
135  virtual bool extractDelta(GA_Index &index,
136  UT_Int64Array &delta) = 0;
137  virtual bool extractDelta(GA_Index &index,
138  UT_Fpreal32Array &delta) = 0;
139  virtual bool extractDelta(GA_Index &index,
140  UT_Int32Array &delta) = 0;
141  /// @}
142 };
143 
144 /// @brief Interface class for loading legacy index pair delta data.
145 ///
146 /// An interface class to allow a GA_AIFEditDelta implementation to load a
147 /// legacy stream without specific knowledge of the stream format.
149 {
150 public:
152 
153  virtual int getObjectCount() const = 0;
154 
155  virtual int getPropertyCount() const = 0;
156  virtual bool getPropertyInfo(int prop_index, UT_String &name,
158  int &size) const = 0;
159  virtual bool getPropertyDefault(int prop_index,
160  UT_StringArray &def) const = 0;
161  virtual bool getPropertyDefault(int prop_index,
162  UT_IntArray &def) const = 0;
163  virtual bool getPropertyDefault(int prop_index,
164  UT_FloatArray &def) const = 0;
165  virtual bool getPropertyValue(int obj_index, int prop_index,
166  UT_StringArray &value) const = 0;
167  virtual bool getPropertyValue(int obj_index, int prop_index,
168  UT_IntArray &value) const = 0;
169  virtual bool getPropertyValue(int obj_index, int prop_index,
170  UT_FloatArray &value) const = 0;
171 
172  /// This method should be called once per object immediately before
173  /// extracting that object's deltas.
174  virtual GA_Size extractObjectDeltaCount() = 0;
175 
176  /// Extracting a delta will consume it, so this method should be called
177  /// exactly extractObjectDeltaCount() times for each object.
178  /// @code
179  /// for (i = 0; i < stream.getObjectCount(); i++)
180  /// {
181  /// GA_Size delta_count = stream.extractObjectDeltaCount();
182  ///
183  /// for (j = 0; j < delta_count; j++)
184  /// if (!stream.extractObjectDelta(delta_index, delta_data))
185  /// return error();
186  /// }
187  ///
188  /// @endcode
189  virtual bool extractObjectDelta(GA_Index &index,
190  fpreal &delta) = 0;
191 };
192 
193 /// @brief Base class to store recorder data.
194 ///
195 /// This class is responsible for maintaining changes to an attribute. The
196 /// class must be able to save/load to a JSON stream.
197 ///
198 /// The deltas are used by painting, editing and other modelling operations.
199 /// For example, an undo mechanism might be implemented by:
200 /// @code
201 /// changeAttrib()
202 /// {
203 /// GA_AIFEditDelta *delta;
204 /// GA_Attribute *P;
205 /// GA_AIFEditSnapshot *snapshot;
206 /// delta = P->getAIFEdit()->createDelta(); // TODO: NULL ptr check
207 /// snapshot = delta->startEdit(P, GA_Range(P->getIndexMap()));
208 /// letUserEditPoints(P);
209 /// delta->endEdit(snapshot, GA_AIFEditDeltaIndexMap(P->getIndexMap()));
210 /// }
211 ///
212 /// doUndoRedo(GA_Attribute *P, GA_AIFEditDelta *delta, bool undo)
213 /// {
214 /// delta->applyEdit(P, GA_AIFEditDeltaIndexMap(P->getIndexMap()), undo);
215 /// }
216 /// @endcode
218 {
219 public:
220  GA_AIFEditDelta();
221  virtual ~GA_AIFEditDelta();
222 
223  virtual int64 getMemoryUsage(bool inclusive=false) const = 0;
224 
225  /// Create a new (empty) instance of the derived class.
226  virtual GA_AIFEditDelta *createNew() const = 0;
227 
228  /// Create a copy of this delta.
229  virtual GA_AIFEditDelta *clone() const = 0;
230 
231  /// Test compatibility with a particular attribute.
232  virtual bool isCompatible(const GA_Attribute *attrib) const = 0;
233 
234  /// Test compatibility with another delta. Compatibility in this case
235  /// refers to ability to merge the deltas.
236  virtual bool isCompatible(const GA_AIFEditDelta *delta) const = 0;
237 
238  /// The @c startEdit() method allows the snapshot to see the state of
239  /// the attribute @b before any edits are made to the data.
240  virtual GA_AIFEditSnapshot *startEdit(const GA_Attribute *attrib,
241  GA_Offset element) = 0;
242  virtual GA_AIFEditSnapshot *startEdit(const GA_Attribute *attrib,
243  const GA_Range &elements) = 0;
244  /// After editing, the @c endEdit() method is called. This allows the
245  /// computation of the actual delta from the snapshot. Do not use the
246  /// snapshot again after calling this method. The optional coordinate
247  /// frames will be used to store the delta relative to the local frame
248  /// if supported.
249  virtual bool endEdit(GA_AIFEditSnapshot *snapshot,
250  const GA_AIFEditDeltaMap &map,
251  const GA_AIFEditDeltaCoordFrames *frames=0) = 0;
252 
253  /// Merge a separate edit into this edit, matching elements by the
254  /// internal ordered index. The optional coordinate frames will be
255  /// used to store the delta relative to the local frame if supported.
256  virtual bool mergeEdit(const GA_AIFEditDelta *other,
257  const GA_AIFEditDeltaCoordFrames *otherfr = 0,
258  const GA_AIFEditDeltaCoordFrames *localfr = 0,
259  bool inverse = false) = 0;
260 
261  /// Merge the edits symmetric to those in a separate edit into this edit,
262  /// matching elements by internal ordered index. The optional coordinate
263  /// frames will be used to store the delta relative to the local frame if
264  /// supported.
265  virtual bool mergeSymmetricEdit(const GA_AIFEditDelta *other,
266  const GA_AIFEditDeltaCoordFrames *otherfr,
267  GA_AIFEditSymmetry &symmetry,
268  const GA_AIFEditDeltaMap &map,
269  const GA_AIFEditDeltaCoordFrames *localfr,
270  bool inverse = false) = 0;
271 
272  /// Apply this snapshot's edit delta to the attribute, optionally
273  /// restricting which delta indices get applied. The optional coordinate
274  /// frames will be used to apply deltas previously mapped to local space
275  /// in world space (if supported).
276  virtual bool applyEdit(GA_Attribute *attrib,
277  const GA_AIFEditDeltaMap &map,
278  const UT_Int64Array *subset = 0,
279  const GA_AIFEditDeltaCoordFrames *frames = 0,
280  bool inverse = false) const = 0;
281 
282  /// Scale and apply this snapshot's edit delta to the attribute, optionally
283  /// restricting which delta indices get applied. This operation is not
284  /// supported by all attributes supporting AIF_Edit. The optional
285  /// coordinate frames will be used to apply deltas previously mapped to
286  /// local space in world space (if supported).
287  virtual bool applyScaledEdit(GA_Attribute *attrib,
288  fpreal scale,
289  const GA_AIFEditDeltaMap &map,
290  const UT_Int64Array *subset = 0,
291  const GA_AIFEditDeltaCoordFrames *frames = 0,
292  bool inverse = false) const = 0;
293 
294  /// @{
295  /// Clear currently stored deltas. The first method, zeroDeltas(), is a
296  /// lighter-weight clear that will endeavour to hold onto and reuse most
297  /// allocated memory.
298  virtual void zeroDeltas() = 0;
299  virtual void clearDeltas() = 0;
300  /// @}
301 
302  /// Query the number of indices that have recorded deltas.
303  virtual GA_Size getDeltaCount() const = 0;
304 
305  /// Query the indices that have recorded deltas. Note that these are the
306  /// delta indices, not the orders of the elements in the GA_IndexMap.
307  virtual void getDeltaIndices(UT_Int64Array &indices) const = 0;
308 
309  /// @section JSON-GA_AIFEditDelta JSON Schema: GA_AIFEditDelta
310  ///
311  /// The schema for a delta consists of an ordered map (array) with two
312  /// elements. The first, "type", is an ordered pair (array) providing
313  /// the information needed to allocate a subclass of GA_AIFEditDelta.
314  /// The second, "data", holds. the private data for the delta, which is
315  /// saved and loaded by the GA_AIFEditDelta subclass.
316  ///
317  /// @code
318  /// [
319  /// "name" : "GA_AIFEditDelta",
320  /// "description" :
321  /// "A delta is defined by an ordered map (array) with two
322  /// elements, the definition ("type") and the private data
323  /// ("data").
324  /// "type" : "orderedmap",
325  /// "properties": {
326  /// "type": {
327  /// "type" : "string",
328  /// "description" : "Ordered pair (type name, args)",
329  /// },
330  /// "data": {
331  /// "type" : "string",
332  /// "description" : "Internal delta data",
333  /// },
334  /// }
335  /// ]
336  /// @endcode
337  ///
338  /// @section JSON-GA_AIFEditDelta-Type JSON Schema: GA_AIFEditDelta-Type
339  /// The delta "type" field is an ordered pair containing the attribute type
340  /// and an object holding additional type arguments needed to recreate the
341  /// delta.
342  /// @code
343  /// {
344  /// "name" : "GA_AIFEditDelta-Type",
345  /// "description" : "An ordered pair defining the attribute",
346  /// "type" : "array",
347  /// "items": [
348  /// <"Attribute Type Name">, <"Type Arguments">
349  /// ],
350  /// }
351  /// @endcode
352  /// @see @ref GA_AttributeType
353  static bool jsonSaveDelta(UT_JSONWriter &w,
354  const GA_AIFEditDelta *delta);
355  static bool jsonLoadDelta(UT_JSONParser &p,
356  GA_AIFEditDelta *&delta);
357 
358  /// GA_AttributeType::jsonLoadDeltaDefinition() is the counterpart to this
359  /// method.
360  virtual bool jsonSaveDefinition(UT_JSONWriter &w) const = 0;
361 
362  /// Save the delta object to a JSON stream.
363  virtual bool jsonSave(UT_JSONWriter &w) const=0;
364  /// Load a delta object from a JSON stream
365  virtual bool jsonLoad(UT_JSONParser &p) = 0;
366 
367  /// Load a legacy tuple delta. Only supported by some subclasses.
368  virtual bool legacyLoadTuple(
370  /// Load a legacy index pair delta. Only supported by some subclasses.
371  virtual bool legacyLoadIndexPair(
373 
374  /// @{
375  /// Query and set information about objects referenced by index pair data.
376  /// Only supported by some subclasses.
377  virtual int getObjectSetCount() const;
378  virtual void setObjectSetCount(int n);
379  virtual const GA_AIFIndexPairObjects *getObjects(int s = 0) const;
380  virtual GA_AIFIndexPairObjects *getObjects(int s = 0);
381  /// @}
382 
383  /// @{
384  /// The new & delete operators are overloaded to help with memory tracking.
385  /// Allocate new object
386  static void *operator new(size_t size);
387  /// In-place construction
388  static void *operator new(size_t size, void *p);
389  /// Deletion of an allocated object
390  static void operator delete(void *p, size_t size);
391  /// Get memory statistics
392  static void getAllocationStats(int64 &used, int64 &peak);
393  /// @}
394 };
395 
396 /// @brief AIF to record changes to attribute values
398 {
399 public:
400  /// Constructor
401  GA_AIFEdit();
402  /// Destructor
403  virtual ~GA_AIFEdit();
404 
405  /// Allocate a delta object for the attribute
406  virtual GA_AIFEditDelta *createDelta(const GA_Attribute *a) const=0;
407 };
408 
409 #endif
410 
A class to manage an ordered array which has fixed offset handles.
Definition: GA_IndexMap.h:63
Definition of a geometry attribute.
Definition: GA_Attribute.h:198
GLsizei GLenum const void * indices
Definition: glcorearb.h:406
getFileOption("OpenEXR:storage") storage
Definition: HDK_Image.dox:276
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1222
virtual ~GA_AIFEditDeltaCoordFrames()
Definition: GA_AIFEdit.h:82
GLdouble s
Definition: glad.h:3009
GA_AIFEditDeltaIndexMap(const GA_IndexMap &index_map)
Definition: GA_AIFEdit.h:63
JSON reader class which handles parsing of JSON or bJSON files.
Definition: UT_JSONParser.h:87
#define GA_API
Definition: GA_API.h:14
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:37
exint GA_Size
Defines the bit width for index and offset types in GA.
Definition: GA_Types.h:236
A range of elements in an index-map.
Definition: GA_Range.h:42
Base class for specifying symmetry for operations.
Definition: GA_AIFEdit.h:93
GA_Size GA_Offset
Definition: GA_Types.h:646
Base class for supplying coordinate frames.
Definition: GA_AIFEdit.h:79
GA_API const UT_StringHolder scale
GLdouble n
Definition: glcorearb.h:2008
Interface class for loading legacy tuple delta data.
Definition: GA_AIFEdit.h:122
long long int64
Definition: SYS_Types.h:116
virtual ~GA_AIFEditSnapshot()
Definition: GA_AIFEdit.h:115
Base class for storing snapshots during an edit operation.
Definition: GA_AIFEdit.h:112
GLuint const GLchar * name
Definition: glcorearb.h:786
GA_Size GA_Index
Define the strictness of GA_Offset/GA_Index.
Definition: GA_Types.h:640
virtual GA_Index getDeltaIndex(GA_Offset data_offset) const =0
GLsizeiptr size
Definition: glcorearb.h:664
virtual ~GA_AIFEditSymmetry()
Definition: GA_AIFEdit.h:96
fpreal64 fpreal
Definition: SYS_Types.h:277
GLuint index
Definition: glcorearb.h:786
Base class to store recorder data.
Definition: GA_AIFEdit.h:217
Interface class for loading legacy index pair delta data.
Definition: GA_AIFEdit.h:148
virtual ~GA_AIFEditDeltaMap()
Definition: GA_AIFEdit.h:51
virtual GA_Offset getDataOffset(GA_Index delta_index) const =0
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
Definition: core.h:1131
Simple GA_AIFEditDeltaMap mapping data offset to element's ordered.
Definition: GA_AIFEdit.h:60
AIF to record changes to attribute values.
Definition: GA_AIFEdit.h:397
GA_Storage
Definition: GA_Types.h:51
Class for mapping between an index and an attribute data offset.
Definition: GA_AIFEdit.h:48