Commit b0c4ce00 authored by Laszlo Agocs's avatar Laszlo Agocs

A whole lot of more rhi docs

parent e0d99517
......@@ -4,7 +4,7 @@
"Name": "Dear ImGui",
"QDocModule": "qtrhi",
"Description": "Dear ImGui",
"QtUsage": "Bloat-free GUI library for in-scene visualization of profiling and debugging data",
"QtUsage": "Used in examples to demo integration of an external GUI library.",
"Homepage": "",
"Version": "v1.66b",
......@@ -3,8 +3,8 @@
"Id": "SpirvCross",
"Name": "SPIRV-Cross",
"QDocModule": "qtshadertools",
"Description": "A practical tool and library for performing reflection on SPIR-V and disassembling SPIR-V back to high level languages",
"QtUsage": "Shader code generation",
"Description": "A practical tool and library for performing reflection on SPIR-V and disassembling SPIR-V back to high level languages.",
"QtUsage": "Shader code generation.",
"Homepage": "",
"Version": "bfeb388edfb63c9a927e517b634abaaa5bfb1caf",
......@@ -4,7 +4,7 @@
"Name": "Vulkan Memory Allocator",
"QDocModule": "qtrhi",
"Description": "Vulkan Memory Allocator",
"QtUsage": "Memory management for the Vulkan backend",
"QtUsage": "Memory management for the Vulkan backend of QRhi.",
"Homepage": "",
"Version": "2.1.0",
......@@ -4,7 +4,7 @@
"Name": "glslang",
"QDocModule": "qtshadertools",
"Description": "An OpenGL and OpenGL ES shader front end and validator.",
"QtUsage": "Compile Vulkan-flavor GLSL to SPIR-V",
"QtUsage": "Compile GLSL to SPIR-V.",
"Homepage": "",
"Version": "816bc4447ce58c048a40e3f2a3a46b4d1019083b",
......@@ -58,6 +58,172 @@ QT_BEGIN_NAMESPACE
\inmodule QtRhi
\brief Accelerated 2D/3D graphics API abstraction.
QRhi is an abstraction for hardware accelerated graphics APIs, such as,
\l{}{OpenGL ES},
\l{}{Metal}, and
Each QRhi instance is backed by a backend for a specific graphics API. The
selection of the backend is a run time choice and is up to the application
or library that creates the QRhi instance. Some backends are available on
multiple platforms (OpenGL, Vulkan, Null), while APIs specific to a given
platform are only available when running on the platform in question (Metal
on macOS/iOS/tvOS, Direct3D on Windows).
\section2 Design Fundamentals
A QRhi cannot be instantiated directly. Instead, use the create()
function. Delete the QRhi instance normally to release the graphics device.
\section3 Resources
Instances of classes deriving from QRhiResource, such as, QRhiBuffer,
QRhiTexture, etc., encapsulate zero, one, or more native graphics
resources. Instances of such classes are always created via the \c new
functions of the QRhi, such as, newBuffer(), newTexture(),
newTextureRenderTarget(), newSwapChain().
\li The returned value from both create() and functions like newBuffer() is
owned by the caller.
\li Unlike QRhi, subclasses of QRhiResource should not be destroyed
directly via delete without calling QRhiResource::release(). The typical
approach is to call QRhiResource::releaseAndDestroy(). This is equivalent
to QRhiResource::release() followed by \c delete.
\li Just creating a QRhiResource subclass never allocates or initalizes any
native resources. That is only done when calling the \c build function of a
subclass, for example, QRhiBuffer::build() or QRhiTexture::build().
\li The exception is
QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor() and
QRhiSwapChain::newCompatibleRenderPassDescriptor(). There is no \c build
operation for these and the returned object is immediately active.
\li The resource objects themselves are treated as immutable: once a
resource is built, changing any parameters via the setters, such as,
QRhiTexture::setPixelSize(), has no effect, unless the underlying native
resource is released and \c build is called again. See more about resource
reuse in the sections below.
\li The underlying native resources are scheduled for releasing by calling
QRhiResource::release(). Backends often queue release requests and defer
executing them to an unspecified time, this is hidden from the
applications. This way applications do not have to worry about releasing a
native resource that may still be in use by an in flight frame.
vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));
if (!vbuf->build()) { error }
\section3 Resource reuse
From the user's point of view the QRhiResource is reusable immediately
after calling QRhiResource::release(). With the exception of swapchains,
calling \c build on an already built object does an implicit release. This
provides a handy shortcut to reuse a QRhiResource instance with different
parameters, with a new native graphics resource underneath.
The importance of reusing the same object lies in the fact that some
objects reference other objects: for example, a QRhiShaderResourceBindings
can reference QRhiBuffer, QRhiTexture, and QRhiSampler instances. If now
one of these buffers need to be resized or a sampler parameter needs
changing, destroying and creating a whole new QRhiBuffer or QRhiSampler
would invalidate all references to the old instance. By just changing the
appropriate parameters via QRhiBuffer::setSize() or similar and then
calling QRhiBuffer::build(), everything works as expected and there is no
need to touch the QRhiShaderResourceBindings at all, even though there is a
good chance that under the hood the QRhiBuffer is now backed by a whole new
native buffer.
ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);
srb = m_r->newShaderResourceBindings()
QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf)
// now suddenly we need buffer with a different size
ubuf->build(); // same as ubuf->release(); ubuf->build();
// that's it, srb needs no changes whatsoever
\section3 Pooled objects
There are pooled objects too, like QRhiResourceUpdateBatch. An instance is
retrieved via a \c next function, such as, nextResourceUpdateBatch(). The
caller does not own the returned instance in this case. The only valid way
of operating here is calling functions on the QRhiResourceUpdateBatch and
then passing it to QRhiCommandBuffer::beginPass() or
QRhiCommandBuffer::endPass(). These functions take care of returning the
batch to the pool. Alternatively, a batch can be "canceled" and returned to
the pool without processing by calling QRhiResourceUpdateBatch::release().
A typical pattern is thus:
QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
resUpdates->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());
if (!image.isNull()) {
resUpdates->uploadTexture(texture, image);
image = QImage();
QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();
cb->beginPass(swapchain->currentFrameRenderTarget(), clearCol, clearDs, resUpdates);
\section3 Swapchain specifics
QRhiSwapChain features some special semantics due to the peculiar nature of
\li It has no \c build but rather a QRhiSwapChain::buildOrResize().
Repeatedly calling this function is \b not the same as calling
QRhiSwapChain::release() followed by QRhiSwapChain::buildOrResize(). This
is because swapchains often have ways to handle the case where buffers need
to be resized in a manner that is more efficient than a brute force
destroying and recreating from scratch.
\li An active QRhiSwapChain must be released by calling
QRhiSwapChain::release() whenever the targeted QWindow sends the
QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed event. It should not be
postponed since releasing the swapchain may become problematic when the
native window is not around anymore (e.g. because the QPlatformWindow got
destroyed already when getting a QWindow::close())
\section3 Ownership
The general rule is no ownership transfer. Creating a QRhi with an already
existing graphics device does not mean the QRhi takes ownership of the
device object. Similarly, ownership is not given away when a device or
texture object is "exported" via QRhi::nativeHandles() or
QRhiTexture::nativeHandles(). Most importantly, passing pointers in structs
and via setters does not transfer ownership.
\sa {Qt Shader Tools}
......@@ -174,24 +340,73 @@ QT_BEGIN_NAMESPACE
\brief Describes a vertex input binding.
\enum QRhiVertexInputLayout::Binding::Classification
Describes the input data classification.
\value PerVertex Data is per-vertex
\value PerInstance Data is per-instance
\class QRhiVertexInputLayout::Attribute
\inmodule QtRhi
\brief Describes a single vertex input element.
\enum QRhiVertexInputLayout::Attribute::Format
Specifies the type of the element data.
\value Float4 Four component float vector
\value Float3 Three component float vector
\value Float2 Two component float vector
\value Float Float
\value UNormByte4 Four component normalized unsigned byte vector
\value UNormByte2 Two component normalized unsigned byte vector
\value UNormByte Normalized unsigned byte
\class QRhiGraphicsShaderStage
\inmodule QtRhi
\brief Specifies the type and the shader code for a shader stage in the graphics pipeline.
\enum QRhiGraphicsShaderStage::Type
Specifies the type of the shader stage.
\value Vertex Vertex stage
\value Fragment Fragment (pixel) stage
\value TessellationControl Tessellation control (hull) stage
\value TessellationEvaluation Tessellation evaluation (domain) stage
\class QRhiShaderResourceBinding
\inmodule QtRhi
\brief Specifies the shader resources that are made visible to one or more shader stages.
\enum QRhiShaderResourceBinding::Type
Specifies type of the shader resource bound to a binding point
\value UniformBuffer Uniform buffer
\value SampledTexture Combined image sampler
\enum QRhiShaderResourceBinding::StageFlag
Flag values to indicate which stages the shader resource is visible in
\value VertexStage Vertex stage
\value FragmentStage Fragment (pixel) stage
\value TessellationControlStage Tessellation control (hull) stage
\value TessellationEvaluationStage Tessellation evaluation (domain) stage
\class QRhiTextureRenderTargetDescription
\inmodule QtRhi
......@@ -258,24 +473,176 @@ QT_BEGIN_NAMESPACE
\brief Vertex, index, or uniform (constant) buffer resource.
\enum QRhiBuffer::Type
Specifies 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 frequent changes can be
expensive. 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 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.
\enum QRhiBuffer::UsageFlag
Flag values to specify how the buffer is going to be used.
\value VertexBuffer Vertex buffer
\value IndexBuffer Index buffer
\value UniformBuffer Uniform (constant) buffer
\class QRhiTexture
\inmodule QtRhi
\brief Texture resource.
\enum QRhiTexture::Flag
Flag values to specify how the texture is going to be used. Not honoring
the flags set before build() and attempting to use the texture in ways that
was not declared upfront can lead to unspecified behavior or decreased
performance depending on the backend and the underlying graphics API.
\value RenderTarget The texture going to be used in combination with
\value ChangesFrequently Performance hint to indicate that the texture
contents will change frequently and so staging buffers, if any, are to be
kept alive to avoid performance hits
\value CubeMap The texture is a cubemap. Such textures have 6 layers, one
for each face in the order of +X, -X, +Y, -Y, +Z, -Z. Cubemap textures
cannot be multisample.
\value MipMapped The texture has mipmaps. The appropriate mip count is
calculated automatically and can also be retrieved via
QRhi::mipLevelsForSize(). The images for the mip levels have to be
provided in the texture uploaded or generated via
QRhiResourceUpdateBatch::generateMips(). Multisample textures cannot have
\value sRGB Use an sRGB format
\value UsedAsTransferSource The texture is used as the source of a texture
copy or readback, meaning the texture is given as the source in
QRhiResourceUpdateBatch::copyTexture() or
\value UsedWithGenerateMips The texture is going to be used with
\enum QRhiTexture::Format
Specifies the texture format. See also QRhi::isTextureFormatSupported() and
note that flags() can modify the format when QRhiTexture::sRGB is set.
\value UnknownFormat Not a valid format. This cannot be passed to setFormat().
\value RGBA8
\value BGRA8
\value R8
\value R16
\value D16
\value D32
\value BC1
\value BC2
\value BC3
\value BC4
\value BC5
\value BC6H
\value BC7
\value ETC2_RGB8
\value ETC2_RGB8A1
\value ETC2_RGBA8
\value ASTC_4x4
\value ASTC_5x4
\value ASTC_5x5
\value ASTC_6x5
\value ASTC_6x6
\value ASTC_8x5
\value ASTC_8x6
\value ASTC_8x8
\value ASTC_10x5
\value ASTC_10x6
\value ASTC_10x8
\value ASTC_10x10
\value ASTC_12x10
\value ASTC_12x12
\class QRhiSampler
\inmodule QtRhi
\brief Sampler resource.
\enum QRhiSampler::Filter
Specifies the minification, magnification, or mipmap filtering
\value None Applicable only for mipmapMode(), indicates no mipmaps to be used
\value Nearest
\value Linear
\enum QRhiSampler::AddressMode
Specifies the addressing mode
\value Repeat
\value ClampToEdge
\value Border
\value Mirror
\value MirrorOnce
\class QRhiRenderBuffer
\inmodule QtRhi
\brief Renderbuffer resource.
\enum QRhiRenderBuffer::Type
Specifies the type of the renderbuffer
\value DepthStencil Combined depth/stencil
\value Color Color
\enum QRhiRenderBuffer::Flag
Flag values for flags() and setFlags()
\value UsedWithSwapChainOnly For DepthStencil renderbuffers this indicates
that the renderbuffer is only used in combination with a QRhiSwapChain and
never in other ways. Relevant with some backends, while others ignore it.
With OpenGL where a separate windowing system interface API is in use (EGL,
GLX, etc.), the flag is important since it avoids creating any actual
resource as there is already a windowing system provided depth/stencil
buffer as requested by QSurfaceFormat.
\class QRhiRenderPassDescriptor
\inmodule QtRhi
......@@ -288,12 +655,39 @@ QT_BEGIN_NAMESPACE
\brief Represents an onscreen (swapchain) or offscreen (texture) render target.
\enum QRhiRenderTarget::Type
Specifies the type of the render target
\value RtRef This is a reference to another resource's buffer(s). Used by
targets returned from QRhiSwapChain::currentFrameRenderTarget().
\value RtTexture This is a QRhiTextureRenderTarget.
\class QRhiTextureRenderTarget
\inmodule QtRhi
\brief Texture render target resource.
\enum QRhiTextureRenderTarget::Flag
Flag values describing the load/store behavior for the render target
\value PreserveColorContents Indicates that the contents of the color
attachments is to be loaded when starting a render pass, instead of
clearing. This is potentially more expensive, especially on mobile (tiled)
GPUs, but allows preserving the existing contents between passes.
\value PreserveDepthStencilContents Indicates that the contents of the
depth texture is to be loaded when starting a render pass, instead
clearing. Only applicable when a texture is used as the depth buffer
(QRhiTextureRenderTargetDescription::depthTexture is set) because
depth/stencil renderbuffers may not have any physical backing and data may
not be written out in the first place.
\class QRhiShaderResourceBindings
\inmodule QtRhi
......@@ -306,10 +700,136 @@ QT_BEGIN_NAMESPACE
\brief Graphics pipeline state resource.
\enum QRhiGraphicsPipeline::Flag
Flag values for describing the dynamic state of the pipeline. The viewport is always dynamic.
\value UsesBlendConstants Indicates that a blend color constant will be set
via QRhiCommandBuffer::setBlendConstants()
\value UsesStencilRef Indicates that a stencil reference value will be set
via QRhiCommandBuffer::setStencilRef()
\value UsesScissor Indicates that a scissor rectangle will be set via
\enum QRhiGraphicsPipeline::Topology
Specifies the primitive topology
\value Triangles (default)
\value TriangleStrip
\value Lines
\value LineStrip
\value Points
\enum QRhiGraphicsPipeline::CullMode
Specifies the culling mode
\value None No culling (default)
\value Front Cull front faces
\value Back Cull back faces
\enum QRhiGraphicsPipeline::FrontFace
Specifies the front face winding order
\value CCW Counter clockwise (default)
\value CW Clockwise
\enum QRhiGraphicsPipeline::ColorMaskComponent
Flag values for specifying the color write mask
\value R
\value G
\value B
\value A
\enum QRhiGraphicsPipeline::BlendFactor
Specifies the blend factor
\value Zero
\value One
\value SrcColor
\value OneMinusSrcColor
\value DstColor
\value OneMinusDstColor
\value SrcAlpha
\value OneMinusSrcAlpha
\value DstAlpha
\value OneMinusDstAlpha
\value ConstantColor
\value OneMinusConstantColor
\value ConstantAlpha
\value OneMinusConstantAlpha
\value SrcAlphaSaturate
\value Src1Color
\value OneMinusSrc1Color
\value Src1Alpha
\value OneMinusSrc1Alpha
\enum QRhiGraphicsPipeline::BlendOp
Specifies the blend operation
\value Add
\value Subtract
\value ReverseSubtract
\value Min
\value Max
\enum QRhiGraphicsPipeline::CompareOp
Specifies the depth or stencil comparison function
\value Never
\value Less (default for depth)
\value Equal
\value LessOrEqual
\value Greater
\value NotEqual
\value GreaterOrEqual
\value Always (default for stencil)
\enum QRhiGraphicsPipeline::StencilOp
Specifies the stencil operation
\value StencilZero
\value Keep (default)
\value Replace
\value IncrementAndClamp
\value DecrementAndClamp
\value Invert
\value IncrementAndWrap
\value DecrementAndWrap
\class QRhiGraphicsPipeline::TargetBlend
\inmodule QtRhi
\brief Describes the blend state for one color attachment.
Defaults to color write enabled, blending disabled. The blend values are
set up for pre-multiplied alpha (One, OneMinusSrcAlpha, One,
OneMinusSrcAlpha) by default.
Not having any TargetBlend specified in
QRhiGraphicsPipeline::setTargetBlends() disables blending and is a
convenient shortcut when having only one color attachment and no blending
is desired. Otherwise a TargetBlend for each color attachment is expected.
......@@ -324,6 +844,27 @@ QT_BEGIN_NAMESPACE
\brief Swapchain resource.
\enum QRhiSwapChain::Flag
Flag values to describe swapchain properties
\value SurfaceHasPreMulAlpha Indicates that the target surface has
transparency with premultiplied alpha.
\value SurfaceHasNonPreMulAlpha Indicates the target surface has
transparencyt with non-premultiplied alpha.
\value sRGB Requests to pick an sRGB format.
\value UsedAsTransferSource Indicates the the swapchain will be used as the
source of a readback in QRhiResourceUpdateBatch::readBackTexture().
\value NoVSync Requests disabling waiting for vertical sync, also avoiding
throttling the rendering thread. The behavior is backend specific and
applicable only where it is possible to control this. Some may ignore the
request altogether. For OpenGL, use QSurfaceFormat::setSwapInterval().
\class QRhiCommandBuffer
\inmodule QtRhi
......@@ -332,7 +873,15 @@ QT_BEGIN_NAMESPACE
Not creatable by applications at the moment. The only ways to obtain a
valid QRhiCommandBuffer are to get it from the targeted swapchain via
QRhiSwapChain::currentFrameCommandBuffer(), or, in case of rendering
compeletely offscreen, initializing one via beginOffscreenFrame().
compeletely offscreen, initializing one via QRhi::beginOffscreenFrame().
\enum QRhiCommandBuffer::IndexFormat
Specifies the index data type
\value IndexUInt16 Unsigned 16-bit (quint16)
\value IndexUInt32 Unsigned 32-bit (quint32)