HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
bufferArray.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_HD_BUFFER_ARRAY_H
25 #define PXR_IMAGING_HD_BUFFER_ARRAY_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hd/api.h"
29 #include "pxr/imaging/hd/version.h"
32 #include "pxr/base/tf/token.h"
33 #include "pxr/base/vt/value.h"
34 
35 #include <atomic>
36 #include <memory>
37 #include <mutex>
38 
40 
41 
42 class HdBufferArrayRange;
43 
44 using HdBufferArraySharedPtr = std::shared_ptr<class HdBufferArray>;
45 using HdBufferArrayRangeSharedPtr = std::shared_ptr<HdBufferArrayRange>;
46 using HdBufferArrayRangePtr = std::weak_ptr<HdBufferArrayRange>;
47 
48 /// \union HdBufferArrayUsageHint
49 ///
50 /// The union provides a set of flags that provide hints to the memory
51 /// management system about the properties of a Buffer Array Range (BAR),
52 /// so it can efficiently organize that memory. For example,
53 /// the memory manager should probably not aggregate BARs with different
54 /// usage hints.
55 ///
56 /// The union provides two members:
57 /// - value: The combined set of flags
58 /// - bits: Access to individual flag bits
59 ///
60 /// The flag bits are:
61 /// - immutable: The BAR will not be modified once created and populated.
62 /// - sizeVarying: The number of elements in the BAR changes with time.
63 ///
64 /// Some flag bits may not make sense in combination
65 /// (i.e. mutually exclusive to each other). For example, it is logically
66 /// impossible to be both immutable (i.e. not changing) and sizeVarying
67 /// (changing). However, these logically impossible combinations are
68 /// not enforced and remain valid potential values.
69 ///
71  struct _Bits {
72  uint32_t immutable : 1;
73  uint32_t sizeVarying : 1;
74  uint32_t pad : 30;
75  } bits;
76  uint32_t value;
77 
79 };
80 
81 
82 /// \class HdBufferArray
83 ///
84 /// Similar to a VAO, this object is a bundle of coherent buffers. This object
85 /// can be shared across multiple HdRprims, in the context of buffer
86 /// aggregation.
87 ///
88 class HdBufferArray : public std::enable_shared_from_this<HdBufferArray>
89 {
90 public:
91  HD_API
92  HdBufferArray(TfToken const &role,
93  TfToken const garbageCollectionPerfToken,
94  HdBufferArrayUsageHint usageHint);
95 
96  HD_API
97  virtual ~HdBufferArray();
98 
99  /// Returns the role of the GPU data in this bufferArray.
100  TfToken const& GetRole() const {return _role;}
101 
102  /// Returns the version of this buffer array.
103  /// Used to determine when to rebuild outdated indirect dispatch buffers
104  size_t GetVersion() const {
105  return _version;
106  }
107 
108  /// Increments the version of this buffer array.
109  HD_API
110  void IncrementVersion();
111 
112  /// Attempts to assign a range to this buffer array.
113  /// Multiple threads could be trying to assign to this buffer at the same time.
114  /// Returns true is the range is assigned to this buffer otherwise
115  /// returns false if the buffer doesn't have space to assign the range.
116  HD_API
118 
119  /// Performs compaction if necessary and returns true if it becomes empty.
120  virtual bool GarbageCollect() = 0;
121 
122  /// Performs reallocation. After reallocation, the buffer will contain
123  /// the specified \a ranges. If these ranges are currently held by a
124  /// different buffer array instance, then their data will be copied
125  /// from the specified \a curRangeOwner.
126  virtual void Reallocate(
127  std::vector<HdBufferArrayRangeSharedPtr> const &ranges,
128  HdBufferArraySharedPtr const &curRangeOwner) = 0;
129 
130  /// Returns the maximum number of elements capacity.
131  HD_API
132  virtual size_t GetMaxNumElements() const;
133 
134  /// Debug output
135  virtual void DebugDump(std::ostream &out) const = 0;
136 
137  /// How many ranges are attached to the buffer array.
138  size_t GetRangeCount() const { return _rangeCount; }
139 
140  /// Get the attached range at the specified index.
141  HD_API
142  HdBufferArrayRangePtr GetRange(size_t idx) const;
143 
144  /// Remove any ranges from the range list that have been deallocated
145  /// Returns number of ranges after clean-up
146  HD_API
147  void RemoveUnusedRanges();
148 
149  /// Returns true if Reallocate() needs to be called on this buffer array.
150  bool NeedsReallocation() const {
151  return _needsReallocation;
152  }
153 
154  /// Returns true if this buffer array is marked as immutable.
155  bool IsImmutable() const {
156  return _usageHint.bits.immutable;
157  }
158 
159  /// Returns the usage hints for this buffer array.
161  return _usageHint;
162  }
163 
164 protected:
165  /// Dirty bit to set when the ranges attached to the buffer
166  /// changes. If set Reallocate() should be called to clean it.
168 
169  /// Limits the number of ranges that can be
170  /// allocated to this buffer to max.
171  void _SetMaxNumRanges(size_t max) { _maxNumRanges = max; }
172 
173  /// Swap the rangelist with \p ranges
174  HD_API
175  void _SetRangeList(std::vector<HdBufferArrayRangeSharedPtr> const &ranges);
176 
177 private:
178 
179  // Do not allow copies.
180  HdBufferArray(const HdBufferArray &) = delete;
181  HdBufferArray &operator=(const HdBufferArray &) = delete;
182 
183 
184  typedef std::vector<HdBufferArrayRangePtr> _RangeList;
185 
186  // Vector of ranges associated with this buffer
187  // We add values to the list in a multi-threaded fashion
188  // but can later remove them in _RemoveUnusedRanges
189  // than add more.
190  //
191  _RangeList _rangeList;
192  std::atomic_size_t _rangeCount; // how many ranges are valid in list
193  std::mutex _rangeListLock;
194 
195  const TfToken _role;
196  const TfToken _garbageCollectionPerfToken;
197 
198  size_t _version;
199 
200  size_t _maxNumRanges;
201  HdBufferArrayUsageHint _usageHint;
202 };
203 
204 
206 
207 #endif //PXR_IMAGING_HD_BUFFER_ARRAY_H
virtual bool GarbageCollect()=0
Performs compaction if necessary and returns true if it becomes empty.
bool NeedsReallocation() const
Returns true if Reallocate() needs to be called on this buffer array.
Definition: bufferArray.h:150
bool _needsReallocation
Definition: bufferArray.h:167
TfToken const & GetRole() const
Returns the role of the GPU data in this bufferArray.
Definition: bufferArray.h:100
std::shared_ptr< class HdBufferArray > HdBufferArraySharedPtr
Definition: bufferArray.h:44
struct HdBufferArrayUsageHint::_Bits bits
void _SetMaxNumRanges(size_t max)
Definition: bufferArray.h:171
bool IsImmutable() const
Returns true if this buffer array is marked as immutable.
Definition: bufferArray.h:155
HD_API void _SetRangeList(std::vector< HdBufferArrayRangeSharedPtr > const &ranges)
Swap the rangelist with ranges.
#define HD_API
Definition: api.h:40
virtual void Reallocate(std::vector< HdBufferArrayRangeSharedPtr > const &ranges, HdBufferArraySharedPtr const &curRangeOwner)=0
virtual HD_API size_t GetMaxNumElements() const
Returns the maximum number of elements capacity.
HD_API HdBufferArrayRangePtr GetRange(size_t idx) const
Get the attached range at the specified index.
Definition: token.h:87
HD_API void IncrementVersion()
Increments the version of this buffer array.
HD_API bool TryAssignRange(HdBufferArrayRangeSharedPtr &range)
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
virtual void DebugDump(std::ostream &out) const =0
Debug output.
virtual HD_API ~HdBufferArray()
size_t GetVersion() const
Definition: bufferArray.h:104
HdBufferArrayUsageHint GetUsageHint() const
Returns the usage hints for this buffer array.
Definition: bufferArray.h:160
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
HD_API HdBufferArray(TfToken const &role, TfToken const garbageCollectionPerfToken, HdBufferArrayUsageHint usageHint)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
std::shared_ptr< HdBufferArrayRange > HdBufferArrayRangeSharedPtr
Definition: bufferArray.h:45
GLsizei const GLfloat * value
Definition: glcorearb.h:823
GLenum GLint * range
Definition: glcorearb.h:1924
size_t GetRangeCount() const
How many ranges are attached to the buffer array.
Definition: bufferArray.h:138
HD_API void RemoveUnusedRanges()
std::weak_ptr< HdBufferArrayRange > HdBufferArrayRangePtr
Definition: bufferArray.h:46