HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Metadata.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2012-2018 DreamWorks Animation LLC
4 //
5 // All rights reserved. This software is distributed under the
6 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
7 //
8 // Redistributions of source code must retain the above copyright
9 // and license notice and the following restrictions and disclaimer.
10 //
11 // * Neither the name of DreamWorks Animation nor the names of
12 // its contributors may be used to endorse or promote products derived
13 // from this software without specific prior written permission.
14 //
15 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
19 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
20 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 // IN NO EVENT SHALL THE COPYRIGHT HOLDERS' AND CONTRIBUTORS' AGGREGATE
27 // LIABILITY FOR ALL CLAIMS REGARDLESS OF THEIR BASIS EXCEED US$250.00.
28 //
29 ///////////////////////////////////////////////////////////////////////////
30 
31 #ifndef OPENVDB_METADATA_HAS_BEEN_INCLUDED
32 #define OPENVDB_METADATA_HAS_BEEN_INCLUDED
33 
34 #include "version.h"
35 #include "Exceptions.h"
36 #include "Types.h"
37 #include "math/Math.h" // for math::isZero()
38 #include "util/Name.h"
39 #include <cstdint>
40 #include <iostream>
41 #include <string>
42 #include <vector>
43 
44 
45 namespace openvdb {
47 namespace OPENVDB_VERSION_NAME {
48 
49 /// @brief Base class for storing metadata information in a grid.
51 {
52 public:
55 
56  Metadata() {}
57  virtual ~Metadata() {}
58 
59  // Disallow copying of instances of this class.
60  Metadata(const Metadata&) = delete;
61  Metadata& operator=(const Metadata&) = delete;
62 
63  /// Return the type name of the metadata.
64  virtual Name typeName() const = 0;
65 
66  /// Return a copy of the metadata.
67  virtual Metadata::Ptr copy() const = 0;
68 
69  /// Copy the given metadata into this metadata.
70  virtual void copy(const Metadata& other) = 0;
71 
72  /// Return a textual representation of this metadata.
73  virtual std::string str() const = 0;
74 
75  /// Return the boolean representation of this metadata (empty strings
76  /// and zeroVals evaluate to false; most other values evaluate to true).
77  virtual bool asBool() const = 0;
78 
79  /// Return @c true if the given metadata is equivalent to this metadata.
80  bool operator==(const Metadata& other) const;
81  /// Return @c true if the given metadata is different from this metadata.
82  bool operator!=(const Metadata& other) const { return !(*this == other); }
83 
84  /// Return the size of this metadata in bytes.
85  virtual Index32 size() const = 0;
86 
87  /// Unserialize this metadata from a stream.
88  void read(std::istream&);
89  /// Serialize this metadata to a stream.
90  void write(std::ostream&) const;
91 
92  /// Create new metadata of the given type.
93  static Metadata::Ptr createMetadata(const Name& typeName);
94 
95  /// Return @c true if the given type is known by the metadata type registry.
96  static bool isRegisteredType(const Name& typeName);
97 
98  /// Clear out the metadata registry.
99  static void clearRegistry();
100 
101  /// Register the given metadata type along with a factory function.
102  static void registerType(const Name& typeName, Metadata::Ptr (*createMetadata)());
103  static void unregisterType(const Name& typeName);
104 
105 protected:
106  /// Read the size of the metadata from a stream.
107  static Index32 readSize(std::istream&);
108  /// Write the size of the metadata to a stream.
109  void writeSize(std::ostream&) const;
110 
111  /// Read the metadata from a stream.
112  virtual void readValue(std::istream&, Index32 numBytes) = 0;
113  /// Write the metadata to a stream.
114  virtual void writeValue(std::ostream&) const = 0;
115 };
116 
117 
118 #if OPENVDB_ABI_VERSION_NUMBER >= 5
119 
120 /// @brief Subclass to hold raw data of an unregistered type
122 {
123 public:
124  using ByteVec = std::vector<uint8_t>;
125 
126  explicit UnknownMetadata(const Name& typ = "<unknown>"): mTypeName(typ) {}
127 
128  Name typeName() const override { return mTypeName; }
129  Metadata::Ptr copy() const override;
130  void copy(const Metadata&) override;
131  std::string str() const override { return (mBytes.empty() ? "" : "<binary data>"); }
132  bool asBool() const override { return !mBytes.empty(); }
133  Index32 size() const override { return static_cast<Index32>(mBytes.size()); }
134 
135  void setValue(const ByteVec& bytes) { mBytes = bytes; }
136  const ByteVec& value() const { return mBytes; }
137 
138 protected:
139  void readValue(std::istream&, Index32 numBytes) override;
140  void writeValue(std::ostream&) const override;
141 
142 private:
143  Name mTypeName;
144  ByteVec mBytes;
145 };
146 
147 #else // if OPENVDB_ABI_VERSION_NUMBER < 5
148 
149 /// @brief Subclass to read (and ignore) data of an unregistered type
150 class OPENVDB_API UnknownMetadata: public Metadata
151 {
152 public:
153  UnknownMetadata() {}
154  Name typeName() const override { return "<unknown>"; }
155  Metadata::Ptr copy() const override { OPENVDB_THROW(TypeError, "Metadata has unknown type"); }
156  void copy(const Metadata&) override {OPENVDB_THROW(TypeError, "Destination has unknown type");}
157  std::string str() const override { return "<unknown>"; }
158  bool asBool() const override { return false; }
159  Index32 size() const override { return 0; }
160 
161 protected:
162  void readValue(std::istream&, Index32 numBytes) override;
163  void writeValue(std::ostream&) const override;
164 };
165 
166 #endif
167 
168 
169 /// @brief Templated metadata class to hold specific types.
170 template<typename T>
171 class TypedMetadata: public Metadata
172 {
173 public:
176 
177  TypedMetadata();
178  TypedMetadata(const T& value);
179  TypedMetadata(const TypedMetadata<T>& other);
180  ~TypedMetadata() override;
181 
182  Name typeName() const override;
183  Metadata::Ptr copy() const override;
184  void copy(const Metadata& other) override;
185  std::string str() const override;
186  bool asBool() const override;
187  Index32 size() const override { return static_cast<Index32>(sizeof(T)); }
188 
189  /// Set this metadata's value.
190  void setValue(const T&);
191  /// Return this metadata's value.
192  T& value();
193  const T& value() const;
194 
195  // Static specialized function for the type name. This function must be
196  // template specialized for each type T.
197  static Name staticTypeName() { return typeNameAsString<T>(); }
198 
199  /// Create new metadata of this type.
200  static Metadata::Ptr createMetadata();
201 
202  static void registerType();
203  static void unregisterType();
204  static bool isRegisteredType();
205 
206 protected:
207  void readValue(std::istream&, Index32 numBytes) override;
208  void writeValue(std::ostream&) const override;
209 
210 private:
211  T mValue;
212 };
213 
214 /// Write a Metadata to an output stream
215 std::ostream& operator<<(std::ostream& ostr, const Metadata& metadata);
216 
217 
218 ////////////////////////////////////////
219 
220 
221 inline void
222 Metadata::writeSize(std::ostream& os) const
223 {
224  const Index32 n = this->size();
225  os.write(reinterpret_cast<const char*>(&n), sizeof(Index32));
226 }
227 
228 
229 inline Index32
230 Metadata::readSize(std::istream& is)
231 {
232  Index32 n = 0;
233  is.read(reinterpret_cast<char*>(&n), sizeof(Index32));
234  return n;
235 }
236 
237 
238 inline void
239 Metadata::read(std::istream& is)
240 {
241  const Index32 numBytes = this->readSize(is);
242  this->readValue(is, numBytes);
243 }
244 
245 
246 inline void
247 Metadata::write(std::ostream& os) const
248 {
249  this->writeSize(os);
250  this->writeValue(os);
251 }
252 
253 
254 ////////////////////////////////////////
255 
256 
257 template <typename T>
258 inline
260 {
261 }
262 
263 template <typename T>
264 inline
265 TypedMetadata<T>::TypedMetadata(const T &value) : mValue(value)
266 {
267 }
268 
269 template <typename T>
270 inline
272  Metadata(),
273  mValue(other.mValue)
274 {
275 }
276 
277 template <typename T>
278 inline
280 {
281 }
282 
283 template <typename T>
284 inline Name
286 {
288 }
289 
290 template <typename T>
291 inline void
293 {
294  mValue = val;
295 }
296 
297 template <typename T>
298 inline T&
300 {
301  return mValue;
302 }
303 
304 template <typename T>
305 inline const T&
307 {
308  return mValue;
309 }
310 
311 template <typename T>
312 inline Metadata::Ptr
314 {
315  Metadata::Ptr metadata(new TypedMetadata<T>());
316  metadata->copy(*this);
317  return metadata;
318 }
319 
320 template <typename T>
321 inline void
323 {
324  const TypedMetadata<T>* t = dynamic_cast<const TypedMetadata<T>*>(&other);
325  if (t == nullptr) OPENVDB_THROW(TypeError, "Incompatible type during copy");
326  mValue = t->mValue;
327 }
328 
329 
330 template<typename T>
331 inline void
332 TypedMetadata<T>::readValue(std::istream& is, Index32 /*numBytes*/)
333 {
334  //assert(this->size() == numBytes);
335  is.read(reinterpret_cast<char*>(&mValue), this->size());
336 }
337 
338 template<typename T>
339 inline void
340 TypedMetadata<T>::writeValue(std::ostream& os) const
341 {
342  os.write(reinterpret_cast<const char*>(&mValue), this->size());
343 }
344 
345 template <typename T>
346 inline std::string
348 {
349  std::ostringstream ostr;
350  ostr << mValue;
351  return ostr.str();
352 }
353 
354 template<typename T>
355 inline bool
357 {
358  return !math::isZero(mValue);
359 }
360 
361 template <typename T>
362 inline Metadata::Ptr
364 {
365  Metadata::Ptr ret(new TypedMetadata<T>());
366  return ret;
367 }
368 
369 template <typename T>
370 inline void
372 {
375 }
376 
377 template <typename T>
378 inline void
380 {
382 }
383 
384 template <typename T>
385 inline bool
387 {
389 }
390 
391 
392 template<>
393 inline std::string
395 {
396  return (mValue ? "true" : "false");
397 }
398 
399 
400 inline std::ostream&
401 operator<<(std::ostream& ostr, const Metadata& metadata)
402 {
403  ostr << metadata.str();
404  return ostr;
405 }
406 
407 
422 
423 
424 ////////////////////////////////////////
425 
426 
427 template<>
428 inline Index32
429 StringMetadata::size() const
430 {
431  return static_cast<Index32>(mValue.size());
432 }
433 
434 
435 template<>
436 inline std::string
437 StringMetadata::str() const
438 {
439  return mValue;
440 }
441 
442 
443 template<>
444 inline void
445 StringMetadata::readValue(std::istream& is, Index32 size)
446 {
447  mValue.resize(size, '\0');
448  is.read(&mValue[0], size);
449 }
450 
451 template<>
452 inline void
453 StringMetadata::writeValue(std::ostream& os) const
454 {
455  os.write(reinterpret_cast<const char*>(&mValue[0]), this->size());
456 }
457 
458 } // namespace OPENVDB_VERSION_NAME
459 } // namespace openvdb
460 
461 #endif // OPENVDB_METADATA_HAS_BEEN_INCLUDED
462 
463 // Copyright (c) 2012-2018 DreamWorks Animation LLC
464 // All rights reserved. This software is distributed under the
465 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
Name typeName() const override
Return the type name of the metadata.
Definition: Metadata.h:128
void read(std::istream &)
Unserialize this metadata from a stream.
Definition: Metadata.h:239
Definition: ImfName.h:53
std::ostream & operator<<(std::ostream &ostr, const Metadata &metadata)
Write a Metadata to an output stream.
Definition: Metadata.h:401
Metadata::Ptr copy() const override
Return a copy of the metadata.
Definition: Metadata.h:313
std::string str() const override
Return a textual representation of this metadata.
Definition: Metadata.h:131
T & value()
Return this metadata's value.
Definition: Metadata.h:299
Index32 size() const override
Return the size of this metadata in bytes.
Definition: Metadata.h:133
Name typeName() const override
Return the type name of the metadata.
Definition: Metadata.h:285
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
UnknownMetadata(const Name &typ="<unknown>")
Definition: Metadata.h:126
virtual Index32 size() const =0
Return the size of this metadata in bytes.
virtual std::string str() const =0
Return a textual representation of this metadata.
static void unregisterType(const Name &typeName)
static Index32 readSize(std::istream &)
Read the size of the metadata from a stream.
Definition: Metadata.h:230
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:189
bool operator!=(const Metadata &other) const
Return true if the given metadata is different from this metadata.
Definition: Metadata.h:82
SharedPtr< const Metadata > ConstPtr
Definition: Metadata.h:54
void read(T &in, bool &v)
Definition: ImfXdr.h:611
GLsizeiptr size
Definition: glcorearb.h:663
void write(std::ostream &) const
Serialize this metadata to a stream.
Definition: Metadata.h:247
std::string str() const override
Return a textual representation of this metadata.
Definition: Metadata.h:347
std::shared_ptr< T > SharedPtr
Definition: Types.h:139
static bool isRegisteredType(const Name &typeName)
Return true if the given type is known by the metadata type registry.
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
GLdouble n
Definition: glcorearb.h:2007
#define OPENVDB_API
Helper macros for defining library symbol visibility.
Definition: Platform.h:194
Subclass to hold raw data of an unregistered type.
Definition: Metadata.h:121
Templated metadata class to hold specific types.
Definition: Metadata.h:171
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
void setValue(const ByteVec &bytes)
Definition: Metadata.h:135
void setValue(const T &)
Set this metadata's value.
Definition: Metadata.h:292
virtual void writeValue(std::ostream &) const =0
Write the metadata to a stream.
void writeValue(std::ostream &) const override
Write the metadata to a stream.
Definition: Metadata.h:340
static void registerType(const Name &typeName, Metadata::Ptr(*createMetadata)())
Register the given metadata type along with a factory function.
void readValue(std::istream &, Index32 numBytes) override
Read the metadata from a stream.
Definition: Metadata.h:332
GLsizei const GLfloat * value
Definition: glcorearb.h:823
virtual void readValue(std::istream &, Index32 numBytes)=0
Read the metadata from a stream.
Base class for storing metadata information in a grid.
Definition: Metadata.h:50
GLuint GLfloat * val
Definition: glcorearb.h:1607
Index32 size() const override
Return the size of this metadata in bytes.
Definition: Metadata.h:187
void write(T &out, bool v)
Definition: ImfXdr.h:332
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:135
static Metadata::Ptr createMetadata()
Create new metadata of this type.
Definition: Metadata.h:363
void writeSize(std::ostream &) const
Write the size of the metadata to a stream.
Definition: Metadata.h:222
bool isZero(const Type &x)
Return true if x is exactly equal to zero.
Definition: Math.h:308
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:109