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 2020 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_HGI_TYPES_H
25 #define PXR_IMAGING_HGI_TYPES_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/base/gf/vec3i.h"
29 #include "pxr/imaging/hgi/api.h"
30 #include <vector>
31 #include <limits>
32 #include <stdlib.h>
33 
34 
36 
37 /// \enum HgiFormat
38 ///
39 /// HgiFormat describes the memory format of image buffers used in Hgi.
40 /// These formats are closely aligned with HdFormat and allow us to keep Hgi
41 /// independent of Hd.
42 ///
43 /// For reference, see:
44 /// https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#VkFormat
45 enum HgiFormat : int
46 {
48 
49  // UNorm8 - a 1-byte value representing a float between 0 and 1.
50  // float value = (unorm / 255.0f);
53  /* HgiFormatUNorm8Vec3 */ // Unsupported Metal (MTLPixelFormat)
55 
56  // SNorm8 - a 1-byte value representing a float between -1 and 1.
57  // float value = max(snorm / 127.0f, -1.0f);
60  /* HgiFormatSNorm8Vec3 */ // Unsupported Metal (MTLPixelFormat)
62 
63  // Float16 - a 2-byte IEEE half-precision float.
68 
69  // Float32 - a 4-byte IEEE float.
74 
75  // Int16 - a 2-byte signed integer
80 
81  // UInt16 - a 2-byte unsigned integer
86 
87  // Int32 - a 4-byte signed integer
92 
93  // UNorm8 SRGB - a 1-byte value representing a float between 0 and 1.
94  // Gamma compression/decompression happens during read/write.
95  // Alpha component is linear.
96  /* HgiFormatUNorm8srgb */ // Unsupported by OpenGL
97  /* HgiFormatUNorm8Vec2srgb */ // Unsupported by OpenGL
98  /* HgiFormatUNorm8Vec3srgb */ // Unsupported Metal (MTLPixelFormat)
100 
101  // BPTC compressed. 3-component, 4x4 blocks, signed floating-point
103 
104  // BPTC compressed. 3-component, 4x4 blocks, unsigned floating-point
106 
107  // BPTC compressed. 4-component, 4x4 blocks, unsigned byte.
108  // Representing a float between 0 and 1.
110 
111  // BPTC compressed. 4-component, 4x4 blocks, unsigned byte, sRGB.
112  // Representing a float between 0 and 1.
114 
115  // S3TC/DXT compressed. 4-component, 4x4 blocks, unsigned byte
116  // Representing a float between 0 and 1.
118 
119  // S3TC/DXT compressed. 4-component, 4x4 blocks, unsigned byte
120  // Representing a float between 0 and 1.
122 
123  // Depth stencil format (Float32 can be used for just depth)
125 
126  // Packed 32-bit value with four normalized signed two's complement
127  // integer values arranged as 10 bits, 10 bits, 10 bits, and 2 bits.
129 
131 };
132 
133 /// \class HgiMipInfo
134 ///
135 /// HgiMipInfo describes size and other info for a mip level.
137 {
138  /// Offset in bytes from start of texture data to start of mip map.
139  size_t byteOffset;
140  /// Dimension of mip GfVec3i.
142  /// size of (one layer if array of) mip map in bytes.
144 };
145 
146 /// Return the count of components in the given format.
147 HGI_API
149 
150 /// Return the size of a single element of the given format.
151 ///
152 /// For an uncompressed format, returns the number of bytes per pixel
153 /// and sets blockWidth and blockHeight to 1.
154 /// For a compressed format (e.g., BC6), returns the number of bytes per
155 /// block and sets blockWidth and blockHeight to the width and height of
156 /// a block.
157 ///
158 HGI_API
160  HgiFormat f,
161  size_t *blockWidth = nullptr,
162  size_t *blockHeight = nullptr);
163 
164 /// Return whether the given format uses compression.
165 HGI_API
167 
168 /// Returns the size necessary to allocate a buffer of given dimensions
169 /// and format, rounding dimensions up to suitable multiple when
170 /// using a compressed format.
171 HGI_API
172 size_t HgiGetDataSize(
173  HgiFormat f,
174  const GfVec3i &dimensions);
175 
176 /// Returns the scalar type of the format, in the form of an HgiFormat, if
177 /// possible.
178 HGI_API
180  HgiFormat f);
181 
182 /// Returns mip infos.
183 ///
184 /// If dataByteSize is specified, the levels stops when the total memory
185 /// required by all levels up to that point reach the specified value.
186 /// Otherwise, the levels stop when all dimensions are 1.
187 /// Mip map sizes are calculated by dividing the previous mip level by two and
188 /// rounding down to the nearest integer (minimum integer is 1).
189 /// level 0: 37x53
190 /// level 1: 18x26
191 /// level 2: 9x13
192 /// level 3: 4x6
193 /// level 4: 2x3
194 /// level 5: 1x1
195 HGI_API
196 std::vector<HgiMipInfo>
199  const GfVec3i& dimensions,
200  size_t layerCount,
201  size_t dataByteSize = std::numeric_limits<size_t>::max());
202 
204 
205 #endif
size_t byteOffset
Offset in bytes from start of texture data to start of mip map.
Definition: types.h:139
HGI_API bool HgiIsCompressed(HgiFormat f)
Return whether the given format uses compression.
HGI_API size_t HgiGetDataSizeOfFormat(HgiFormat f, size_t *blockWidth=nullptr, size_t *blockHeight=nullptr)
HGI_API std::vector< HgiMipInfo > HgiGetMipInfos(HgiFormat format, const GfVec3i &dimensions, size_t layerCount, size_t dataByteSize=std::numeric_limits< size_t >::max())
HgiFormat
Definition: types.h:45
GLfloat f
Definition: glcorearb.h:1926
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
Definition: vec3i.h:60
HGI_API size_t HgiGetDataSize(HgiFormat f, const GfVec3i &dimensions)
GfVec3i dimensions
Dimension of mip GfVec3i.
Definition: types.h:141
#define HGI_API
Definition: api.h:40
HGI_API size_t HgiGetComponentCount(HgiFormat f)
Return the count of components in the given format.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
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
size_t byteSizePerLayer
size of (one layer if array of) mip map in bytes.
Definition: types.h:143
HGI_API HgiFormat HgiGetComponentBaseFormat(HgiFormat f)