HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
LeafBuffer.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: MPL-2.0
3 
4 #ifndef OPENVDB_TREE_LEAFBUFFER_HAS_BEEN_INCLUDED
5 #define OPENVDB_TREE_LEAFBUFFER_HAS_BEEN_INCLUDED
6 
7 #include <openvdb/Types.h>
8 #include <openvdb/io/Compression.h> // for io::readCompressedValues(), etc
10 #include <tbb/spin_mutex.h>
11 #include <algorithm> // for std::swap
12 #include <atomic>
13 #include <cstddef> // for offsetof()
14 #include <iostream>
15 #include <memory>
16 #include <type_traits>
17 
18 
19 class TestLeaf;
20 
21 namespace openvdb {
23 namespace OPENVDB_VERSION_NAME {
24 namespace tree {
25 
26 
27 /// @brief Array of fixed size 2<SUP>3<I>Log2Dim</I></SUP> that stores
28 /// the voxel values of a LeafNode
29 template<typename T, Index Log2Dim>
31 {
32 public:
33  using ValueType = T;
36  static const Index SIZE = 1 << 3 * Log2Dim;
37 
38 #ifdef OPENVDB_USE_DELAYED_LOADING
39  struct FileInfo
40  {
41  FileInfo(): bufpos(0) , maskpos(0) {}
42  std::streamoff bufpos;
43  std::streamoff maskpos;
44  io::MappedFile::Ptr mapping;
46  };
47 #endif
48 
49  /// Default constructor
50  inline LeafBuffer(): mData(new ValueType[SIZE])
51  {
52 #ifdef OPENVDB_USE_DELAYED_LOADING
53  mOutOfCore = 0;
54 #endif
55  }
56  /// Construct a buffer populated with the specified value.
57  explicit inline LeafBuffer(const ValueType&);
58  /// Copy constructor
59  inline LeafBuffer(const LeafBuffer&);
60  /// Construct a buffer but don't allocate memory for the full array of values.
61  LeafBuffer(PartialCreate, const ValueType&): mData(nullptr)
62  {
63 #ifdef OPENVDB_USE_DELAYED_LOADING
64  mOutOfCore = 0;
65 #endif
66  }
67  /// Destructor
68  inline ~LeafBuffer();
69 
70  /// Return @c true if this buffer's values have not yet been read from disk.
71  bool isOutOfCore() const
72  {
73 #ifdef OPENVDB_USE_DELAYED_LOADING
74  return bool(mOutOfCore);
75 #else
76  return false;
77 #endif
78  }
79  /// Return @c true if memory for this buffer has not yet been allocated.
80  bool empty() const { return !mData || this->isOutOfCore(); }
81  /// Allocate memory for this buffer if it has not already been allocated.
82  bool allocate() { if (mData == nullptr) mData = new ValueType[SIZE]; return true; }
83 
84  /// Populate this buffer with a constant value.
85  inline void fill(const ValueType&);
86 
87  /// Return a const reference to the i'th element of this buffer.
88  const ValueType& getValue(Index i) const { return this->at(i); }
89  /// Return a const reference to the i'th element of this buffer.
90  const ValueType& operator[](Index i) const { return this->at(i); }
91  /// Set the i'th value of this buffer to the specified value.
92  inline void setValue(Index i, const ValueType&);
93 
94  /// Copy the other buffer's values into this buffer.
95  inline LeafBuffer& operator=(const LeafBuffer&);
96 
97  /// @brief Return @c true if the contents of the other buffer
98  /// exactly equal the contents of this buffer.
99  inline bool operator==(const LeafBuffer&) const;
100  /// @brief Return @c true if the contents of the other buffer
101  /// are not exactly equal to the contents of this buffer.
102  inline bool operator!=(const LeafBuffer& other) const { return !(other == *this); }
103 
104  /// Exchange this buffer's values with the other buffer's values.
105  inline void swap(LeafBuffer&);
106 
107  /// Return the memory footprint of this buffer in bytes.
108  inline Index memUsage() const;
109  inline Index memUsageIfLoaded() const;
110  /// Return the number of values contained in this buffer.
111  static Index size() { return SIZE; }
112 
113  /// @brief Return a const pointer to the array of voxel values.
114  /// @details This method guarantees that the buffer is allocated and loaded.
115  /// @warning This method should only be used by experts seeking low-level optimizations.
116  const ValueType* data() const;
117  /// @brief Return a pointer to the array of voxel values.
118  /// @details This method guarantees that the buffer is allocated and loaded.
119  /// @warning This method should only be used by experts seeking low-level optimizations.
120  ValueType* data();
121 
122 private:
123  /// If this buffer is empty, return zero, otherwise return the value at index @ i.
124  inline const ValueType& at(Index i) const;
125 
126  /// @brief Return a non-const reference to the value at index @a i.
127  /// @details This method is private since it makes assumptions about the
128  /// buffer's memory layout. LeafBuffers associated with custom leaf node types
129  /// (e.g., a bool buffer implemented as a bitmask) might not be able to
130  /// return non-const references to their values.
131  ValueType& operator[](Index i) { return const_cast<ValueType&>(this->at(i)); }
132 
133  bool deallocate();
134 
135  inline void setOutOfCore(bool b)
136  {
137  (void) b;
138 #ifdef OPENVDB_USE_DELAYED_LOADING
139  mOutOfCore = b;
140 #endif
141  }
142  // To facilitate inlining in the common case in which the buffer is in-core,
143  // the loading logic is split into a separate function, doLoad().
144  inline void loadValues() const
145  {
146 #ifdef OPENVDB_USE_DELAYED_LOADING
147  if (this->isOutOfCore()) this->doLoad();
148 #endif
149  }
150  inline void doLoad() const;
151  inline bool detachFromFile();
152 
153  using FlagsType = std::atomic<Index32>;
154 
155 #ifdef OPENVDB_USE_DELAYED_LOADING
156  union {
157  ValueType* mData;
158  FileInfo* mFileInfo;
159  };
160 #else
161  ValueType* mData;
162 #endif
163  FlagsType mOutOfCore; // interpreted as bool; extra bits reserved for future use
164  tbb::spin_mutex mMutex; // 1 byte
165  //int8_t mReserved[3]; // padding for alignment
166 
167  friend class ::TestLeaf;
168  // Allow the parent LeafNode to access this buffer's data pointer.
169  template<typename, Index> friend class LeafNode;
170 }; // class LeafBuffer
171 
172 
173 ////////////////////////////////////////
174 
175 
176 template<typename T, Index Log2Dim>
177 inline
179  : mData(new ValueType[SIZE])
180 {
181 #ifdef OPENVDB_USE_DELAYED_LOADING
182  mOutOfCore = 0;
183 #endif
184  this->fill(val);
185 }
186 
187 
188 template<typename T, Index Log2Dim>
189 inline
191 {
192 #ifdef OPENVDB_USE_DELAYED_LOADING
193  if (this->isOutOfCore()) {
194  this->detachFromFile();
195  } else {
196  this->deallocate();
197  }
198 #else
199  this->deallocate();
200 #endif
201 }
202 
203 
204 template<typename T, Index Log2Dim>
205 inline
207  : mData(nullptr)
209  , mOutOfCore(other.mOutOfCore.load())
210 #endif
211 {
212 #ifdef OPENVDB_USE_DELAYED_LOADING
213  if (other.isOutOfCore()) {
214  mFileInfo = new FileInfo(*other.mFileInfo);
215  } else {
216 #endif
217  if (other.mData != nullptr) {
218  this->allocate();
219  ValueType* target = mData;
220  const ValueType* source = other.mData;
221  Index n = SIZE;
222  while (n--) *target++ = *source++;
223  }
224 #ifdef OPENVDB_USE_DELAYED_LOADING
225  }
226 #endif
227 }
228 
229 
230 template<typename T, Index Log2Dim>
231 inline void
233 {
234  assert(i < SIZE);
235  this->loadValues();
236  if (mData) mData[i] = val;
237 }
238 
239 
240 template<typename T, Index Log2Dim>
243 {
244  if (&other != this) {
245 #ifdef OPENVDB_USE_DELAYED_LOADING
246  if (this->isOutOfCore()) {
247  this->detachFromFile();
248  } else {
249  if (other.isOutOfCore()) this->deallocate();
250  }
251  if (other.isOutOfCore()) {
252  mOutOfCore.store(other.mOutOfCore.load(std::memory_order_acquire),
253  std::memory_order_release);
254  mFileInfo = new FileInfo(*other.mFileInfo);
255  } else {
256 #endif
257  if (other.mData != nullptr) {
258  this->allocate();
259  ValueType* target = mData;
260  const ValueType* source = other.mData;
261  Index n = SIZE;
262  while (n--) *target++ = *source++;
263  }
264 #ifdef OPENVDB_USE_DELAYED_LOADING
265  }
266 #endif
267  }
268  return *this;
269 }
270 
271 
272 template<typename T, Index Log2Dim>
273 inline void
275 {
276  this->detachFromFile();
277  if (mData != nullptr) {
278  ValueType* target = mData;
279  Index n = SIZE;
280  while (n--) *target++ = val;
281  }
282 }
283 
284 
285 template<typename T, Index Log2Dim>
286 inline bool
288 {
289  this->loadValues();
290  other.loadValues();
291  const ValueType *target = mData, *source = other.mData;
292  if (!target && !source) return true;
293  if (!target || !source) return false;
294  Index n = SIZE;
295  while (n && math::isExactlyEqual(*target++, *source++)) --n;
296  return n == 0;
297 }
298 
299 
300 template<typename T, Index Log2Dim>
301 inline void
303 {
304  std::swap(mData, other.mData);
305 #ifdef OPENVDB_USE_DELAYED_LOADING
306  // Two atomics can't be swapped because it would require hardware support:
307  // https://en.wikipedia.org/wiki/Double_compare-and-swap
308  // Note that there's a window in which other.mOutOfCore could be written
309  // between our load from it and our store to it.
310  auto tmp = other.mOutOfCore.load(std::memory_order_acquire);
311  tmp = mOutOfCore.exchange(std::move(tmp));
312  other.mOutOfCore.store(std::move(tmp), std::memory_order_release);
313 #endif
314 }
315 
316 
317 template<typename T, Index Log2Dim>
318 inline Index
320 {
321  size_t n = sizeof(*this);
322 #ifdef OPENVDB_USE_DELAYED_LOADING
323  if (this->isOutOfCore()) n += sizeof(FileInfo);
324  else {
325 #endif
326  if (mData) n += SIZE * sizeof(ValueType);
327 #ifdef OPENVDB_USE_DELAYED_LOADING
328  }
329 #endif
330  return static_cast<Index>(n);
331 }
332 
333 
334 template<typename T, Index Log2Dim>
335 inline Index
337 {
338  size_t n = sizeof(*this);
339  n += SIZE * sizeof(ValueType);
340  return static_cast<Index>(n);
341 }
342 
343 
344 template<typename T, Index Log2Dim>
345 inline const typename LeafBuffer<T, Log2Dim>::ValueType*
347 {
348  this->loadValues();
349  if (mData == nullptr) {
350  LeafBuffer* self = const_cast<LeafBuffer*>(this);
351 #ifdef OPENVDB_USE_DELAYED_LOADING
352  // This lock will be contended at most once.
353  tbb::spin_mutex::scoped_lock lock(self->mMutex);
354 #endif
355  if (mData == nullptr) self->mData = new ValueType[SIZE];
356  }
357  return mData;
358 }
359 
360 template<typename T, Index Log2Dim>
361 inline typename LeafBuffer<T, Log2Dim>::ValueType*
363 {
364  this->loadValues();
365  if (mData == nullptr) {
366 #ifdef OPENVDB_USE_DELAYED_LOADING
367  // This lock will be contended at most once.
368  tbb::spin_mutex::scoped_lock lock(mMutex);
369 #endif
370  if (mData == nullptr) mData = new ValueType[SIZE];
371  }
372  return mData;
373 }
374 
375 
376 template<typename T, Index Log2Dim>
377 inline const typename LeafBuffer<T, Log2Dim>::ValueType&
379 {
380  static const ValueType sZero = zeroVal<T>();
381  assert(i < SIZE);
382  this->loadValues();
383  // We can't use the ternary operator here, otherwise Visual C++ returns
384  // a reference to a temporary.
385  if (mData) return mData[i]; else return sZero;
386 }
387 
388 
389 template<typename T, Index Log2Dim>
390 inline bool
391 LeafBuffer<T, Log2Dim>::deallocate()
392 {
393 
394  if (mData != nullptr) {
395 #ifdef OPENVDB_USE_DELAYED_LOADING
396  if (this->isOutOfCore()) return false;
397 #endif
398  delete[] mData;
399  mData = nullptr;
400  return true;
401  }
402  return false;
403 }
404 
405 
406 template<typename T, Index Log2Dim>
407 inline void
408 LeafBuffer<T, Log2Dim>::doLoad() const
409 {
410 #ifdef OPENVDB_USE_DELAYED_LOADING
411  if (!this->isOutOfCore()) return;
412 
413  LeafBuffer<T, Log2Dim>* self = const_cast<LeafBuffer<T, Log2Dim>*>(this);
414 
415  // This lock will be contended at most once, after which this buffer
416  // will no longer be out-of-core.
417  tbb::spin_mutex::scoped_lock lock(self->mMutex);
418  if (!this->isOutOfCore()) return;
419 
420  std::unique_ptr<FileInfo> info(self->mFileInfo);
421  assert(info.get() != nullptr);
422  assert(info->mapping.get() != nullptr);
423  assert(info->meta.get() != nullptr);
424 
425  /// @todo For now, we have to clear the mData pointer in order for allocate() to take effect.
426  self->mData = nullptr;
427  self->allocate();
428 
429  SharedPtr<std::streambuf> buf = info->mapping->createBuffer();
430  std::istream is(buf.get());
431 
432  io::setStreamMetadataPtr(is, info->meta, /*transfer=*/true);
433 
434  NodeMaskType mask;
435  is.seekg(info->maskpos);
436  mask.load(is);
437 
438  is.seekg(info->bufpos);
439  io::readCompressedValues(is, self->mData, SIZE, mask, io::getHalfFloat(is));
440 
441  self->setOutOfCore(false);
442 #endif
443 }
444 
445 
446 template<typename T, Index Log2Dim>
447 inline bool
448 LeafBuffer<T, Log2Dim>::detachFromFile()
449 {
450 #ifdef OPENVDB_USE_DELAYED_LOADING
451  if (this->isOutOfCore()) {
452  delete mFileInfo;
453  mFileInfo = nullptr;
454  this->setOutOfCore(false);
455  return true;
456  }
457 #endif
458  return false;
459 }
460 
461 
462 ////////////////////////////////////////
463 
464 
465 // Partial specialization for bool ValueType
466 template<Index Log2Dim>
467 class LeafBuffer<bool, Log2Dim>
468 {
469 public:
471  using WordType = typename NodeMaskType::Word;
472  using ValueType = bool;
474 
475  static const Index WORD_COUNT = NodeMaskType::WORD_COUNT;
476  static const Index SIZE = 1 << 3 * Log2Dim;
477 
478  static inline const bool sOn = true;
479  static inline const bool sOff = false;
480 
482  LeafBuffer(bool on): mData(on) {}
483  LeafBuffer(const NodeMaskType& other): mData(other) {}
484  LeafBuffer(const LeafBuffer& other): mData(other.mData) {}
486  void fill(bool val) { mData.set(val); }
487  LeafBuffer& operator=(const LeafBuffer& b) { if (&b != this) { mData=b.mData; } return *this; }
488 
489  const bool& getValue(Index i) const
490  {
491  assert(i < SIZE);
492  // We can't use the ternary operator here, otherwise Visual C++ returns
493  // a reference to a temporary.
494  if (mData.isOn(i)) return sOn; else return sOff;
495  }
496  const bool& operator[](Index i) const { return this->getValue(i); }
497 
498  bool operator==(const LeafBuffer& other) const { return mData == other.mData; }
499  bool operator!=(const LeafBuffer& other) const { return mData != other.mData; }
500 
501  void setValue(Index i, bool val) { assert(i < SIZE); mData.set(i, val); }
502 
503  void swap(LeafBuffer& other) { if (&other != this) std::swap(mData, other.mData); }
504 
505  Index memUsage() const { return sizeof(*this); }
506  Index memUsageIfLoaded() const { return sizeof(*this); }
507  static Index size() { return SIZE; }
508 
509  /// @brief Return a pointer to the C-style array of words encoding the bits.
510  /// @warning This method should only be used by experts seeking low-level optimizations.
511  WordType* data() { return &(mData.template getWord<WordType>(0)); }
512  /// @brief Return a const pointer to the C-style array of words encoding the bits.
513  /// @warning This method should only be used by experts seeking low-level optimizations.
514  const WordType* data() const { return const_cast<LeafBuffer*>(this)->data(); }
515 
516 private:
517  // Allow the parent LeafNode to access this buffer's data.
518  template<typename, Index> friend class LeafNode;
519 
520  NodeMaskType mData;
521 }; // class LeafBuffer
522 
523 } // namespace tree
524 } // namespace OPENVDB_VERSION_NAME
525 } // namespace openvdb
526 
527 #endif // OPENVDB_TREE_LEAFBUFFER_HAS_BEEN_INCLUDED
GLenum GLuint GLenum GLsizei const GLchar * buf
Definition: glcorearb.h:2540
LeafBuffer & operator=(const LeafBuffer &)
Copy the other buffer's values into this buffer.
Definition: LeafBuffer.h:242
bool isExactlyEqual(const T0 &a, const T1 &b)
Return true if a is exactly equal to b.
Definition: Math.h:443
void
Definition: png.h:1083
void swap(UT::ArraySet< Key, MULTI, MAX_LOAD_FACTOR_256, Clearer, Hash, KeyEqual > &a, UT::ArraySet< Key, MULTI, MAX_LOAD_FACTOR_256, Clearer, Hash, KeyEqual > &b)
Definition: UT_ArraySet.h:1639
LeafBuffer(PartialCreate, const ValueType &)
Construct a buffer but don't allocate memory for the full array of values.
Definition: LeafBuffer.h:61
OPENVDB_API bool getHalfFloat(std::ios_base &)
Return true if floating-point values should be quantized to 16 bits when writing to the given stream ...
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:239
bool operator==(const LeafBuffer &) const
Return true if the contents of the other buffer exactly equal the contents of this buffer...
Definition: LeafBuffer.h:287
bool empty() const
Return true if memory for this buffer has not yet been allocated.
Definition: LeafBuffer.h:80
Tag dispatch class that distinguishes constructors during file input.
Definition: Types.h:689
void readCompressedValues(std::istream &is, ValueT *destBuf, Index destCount, const MaskT &valueMask, bool fromHalf)
Definition: Compression.h:465
std::shared_ptr< T > SharedPtr
Definition: Types.h:114
GLdouble n
Definition: glcorearb.h:2008
Bit mask for the internal and leaf nodes of VDB. This is a 64-bit implementation. ...
Definition: NodeMasks.h:307
void swap(LeafBuffer &)
Exchange this buffer's values with the other buffer's values.
Definition: LeafBuffer.h:302
Templated block class to hold specific data types and a fixed number of values determined by Log2Dim...
Definition: LeafNode.h:37
#define OPENVDB_USE_DELAYED_LOADING
Definition: version.h:143
bool allocate()
Allocate memory for this buffer if it has not already been allocated.
Definition: LeafBuffer.h:82
static Index size()
Return the number of values contained in this buffer.
Definition: LeafBuffer.h:111
GLsizei GLsizei GLchar * source
Definition: glcorearb.h:803
const ValueType & getValue(Index i) const
Return a const reference to the i'th element of this buffer.
Definition: LeafBuffer.h:88
GLint GLuint mask
Definition: glcorearb.h:124
GLenum target
Definition: glcorearb.h:1667
Index memUsage() const
Return the memory footprint of this buffer in bytes.
Definition: LeafBuffer.h:319
WordType * data()
Return a pointer to the C-style array of words encoding the bits.
Definition: LeafBuffer.h:511
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
OPENVDB_API void setStreamMetadataPtr(std::ios_base &, SharedPtr< StreamMetadata > &, bool transfer=true)
Associate the given stream with (a shared pointer to) an object that stores metadata (file format...
const ValueType * data() const
Return a const pointer to the array of voxel values.
Definition: LeafBuffer.h:346
const ValueType & operator[](Index i) const
Return a const reference to the i'th element of this buffer.
Definition: LeafBuffer.h:90
void fill(const ValueType &)
Populate this buffer with a constant value.
Definition: LeafBuffer.h:274
bool isOutOfCore() const
Return true if this buffer's values have not yet been read from disk.
Definition: LeafBuffer.h:71
Array of fixed size 23Log2Dim that stores the voxel values of a LeafNode.
Definition: LeafBuffer.h:30
GLuint GLfloat * val
Definition: glcorearb.h:1608
#define SIZE
Definition: simple.C:41
void setValue(Index i, const ValueType &)
Set the i'th value of this buffer to the specified value.
Definition: LeafBuffer.h:232
bool operator!=(const LeafBuffer &other) const
Return true if the contents of the other buffer are not exactly equal to the contents of this buffer...
Definition: LeafBuffer.h:102
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:119
bool ValueType
Definition: NanoVDB.h:5729
const WordType * data() const
Return a const pointer to the C-style array of words encoding the bits.
Definition: LeafBuffer.h:514