HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_DataArrayTuple.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_DataArrayTuple.h ( GA Library, C++)
7  *
8  * COMMENTS: Maintains an tuple of GA_DataArray objects.
9  * This is a tuple of arrays.
10  */
11 
12 #ifndef __GA_DataArrayTuple__
13 #define __GA_DataArrayTuple__
14 
15 #include "GA_API.h"
17 #include "GA_Types.h"
18 
19 #include <UT/UT_Assert.h>
20 #include <UT/UT_UniquePtr.h>
21 #include <UT/UT_BitArray.h>
22 #include <UT/UT_VectorTypes.h>
23 
24 #include <SYS/SYS_Types.h>
25 
26 class GA_DataArray;
27 class GA_Defaults;
28 class GA_Range;
29 class GA_MergeMap;
30 class GA_LoadMap;
31 class GA_Defragment;
32 class UT_BitArray;
33 class UT_JSONWriter;
34 class UT_JSONParser;
35 class UT_MemoryCounter;
36 class UT_Options;
37 class GA_SaveOptions;
38 
39 /// @brief A tuple of scalar arrays
40 ///
41 /// This class maintains a tuple of arrays. For example storing a position is
42 /// kept as three distinct arrays (one for x, y and z). The storage for all
43 /// arrays is uniform.
44 ///
45 /// See also: @ref JSON-GA_DataArrayTuple
46 ///
47 /// @see GA_DataArray
48 
50 {
51 public:
52  /// Regardless of packing, we always have one GA_DataArray for
53  /// each of our tuple_size components. Packing causes the first
54  /// set of these data arrays to share data tables and store their
55  /// actual data in an interleaved format. If tuplesize is larger
56  /// than the packing size, the extra components are normal arrays,
57  /// so P + Pw works as expected with a PACK_VECTOR3
59  {
62  };
63 
67 
68  /// Report memory usage
69  int64 getMemoryUsage(bool inclusive) const;
70 
71  /// Count memory usage using a UT_MemoryCounter in order to count
72  /// shared memory correctly.
73  /// If inclusive is true, the size of this object is counted,
74  /// else only memory owned by this object is counted.
75  /// If this is pointed to by the calling object, inclusive should be true.
76  /// If this is contained in the calling object, inclusive should be false.
77  /// (Its memory was already counted in the size of the calling object.)
78  void countMemory(UT_MemoryCounter &counter, bool inclusive) const;
79 
81 
82  /// Changing the storage requires a copy iterator which accesses each and
83  /// every element of the array and the defaults
84  /// The @c allow_packing parameter should be set if the attribute allows it.
85  void setStorage(GA_Storage storage,
86  const GA_Range &copy_iterator,
87  const GA_Defaults &defs,
88  bool allow_packing=false);
89 
90  /// Setting the tuple size requires the array_size and the defaults
91  void setTupleSize(int tuple_size,
92  GA_Offset array_size, const GA_Defaults &defs,
93  ga_Packing packing = PACK_NONE);
94 
95  /// This method grows each array of the tuple
96  void setArraySize(GA_Offset size);
97 
98  /// This method queries the (common) size of the arrays.
99  GA_Offset getArraySize() const;
100 
101  /// Try to compress data pages
102  /// Will compress *all* pages overlapping the specified offset range.
103  void tryCompressAllPages(
104  GA_Offset start_offset = GA_Offset(0),
105  GA_Offset end_offset = GA_INVALID_OFFSET);
106 
107  /// Harden data pages
108  /// Will harden *all* pages overlapping the specified offset range.
109  void hardenAllPages(
110  GA_Offset start_offset = GA_Offset(0),
111  GA_Offset end_offset = GA_INVALID_OFFSET);
112 
113  void mergeGrowArrayAndCopy(const GA_MergeMap &map,
114  GA_AttributeOwner owner,
115  const GA_DataArrayTuple &src);
116 
117  GA_Storage getStorage() const { return myStorage; }
118  int getTupleSize() const { return myTupleSize; }
119  ga_Packing getPacking() const { return myPacking; }
120  GA_DataArray *getData(int tuple_index)
121  {
122  UT_ASSERT_P(tuple_index >= 0);
123  UT_ASSERT_P(tuple_index < myTupleSize);
124  return myData[tuple_index];
125  }
126  const GA_DataArray *getData(int tuple_index) const
127  {
128  UT_ASSERT_P(tuple_index >= 0);
129  UT_ASSERT_P(tuple_index < myTupleSize);
130  return myData[tuple_index];
131  }
132 
133  /// @{
134  /// Interface for defragmentation
135  void defragment(const GA_Defragment &defrag);
136  /// @}
137 
138  /// @{
139  /// Access to data as arrays of tuples
140  const GA_DataArray *const*getDataPtr() const { return myData; }
141  GA_DataArray *const*getDataPtr() { return myData; }
142  /// @}
143 
144  /// @cond INTERNAL
145  GA_Private::ga_DataArrayPageTableImplV3 * getPageTableImplV3();
146  /// @endcond
147 
148  /// Save data to JSON schema.
149  /// @section JSON-GA_DataArrayTuple JSON Schema: GA_DataArrayTuple
150  /// The data values are stored as an array of structs. That is, if the
151  /// DataArrayTuple is a 2-vector (tuple size 2) containing 4 elements, the
152  /// value array will be an array of 4 2-vectors (i.e. [ [0,0], [1,1],
153  /// [2,2], [3,3] ]). For single valued (tuple size == 1), a single array
154  /// of values is saved out. The keyword for this is "arrays" vs. "tuples".
155  /// @code
156  /// {
157  /// "name" : "GA_DataArrayTuple",
158  /// "description : "A tuple of scalar arrays",
159  /// "type" : "orderedmap",
160  /// "properties" :
161  /// {
162  /// "size": {
163  /// "type" : "integer",
164  /// "minimum" : 1,
165  /// },
166  /// "storage": {
167  /// "type" : "string",
168  /// "enum" : [ "uint8","int8","int16","int32","int64",
169  /// "fpreal16", "fpreal32", "fpreal64" ],
170  /// },
171  /// "tuples": {
172  /// "type" : "array",
173  /// "description" :
174  /// "Saved as an array of structs (not a struct of arrays)."
175  /// "items" : {
176  /// "description" :
177  /// "Each item is a number array for each tuple",
178  /// "type" : "array"
179  /// "items" : "number",
180  /// }
181  /// }
182  /// "arrays": {
183  /// "type" : "array",
184  /// "description" :
185  /// "For scalars, just save out the single GA_DataArray",
186  /// "items" : { "$ref":"GA_DataArray" }
187  /// }
188  /// }
189  /// }
190  /// @endcode
191  /// @see @ref JSON_FileFormat
192  bool jsonSave(UT_JSONWriter &w, const GA_Range &it,
193  const GA_SaveOptions *options) const;
194 
195  static bool jsonSave(UT_JSONWriter &w, const GA_Range &it,
196  const GA_SaveOptions *options,
197  const GA_DataArray * const *data, int data_tuple_size,
198  GA_Storage data_storage, ga_Packing data_packing);
199 
200  /// Load from a JSON stream
201  bool jsonLoad(UT_JSONParser &w,
202  const GA_LoadMap &map, GA_AttributeOwner owner);
203 
204  static bool jsonLoad(UT_JSONParser &w,
205  const GA_LoadMap &map, GA_AttributeOwner owner,
206  GA_DataArray * const *data, int data_tuple_size,
207  GA_Storage data_storage, ga_Packing data_packing);
208 
209  /// Save with an integer translation. This method is just like the
210  /// standard jsonSave() method. However each value is used as an index
211  /// into the integer array. The value stored in the array is written
212  /// instead of the raw value.
213  /// @code
214  /// for (GA_Iterator it(range); !it.atEnd(); ++it) {
215  /// idx = getInteger(it.getOffset());
216  /// json.write( idx < 0 || idx >= map.entries() ? -1 : map(idx) );
217  /// }
218  /// @endcode
219  /// @see GA_DataArray::jsonSave()
220  bool jsonSave(UT_JSONWriter &w, const GA_Range &range,
221  const GA_SaveOptions *options,
222  const UT_IntArray *map, int defvalue=-1) const;
223 
224  static bool jsonSave(UT_JSONWriter &w, const GA_Range &range,
225  const GA_SaveOptions *options,
226  const UT_IntArray *map, int defvalue,
227  const GA_DataArray * const *data, int data_tuple_size,
228  GA_Storage data_storage, ga_Packing data_packing);
229 
230  // Sets bits for all pages with differing values.
231  void comparePages(UT_BitArray &pages, const GA_DataArrayTuple &other) const;
232 
233 protected:
234  GA_DataArray *buildDataArray(int idx, GA_Offset length, const GA_Defaults &defs);
235  bool isSharedArray(int idx) const;
236 
237 private:
238  typedef UT_UniquePtr<UT_BitArray> ga_BitArrayPtr;
239 
240  static bool jsonLoadSOA(UT_JSONParser &w, const GA_LoadMap &map,
241  GA_AttributeOwner owner,
242  GA_DataArray * const *data,
243  int data_tuple_size);
244  static bool jsonLoadAOS(UT_JSONParser &w, const GA_LoadMap &map,
245  GA_AttributeOwner owner,
246  GA_DataArray *const *data,
247  int data_tuple_size,
248  GA_Storage data_storage);
249  static bool jsonSaveRawPageData(UT_JSONWriter &w,
250  const GA_Range &range,
251  GA_Size output_page_size,
252  const int *packing,
253  int n_packing_entries,
254  const ga_BitArrayPtr *const_output_pages,
255  const UT_IntArray *map,
256  int defvalue,
257  const GA_DataArray * const *data,
258  int data_tuple_size,
259  GA_Storage data_storage);
260 
261  static bool jsonLoadRawPageData(UT_JSONParser &p,
262  const GA_LoadMap &map,
263  GA_AttributeOwner owner,
264  GA_Size input_page_size,
265  const int *packing,
266  int n_packing_entries,
267  ga_BitArrayPtr *const_input_pages,
268  GA_DataArray * const *data,
269  int data_tuple_size,
270  GA_Storage data_storage,
271  ga_Packing data_packing);
272 
273  GA_DataArray **myData;
274  int myTupleSize;
275  GA_Storage myStorage;
276  ga_Packing myPacking;
277 };
278 
279 #endif
GLenum GLint * range
Definition: glcorearb.h:1925
Class which stores the default values for a GA_Attribute.
Definition: GA_Defaults.h:35
getFileOption("OpenEXR:storage") storage
Definition: HDK_Image.dox:276
The merge map keeps track of information when merging details.
Definition: GA_MergeMap.h:53
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:795
const GA_DataArray *const * getDataPtr() const
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
ga_Packing getPacking() const
exint GA_Size
Defines the bit width for index and offset types in GA.
Definition: GA_Types.h:236
#define GA_INVALID_OFFSET
Definition: GA_Types.h:687
A range of elements in an index-map.
Definition: GA_Range.h:42
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:39
GA_Size GA_Offset
Definition: GA_Types.h:646
#define UT_ASSERT_P(ZZ)
Definition: UT_Assert.h:155
GA_DataArray * getData(int tuple_index)
An array of numbers with various storage types.
Definition: GA_DataArray.h:49
long long int64
Definition: SYS_Types.h:116
Options during loading.
Definition: GA_LoadMap.h:42
Defragmentation of IndexMaps.
Definition: GA_Defragment.h:45
A tuple of scalar arrays.
GLsizeiptr size
Definition: glcorearb.h:664
GA_AttributeOwner
Definition: GA_Types.h:35
A map of string to various well defined value types.
Definition: UT_Options.h:84
GA_DataArray *const * getDataPtr()
LeafData & operator=(const LeafData &)=delete
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
GA_Storage getStorage() const
GA_Storage
Definition: GA_Types.h:51
Definition: format.h:895
const GA_DataArray * getData(int tuple_index) const
int getTupleSize() const
GLenum src
Definition: glcorearb.h:1793