textureUtils.h
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_HD_ST_TEXTURE_UTILS_H
25 #define PXR_IMAGING_HD_ST_TEXTURE_UTILS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hdSt/api.h"
29 
30 #include "pxr/imaging/hio/image.h"
31 
32 #include "pxr/imaging/hgi/handle.h"
33 #include "pxr/imaging/hgi/types.h"
34 
35 #include "pxr/base/arch/align.h"
36 
37 #include <memory>
38 
39 PXR_NAMESPACE_OPEN_SCOPE
40 
41 class Hgi;
42 using HgiTextureHandle = HgiHandle<class HgiTexture>;
43 
49 {
50 public:
55  using ConversionFunction =
56  void(*)(const void * src,
57  size_t numTexels,
58  void * dst);
59 
64  HDST_API
65  static
66  HgiFormat GetHgiFormat(
67  HioFormat hioFormat,
68  bool premultiplyAlpha);
69 
74  HDST_API
75  static
77  HioFormat hioFormat,
78  bool premultiplyAlpha);
79 
81  HDST_API
82  static
83  std::vector<HioImageSharedPtr> GetAllMipImages(
84  const std::string &filePath,
85  HioImage::SourceColorSpace sourceColorSpace);
86 
87  // Compute dimensions so that all tiles fit into the given target memory.
88  // First by traversing the given images and then by computing a mip chain
89  // starting with the lowest resolution image.
90  // Optionally, can also give the index of the image in mips that was used
91  // to compute the dimensions.
92  HDST_API
93  static
94  GfVec3i
95  ComputeDimensionsFromTargetMemory(
96  const std::vector<HioImageSharedPtr> &mips,
97  HgiFormat targetFormat,
98  size_t tileCount,
99  size_t targetMemory,
100  size_t * mipIndex = nullptr);
101 
102  // Read given HioImage and convert it to corresponding Hgi format.
103  // Returns false if reading the HioImage failed.
104  //
105  // bufferStart is assumed to point at the beginning of a mip chain
106  // with mipInfo describing what mip level of the mip chain to be
107  // filled. layer gives the layer number if the mip chain is for an
108  // array texture.
109  HDST_API
110  static
111  bool
112  ReadAndConvertImage(
113  HioImageSharedPtr const &image,
114  bool flipped,
115  bool premultiplyAlpha,
116  const HgiMipInfo &mipInfo,
117  size_t layer,
118  void * bufferStart);
119 
120  // Because the underlying graphics API may have alignment
121  // restrictions we use this wrapper class to manage the
122  // allocation of the returned buffer data, and expose a
123  // restricted subset of underlyling pointer's access methods.
124  template <typename T>
125  class AlignedBuffer
126  {
127  public:
128  AlignedBuffer()
129  : AlignedBuffer(nullptr)
130  { }
131 
132  T *get() const {
133  return _alignedPtr.get();
134  }
135 
136  private:
137  friend class HdStTextureUtils;
138 
139  explicit AlignedBuffer(T * alignedPtr)
140  : _alignedPtr(alignedPtr, ArchAlignedFree)
141  { }
142 
143  T *release() {
144  return _alignedPtr.release();
145  }
146 
147  std::unique_ptr<T[], decltype(ArchAlignedFree)*> _alignedPtr;
148  };
149 
151  HDST_API
152  static
153  AlignedBuffer<uint8_t>
154  HgiTextureReadback(Hgi * const hgi,
155  HgiTextureHandle const & texture,
156  size_t * bufferSize);
157 
159  template <typename T>
160  static
161  AlignedBuffer<T>
162  HgiTextureReadback(Hgi * const hgi,
163  HgiTextureHandle const & texture,
164  size_t * bufferSize);
165 };
166 
167 template <typename T>
168 HdStTextureUtils::AlignedBuffer<T>
170  HgiTextureHandle const & texture,
171  size_t * bufferSize)
172 {
173  HdStTextureUtils::AlignedBuffer<uint8_t> buffer =
174  HdStTextureUtils::HgiTextureReadback(hgi, texture, bufferSize);
175 
176  T * typedData = reinterpret_cast<T *>(buffer.release());
177  return HdStTextureUtils::AlignedBuffer<T>(typedData);
178 }
179 
180 PXR_NAMESPACE_CLOSE_SCOPE
181 
182 #endif
static HDST_API AlignedBuffer< uint8_t > HgiTextureReadback(Hgi *const hgi, HgiTextureHandle const &texture, size_t *bufferSize)
Returns an unsigned byte buffer with data read back from texture.
Provide architecture-specific memory-alignment information.
static HDST_API HgiFormat GetHgiFormat(HioFormat hioFormat, bool premultiplyAlpha)
Get the Hgi format suitable for a given Hio format.
ARCH_API void ArchAlignedFree(void *ptr)
Free memory allocated by ArchAlignedAlloc.
SourceColorSpace
Specifies the source color space in which the texture is encoded, with "Auto" indicating the texture ...
Definition: image.h:68
Helpers for loading textures.
Definition: textureUtils.h:48
static HDST_API ConversionFunction GetHioToHgiConversion(HioFormat hioFormat, bool premultiplyAlpha)
Returns the conversion function to return a HioFormat to the corresponding HgiFormat given by GetHgiF...
HgiMipInfo describes size and other info for a mip level.
Definition: types.h:136
Basic type for a vector of 3 int components.
Definition: vec3i.h:61
Hydra Graphics Interface.
Definition: hgi.h:108
void(*)(const void *src, size_t numTexels, void *dst) ConversionFunction
Converts given number of texels.
Definition: textureUtils.h:58
static HDST_API std::vector< HioImageSharedPtr > GetAllMipImages(const std::string &filePath, HioImage::SourceColorSpace sourceColorSpace)
Get all mip levels from a file.