HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
buffer.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_BUFFER_H
25 #define PXR_IMAGING_HGI_BUFFER_H
26 
27 #include <string>
28 #include <vector>
29 
30 #include "pxr/pxr.h"
31 #include "pxr/base/gf/vec3i.h"
32 #include "pxr/imaging/hgi/api.h"
33 #include "pxr/imaging/hgi/enums.h"
34 #include "pxr/imaging/hgi/handle.h"
35 #include "pxr/imaging/hgi/types.h"
36 
37 
39 
40 
41 /// \struct HgiBufferDesc
42 ///
43 /// Describes the properties needed to create a GPU buffer.
44 ///
45 /// <ul>
46 /// <li>debugName:
47 /// This label can be applied as debug label for gpu debugging.</li>
48 /// <li>usage:
49 /// Bits describing the intended usage and properties of the buffer.</li>
50 /// <li>byteSize:
51 /// Length of buffer in bytes</li>
52 /// <Li>vertexStride:
53 /// The size of a vertex in a vertex buffer.
54 /// This property is only required for vertex buffers.</li>
55 /// <li>initialData:
56 /// CPU pointer to initialization data of buffer.
57 /// The memory is consumed immediately during the creation of the HgiBuffer.
58 /// The application may alter or free this memory as soon as the constructor
59 /// of the HgiBuffer has returned.</li>
60 /// </ul>
61 ///
63 {
64  HGI_API
67  , byteSize(0)
68  , vertexStride(0)
69  , initialData(nullptr)
70  {}
71 
74  size_t byteSize;
75  uint32_t vertexStride;
76  void const* initialData;
77 };
78 
79 HGI_API
80 bool operator==(
81  const HgiBufferDesc& lhs,
82  const HgiBufferDesc& rhs);
83 
84 HGI_API
85 inline bool operator!=(
86  const HgiBufferDesc& lhs,
87  const HgiBufferDesc& rhs);
88 
89 
90 ///
91 /// \class HgiBuffer
92 ///
93 /// Represents a graphics platform independent GPU buffer resource (base class).
94 /// Buffers should be created via Hgi::CreateBuffer.
95 /// The fill the buffer with data you supply `initialData` in the descriptor.
96 /// To update the data inside the buffer later on, use blitCmds.
97 ///
98 class HgiBuffer
99 {
100 public:
101  HGI_API
102  virtual ~HgiBuffer();
103 
104  /// The descriptor describes the object.
105  HGI_API
106  HgiBufferDesc const& GetDescriptor() const;
107 
108  /// Returns the byte size of the GPU buffer.
109  /// This can be helpful if the application wishes to tally up memory usage.
110  HGI_API
111  virtual size_t GetByteSizeOfResource() const = 0;
112 
113  /// This function returns the handle to the Hgi backend's gpu resource, cast
114  /// to a uint64_t. Clients should avoid using this function and instead
115  /// use Hgi base classes so that client code works with any Hgi platform.
116  /// For transitioning code to Hgi, it can however we useful to directly
117  /// access a platform's internal resource handles.
118  /// There is no safety provided in using this. If you by accident pass a
119  /// HgiMetal resource into an OpenGL call, bad things may happen.
120  /// In OpenGL this returns the GLuint resource name.
121  /// In Metal this returns the id<MTLBuffer> as uint64_t.
122  /// In Vulkan this returns the VkBuffer as uint64_t.
123  /// In DX12 this returns the ID3D12Resource pointer as uint64_t.
124  HGI_API
125  virtual uint64_t GetRawResource() const = 0;
126 
127  /// Returns the 'staging area' in which new buffer data is copied before
128  /// it is flushed to GPU.
129  /// Some implementations (e.g. Metal) may have build in support for
130  /// queueing up CPU->GPU copies. Those implementations can return the
131  /// CPU pointer to the buffer's content directly.
132  /// The caller should not assume that the data from the CPU staging area
133  /// is automatically flushed to the GPU. Instead, after copying is finished,
134  /// the caller should use BlitCmds CopyBufferCpuToGpu to ensure the transfer
135  /// from the staging area to the GPU is scheduled.
136  HGI_API
137  virtual void* GetCPUStagingAddress() = 0;
138 
139 protected:
140  HGI_API
141  HgiBuffer(HgiBufferDesc const& desc);
142 
144 
145 private:
146  HgiBuffer() = delete;
147  HgiBuffer & operator=(const HgiBuffer&) = delete;
148  HgiBuffer(const HgiBuffer&) = delete;
149 };
150 
152 using HgiBufferHandleVector = std::vector<HgiBufferHandle>;
153 
154 
156 
157 #endif
HgiBufferDesc _descriptor
Definition: buffer.h:143
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
virtual HGI_API void * GetCPUStagingAddress()=0
HGI_API HgiBufferDesc const & GetDescriptor() const
The descriptor describes the object.
std::string debugName
Definition: buffer.h:72
virtual HGI_API size_t GetByteSizeOfResource() const =0
HgiBufferUsage usage
Definition: buffer.h:73
uint32_t vertexStride
Definition: buffer.h:75
virtual HGI_API ~HgiBuffer()
std::vector< HgiBufferHandle > HgiBufferHandleVector
Definition: buffer.h:152
bool operator!=(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Inequality operator, does exact floating point comparisons.
Definition: Mat3.h:556
virtual HGI_API uint64_t GetRawResource() const =0
size_t byteSize
Definition: buffer.h:74
#define HGI_API
Definition: api.h:40
GLsizeiptr const void GLenum usage
Definition: glcorearb.h:664
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
HgiBits HgiBufferUsage
Definition: enums.h:329
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HGI_API HgiBufferDesc()
Definition: buffer.h:65
void const * initialData
Definition: buffer.h:76
bool operator==(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Equality operator, does exact floating point comparisons.
Definition: Mat3.h:542