HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
types.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_TYPES_H
25 #define PXR_IMAGING_HD_TYPES_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hd/api.h"
29 #include "pxr/imaging/hd/enums.h"
30 #include "pxr/imaging/hd/version.h"
31 #include "pxr/base/vt/value.h"
32 #include <algorithm>
33 #include <cmath>
34 #include <cstddef>
35 #include <cstdint>
36 
38 
39 /// \enum HdWrap
40 ///
41 /// Enumerates wrapping attributes type values.
42 ///
43 /// <ul>
44 /// <li>\b HdWrapClamp Clamp coordinate to range [1/(2N),1-1/(2N)] where N is the size of the texture in the direction of clamping</li>
45 /// <li>\b HdWrapRepeat Creates a repeating pattern</li>
46 /// <li>\b HdWrapBlack Clamp coordinate to range [-1/(2N),1+1/(2N)] where N is the size of the texture in the direction of clamping</li>
47 /// <li>\b HdWrapMirror Creates a mirrored repeating pattern.</li>
48 /// <li>\b HdWrapNoOpinion No opinion. The data texture can define its own wrap mode that we can use instead. Fallback to HdWrapBlack</li>
49 /// <li>\b HdWrapLegacyNoOpinionFallbackRepeat (deprecated) Similar to HdWrapNoOpinon but fallback to HdWrapRepeat</li>
50 /// <li>\b HdWrapUseMetadata (deprecated) Alias for HdWrapNoOpinion</li>
51 /// <li>\b HdWrapLegacy (deprecated) Alias for HdWrapLegacyNoOpinionFallbackRepeat</li>
52 /// </ul>
53 ///
54 enum HdWrap
55 {
60 
63 
64  HdWrapUseMetadata = HdWrapNoOpinion, // deprecated alias
66 };
67 
68 /// \enum HdMinFilter
69 ///
70 /// Enumerates minFilter attribute type values.
71 ///
72 /// <ul>
73 /// <li>\b HdMinFilterNearest Nearest to center of the pixel</li>
74 /// <li>\b HdMinFilterLinear Weighted average od the four texture elements closest to the pixel</li>
75 /// <li>\b HdMinFilterNearestMipmapNearest Nearest to center of the pixel from the nearest mipmaps</li>
76 /// <li>\b HdMinFilterLinearMipmapNeares Weighted average using texture elements from the nearest mipmaps</li>
77 /// <li>\b HdMinFilterNearestMipmapLinear Weighted average of the nearest pixels from the two nearest mipmaps</li>
78 /// <li>\b HdMinFilterLinearMipmapLinear WeightedAverage of the weighted averages from the nearest mipmaps</li>
79 /// </ul>
80 ///
82 {
89 };
90 
91 /// \enum HdMagFilter
92 ///
93 /// Enumerates magFilter attribute type values.
94 ///
95 /// <ul>
96 /// <li>HdFilterNearest Nearest to center of the pixel</li>
97 /// <li>HdFilterLinear Weighted average of the four texture elements closest to the pixel</li>
98 /// </ul>
99 ///
101 {
104 };
105 
106 /// \enum HdBorderColor
107 ///
108 /// Border color to use for clamped texture values.
109 ///
110 /// <ul>
111 /// <li>HdBorderColorTransparentBlack</li>
112 /// <li>HdBorderColorOpaqueBlack</li>
113 /// <li>HdBorderColorOpaqueWhite</li>
114 /// </ul>
115 ///
117 {
121 };
122 
123 /// \class HdSamplerParameters
124 ///
125 /// Collection of standard parameters such as wrap modes to sample a texture.
126 ///
128 public:
137 
138  HD_API
140 
141  HD_API
145  bool enableCompare=false,
147 
148  HD_API
149  bool operator==(const HdSamplerParameters &other) const;
150 
151  HD_API
152  bool operator!=(const HdSamplerParameters &other) const;
153 };
154 
155 ///
156 /// Type representing a set of dirty bits.
157 ///
158 typedef uint32_t HdDirtyBits;
159 
160 // GL Spec 2.3.5.2 (signed case, eq 2.4)
161 inline int HdConvertFloatToFixed(float v, int b)
162 {
163  return int(
164  std::round(
165  std::min(std::max(v, -1.0f), 1.0f) * (float(1 << (b-1)) - 1.0f)));
166 }
167 
168 // GL Spec 2.3.5.1 (signed case, eq 2.2)
169 inline float HdConvertFixedToFloat(int v, int b)
170 {
171  return float(
172  std::max(-1.0f,
173  (v / (float(1 << (b-1)) - 1.0f))));
174 }
175 
176 ///
177 /// HdVec4f_2_10_10_10_REV is a compact representation of a GfVec4f.
178 /// It uses 10 bits for x, y, and z, and 2 bits for w.
179 ///
180 /// XXX We expect this type to move again as we continue work on
181 /// refactoring the GL dependencies.
182 ///
184 {
186 
187  template <typename Vec3Type>
188  HdVec4f_2_10_10_10_REV(Vec3Type const &value) {
189  x = HdConvertFloatToFixed(value[0], 10);
190  y = HdConvertFloatToFixed(value[1], 10);
191  z = HdConvertFloatToFixed(value[2], 10);
192  w = 0;
193  }
194 
196  HdVec4f_2_10_10_10_REV const* other =
197  reinterpret_cast<HdVec4f_2_10_10_10_REV const*>(&value);
198  x = other->x;
199  y = other->y;
200  z = other->z;
201  w = other->w;
202  }
203 
204  template <typename Vec3Type>
205  Vec3Type GetAsVec() const {
206  return Vec3Type(HdConvertFixedToFloat(x, 10),
208  HdConvertFixedToFloat(z, 10));
209  }
210 
211  int GetAsInt() const {
212  int const* asInt = reinterpret_cast<int const*>(this);
213  return *asInt;
214  }
215 
216  bool operator==(const HdVec4f_2_10_10_10_REV &other) const {
217  return (other.w == w &&
218  other.z == z &&
219  other.y == y &&
220  other.x == x);
221  }
222  bool operator!=(const HdVec4f_2_10_10_10_REV &other) const {
223  return !(*this == other);
224  }
225 
226  int x : 10;
227  int y : 10;
228  int z : 10;
229  int w : 2;
230 };
231 
232 /// \enum HdType
233 ///
234 /// HdType describes the type of an attribute value used in Hd.
235 ///
236 /// HdType values have a specific machine representation and size.
237 /// See HdDataSizeOfType().
238 ///
239 /// HdType specifies a scalar, vector, or matrix type. Vector and
240 /// matrix types can be unpacked into the underlying "component"
241 /// type; see HdGetComponentType().
242 ///
243 /// HdType is intended to span the common set of attribute types
244 /// used in shading languages such as GLSL. However, it currently
245 /// does not include non-4x4 matrix types, nor struct types.
246 ///
247 /// Fixed-size array types are represented by the related class
248 /// HdTupleType. HdTupleType is used anywhere there is a
249 /// possibility of an array of values.
250 ///
251 /// ## Value arrays and attribute buffers
252 ///
253 /// Attribute data is often stored in linear buffers. These buffers
254 /// have multiple dimensions and it is important to distinguish them:
255 ///
256 /// - "Components" refer to the scalar components that comprise a vector
257 /// or matrix. For example, a vec3 has 3 components, a mat4 has
258 /// 16 components, and a float has a single component.
259 ///
260 /// - "Elements" refer to external concepts that entries in a buffer
261 /// associate with. Typically these are pieces of geometry,
262 /// such as faces or vertices.
263 ///
264 /// - "Arrays" refer to the idea that each element may associate
265 /// with a fixed-size array of values. For example, one approach
266 /// to motion blur might store a size-2 array of HdFloatMat4
267 /// values for each element of geometry, holding the transforms
268 /// at the beginning and ending of the camera shutter interval.
269 ///
270 /// Combining these concepts in an example, a primvar buffer might hold
271 /// data for 10 vertices (the elements) with each vertex having a
272 /// 2 entries (an array) of 4x4 matrices (with 16 components each).
273 /// As a packed linear buffer, this would occupy 10*2*16==320 floats.
274 ///
275 /// It is important to distinguish components from array entries,
276 /// and arrays from elements. HdType and HdTupleType only
277 /// addresses components and arrays; elements are tracked by buffers.
278 /// See for example HdBufferSource::GetNumElements().
279 ///
280 /// In other words, HdType and HdTupleType describe values.
281 /// Buffers describe elements and all other details regarding buffer
282 /// layout, such as offset/stride used to interleave attribute data.
283 ///
284 /// For more background, see the OpenGL discussion on data types:
285 /// - https://www.khronos.org/opengl/wiki/OpenGL_Type
286 ///
287 enum HdType
288 {
290 
291  /// Corresponds to GL_BOOL
297 
298  /// Corresponds to GL_INT
300  /// A 2-component vector with Int32-valued components.
302  /// A 3-component vector with Int32-valued components.
304  /// A 4-component vector with Int32-valued components.
306 
307  /// An unsigned 32-bit integer. Corresponds to GL_UNSIGNED_INT.
309  /// A 2-component vector with UInt32-valued components.
311  /// A 3-component vector with UInt32-valued components.
313  /// A 4-component vector with UInt32-valued components.
315 
316  /// Corresponds to GL_FLOAT
318  /// Corresponds to GL_FLOAT_VEC2
320  /// Corresponds to GL_FLOAT_VEC3
322  /// Corresponds to GL_FLOAT_VEC4
324  /// Corresponds to GL_FLOAT_MAT3
326  /// Corresponds to GL_FLOAT_MAT4
328 
329  /// Corresponds to GL_DOUBLE
331  /// Corresponds to GL_DOUBLE_VEC2
333  /// Corresponds to GL_DOUBLE_VEC3
335  /// Corresponds to GL_DOUBLE_VEC4
337  /// Corresponds to GL_DOUBLE_MAT3
339  /// Corresponds to GL_DOUBLE_MAT4
341 
346 
347  /// Packed, reverse-order encoding of a 4-component vector into Int32.
348  /// Corresponds to GL_INT_2_10_10_10_REV.
349  /// \see HdVec4f_2_10_10_10_REV
351 
353 };
354 
355 /// HdTupleType represents zero, one, or more values of the same HdType.
356 /// It can be used to represent fixed-size array types, as well as single
357 /// values. See HdType for more discussion about arrays.
358 struct HdTupleType {
360  size_t count;
361 
362  bool operator< (HdTupleType const& rhs) const {
363  return (type < rhs.type) || (type == rhs.type && count < rhs.count);
364  }
365  bool operator== (HdTupleType const& rhs) const {
366  return type == rhs.type && count == rhs.count;
367  }
368  bool operator!= (HdTupleType const& rhs) const {
369  return !(*this == rhs);
370  }
371 };
372 
373 // Support TfHash.
374 template <class HashState>
375 void
376 TfHashAppend(HashState &h, HdTupleType const &tt)
377 {
378  h.Append(tt.type, tt.count);
379 }
380 
381 /// Returns a direct pointer to the data held by a VtValue.
382 /// Returns nullptr if the VtValue is empty or holds a type unknown to Hd.
383 HD_API
384 const void* HdGetValueData(const VtValue &);
385 
386 /// Returns the HdTupleType that describes the given VtValue.
387 /// For scalar, vector, and matrix types, the count is 1.
388 /// For any VtArray type, the count is the number of array members.
389 HD_API
391 
392 /// Return the component type for the given value type.
393 /// For vectors and matrices, this is the scalar type of their components.
394 /// For scalars, this is the type itself.
395 /// As an example, the component type of HdTypeFloatMat4 is HdTypeFloat.
396 HD_API
398 
399 /// Return the count of components in the given value type.
400 /// For example, HdTypeFloatVec3 has 3 components.
401 HD_API
403 
404 /// Return the size, in bytes, of a single value of the given type.
405 HD_API
406 size_t HdDataSizeOfType(HdType);
407 
408 /// Return the size, in bytes, of a value with HdTupleType.
409 HD_API
411 
412 /// \enum HdFormat
413 ///
414 /// HdFormat describes the memory format of image buffers used in Hd.
415 /// It's similar to HdType but with more specific associated semantics.
416 ///
417 /// The list of supported formats is modelled after Vulkan and DXGI, though
418 /// Hydra only supports a subset. Endian-ness is explicitly not captured;
419 /// color data is assumed to always be RGBA.
420 ///
421 /// For reference, see:
422 /// https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#VkFormat
424 {
426 
427  // UNorm8 - a 1-byte value representing a float between 0 and 1.
428  // float value = (unorm / 255.0f);
433 
434  // SNorm8 - a 1-byte value representing a float between -1 and 1.
435  // float value = max(snorm / 127.0f, -1.0f);
440 
441  // Float16 - a 2-byte IEEE half-precision float.
446 
447  // Float32 - a 4-byte IEEE float.
452 
453  // Int16 - a 2-byte signed integer
458 
459  // UInt16 - a 2-byte unsigned integer
464 
465  // Int32 - a 4-byte signed integer
470 
471  // Depth-stencil format
473 
475 };
476 
477 /// Return the single-channel version of a given format.
478 HD_API
480 
481 /// Return the count of components in the given format.
482 HD_API
484 
485 /// Return the size of a single element of the given format.
486 /// For block formats, this will return 0.
487 HD_API
489 
491 
492 #endif // PXR_IMAGING_HD_TYPES_H
HD_API size_t HdDataSizeOfType(HdType)
Return the size, in bytes, of a single value of the given type.
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
HdCompareFunction
Definition: enums.h:36
HdFormat
Definition: types.h:423
HdWrap
Definition: types.h:54
A 2-component vector with Int32-valued components.
Definition: types.h:301
bool operator==(const HdVec4f_2_10_10_10_REV &other) const
Definition: types.h:216
size_t count
Definition: types.h:360
uint32_t HdDirtyBits
Definition: types.h:158
HD_API size_t HdDataSizeOfTupleType(HdTupleType)
Return the size, in bytes, of a value with HdTupleType.
Corresponds to GL_FLOAT_VEC3.
Definition: types.h:321
#define HD_API
Definition: api.h:40
A 4-component vector with Int32-valued components.
Definition: types.h:305
HD_API HdType HdGetComponentType(HdType)
HdCompareFunction compareFunction
Definition: types.h:136
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
int HdConvertFloatToFixed(float v, int b)
Definition: types.h:161
Corresponds to GL_DOUBLE_VEC4.
Definition: types.h:336
bool operator!=(HdTupleType const &rhs) const
Definition: types.h:368
float HdConvertFixedToFloat(int v, int b)
Definition: types.h:169
A 3-component vector with Int32-valued components.
Definition: types.h:303
GLdouble GLdouble t
Definition: glew.h:1403
bool operator<(HdTupleType const &rhs) const
Definition: types.h:362
Corresponds to GL_DOUBLE_VEC3.
Definition: types.h:334
Corresponds to GL_INT.
Definition: types.h:299
GLint GLenum GLint x
Definition: glcorearb.h:409
int GetAsInt() const
Definition: types.h:211
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
HdMinFilter
Definition: types.h:81
HdBorderColor
Definition: types.h:116
HD_API const void * HdGetValueData(const VtValue &)
HD_API HdTupleType HdGetValueTupleType(const VtValue &)
bool operator!=(const HdVec4f_2_10_10_10_REV &other) const
Definition: types.h:222
const GLdouble * v
Definition: glcorearb.h:837
bool operator==(HdTupleType const &rhs) const
Definition: types.h:365
GLdouble GLdouble GLdouble z
Definition: glcorearb.h:848
typedef int(WINAPI *PFNWGLRELEASEPBUFFERDCARBPROC)(HPBUFFERARB hPbuffer
Corresponds to GL_FLOAT.
Definition: types.h:317
GLint GLsizei count
Definition: glcorearb.h:405
void TfHashAppend(HashState &h, HdTupleType const &tt)
Definition: types.h:376
A 3-component vector with UInt32-valued components.
Definition: types.h:312
vfloat4 round(const vfloat4 &a)
Definition: simd.h:7436
Corresponds to GL_BOOL.
Definition: types.h:292
HdVec4f_2_10_10_10_REV(Vec3Type const &value)
Definition: types.h:188
An unsigned 32-bit integer. Corresponds to GL_UNSIGNED_INT.
Definition: types.h:308
HdMagFilter
Definition: types.h:100
Corresponds to GL_DOUBLE_MAT3.
Definition: types.h:338
Corresponds to GL_FLOAT_VEC2.
Definition: types.h:319
HdVec4f_2_10_10_10_REV(int const value)
Definition: types.h:195
HD_API bool operator!=(const HdSamplerParameters &other) const
Corresponds to GL_FLOAT_MAT4.
Definition: types.h:327
Corresponds to GL_FLOAT_MAT3.
Definition: types.h:325
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
A 4-component vector with UInt32-valued components.
Definition: types.h:314
HD_API HdFormat HdGetComponentFormat(HdFormat f)
Return the single-channel version of a given format.
HdMinFilter minFilter
Definition: types.h:132
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
HD_API size_t HdGetComponentCount(HdType t)
Corresponds to GL_DOUBLE_VEC2.
Definition: types.h:332
Corresponds to GL_FLOAT_VEC4.
Definition: types.h:323
Corresponds to GL_DOUBLE_MAT4.
Definition: types.h:340
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
HdBorderColor borderColor
Definition: types.h:134
GLsizei const GLfloat * value
Definition: glcorearb.h:824
GLfloat f
Definition: glcorearb.h:1926
Vec3Type GetAsVec() const
Definition: types.h:205
Definition: core.h:1131
#define const
Definition: zconf.h:214
type
Definition: core.h:1059
HdType
Definition: types.h:287
HdMagFilter magFilter
Definition: types.h:133
GLint y
Definition: glcorearb.h:103
Definition: value.h:166
Corresponds to GL_DOUBLE.
Definition: types.h:330
HD_API size_t HdDataSizeOfFormat(HdFormat f)
HD_API bool operator==(const HdSamplerParameters &other) const
A 2-component vector with UInt32-valued components.
Definition: types.h:310
HdType type
Definition: types.h:359
HD_API HdSamplerParameters()
bool enableCompare
Definition: types.h:135