HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
binding.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_IMAGING_HDST_BINDING_H
8 #define PXR_IMAGING_HDST_BINDING_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/imaging/hdSt/api.h"
13 
15 #include "pxr/imaging/hd/types.h"
16 
17 #include "pxr/base/tf/hash.h"
18 
20 
21 
22 using HdStBindingVector = std::vector<class HdStBinding>;
23 using HdStBindingRequestVector = std::vector<class HdStBindingRequest>;
24 
25 /// \class HdStBinding
26 ///
27 /// Bindings are used for buffers or textures, it simply associates a binding
28 /// type with a binding location.
29 ///
30 class HdStBinding {
31 public:
32  enum Type { // primvar, drawing coordinate and dispatch buffer bindings
33  // also shader fallback values
35  DISPATCH, // GL_DRAW_INDIRECT_BUFFER
36  DRAW_INDEX, // per-drawcall. not instanced
37  DRAW_INDEX_INSTANCE, // per-drawcall. attribdivisor=on
38  DRAW_INDEX_INSTANCE_ARRAY, // per-drawcall. attribdivisor=on, array
39  VERTEX_ATTR, // vertex-attribute
40  INDEX_ATTR, // GL_ELEMENT_ARRAY_BUFFER
41  SSBO, //
43  UBO, //
45  UNIFORM, //
47 
48  // shader parameter bindings
49  FALLBACK, // fallback value
50  TEXTURE_2D, // non-bindless uv texture
51  ARRAY_OF_TEXTURE_2D, // non-bindless array of uv textures. Not
52  // to be confused with a texture array
53  // (what udim and ptex textures use).
54  TEXTURE_FIELD, // non-bindless field texture
55  // creates accessor that samples uvw
56  // texture after transforming coordinates
57  // by a sampling transform
58  TEXTURE_UDIM_ARRAY, // non-bindless udim texture array
59  TEXTURE_UDIM_LAYOUT, // non-bindless udim layout
60  TEXTURE_PTEX_TEXEL, // non-bindless ptex texels
61  TEXTURE_PTEX_LAYOUT, // non-bindless ptex layout
62  BINDLESS_TEXTURE_2D, // bindless uv texture
63  BINDLESS_ARRAY_OF_TEXTURE_2D, // bindless array of uv textures
64  BINDLESS_TEXTURE_FIELD, // bindless field texture
65  // (see above)
66  BINDLESS_TEXTURE_UDIM_ARRAY, // bindless uv texture array
67  BINDLESS_TEXTURE_UDIM_LAYOUT, // bindless udim layout
68  BINDLESS_TEXTURE_PTEX_TEXEL, // bindless ptex texels
69  BINDLESS_TEXTURE_PTEX_LAYOUT, // bindless ptex layout
70  PRIMVAR_REDIRECT, // primvar redirection
71  FIELD_REDIRECT, // accesses a field texture by name and
72  // uses fallbackValue if no accessor for
73  // the texture exists.
74  TRANSFORM_2D // transform2d
75  };
76  enum Location {
77  // NOT_EXIST is a special value of location for a uniform
78  // which is assigned but optimized out after linking program.
79  NOT_EXIST = 0xffff
80  };
81  HdStBinding() : _typeAndLocation(-1) { }
82  HdStBinding(Type type, int location, int textureUnit=0) {
83  Set(type, location, textureUnit);
84  }
85  void Set(Type type, int location, int textureUnit) {
86  _typeAndLocation = (textureUnit << 24)|(location << 8)|(int)(type);
87  }
88  bool IsValid() const { return _typeAndLocation >= 0; }
89  Type GetType() const { return (Type)(_typeAndLocation & 0xff); }
90  int GetLocation() const { return (_typeAndLocation >> 8) & 0xffff; }
91  int GetTextureUnit() const { return (_typeAndLocation >> 24) & 0xff; }
92  int GetValue() const { return _typeAndLocation; }
93  bool operator < (HdStBinding const &b) const {
94  return (_typeAndLocation < b._typeAndLocation);
95  }
96 private:
97  int _typeAndLocation;
98 };
99 
100 /// BindingRequest allows externally allocated buffers to be bound at render
101 /// time. The different modes of binding discussed below allow the caller a
102 /// range of opt-in binding behaviors, from simply reserving a binding location
103 /// so it can be managed from client code, to fully generating buffer accessor
104 /// code at compile time (i.e. when using a BufferArrayRange or BufferResource).
105 ///
106 /// This is a "request" because the caller makes a request before bindings are
107 /// resolved. All requests are consulted and fulfilled during binding
108 /// resolution.
110 public:
111 
112  HdStBindingRequest() = default;
113 
114  /// A data binding, not backed by neither BufferArrayRange nor
115  /// BufferResource. This binding request simply
116  /// generates named metadata (#define HD_HAS_foo 1, #define HD_foo_Binding)
118  : _bindingType(bindingType)
119  , _dataType(HdTypeInvalid)
120  , _name(name)
121  , _resource(nullptr)
122  , _bar(nullptr)
123  , _isInterleaved(false)
124  , _isWritable(false)
125  , _arraySize(0)
126  , _concatenateNames(false)
127  {}
128 
129  /// A data binding, not backed by neither BufferArrayRange nor
130  /// BufferResource.
133  : _bindingType(bindingType)
134  , _dataType(dataType)
135  , _name(name)
136  , _resource(nullptr)
137  , _bar(nullptr)
138  , _isInterleaved(false)
139  , _isWritable(false)
140  , _arraySize(0)
141  , _concatenateNames(false)
142  {}
143 
144  /// A buffer resource binding. Binds a given buffer resource to a specified
145  /// name. The data type is set from the resource.
147  HdStBufferResourceSharedPtr const& resource)
148  : _bindingType(bindingType)
149  , _dataType(resource->GetTupleType().type)
150  , _name(name)
151  , _resource(resource)
152  , _bar(nullptr)
153  , _isInterleaved(false)
154  , _isWritable(false)
155  , _arraySize(0)
156  , _concatenateNames(false)
157  {}
158 
159  /// A named struct binding. From an interleaved BufferArray, an array of
160  /// structs will be generated, consuming a single binding point. Note that
161  /// all resources in the buffer array must have the same underlying
162  /// identifier, hence must be interleaved and bindable as a single resource.
163  /// Data types can be derived from each HdStBufferResource of bar.
166  bool interleave, bool writable = false,
167  size_t arraySize = 0, bool concatenateNames = false)
168  : _bindingType(type)
169  , _dataType(HdTypeInvalid)
170  , _name(name)
171  , _resource(nullptr)
172  , _bar(bar)
173  , _isInterleaved(interleave)
174  , _isWritable(writable)
175  , _arraySize(arraySize)
176  , _concatenateNames(concatenateNames)
177  {}
178 
179  // ---------------------------------------------------------------------- //
180  /// \name Discriminators
181  // ---------------------------------------------------------------------- //
182 
183  /// Resource bingings have a single associated Hydra resource, but no buffer
184  /// array.
185  bool IsResource() const {
186  return bool(_resource);
187  }
188 
189  /// A buffer array binding has several buffers bundled together and each
190  /// buffer will be bound individually and exposed as independent arrays in
191  /// the shader.
192  bool IsBufferArray() const {
193  return _bar && !_isInterleaved;
194  }
195 
196  /// Like BufferArray binding requests, struct bindings have several buffers,
197  /// however they must be allocated into a single resource and interleaved.
198  /// This type of binding request is exposed in the shader an array of
199  /// structs.
201  return _bar && _isInterleaved;
202  }
203 
204  /// True when the resource is being bound so that it can be written to.
205  /// This affects whether it will be declared 'const' or not.
206  bool isWritable() const {
207  return _bar && _isWritable;
208  }
209 
210  /// This binding is typelss. CodeGen only allocate location and
211  /// skip emitting declarations and accessors.
212  bool IsTypeless() const {
213  return (!_bar) && (!_resource) && (_dataType == HdTypeInvalid);
214  }
215 
216  // ---------------------------------------------------------------------- //
217  /// \name Accessors
218  // ---------------------------------------------------------------------- //
219 
220  /// Returns the name of the binding point, if any; buffer arrays and structs
221  /// need not be named.
222  TfToken const& GetName() const {
223  return _name;
224  }
225  /// Returns the HdStBinding type of this request.
227  return _bindingType;
228  }
229  /// Returns the single resource associated with this binding request or
230  /// null when IsResource() returns false.
232  return _resource;
233  }
234  /// Returns the resource or buffer array range offset, defaults to zero.
235  int GetByteOffset() const {
236  // buffer resource binding
237  if (_resource) return _resource->GetOffset();
238 
239  // named struct binding (interleaved) - the resource name doesn't matter
240  // since a single binding point is used.
241  if (_bar) return _bar->GetByteOffset(TfToken());
242  return 0;
243  }
244  /// Returns the buffer array range associated with this binding request or
245  /// null when IsBufferArrqay() returns false.
247  return _bar;
248  }
249 
250  /// Return the data type of this request
251  HdType GetDataType() const {
252  return _dataType;
253  }
254 
255  /// Array size if request is for an array of structs.
256  size_t GetArraySize() const {
257  return _arraySize;
258  }
259 
260  /// Returns whether the struct binding point and struct member names
261  /// should be concatenated when codegen'ing the accessor.
262  bool ConcatenateNames() const {
263  return _concatenateNames;
264  }
265 
266  // ---------------------------------------------------------------------- //
267  /// \name Comparison
268  // ---------------------------------------------------------------------- //
269  HDST_API
270  bool operator==(HdStBindingRequest const &other) const;
271 
272  HDST_API
273  bool operator!=(HdStBindingRequest const &other) const;
274 
275  // ---------------------------------------------------------------------- //
276  /// \name Hash
277  // ---------------------------------------------------------------------- //
278 
279  /// Returns the hash corresponding to this buffer request.
280  ///
281  /// Note that this hash captures the structural state of the request, not
282  /// the contents. For example, buffer array versions/reallocations will not
283  /// affect hash, but changing the BAR pointer will.
284  HDST_API
285  size_t ComputeHash() const;
286 
287  // TfHash support.
288  template <class HashState>
289  friend void TfHashAppend(HashState &h, HdStBindingRequest const &br) {
290  h.Append(br._name,
291  br._bindingType,
292  br._dataType,
293  br._isInterleaved);
294  }
295 
296 private:
297  // This class unfortunately represents several concepts packed into a single
298  // class. Ideally, we would break this out as one class per concept,
299  // however that would also require virtual dispatch, which is overkill for
300  // the current use cases.
301 
302  // Named binding request
303  HdStBinding::Type _bindingType;
304  HdType _dataType;
305  TfToken _name;
306 
307  // Resource binding request
308  HdStBufferResourceSharedPtr _resource;
309 
310  // Struct binding request
312  bool _isInterleaved;
313 
314  bool _isWritable;
315 
316  size_t _arraySize;
317 
318  bool _concatenateNames;
319 };
320 
321 
323 
324 #endif // PXR_IMAGING_HDST_BINDING_H
HdStBindingRequest(HdStBinding::Type bindingType, TfToken const &name)
Definition: binding.h:117
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
size_t GetArraySize() const
Array size if request is for an array of structs.
Definition: binding.h:256
HdStBindingRequest(HdStBinding::Type bindingType, TfToken const &name, HdType dataType)
Definition: binding.h:131
friend void TfHashAppend(HashState &h, HdStBindingRequest const &br)
Definition: binding.h:289
std::vector< class HdStBindingRequest > HdStBindingRequestVector
Definition: binding.h:23
int GetTextureUnit() const
Definition: binding.h:91
HdStBinding::Type GetBindingType() const
Returns the HdStBinding type of this request.
Definition: binding.h:226
HDST_API bool operator==(HdStBindingRequest const &other) const
HdBufferArrayRangeSharedPtr const & GetBar() const
Definition: binding.h:246
OutGridT const XformOp bool bool
bool IsBufferArray() const
Definition: binding.h:192
HDST_API size_t ComputeHash() const
bool IsValid() const
Definition: binding.h:88
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:108
Definition: token.h:70
HdStBinding(Type type, int location, int textureUnit=0)
Definition: binding.h:82
HdStBinding()
Definition: binding.h:81
bool ConcatenateNames() const
Definition: binding.h:262
bool IsTypeless() const
Definition: binding.h:212
HdStBufferResourceSharedPtr const & GetResource() const
Definition: binding.h:231
HdStBindingRequest()=default
GLint location
Definition: glcorearb.h:805
GLuint const GLchar * name
Definition: glcorearb.h:786
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
HdStBindingRequest(HdStBinding::Type bindingType, TfToken const &name, HdStBufferResourceSharedPtr const &resource)
Definition: binding.h:146
bool IsResource() const
Definition: binding.h:185
std::shared_ptr< class HdStBufferResource > HdStBufferResourceSharedPtr
Type GetType() const
Definition: binding.h:89
int GetByteOffset() const
Returns the resource or buffer array range offset, defaults to zero.
Definition: binding.h:235
bool isWritable() const
Definition: binding.h:206
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
TfToken const & GetName() const
Definition: binding.h:222
bool IsInterleavedBufferArray() const
Definition: binding.h:200
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define HDST_API
Definition: api.h:23
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
std::shared_ptr< HdBufferArrayRange > HdBufferArrayRangeSharedPtr
Definition: bufferArray.h:27
void Set(Type type, int location, int textureUnit)
Definition: binding.h:85
HdType GetDataType() const
Return the data type of this request.
Definition: binding.h:251
HdStBindingRequest(HdStBinding::Type type, TfToken const &name, HdBufferArrayRangeSharedPtr bar, bool interleave, bool writable=false, size_t arraySize=0, bool concatenateNames=false)
Definition: binding.h:164
int GetValue() const
Definition: binding.h:92
std::vector< class HdStBinding > HdStBindingVector
Definition: binding.h:22
that also have some descendant prim *whose name begins with bar
HdType
Definition: types.h:272
HDST_API bool operator!=(HdStBindingRequest const &other) const
HUSD_API const char * dataType()
int GetLocation() const
Definition: binding.h:90
bool operator<(HdStBinding const &b) const
Definition: binding.h:93