HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
texture.h
Go to the documentation of this file.
1 //
2 // Copyright 2019 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_TEXTURE_H
25 #define PXR_IMAGING_HGI_TEXTURE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/base/gf/vec3i.h"
29 #include "pxr/imaging/hgi/api.h"
30 #include "pxr/imaging/hgi/enums.h"
31 #include "pxr/imaging/hgi/handle.h"
32 #include "pxr/imaging/hgi/types.h"
33 
34 #include <string>
35 #include <vector>
36 
38 
39 /// \struct HgiComponentMapping
40 ///
41 /// Describes color component mapping.
42 ///
43 /// <ul>
44 /// <li>r:
45 /// What component is used for red channel.
46 /// <li>g:
47 /// What component is used for green channel.
48 /// <li>b:
49 /// What component is used for blue channel.
50 /// <li>a:
51 /// What component is used for alpha channel.
52 /// </ul>
53 ///
55 {
60 };
61 
62 HGI_API
63 bool operator==(
64  const HgiComponentMapping& lhs,
65  const HgiComponentMapping& rhs);
66 
67 HGI_API
68 bool operator!=(
69  const HgiComponentMapping& lhs,
70  const HgiComponentMapping& rhs);
71 
72 /// \struct HgiTextureDesc
73 ///
74 /// Describes the properties needed to create a GPU texture.
75 ///
76 /// <ul>
77 /// <li>debugName:
78 /// This label can be applied as debug label for GPU debugging.</li>
79 /// <li>usage:
80 /// Describes how the texture is intended to be used.</li>
81 /// <li>format:
82 /// The format of the texture.
83 /// <li>componentMapping:
84 /// The mapping of rgba components when accessing the texture.</li>
85 /// <li>dimensions:
86 /// The resolution of the texture (width, height, depth).</li>
87 /// <li>type:
88 /// Type of texture (2D, 3D).</li>
89 /// <li>layerCount:
90 /// The number of layers (texture-arrays).</li>
91 /// <li>mipLevels:
92 /// The number of mips in texture.</li>
93 /// <li>sampleCount:
94 /// samples per texel (multi-sampling).</li>
95 /// <li>pixelsByteSize:
96 /// Byte size (length) of pixel data (i.e., initialData).</li>
97 /// <li>initialData:
98 /// CPU pointer to initialization pixels of the texture.
99 /// The memory is consumed immediately during the creation of the HgiTexture.
100 /// The application may alter or free this memory as soon as the constructor
101 /// of the HgiTexture has returned.
102 /// Data may optionally include pixels for each mip-level.
103 /// HgiGetMipInitialData can be used to get to each mip's data and describes
104 /// in more detail how mip dimensions are rounded.</li>
105 /// </ul>
106 ///
108 {
110  : usage(0)
118  , dimensions(0)
119  , layerCount(1)
120  , mipLevels(1)
122  , pixelsByteSize(0)
123  , initialData(nullptr)
124  {}
125 
132  uint16_t layerCount;
133  uint16_t mipLevels;
136  void const* initialData;
137 };
138 
139 HGI_API
140 bool operator==(
141  const HgiTextureDesc& lhs,
142  const HgiTextureDesc& rhs);
143 
144 HGI_API
145 bool operator!=(
146  const HgiTextureDesc& lhs,
147  const HgiTextureDesc& rhs);
148 
149 
150 ///
151 /// \class HgiTexture
152 ///
153 /// Represents a graphics platform independent GPU texture resource.
154 /// Textures should be created via Hgi::CreateTexture.
155 ///
156 /// Base class for Hgi textures.
157 /// To the client (HdSt) texture resources are referred to via
158 /// opaque, stateless handles (HgTextureHandle).
159 ///
161 {
162 public:
163  HGI_API
164  virtual ~HgiTexture();
165 
166  /// The descriptor describes the object.
167  HGI_API
168  HgiTextureDesc const& GetDescriptor() const;
169 
170  /// Returns the byte size of the GPU texture.
171  /// This can be helpful if the application wishes to tally up memory usage.
172  HGI_API
173  virtual size_t GetByteSizeOfResource() const = 0;
174 
175  /// This function returns the handle to the Hgi backend's gpu resource, cast
176  /// to a uint64_t. Clients should avoid using this function and instead
177  /// use Hgi base classes so that client code works with any Hgi platform.
178  /// For transitioning code to Hgi, it can however we useful to directly
179  /// access a platform's internal resource handles.
180  /// There is no safety provided in using this. If you by accident pass a
181  /// HgiMetal resource into an OpenGL call, bad things may happen.
182  /// In OpenGL this returns the GLuint resource name.
183  /// In Metal this returns the id<MTLTexture> as uint64_t.
184  /// In Vulkan this returns the VkImage as uint64_t.
185  /// In DX12 this returns the ID3D12Resource pointer as uint64_t.
186  HGI_API
187  virtual uint64_t GetRawResource() const = 0;
188 
189 protected:
190  HGI_API
191  static
192  size_t _GetByteSizeOfResource(const HgiTextureDesc &descriptor);
193 
194  HGI_API
195  HgiTexture(HgiTextureDesc const& desc);
196 
198 
199 private:
200  HgiTexture() = delete;
201  HgiTexture & operator=(const HgiTexture&) = delete;
202  HgiTexture(const HgiTexture&) = delete;
203 };
204 
205 
207 using HgiTextureHandleVector = std::vector<HgiTextureHandle>;
208 
209 
210 /// \struct HgiTextureViewDesc
211 ///
212 /// Describes the properties needed to create a GPU texture view from an
213 /// existing GPU texture object.
214 ///
215 /// <ul>
216 /// <li>debugName:
217 /// This label can be applied as debug label for GPU debugging.</li>
218 /// <li>format:
219 /// The format of the texture view. This format must be compatible with
220 /// the sourceTexture, but does not have to be the identical format.
221 /// Generally: All 8-, 16-, 32-, 64-, and 128-bit color formats are
222 /// compatible with other formats with the same bit length.
223 /// For example HgiFormatFloat32Vec4 and HgiFormatInt32Vec4 are compatible.
224 /// <li>layerCount:
225 /// The number of layers (texture-arrays).</li>
226 /// <li>mipLevels:
227 /// The number of mips in texture.</li>
228 /// <li>sourceTexture:
229 /// Handle to the HgiTexture to be used as the source data backing.</li>
230 /// <li>sourceFirstLayer:
231 /// The layer index to use from the source texture as the first layer of the
232 /// view.</li>
233 /// <li>sourceFirstMip:
234 /// The mip index to ues from the source texture as the first mip of the
235 /// view.</li>
236 /// </ul>
237 ///
239 {
242  , layerCount(1)
243  , mipLevels(1)
244  , sourceTexture()
245  , sourceFirstLayer(0)
246  , sourceFirstMip(0)
247  {}
248 
251  uint16_t layerCount;
252  uint16_t mipLevels;
255  uint16_t sourceFirstMip;
256 };
257 
258 HGI_API
259 bool operator==(
260  const HgiTextureViewDesc& lhs,
261  const HgiTextureViewDesc& rhs);
262 
263 HGI_API
264 bool operator!=(
265  const HgiTextureViewDesc& lhs,
266  const HgiTextureViewDesc& rhs);
267 
268 ///
269 /// \class HgiTextureView
270 ///
271 /// Represents a graphics platform independent GPU texture view resource.
272 /// Texture Views should be created via Hgi::CreateTextureView.
273 ///
274 /// A TextureView aliases the data of another texture and is a thin wrapper
275 /// around a HgiTextureHandle. The embeded texture handle is used to
276 /// add the texture to resource bindings for use in shaders.
277 ///
278 /// For example when using a compute shader to fill the mip levels of a
279 /// texture, like a lightDome texture, we can use a texture view to give the
280 /// shader access to a specific mip level of a sourceTexture via a TextureView.
281 ///
282 /// Another example is to conserve resources by reusing a RGBAF32 texture as
283 /// a RGBAI32 texture once the F32 texture is no longer needed
284 /// (transient resources).
285 ///
287 {
288 public:
289  HGI_API
290  HgiTextureView(HgiTextureViewDesc const& desc);
291 
292  HGI_API
293  virtual ~HgiTextureView();
294 
295  /// Set the handle to the texture that aliases another texture.
296  HGI_API
297  void SetViewTexture(HgiTextureHandle const& handle);
298 
299  /// Returns the handle to the texture that aliases another texture.
300  HGI_API
301  HgiTextureHandle const& GetViewTexture() const;
302 
303 protected:
305 
306 private:
307  HgiTextureView() = delete;
308  HgiTextureView & operator=(const HgiTextureView&) = delete;
309  HgiTextureView(const HgiTextureView&) = delete;
310 };
311 
313 using HgiTextureViewHandleVector = std::vector<HgiTextureViewHandle>;
314 
316 
317 #endif
HgiComponentSwizzle a
Definition: texture.h:59
HgiTextureHandle sourceTexture
Definition: texture.h:253
std::string debugName
Definition: texture.h:126
std::string debugName
Definition: texture.h:249
virtual HGI_API size_t GetByteSizeOfResource() const =0
HgiTextureHandle _viewTexture
Definition: texture.h:304
uint16_t layerCount
Definition: texture.h:251
HgiTextureDesc _descriptor
Definition: texture.h:197
size_t pixelsByteSize
Definition: texture.h:135
int HgiHandle< class HgiTexture > HgiTextureHandle
static HGI_API size_t _GetByteSizeOfResource(const HgiTextureDesc &descriptor)
std::vector< HgiTextureHandle > HgiTextureHandleVector
Definition: texture.h:207
HgiFormat
Definition: types.h:45
HgiFormat format
Definition: texture.h:250
HgiBits HgiTextureUsage
Definition: enums.h:161
HgiComponentSwizzle
Definition: enums.h:567
HgiComponentMapping componentMapping
Definition: texture.h:129
HgiSampleCount sampleCount
Definition: texture.h:134
uint16_t mipLevels
Definition: texture.h:252
virtual HGI_API uint64_t GetRawResource() const =0
HGI_API HgiTextureDesc const & GetDescriptor() const
The descriptor describes the object.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
virtual HGI_API ~HgiTexture()
uint16_t sourceFirstMip
Definition: texture.h:255
bool operator!=(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Inequality operator, does exact floating point comparisons.
Definition: Mat3.h:570
uint16_t sourceFirstLayer
Definition: texture.h:254
Definition: vec3i.h:61
HGI_API void SetViewTexture(HgiTextureHandle const &handle)
Set the handle to the texture that aliases another texture.
HgiTextureType
Definition: enums.h:115
HgiFormat format
Definition: texture.h:128
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
#define HGI_API
Definition: api.h:40
std::vector< HgiTextureViewHandle > HgiTextureViewHandleVector
Definition: texture.h:313
GLsizeiptr const void GLenum usage
Definition: glcorearb.h:664
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
HgiComponentSwizzle r
Definition: texture.h:56
HgiTextureUsage usage
Definition: texture.h:127
GfVec3i dimensions
Definition: texture.h:131
HgiComponentSwizzle b
Definition: texture.h:58
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
uint16_t layerCount
Definition: texture.h:132
void const * initialData
Definition: texture.h:136
virtual HGI_API ~HgiTextureView()
HGI_API HgiTextureHandle const & GetViewTexture() const
Returns the handle to the texture that aliases another texture.
HgiSampleCount
Definition: enums.h:242
uint16_t mipLevels
Definition: texture.h:133
bool operator==(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Equality operator, does exact floating point comparisons.
Definition: Mat3.h:556
HgiComponentSwizzle g
Definition: texture.h:57
HgiTextureType type
Definition: texture.h:130