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 
40 /// \struct HgiTextureDesc
41 ///
42 /// Describes the properties needed to create a GPU texture.
43 ///
44 /// <ul>
45 /// <li>debugName:
46 /// This label can be applied as debug label for GPU debugging.</li>
47 /// <li>usage:
48 /// Describes how the texture is intended to be used.</li>
49 /// <li>format:
50 /// The format of the texture.
51 /// <li>dimensions:
52 /// The resolution of the texture (width, height, depth).</li>
53 /// <li>type:
54 /// Type of texture (2D, 3D).</li>
55 /// <li>layerCount:
56 /// The number of layers (texture-arrays).</li>
57 /// <li>mipLevels:
58 /// The number of mips in texture.</li>
59 /// <li>sampleCount:
60 /// samples per texel (multi-sampling).</li>
61 /// <li>pixelsByteSize:
62 /// Byte size (length) of pixel data (i.e., initialData).</li>
63 /// <li>initialData:
64 /// CPU pointer to initialization pixels of the texture.
65 /// The memory is consumed immediately during the creation of the HgiTexture.
66 /// The application may alter or free this memory as soon as the constructor
67 /// of the HgiTexture has returned.
68 /// Data may optionally include pixels for each mip-level.</li>
69 /// </ul>
70 ///
72 {
74  : usage(0)
77  , dimensions(0)
78  , layerCount(1)
79  , mipLevels(1)
81  , pixelsByteSize(0)
82  , initialData(nullptr)
83  {}
84 
90  uint16_t layerCount;
91  uint16_t mipLevels;
94  void const* initialData;
95 };
96 
97 HGI_API
98 bool operator==(
99  const HgiTextureDesc& lhs,
100  const HgiTextureDesc& rhs);
101 
102 HGI_API
103 bool operator!=(
104  const HgiTextureDesc& lhs,
105  const HgiTextureDesc& rhs);
106 
107 
108 ///
109 /// \class HgiTexture
110 ///
111 /// Represents a graphics platform independent GPU texture resource.
112 /// Textures should be created via Hgi::CreateTexture.
113 ///
114 /// Base class for Hgi textures.
115 /// To the client (HdSt) texture resources are referred to via
116 /// opaque, stateless handles (HgTextureHandle).
117 ///
119 {
120 public:
121  HGI_API
122  virtual ~HgiTexture();
123 
124  /// The descriptor describes the object.
125  HGI_API
126  HgiTextureDesc const& GetDescriptor() const;
127 
128  /// Returns the byte size of the GPU texture.
129  /// This can be helpful if the application wishes to tally up memory usage.
130  HGI_API
131  virtual size_t GetByteSizeOfResource() const = 0;
132 
133  /// This function returns the handle to the Hgi backend's gpu resource, cast
134  /// to a uint64_t. Clients should avoid using this function and instead
135  /// use Hgi base classes so that client code works with any Hgi platform.
136  /// For transitioning code to Hgi, it can however we useful to directly
137  /// access a platform's internal resource handles.
138  /// There is no safety provided in using this. If you by accident pass a
139  /// HgiMetal resource into an OpenGL call, bad things may happen.
140  /// In OpenGL this returns the GLuint resource name.
141  /// In Metal this returns the id<MTLTexture> as uint64_t.
142  /// In Vulkan this returns the VkImage as uint64_t.
143  /// In DX12 this returns the ID3D12Resource pointer as uint64_t.
144  HGI_API
145  virtual uint64_t GetRawResource() const = 0;
146 
147 protected:
148  HGI_API
149  HgiTexture(HgiTextureDesc const& desc);
150 
152 
153 private:
154  HgiTexture() = delete;
155  HgiTexture & operator=(const HgiTexture&) = delete;
156  HgiTexture(const HgiTexture&) = delete;
157 };
158 
159 
160 /// Explicitly instantiate and define texture handle
161 template class HgiHandle<class HgiTexture>;
163 using HgiTextureHandleVector = std::vector<HgiTextureHandle>;
164 
165 
167 
168 #endif
std::string debugName
Definition: texture.h:85
virtual HGI_API size_t GetByteSizeOfResource() const =0
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: glew.h:1254
HgiTextureDesc _descriptor
Definition: texture.h:151
size_t pixelsByteSize
Definition: texture.h:93
std::vector< HgiTextureHandle > HgiTextureHandleVector
Definition: texture.h:163
HgiBits HgiTextureUsage
Definition: enums.h:107
HgiSampleCount sampleCount
Definition: texture.h:92
virtual HGI_API uint64_t GetRawResource() const =0
GLsizeiptr const void GLenum usage
Definition: glew.h:1681
HGI_API HgiTextureDesc const & GetDescriptor() const
The descriptor describes the object.
virtual HGI_API ~HgiTexture()
bool operator!=(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Inequality operator, does exact floating point comparisons.
Definition: Mat3.h:563
Definition: vec3i.h:61
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
HgiTextureType
Definition: enums.h:65
HgiFormat format
Definition: texture.h:87
GLsizei const GLchar *const * string
Definition: glew.h:1844
#define HGI_API
Definition: api.h:40
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
HgiTextureDesc()
Definition: texture.h:73
HgiTextureUsage usage
Definition: texture.h:86
GfVec3i dimensions
Definition: texture.h:89
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
uint16_t layerCount
Definition: texture.h:90
HgiFormat
Definition: types.h:42
void const * initialData
Definition: texture.h:94
HgiSampleCount
Definition: enums.h:169
uint16_t mipLevels
Definition: texture.h:91
bool operator==(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Equality operator, does exact floating point comparisons.
Definition: Mat3.h:549
HgiTextureType type
Definition: texture.h:88