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/version.h"
30 #include "pxr/base/vt/value.h"
31 #include <algorithm>
32 #include <cmath>
33 #include <cstddef>
34 #include <cstdint>
35
36 PXR_NAMESPACE_OPEN_SCOPE
37
38 /// \enum HdWrap
39 ///
40 /// Enumerates wrapping attributes type values.
41 ///
42 /// <ul>
43 /// <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>
44 /// <li>\b HdWrapRepeat Creates a repeating pattern</li>
45 /// <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>
46 /// <li>\b HdWrapMirror Creates a mirrored repeating pattern.</li>
47 /// <li>\b HdWrapNoOpinion No opinion. The data texture can define its own wrap mode that we can use instead. Fallback to HdWrapBlack</li>
48 /// <li>\b HdWrapLegacyNoOpinionFallbackRepeat (deprecated) Similar to HdWrapNoOpinon but fallback to HdWrapRepeat</li>
49 /// <li>\b HdWrapUseMetadata (deprecated) Alias for HdWrapNoOpinion</li>
50 /// <li>\b HdWrapLegacy (deprecated) Alias for HdWrapLegacyNoOpinionFallbackRepeat</li>
51 /// </ul>
52 ///
53 enum HdWrap
54 {
55 HdWrapClamp,
56 HdWrapRepeat,
57 HdWrapBlack,
58 HdWrapMirror,
59
60 HdWrapNoOpinion,
61 HdWrapLegacyNoOpinionFallbackRepeat, // deprecated
62
63 HdWrapUseMetadata = HdWrapNoOpinion, // deprecated alias
64 HdWrapLegacy = HdWrapLegacyNoOpinionFallbackRepeat // deprecated alias
65 };
66
67 /// \enum HdMinFilter
68 ///
69 /// Enumerates minFilter attribute type values.
70 ///
71 /// <ul>
72 /// <li>\b HdMinFilterNearest Nearest to center of the pixel</li>
73 /// <li>\b HdMinFilterLinear Weighted average od the four texture elements closest to the pixel</li>
74 /// <li>\b HdMinFilterNearestMipmapNearest Nearest to center of the pixel from the nearest mipmaps</li>
75 /// <li>\b HdMinFilterLinearMipmapNeares Weighted average using texture elements from the nearest mipmaps</li>
76 /// <li>\b HdMinFilterNearestMipmapLinear Weighted average of the nearest pixels from the two nearest mipmaps</li>
77 /// <li>\b HdMinFilterLinearMipmapLinear WeightedAverage of the weighted averages from the nearest mipmaps</li>
78 /// </ul>
79 ///
80 enum HdMinFilter
81 {
82 HdMinFilterNearest,
83 HdMinFilterLinear,
84 HdMinFilterNearestMipmapNearest,
85 HdMinFilterLinearMipmapNearest,
86 HdMinFilterNearestMipmapLinear,
87 HdMinFilterLinearMipmapLinear,
88 };
89
90 /// \enum HdMagFilter
91 ///
92 /// Enumerates magFilter attribute type values.
93 ///
94 /// <ul>
95 /// <li>HdFilterNearest Nearest to center of the pixel</li>
96 /// <li>HdFilterLinear Weighted average of the four texture elements closest to the pixel</li>
97 /// </ul>
98 ///
99 enum HdMagFilter
100 {
101 HdMagFilterNearest,
102 HdMagFilterLinear,
103 };
104
105 /// \class HdSamplerParameters
106 ///
107 /// Collection of standard parameters such as wrap modes to sample a texture.
108 ///
109 class HdSamplerParameters {
110 public:
111 HdWrap wrapS;
112 HdWrap wrapT;
113 HdWrap wrapR;
114 HdMinFilter minFilter;
115 HdMagFilter magFilter;
116
117 HD_API
118 bool operator==(const HdSamplerParameters &other) const;
119
120 HD_API
121 bool operator!=(const HdSamplerParameters &other) const;
122 };
123
124 ///
125 /// Type representing a set of dirty bits.
126 ///
127 typedef uint32_t HdDirtyBits;
128
129 // GL Spec 2.3.5.2 (signed case, eq 2.4)
HdConvertFloatToFixed(float v,int b)130 inline int HdConvertFloatToFixed(float v, int b)
131 {
132 return int(
133 std::round(
134 std::min(std::max(v, -1.0f), 1.0f) * (float(1 << (b-1)) - 1.0f)));
135 }
136
137 // GL Spec 2.3.5.1 (signed case, eq 2.2)
HdConvertFixedToFloat(int v,int b)138 inline float HdConvertFixedToFloat(int v, int b)
139 {
140 return float(
141 std::max(-1.0f,
142 (v / (float(1 << (b-1)) - 1.0f))));
143 }
144
145 ///
146 /// HdVec4f_2_10_10_10_REV is a compact representation of a GfVec4f.
147 /// It uses 10 bits for x, y, and z, and 2 bits for w.
148 ///
149 /// XXX We expect this type to move again as we continue work on
150 /// refactoring the GL dependencies.
151 ///
152 struct HdVec4f_2_10_10_10_REV
153 {
HdVec4f_2_10_10_10_REVHdVec4f_2_10_10_10_REV154 HdVec4f_2_10_10_10_REV() { }
155
156 template <typename Vec3Type>
HdVec4f_2_10_10_10_REVHdVec4f_2_10_10_10_REV157 HdVec4f_2_10_10_10_REV(Vec3Type const &value) {
158 x = HdConvertFloatToFixed(value[0], 10);
159 y = HdConvertFloatToFixed(value[1], 10);
160 z = HdConvertFloatToFixed(value[2], 10);
161 w = 0;
162 }
163
HdVec4f_2_10_10_10_REVHdVec4f_2_10_10_10_REV164 HdVec4f_2_10_10_10_REV(int const value) {
165 HdVec4f_2_10_10_10_REV const* other =
166 reinterpret_cast<HdVec4f_2_10_10_10_REV const*>(&value);
167 x = other->x;
168 y = other->y;
169 z = other->z;
170 w = other->w;
171 }
172
173 template <typename Vec3Type>
GetAsVecHdVec4f_2_10_10_10_REV174 Vec3Type GetAsVec() const {
175 return Vec3Type(HdConvertFixedToFloat(x, 10),
176 HdConvertFixedToFloat(y, 10),
177 HdConvertFixedToFloat(z, 10));
178 }
179
GetAsIntHdVec4f_2_10_10_10_REV180 int GetAsInt() const {
181 int const* asInt = reinterpret_cast<int const*>(this);
182 return *asInt;
183 }
184
185 bool operator==(const HdVec4f_2_10_10_10_REV &other) const {
186 return (other.w == w &&
187 other.z == z &&
188 other.y == y &&
189 other.x == x);
190 }
191 bool operator!=(const HdVec4f_2_10_10_10_REV &other) const {
192 return !(*this == other);
193 }
194
195 int x : 10;
196 int y : 10;
197 int z : 10;
198 int w : 2;
199 };
200
201 /// \enum HdType
202 ///
203 /// HdType describes the type of an attribute value used in Hd.
204 ///
205 /// HdType values have a specific machine representation and size.
206 /// See HdDataSizeOfType().
207 ///
208 /// HdType specifies a scalar, vector, or matrix type. Vector and
209 /// matrix types can be unpacked into the underlying "component"
210 /// type; see HdGetComponentType().
211 ///
212 /// HdType is intended to span the common set of attribute types
213 /// used in shading languages such as GLSL. However, it currently
214 /// does not include non-4x4 matrix types, nor struct types.
215 ///
216 /// Fixed-size array types are represented by the related class
217 /// HdTupleType. HdTupleType is used anywhere there is a
218 /// possibility of an array of values.
219 ///
220 /// ## Value arrays and attribute buffers
221 ///
222 /// Attribute data is often stored in linear buffers. These buffers
223 /// have multiple dimensions and it is important to distinguish them:
224 ///
225 /// - "Components" refer to the scalar components that comprise a vector
226 /// or matrix. For example, a vec3 has 3 components, a mat4 has
227 /// 16 components, and a float has a single component.
228 ///
229 /// - "Elements" refer to external concepts that entries in a buffer
230 /// associate with. Typically these are pieces of geometry,
231 /// such as faces or vertices.
232 ///
233 /// - "Arrays" refer to the idea that each element may associate
234 /// with a fixed-size array of values. For example, one approach
235 /// to motion blur might store a size-2 array of HdFloatMat4
236 /// values for each element of geometry, holding the transforms
237 /// at the beginning and ending of the camera shutter interval.
238 ///
239 /// Combining these concepts in an example, a primvar buffer might hold
240 /// data for 10 vertices (the elements) with each vertex having a
241 /// 2 entries (an array) of 4x4 matrices (with 16 components each).
242 /// As a packed linear buffer, this would occupy 10*2*16==320 floats.
243 ///
244 /// It is important to distinguish components from array entries,
245 /// and arrays from elements. HdType and HdTupleType only
246 /// addresses components and arrays; elements are tracked by buffers.
247 /// See for example HdBufferSource::GetNumElements().
248 ///
249 /// In other words, HdType and HdTupleType describe values.
250 /// Buffers describe elements and all other details regarding buffer
251 /// layout, such as offset/stride used to interleave attribute data.
252 ///
253 /// For more background, see the OpenGL discussion on data types:
254 /// - https://www.khronos.org/opengl/wiki/OpenGL_Type
255 ///
256 enum HdType
257 {
258 HdTypeInvalid=-1,
259
260 /// Corresponds to GL_BOOL
261 HdTypeBool=0,
262 HdTypeUInt8,
263 HdTypeUInt16,
264 HdTypeInt8,
265 HdTypeInt16,
266
267 /// Corresponds to GL_INT
268 HdTypeInt32,
269 /// A 2-component vector with Int32-valued components.
270 HdTypeInt32Vec2,
271 /// A 3-component vector with Int32-valued components.
272 HdTypeInt32Vec3,
273 /// A 4-component vector with Int32-valued components.
274 HdTypeInt32Vec4,
275
276 /// An unsigned 32-bit integer. Corresponds to GL_UNSIGNED_INT.
277 HdTypeUInt32,
278 /// A 2-component vector with UInt32-valued components.
279 HdTypeUInt32Vec2,
280 /// A 3-component vector with UInt32-valued components.
281 HdTypeUInt32Vec3,
282 /// A 4-component vector with UInt32-valued components.
283 HdTypeUInt32Vec4,
284
285 /// Corresponds to GL_FLOAT
286 HdTypeFloat,
287 /// Corresponds to GL_FLOAT_VEC2
288 HdTypeFloatVec2,
289 /// Corresponds to GL_FLOAT_VEC3
290 HdTypeFloatVec3,
291 /// Corresponds to GL_FLOAT_VEC4
292 HdTypeFloatVec4,
293 /// Corresponds to GL_FLOAT_MAT3
294 HdTypeFloatMat3,
295 /// Corresponds to GL_FLOAT_MAT4
296 HdTypeFloatMat4,
297
298 /// Corresponds to GL_DOUBLE
299 HdTypeDouble,
300 /// Corresponds to GL_DOUBLE_VEC2
301 HdTypeDoubleVec2,
302 /// Corresponds to GL_DOUBLE_VEC3
303 HdTypeDoubleVec3,
304 /// Corresponds to GL_DOUBLE_VEC4
305 HdTypeDoubleVec4,
306 /// Corresponds to GL_DOUBLE_MAT3
307 HdTypeDoubleMat3,
308 /// Corresponds to GL_DOUBLE_MAT4
309 HdTypeDoubleMat4,
310
311 HdTypeHalfFloat,
312 HdTypeHalfFloatVec2,
313 HdTypeHalfFloatVec3,
314 HdTypeHalfFloatVec4,
315
316 /// Packed, reverse-order encoding of a 4-component vector into Int32.
317 /// Corresponds to GL_INT_2_10_10_10_REV.
318 /// \see HdVec4f_2_10_10_10_REV
319 HdTypeInt32_2_10_10_10_REV,
320 };
321
322 /// HdTupleType represents zero, one, or more values of the same HdType.
323 /// It can be used to represent fixed-size array types, as well as single
324 /// values. See HdType for more discussion about arrays.
325 struct HdTupleType {
326 HdType type;
327 size_t count;
328
329 bool operator< (HdTupleType const& rhs) const {
330 return (type < rhs.type) || (type == rhs.type && count < rhs.count);
331 }
332 bool operator== (HdTupleType const& rhs) const {
333 return type == rhs.type && count == rhs.count;
334 }
335 bool operator!= (HdTupleType const& rhs) const {
336 return !(*this == rhs);
337 }
338 };
339
340 // Support TfHash.
341 template <class HashState>
342 void
TfHashAppend(HashState & h,HdTupleType const & tt)343 TfHashAppend(HashState &h, HdTupleType const &tt)
344 {
345 h.Append(tt.type, tt.count);
346 }
347
348 /// Returns a direct pointer to the data held by a VtValue.
349 /// Returns nullptr if the VtValue is empty or holds a type unknown to Hd.
350 HD_API
351 const void* HdGetValueData(const VtValue &);
352
353 /// Returns the HdTupleType that describes the given VtValue.
354 /// For scalar, vector, and matrix types, the count is 1.
355 /// For any VtArray type, the count is the number of array members.
356 HD_API
357 HdTupleType HdGetValueTupleType(const VtValue &);
358
359 /// Return the component type for the given value type.
360 /// For vectors and matrices, this is the scalar type of their components.
361 /// For scalars, this is the type itself.
362 /// As an example, the component type of HdTypeFloatMat4 is HdTypeFloat.
363 HD_API
364 HdType HdGetComponentType(HdType);
365
366 /// Return the count of components in the given value type.
367 /// For example, HdTypeFloatVec3 has 3 components.
368 HD_API
369 size_t HdGetComponentCount(HdType t);
370
371 /// Return the size, in bytes, of a single value of the given type.
372 HD_API
373 size_t HdDataSizeOfType(HdType);
374
375 /// Return the size, in bytes, of a value with HdTupleType.
376 HD_API
377 size_t HdDataSizeOfTupleType(HdTupleType);
378
379 /// \enum HdFormat
380 ///
381 /// HdFormat describes the memory format of image buffers used in Hd.
382 /// It's similar to HdType but with more specific associated semantics.
383 ///
384 /// The list of supported formats is modelled after Vulkan and DXGI, though
385 /// Hydra only supports a subset. Endian-ness is explicitly not captured;
386 /// color data is assumed to always be RGBA.
387 ///
388 /// For reference, see:
389 /// https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#VkFormat
390 enum HdFormat
391 {
392 HdFormatInvalid=-1,
393
394 // UNorm8 - a 1-byte value representing a float between 0 and 1.
395 // float value = (unorm / 255.0f);
396 HdFormatUNorm8=0,
397 HdFormatUNorm8Vec2,
398 HdFormatUNorm8Vec3,
399 HdFormatUNorm8Vec4,
400
401 // SNorm8 - a 1-byte value representing a float between -1 and 1.
402 // float value = max(snorm / 127.0f, -1.0f);
403 HdFormatSNorm8,
404 HdFormatSNorm8Vec2,
405 HdFormatSNorm8Vec3,
406 HdFormatSNorm8Vec4,
407
408 // Float16 - a 2-byte IEEE half-precision float.
409 HdFormatFloat16,
410 HdFormatFloat16Vec2,
411 HdFormatFloat16Vec3,
412 HdFormatFloat16Vec4,
413
414 // Float32 - a 4-byte IEEE float.
415 HdFormatFloat32,
416 HdFormatFloat32Vec2,
417 HdFormatFloat32Vec3,
418 HdFormatFloat32Vec4,
419
420 // Int16 - a 2-byte signed integer
421 HdFormatInt16,
422 HdFormatInt16Vec2,
423 HdFormatInt16Vec3,
424 HdFormatInt16Vec4,
425
426 // UInt16 - a 2-byte unsigned integer
427 HdFormatUInt16,
428 HdFormatUInt16Vec2,
429 HdFormatUInt16Vec3,
430 HdFormatUInt16Vec4,
431
432 // Int32 - a 4-byte signed integer
433 HdFormatInt32,
434 HdFormatInt32Vec2,
435 HdFormatInt32Vec3,
436 HdFormatInt32Vec4,
437
438 // Depth-stencil format
439 HdFormatFloat32UInt8,
440
441 HdFormatCount
442 };
443
444 /// Return the single-channel version of a given format.
445 HD_API
446 HdFormat HdGetComponentFormat(HdFormat f);
447
448 /// Return the count of components in the given format.
449 HD_API
450 size_t HdGetComponentCount(HdFormat f);
451
452 /// Return the size of a single element of the given format.
453 /// For block formats, this will return 0.
454 HD_API
455 size_t HdDataSizeOfFormat(HdFormat f);
456
457 PXR_NAMESPACE_CLOSE_SCOPE
458
459 #endif // PXR_IMAGING_HD_TYPES_H
460