 |
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
|
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
\inmodule QtGui More...
#include <qrhi.h>
Inheritance diagram for QRhiBuffer: Collaboration diagram for QRhiBuffer:Classes | |
| class | NativeBuffer |
| \inmodule QtGui More... | |
Public Types | |
| enum | Type { Immutable , Static , Dynamic } |
| Specifies storage type of buffer resource. More... | |
| enum | UsageFlag { VertexBuffer = 1 << 0 , IndexBuffer = 1 << 1 , UniformBuffer = 1 << 2 , StorageBuffer = 1 << 3 } |
| Flag values to specify how the buffer is going to be used. More... | |
| Public Types inherited from QRhiResource | |
| enum | Type { Buffer , Texture , Sampler , RenderBuffer , RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings , GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer } |
| Specifies type of the resource. More... | |
Public Member Functions | |
| QRhiResource::Type | resourceType () const override |
| Type | type () const |
| void | setType (Type t) |
| Sets the buffer's type to t. | |
| UsageFlags | usage () const |
| void | setUsage (UsageFlags u) |
| Sets the buffer's usage flags to u. | |
| quint32 | size () const |
| void | setSize (quint32 sz) |
| Sets the size of the buffer in bytes. | |
| virtual bool | create ()=0 |
| Creates the corresponding native graphics resources. | |
| virtual NativeBuffer | nativeBuffer () |
| virtual char * | beginFullDynamicBufferUpdateForCurrentFrame () |
| virtual void | endFullDynamicBufferUpdateForCurrentFrame () |
| To be called when the entire contents of the buffer data has been updated in the memory block returned from beginFullDynamicBufferUpdateForCurrentFrame(). | |
| Public Member Functions inherited from QRhiResource | |
| virtual | ~QRhiResource () |
| Destructor. | |
| virtual void | destroy ()=0 |
| Releases (or requests deferred releasing of) the underlying native graphics resources. | |
| void | deleteLater () |
| When called without a frame being recorded, this function is equivalent to deleting the object. | |
| QByteArray | name () const |
| void | setName (const QByteArray &name) |
| Sets a name for the object. | |
| quint64 | globalResourceId () const |
| QRhi * | rhi () const |
Protected Member Functions | |
| QRhiBuffer (QRhiImplementation *rhi, Type type_, UsageFlags usage_, quint32 size_) | |
| \variable QRhiBuffer::NativeBuffer::objects | |
| Protected Member Functions inherited from QRhiResource | |
| QRhiResource (QRhiImplementation *rhi) | |
Protected Attributes | |
| Type | m_type |
| UsageFlags | m_usage |
| quint32 | m_size |
| Protected Attributes inherited from QRhiResource | |
| QRhiImplementation * | m_rhi = nullptr |
| quint64 | m_id |
| QByteArray | m_objectName |
\inmodule QtGui
Vertex, index, or uniform (constant) buffer resource.
A QRhiBuffer encapsulates zero, one, or more native buffer objects (such as a VkBuffer or MTLBuffer). With some graphics APIs and backends certain types of buffers may not use a native buffer object at all (e.g. OpenGL if uniform buffer objects are not used), but this is transparent to the user of the QRhiBuffer API. Similarly, the fact that some types of buffers may use two or three native buffers underneath, in order to allow efficient per-frame content update without stalling the GPU pipeline, is mostly invisible to the applications and libraries.
A QRhiBuffer instance is always created by calling \l{QRhi::newBuffer()}{the QRhi's newBuffer() function}. This creates no native graphics resources. To do that, call create() after setting the appropriate options, such as the type, usage flags, size, although in most cases these are already set based on the arguments passed to \l{QRhi::newBuffer()}{newBuffer()}.
| enum QRhiBuffer::Type |
Specifies storage type of buffer resource.
\value Immutable Indicates that the data is not expected to change ever after the initial upload. Under the hood such buffer resources are typically placed in device local (GPU) memory (on systems where applicable). Uploading new data is possible, but may be expensive. The upload typically happens by copying to a separate, host visible staging buffer from which a GPU buffer-to-buffer copy is issued into the actual GPU-only buffer.
\value Static Indicates that the data is expected to change only infrequently. Typically placed in device local (GPU) memory, where applicable. On backends where host visible staging buffers are used for uploading, the staging buffers are kept around for this type, unlike with Immutable, so subsequent uploads do not suffer in performance. Frequent updates, especially updates in consecutive frames, should be avoided.
\value Dynamic Indicates that the data is expected to change frequently. Not recommended for large buffers. Typically backed by host visible memory in 2 copies in order to allow for changing without stalling the graphics pipeline. The double buffering is managed transparently to the applications and is not exposed in the API here in any form. This is the recommended, and, with some backends, the only possible, type for buffers with UniformBuffer usage.
| Enumerator | |
|---|---|
| Immutable | |
| Static | |
| Dynamic | |
Flag values to specify how the buffer is going to be used.
\value VertexBuffer Vertex buffer. This allows the QRhiBuffer to be used in \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()}.
\value IndexBuffer Index buffer. This allows the QRhiBuffer to be used in \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()}.
\value UniformBuffer Uniform buffer (also called constant buffer). This allows the QRhiBuffer to be used in combination with \l{QRhiShaderResourceBinding::UniformBuffer}{UniformBuffer}. When \l{QRhi::NonDynamicUniformBuffers}{NonDynamicUniformBuffers} is reported as not supported, this usage can only be combined with the type Dynamic.
\value StorageBuffer Storage buffer. This allows the QRhiBuffer to be used in combination with \l{QRhiShaderResourceBinding::BufferLoad}{BufferLoad}, \l{QRhiShaderResourceBinding::BufferStore}{BufferStore}, or \l{QRhiShaderResourceBinding::BufferLoadStore}{BufferLoadStore}. This usage can only be combined with the types Immutable or Static, and is only available when the \l{QRhi::Compute}{Compute feature} is reported as supported.
| Enumerator | |
|---|---|
| VertexBuffer | |
| IndexBuffer | |
| UniformBuffer | |
| StorageBuffer | |
|
protected |
\variable QRhiBuffer::NativeBuffer::objects
an array with pointers to the native object handles.
With OpenGL, the native handle is a GLuint value, so the elements in the objects array are pointers to a GLuint. With Vulkan, the native handle is a VkBuffer, so the elements of the array are pointers to a VkBuffer. With Direct3D 11 and Metal the elements are pointers to a ID3D11Buffer or MTLBuffer pointer, respectively. With Direct3D 12, the elements are pointers to a ID3D12Resource.
\variable QRhiBuffer::NativeBuffer::slotCount
Specifies the number of valid elements in the objects array.
The value can be 0, 1, 2, or 3 in practice. 0 indicates that the QRhiBuffer is not backed by any native buffer objects. This can happen with QRhiBuffers with the usage UniformBuffer when the underlying API does not support (or the backend chooses not to use) native uniform buffers. 1 is commonly used for Immutable and Static types (but some backends may differ). 2 or 3 is typical when the type is Dynamic (but some backends may differ).
|
virtual |
This is a shortcut for medium-to-large dynamic uniform buffers that have their entire contents (or at least all regions that are read by the shaders in the current frame) changed {in every frame} and the QRhiResourceUpdateBatch-based update mechanism is seen too heavy due to the amount of data copying involved.
The call to this function must be eventually followed by a call to endFullDynamicUniformBufferUpdateForCurrentFrame(), before recording any render or compute pass that relies on this buffer.
Reimplemented in QD3D11Buffer, QGles2Buffer, QMetalBuffer, QNullBuffer, and QVkBuffer.
Definition at line 3970 of file qrhi.cpp.
Referenced by RenderHelpers::rhiPrepareRenderable().
Here is the caller graph for this function:
|
pure virtual |
Creates the corresponding native graphics resources.
If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.
true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe. Implemented in QD3D11Buffer, QGles2Buffer, QMetalBuffer, QNullBuffer, and QVkBuffer.
Referenced by QSSGRhiBuffer::QSSGRhiBuffer(), QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRhiShaderPipeline::ensureCombinedMainLightsUniformBuffer(), QSSGRhiShaderPipeline::ensureUniformBuffer(), QSSGLayerRenderData::prepareInstancing(), QSSGReflectionMapEntry::renderMips(), DebugDrawPass::renderPrep(), renderToKTXFileInternal(), QQuick3DSceneRenderer::renderToRhiTexture(), RenderHelpers::rhiPrepareGrid(), rhiPrepareSkyBox_helper(), RenderHelpers::rhiRenderAoTexture(), and RenderHelpers::rhiRenderShadowMap().
Here is the caller graph for this function:
|
virtual |
To be called when the entire contents of the buffer data has been updated in the memory block returned from beginFullDynamicBufferUpdateForCurrentFrame().
Reimplemented in QD3D11Buffer, QGles2Buffer, QMetalBuffer, and QVkBuffer.
|
virtual |
A QRhiBuffer may be backed by multiple native buffer objects, depending on the type() and the QRhi backend in use. When this is the case, all of them are returned in the objects array in the returned struct, with slotCount specifying the number of native buffer objects. While \l{QRhi::beginFrame()}{recording a frame}, QRhi::currentFrameSlot() can be used to determine which of the native buffers QRhi is using for operations that read or write from this QRhiBuffer within the frame being recorded.
In some cases a QRhiBuffer will not be backed by a native buffer object at all. In this case slotCount will be set to 0 and no valid native objects are returned. This is not an error, and is perfectly valid when a given backend does not use native buffers for QRhiBuffers with certain types or usages.
Reimplemented in QD3D11Buffer, QGles2Buffer, QMetalBuffer, and QVkBuffer.
|
overridevirtual |
Implements QRhiResource.
Definition at line 3838 of file qrhi.cpp.
References QRhiResource::Buffer.
Sets the size of the buffer in bytes.
The size is normally specified in QRhi::newBuffer() so this function is only used when the size has to be changed. As with other setters, the size only takes effect when calling create(), and for already created buffers this involves releasing the previous native resource and creating new ones under the hood.
Backends may choose to allocate buffers bigger than sz in order to fulfill alignment requirements. This is hidden from the applications and size() will always report the size requested in sz.
Definition at line 876 of file qrhi.h.
Referenced by QMetalComputePipeline::create(), and QSGBatchRenderer::ensureBuffer().
Here is the caller graph for this function:
|
inline |
|
inline |
This is always the value that was passed to setSize() or QRhi::newBuffer(). Internally, the native buffers may be bigger if that is required by the underlying graphics API.
Definition at line 875 of file qrhi.h.
Referenced by QSSGRhiBuffer::QSSGRhiBuffer().
Here is the caller graph for this function:
|
inline |
|
inline |
|
protected |
Definition at line 889 of file qrhi.h.
Referenced by QD3D11Buffer::create(), QGles2Buffer::create(), QMetalBuffer::create(), QNullBuffer::create(), QVkBuffer::create(), QMetalBuffer::endFullDynamicBufferUpdateForCurrentFrame(), QVkBuffer::endFullDynamicBufferUpdateForCurrentFrame(), and QD3D11Buffer::unorderedAccessView().
|
protected |
Definition at line 887 of file qrhi.h.
Referenced by QD3D11Buffer::beginFullDynamicBufferUpdateForCurrentFrame(), QGles2Buffer::beginFullDynamicBufferUpdateForCurrentFrame(), QMetalBuffer::beginFullDynamicBufferUpdateForCurrentFrame(), QNullBuffer::beginFullDynamicBufferUpdateForCurrentFrame(), QVkBuffer::beginFullDynamicBufferUpdateForCurrentFrame(), QD3D11Buffer::create(), QGles2Buffer::create(), QMetalBuffer::create(), QVkBuffer::create(), QD3D11Buffer::nativeBuffer(), and QVkBuffer::nativeBuffer().
|
protected |
Definition at line 888 of file qrhi.h.
Referenced by QGles2Buffer::beginFullDynamicBufferUpdateForCurrentFrame(), QD3D11Buffer::create(), QGles2Buffer::create(), QMetalBuffer::create(), QVkBuffer::create(), QGles2Buffer::endFullDynamicBufferUpdateForCurrentFrame(), and QGles2Buffer::nativeBuffer().
1.10.0