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"
31 #include "pxr/base/tf/token.h"
32 #include "pxr/base/vt/value.h"
33 
34 #include <atomic>
35 #include <memory>
36 #include <mutex>
37 
39 
40 
41 class HdBufferArrayRange;
42 
43 using HdBufferArraySharedPtr = std::shared_ptr<class HdBufferArray>;
44 using HdBufferArrayRangeSharedPtr = std::shared_ptr<HdBufferArrayRange>;
45 using HdBufferArrayRangePtr = std::weak_ptr<HdBufferArrayRange>;
46 
47 /// \union HdBufferArrayUsageHint
48 ///
49 /// The union provides a set of flags that provide hints to the memory
50 /// management system about the properties of a Buffer Array Range (BAR),
51 /// so it can efficiently organize that memory. For example,
52 /// the memory manager should probably not aggregate BARs with different
53 /// usage hints.
54 ///
55 /// The union provides two members:
56 /// - value: The combined set of flags
57 /// - bits: Access to individual flag bits
58 ///
59 /// The flag bits are:
60 /// - immutable: The BAR will not be modified once created and populated.
61 /// - sizeVarying: The number of elements in the BAR changes with time.
62 ///
63 /// Some flag bits may not make sense in combination
64 /// (i.e. mutually exclusive to each other). For example, it is logically
65 /// impossible to be both immutable (i.e. not changing) and sizeVarying
66 /// (changing). However, these logically impossible combinations are
67 /// not enforced and remain valid potential values.
68 ///
70  struct _Bits {
71  uint32_t immutable : 1;
72  uint32_t sizeVarying : 1;
73  uint32_t pad : 30;
74  } bits;
75  uint32_t value;
76 
78 };
79 
80 
81 /// \class HdBufferArray
82 ///
83 /// Similar to a VAO, this object is a bundle of coherent buffers. This object
84 /// can be shared across multiple HdRprims, in the context of buffer
85 /// aggregation.
86 ///
87 class HdBufferArray : public std::enable_shared_from_this<HdBufferArray>
88 {
89 public:
90  HD_API
91  HdBufferArray(TfToken const &role,
92  TfToken const garbageCollectionPerfToken,
93  HdBufferArrayUsageHint usageHint);
94 
95  HD_API
96  virtual ~HdBufferArray();
97 
98  /// Returns the role of the GPU data in this bufferArray.
99  TfToken const& GetRole() const {return _role;}
100 
101  /// Returns the version of this buffer array.
102  /// Used to determine when to rebuild outdated indirect dispatch buffers
103  size_t GetVersion() const {
104  return _version;
105  }
106 
107  /// Increments the version of this buffer array.
108  HD_API
109  void IncrementVersion();
110 
111  /// Attempts to assign a range to this buffer array.
112  /// Multiple threads could be trying to assign to this buffer at the same time.
113  /// Returns true is the range is assigned to this buffer otherwise
114  /// returns false if the buffer doesn't have space to assign the range.
115  HD_API
117 
118  /// Performs compaction if necessary and returns true if it becomes empty.
119  virtual bool GarbageCollect() = 0;
120 
121  /// Performs reallocation. After reallocation, the buffer will contain
122  /// the specified \a ranges. If these ranges are currently held by a
123  /// different buffer array instance, then their data will be copied
124  /// from the specified \a curRangeOwner.
125  virtual void Reallocate(
126  std::vector<HdBufferArrayRangeSharedPtr> const &ranges,
127  HdBufferArraySharedPtr const &curRangeOwner) = 0;
128 
129  /// Returns the maximum number of elements capacity.
130  HD_API
131  virtual size_t GetMaxNumElements() const;
132 
133  /// Debug output
134  virtual void DebugDump(std::ostream &out) const = 0;
135 
136  /// How many ranges are attached to the buffer array.
137  size_t GetRangeCount() const { return _rangeCount; }
138 
139  /// Get the attached range at the specified index.
140  HD_API
141  HdBufferArrayRangePtr GetRange(size_t idx) const;
142 
143  /// Remove any ranges from the range list that have been deallocated
144  /// Returns number of ranges after clean-up
145  HD_API
146  void RemoveUnusedRanges();
147 
148  /// Returns true if Reallocate() needs to be called on this buffer array.
149  bool NeedsReallocation() const {
150  return _needsReallocation;
151  }
152 
153  /// Returns true if this buffer array is marked as immutable.
154  bool IsImmutable() const {
155  return _usageHint.bits.immutable;
156  }
157 
158  /// Returns the usage hints for this buffer array.
160  return _usageHint;
161  }
162 
163 protected:
164  /// Dirty bit to set when the ranges attached to the buffer
165  /// changes. If set Reallocate() should be called to clean it.
167 
168  /// Limits the number of ranges that can be
169  /// allocated to this buffer to max.
170  void _SetMaxNumRanges(size_t max) { _maxNumRanges = max; }
171 
172  /// Swap the rangelist with \p ranges
173  HD_API
174  void _SetRangeList(std::vector<HdBufferArrayRangeSharedPtr> const &ranges);
175 
176 private:
177 
178  // Do not allow copies.
179  HdBufferArray(const HdBufferArray &) = delete;
180  HdBufferArray &operator=(const HdBufferArray &) = delete;
181 
182 
183  typedef std::vector<HdBufferArrayRangePtr> _RangeList;
184 
185  // Vector of ranges associated with this buffer
186  // We add values to the list in a multi-threaded fashion
187  // but can later remove them in _RemoveUnusedRanges
188  // than add more.
189  //
190  _RangeList _rangeList;
191  std::atomic_size_t _rangeCount; // how many ranges are valid in list
192  std::mutex _rangeListLock;
193 
194  const TfToken _role;
195  const TfToken _garbageCollectionPerfToken;
196 
197  size_t _version;
198 
199  size_t _maxNumRanges;
200  HdBufferArrayUsageHint _usageHint;
201 };
202 
203 
205 
206 #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:149
GLenum GLint * range
Definition: glcorearb.h:1925
bool _needsReallocation
Definition: bufferArray.h:166
TfToken const & GetRole() const
Returns the role of the GPU data in this bufferArray.
Definition: bufferArray.h:99
std::shared_ptr< class HdBufferArray > HdBufferArraySharedPtr
Definition: bufferArray.h:43
struct HdBufferArrayUsageHint::_Bits bits
void _SetMaxNumRanges(size_t max)
Definition: bufferArray.h:170
bool IsImmutable() const
Returns true if this buffer array is marked as immutable.
Definition: bufferArray.h:154
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)
virtual void DebugDump(std::ostream &out) const =0
Debug output.
virtual HD_API ~HdBufferArray()
size_t GetVersion() const
Definition: bufferArray.h:103
HdBufferArrayUsageHint GetUsageHint() const
Returns the usage hints for this buffer array.
Definition: bufferArray.h:159
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
HD_API HdBufferArray(TfToken const &role, TfToken const garbageCollectionPerfToken, HdBufferArrayUsageHint usageHint)
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
std::shared_ptr< HdBufferArrayRange > HdBufferArrayRangeSharedPtr
Definition: bufferArray.h:44
Definition: core.h:1131
size_t GetRangeCount() const
How many ranges are attached to the buffer array.
Definition: bufferArray.h:137
HD_API void RemoveUnusedRanges()
std::weak_ptr< HdBufferArrayRange > HdBufferArrayRangePtr
Definition: bufferArray.h:45