RHI Window Example¶
This example shows how to create a minimal QWindow-based
application using QRhi.
Qt 6.6 starts offering its accelerated 3D API and shader abstraction layer for
application use as well. Applications can now use the same 3D graphics classes
Qt itself uses to implement the Qt Quick scenegraph or the Qt Quick 3D
engine. In earlier Qt versions QRhi and the related classes were all
private APIs. From 6.6 on these classes are in a similar category as QPA family
of classes: neither fully public nor private, but something in-between, with a
more limited compatibility promise compared to public APIs. On the other hand,
QRhi and the related classes now come with full documentation similarly to
public APIs.
There are multiple ways to use QRhi, the example here shows the most
low-level approach: targeting a QWindow, while not using Qt Quick, Qt
Quick 3D, or Widgets in any form, and setting up all the rendering and
windowing infrastructure in the application.
In contrast, when writing a QML application with Qt Quick or Qt Quick
3D, and wanting to add QRhi-based rendering to it, such an application is
going to rely on the window and rendering infrastructure Qt Quick has
already initialized, and it is likely going to query an existing QRhi
instance from the QQuickWindow. There dealing with QRhi::create(),
platform/API specifics or correctly handling QExposeEvent and resize events
for the window are all managed by Qt Quick. Whereas in this example, all that
is managed and taken care of by the application itself.
Note
For QWidget-based applications, see the rhi-widget-example.
Shaders¶
Due to being a Qt GUI/Python module example, this example cannot have a
dependency on the Qt Shader Tools module. This means that CMake helper
functions such as qt_add_shaders are not available for use. Therefore, the
example has the pre-processed .qsb files included in the
shaders/prebuilt folder, and they are simply included within the executable
via a resource file}. This approach is not generally recommended for
applications.
# Copyright (C) 2023 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
from __future__ import annotations
from argparse import ArgumentParser, RawDescriptionHelpFormatter
import sys
from PySide6.QtCore import QCoreApplication
from PySide6.QtGui import QGuiApplication, QRhi, QSurfaceFormat
from rhiwindow import HelloWindow
import rc_rhiwindow # noqa: F401
if __name__ == "__main__":
app = QGuiApplication(sys.argv)
# Use platform-specific defaults when no command-line arguments given.
graphicsApi = QRhi.Implementation.OpenGLES2
if sys.platform == "win32":
graphicsApi = QRhi.Implementation.D3D11
elif sys.platform == "darwin":
graphicsApi = QRhi.Implementation.Metal
parser = ArgumentParser(formatter_class=RawDescriptionHelpFormatter,
description="QRhi render example")
parser.add_argument("--null", "-n", action="store_true", help="Null")
parser.add_argument("--opengl", "-g", action="store_true", help="OpenGL")
parser.add_argument("--d3d11", "-d", action="store_true",
help="Direct3D 11")
parser.add_argument("--d3d12", "-D", action="store_true",
help="Direct3D 12")
parser.add_argument("--metal", "-m", action="store_true",
help="Metal")
args = parser.parse_args()
if args.null:
graphicsApi = QRhi.Implementation.Null
elif args.opengl:
graphicsApi = QRhi.Implementation.OpenGLES2
elif args.d3d11:
graphicsApi = QRhi.Implementation.D3D11
elif args.d3d12:
graphicsApi = QRhi.Implementation.D3D12
elif args.metal:
graphicsApi = QRhi.Implementation.Metal
# graphicsApi = QRhi.Vulkan? detect? needs QVulkanInstance
# For OpenGL, to ensure there is a depth/stencil buffer for the window.
# With other APIs this is under the application's control
# (QRhiRenderBuffer etc.) and so no special setup is needed for those.
fmt = QSurfaceFormat()
fmt.setDepthBufferSize(24)
fmt.setStencilBufferSize(8)
# Special case macOS to allow using OpenGL there.
# (the default Metal is the recommended approach, though)
# gl_VertexID is a GLSL 130 feature, and so the default OpenGL 2.1 context
# we get on macOS is not sufficient.
if sys.platform == "darwin":
fmt.setVersion(4, 1)
fmt.setProfile(QSurfaceFormat.OpenGLContextProfile.CoreProfile)
QSurfaceFormat.setDefaultFormat(fmt)
window = HelloWindow(graphicsApi)
window.resize(1280, 720)
title = QCoreApplication.applicationName() + " - " + window.graphicsApiName()
window.setTitle(title)
window.show()
ret = app.exec()
# RhiWindow::event() will not get invoked when the
# PlatformSurfaceAboutToBeDestroyed event is sent during the QWindow
# destruction. That happens only when exiting via app::quit() instead of
# the more common QWindow::close(). Take care of it: if the QPlatformWindow
# is still around (there was no close() yet), get rid of the swapchain
# while it's not too late.
if window.isVisible():
window.releaseSwapChain()
sys.exit(ret)
# Copyright (C) 2023 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
from __future__ import annotations
import numpy
import sys
from PySide6.QtCore import (QEvent, QFile, QIODevice, QPointF, QRectF, QSize,
qFatal, qWarning, Qt)
from PySide6.QtGui import (QColor, QFont, QGradient, QImage, QMatrix4x4,
QPainter, QPlatformSurfaceEvent, QSurface, QWindow)
from PySide6.QtGui import (QRhi, QRhiBuffer,
QRhiDepthStencilClearValue,
QRhiGraphicsPipeline, QRhiNullInitParams,
QRhiGles2InitParams, QRhiRenderBuffer,
QRhiSampler, QRhiShaderResourceBinding,
QRhiShaderStage, QRhiTexture,
QRhiVertexInputAttribute, QRhiVertexInputBinding,
QRhiVertexInputLayout, QRhiViewport,
QShader)
from PySide6.support import VoidPtr
if sys.platform == "win32":
from PySide6.QtGui import QRhiD3D11InitParams, QRhiD3D12InitParams
elif sys.platform == "darwin":
from PySide6.QtGui import QRhiMetalInitParams
# Y up (note clipSpaceCorrMatrix in m_viewProjection), CCW
VERTEX_DATA = numpy.array([
0.0, 0.5, 1.0, 0.0, 0.0,
-0.5, -0.5, 0.0, 1.0, 0.0,
0.5, -0.5, 0.0, 0.0, 1.0], dtype=numpy.float32)
UBUF_SIZE = 68
def getShader(name):
f = QFile(name)
if f.open(QIODevice.ReadOnly):
result = QShader.fromSerialized(f.readAll())
f.close()
return result
return QShader()
class RhiWindow(QWindow):
def __init__(self, graphicsApi):
super().__init__()
self.m_graphicsApi = QRhi.Null
self.m_initialized = False
self.m_notExposed = False
self.m_newlyExposed = False
self.m_fallbackSurface = None
self.m_rhi = None
self.m_sc = None
self.m_ds = None
self.m_rp = None
self.m_hasSwapChain = False
self.m_viewProjection = QMatrix4x4()
self.m_graphicsApi = graphicsApi
if graphicsApi == QRhi.OpenGLES2:
self.setSurfaceType(QSurface.SurfaceType.OpenGLSurface)
elif graphicsApi == QRhi.Vulkan:
self.setSurfaceType(QSurface.SurfaceType.VulkanSurface)
elif graphicsApi == QRhi.D3D11 or graphicsApi == QRhi.D3D12:
self.setSurfaceType(QSurface.SurfaceType.Direct3DSurface)
elif graphicsApi == QRhi.Metal:
self.setSurfaceType(QSurface.SurfaceType.MetalSurface)
elif graphicsApi == QRhi.Null:
pass # RasterSurface
def __del__(self):
# destruction order matters to a certain degree: the fallbackSurface
# must outlive the rhi, the rhi must outlive all other resources.
# The resources need no special order when destroying.
del self.m_rp
self.m_rp = None
del self.m_ds
self.m_ds = None
del self.m_sc
self.m_sc = None
del self.m_rhi
self.m_rhi = None
if self.m_fallbackSurface:
del self.m_fallbackSurface
self.m_fallbackSurface = None
def graphicsApiName(self):
if self.m_graphicsApi == QRhi.Null:
return "Null (no output)"
if self.m_graphicsApi == QRhi.OpenGLES2:
return "OpenGL"
if self.m_graphicsApi == QRhi.Vulkan:
return "Vulkan"
if self.m_graphicsApi == QRhi.D3D11:
return "Direct3D 11"
if self.m_graphicsApi == QRhi.D3D12:
return "Direct3D 12"
if self.m_graphicsApi == QRhi.Metal:
return "Metal"
return ""
def customInit(self):
pass
def customRender(self):
pass
def exposeEvent(self, e):
# initialize and start rendering when the window becomes usable
# for graphics purposes
is_exposed = self.isExposed()
if is_exposed and not self.m_initialized:
self.init()
self.resizeSwapChain()
self.m_initialized = True
surfaceSize = self.m_sc.surfacePixelSize() if self.m_hasSwapChain else QSize()
# stop pushing frames when not exposed (or size is 0)
if ((not is_exposed or (self.m_hasSwapChain and surfaceSize.isEmpty()))
and self.m_initialized and not self.m_notExposed):
self.m_notExposed = True
# Continue when exposed again and the surface has a valid size. Note
# that surfaceSize can be (0, 0) even though size() reports a valid
# one, hence trusting surfacePixelSize() and not QWindow.
if is_exposed and self.m_initialized and self.m_notExposed and not surfaceSize.isEmpty():
self.m_notExposed = False
self.m_newlyExposed = True
# always render a frame on exposeEvent() (when exposed) in order to
# update immediately on window resize.
if is_exposed and not surfaceSize.isEmpty():
self.render()
def event(self, e):
if e.type() == QEvent.UpdateRequest:
self.render()
elif e.type() == QEvent.PlatformSurface:
# this is the proper time to tear down the swapchain (while
# the native window and surface are still around)
if e.surfaceEventType() == QPlatformSurfaceEvent.SurfaceAboutToBeDestroyed:
self.releaseSwapChain()
return super().event(e)
def init(self):
if self.m_graphicsApi == QRhi.Null:
params = QRhiNullInitParams()
self.m_rhi = QRhi.create(QRhi.Null, params)
if self.m_graphicsApi == QRhi.OpenGLES2:
self.m_fallbackSurface = QRhiGles2InitParams.newFallbackSurface()
params = QRhiGles2InitParams()
params.fallbackSurface = self.m_fallbackSurface
params.window = self
self.m_rhi = QRhi.create(QRhi.OpenGLES2, params)
elif self.m_graphicsApi == QRhi.D3D11:
params = QRhiD3D11InitParams()
# Enable the debug layer, if available. This is optional
# and should be avoided in production builds.
params.enableDebugLayer = True
self.m_rhi = QRhi.create(QRhi.D3D11, params)
elif self.m_graphicsApi == QRhi.D3D12:
params = QRhiD3D12InitParams()
# Enable the debug layer, if available. This is optional
# and should be avoided in production builds.
params.enableDebugLayer = True
self.m_rhi = QRhi.create(QRhi.D3D12, params)
elif self.m_graphicsApi == QRhi.Metal:
params = QRhiMetalInitParams()
self.m_rhi.reset(QRhi.create(QRhi.Metal, params))
if not self.m_rhi:
qFatal("Failed to create RHI backend")
self.m_sc = self.m_rhi.newSwapChain()
# no need to set the size here, due to UsedWithSwapChainOnly
self.m_ds = self.m_rhi.newRenderBuffer(QRhiRenderBuffer.DepthStencil,
QSize(), 1,
QRhiRenderBuffer.UsedWithSwapChainOnly)
self.m_sc.setWindow(self)
self.m_sc.setDepthStencil(self.m_ds)
self.m_rp = self.m_sc.newCompatibleRenderPassDescriptor()
self.m_sc.setRenderPassDescriptor(self.m_rp)
self.customInit()
def resizeSwapChain(self):
self.m_hasSwapChain = self.m_sc.createOrResize() # also handles self.m_ds
outputSize = self.m_sc.currentPixelSize()
self.m_viewProjection = self.m_rhi.clipSpaceCorrMatrix()
r = float(outputSize.width()) / float(outputSize.height())
self.m_viewProjection.perspective(45.0, r, 0.01, 1000.0)
self.m_viewProjection.translate(0, 0, -4)
def releaseSwapChain(self):
if self.m_hasSwapChain:
self.m_hasSwapChain = False
self.m_sc.destroy()
def render(self):
if not self.m_hasSwapChain or self.m_notExposed:
return
# If the window got resized or newly exposed, resize the swapchain.
# (the newly-exposed case is not actually required by some platforms,
# but is here for robustness and portability)
#
# This (exposeEvent + the logic here) is the only safe way to perform
# resize handling. Note the usage of the RHI's surfacePixelSize(), and
# never QWindow::size(). (the two may or may not be the same under the
# hood, # depending on the backend and platform)
if self.m_sc.currentPixelSize() != self.m_sc.surfacePixelSize() or self.m_newlyExposed:
self.resizeSwapChain()
if not self.m_hasSwapChain:
return
self.m_newlyExposed = False
result = self.m_rhi.beginFrame(self.m_sc)
if result == QRhi.FrameOpSwapChainOutOfDate:
self.resizeSwapChain()
if not self.m_hasSwapChain:
return
result = self.m_rhi.beginFrame(self.m_sc)
if result != QRhi.FrameOpSuccess:
qWarning(f"beginFrame failed with {result}, will retry")
self.requestUpdate()
return
self.customRender()
self.m_rhi.endFrame(self.m_sc)
# Always request the next frame via requestUpdate(). On some platforms
# this is backed by a platform-specific solution, e.g. CVDisplayLink
# on macOS, which is potentially more efficient than a timer,
# queued metacalls, etc.
self.requestUpdate()
class HelloWindow(RhiWindow):
def __init__(self, graphicsApi):
super().__init__(graphicsApi)
self.m_vbuf = None
self.m_ubuf = None
self.m_texture = None
self.m_sampler = None
self.m_colorTriSrb = None
self.m_colorPipeline = None
self.m_fullscreenQuadSrb = None
self.m_fullscreenQuadPipeline = None
self.m_initialUpdates = None
self.m_rotation = 0
self.m_opacity = 1
self.m_opacityDir = -1
def ensureFullscreenTexture(self, pixelSize, u):
if self.m_texture and self.m_texture.pixelSize() == pixelSize:
return
if not self.m_texture:
self.m_texture = self.m_rhi.newTexture(QRhiTexture.RGBA8, pixelSize)
else:
self.m_texture.setPixelSize(pixelSize)
self.m_texture.create()
image = QImage(pixelSize, QImage.Format_RGBA8888_Premultiplied)
with QPainter(image) as painter:
painter.fillRect(QRectF(QPointF(0, 0), pixelSize),
QColor.fromRgbF(0.4, 0.7, 0.0, 1.0))
painter.setPen(Qt.transparent)
painter.setBrush(QGradient(QGradient.DeepBlue))
painter.drawRoundedRect(QRectF(QPointF(20, 20), pixelSize - QSize(40, 40)),
16, 16)
painter.setPen(Qt.black)
font = QFont()
font.setPixelSize(0.05 * min(pixelSize.width(), pixelSize.height()))
painter.setFont(font)
name = self.graphicsApiName()
t = (f"Rendering with QRhi to a resizable QWindow.\nThe 3D API is {name}."
"\nUse the command-line options to choose a different API.")
painter.drawText(QRectF(QPointF(60, 60), pixelSize - QSize(120, 120)), 0, t)
if self.m_rhi.isYUpInNDC():
image = image.mirrored()
u.uploadTexture(self.m_texture, image)
def customInit(self):
self.m_initialUpdates = self.m_rhi.nextResourceUpdateBatch()
vertex_size = 4 * VERTEX_DATA.size
self.m_vbuf = self.m_rhi.newBuffer(QRhiBuffer.Immutable, QRhiBuffer.VertexBuffer,
vertex_size)
self.m_vbuf.create()
self.m_initialUpdates.uploadStaticBuffer(self.m_vbuf,
VoidPtr(VERTEX_DATA.tobytes(), vertex_size))
self.m_ubuf = self.m_rhi.newBuffer(QRhiBuffer.Dynamic,
QRhiBuffer.UniformBuffer, UBUF_SIZE)
self.m_ubuf.create()
self.ensureFullscreenTexture(self.m_sc.surfacePixelSize(), self.m_initialUpdates)
self.m_sampler = self.m_rhi.newSampler(QRhiSampler.Linear, QRhiSampler.Linear,
QRhiSampler.None_,
QRhiSampler.ClampToEdge, QRhiSampler.ClampToEdge)
self.m_sampler.create()
self.m_colorTriSrb = self.m_rhi.newShaderResourceBindings()
visibility = (QRhiShaderResourceBinding.VertexStage
| QRhiShaderResourceBinding.FragmentStage)
bindings = [
QRhiShaderResourceBinding.uniformBuffer(0, visibility, self.m_ubuf)
]
self.m_colorTriSrb.setBindings(bindings)
self.m_colorTriSrb.create()
self.m_colorPipeline = self.m_rhi.newGraphicsPipeline()
# Enable depth testing; not quite needed for a simple triangle, but we
# have a depth-stencil buffer so why not.
self.m_colorPipeline.setDepthTest(True)
self.m_colorPipeline.setDepthWrite(True)
# Blend factors default to One, OneOneMinusSrcAlpha, which is convenient.
premulAlphaBlend = QRhiGraphicsPipeline.TargetBlend()
premulAlphaBlend.enable = True
self.m_colorPipeline.setTargetBlends([premulAlphaBlend])
stages = [
QRhiShaderStage(QRhiShaderStage.Vertex, getShader(":/color.vert.qsb")),
QRhiShaderStage(QRhiShaderStage.Fragment, getShader(":/color.frag.qsb"))
]
self.m_colorPipeline.setShaderStages(stages)
inputLayout = QRhiVertexInputLayout()
input_bindings = [QRhiVertexInputBinding(5 * 4)] # sizeof(float)
inputLayout.setBindings(input_bindings)
attributes = [
QRhiVertexInputAttribute(0, 0, QRhiVertexInputAttribute.Float2, 0),
QRhiVertexInputAttribute(0, 1, QRhiVertexInputAttribute.Float3, 2 * 4)] # sizeof(float)
inputLayout.setAttributes(attributes)
self.m_colorPipeline.setVertexInputLayout(inputLayout)
self.m_colorPipeline.setShaderResourceBindings(self.m_colorTriSrb)
self.m_colorPipeline.setRenderPassDescriptor(self.m_rp)
self.m_colorPipeline.create()
self.m_fullscreenQuadSrb = self.m_rhi.newShaderResourceBindings()
bindings = [
QRhiShaderResourceBinding.sampledTexture(0, QRhiShaderResourceBinding.FragmentStage,
self.m_texture, self.m_sampler)
]
self.m_fullscreenQuadSrb.setBindings(bindings)
self.m_fullscreenQuadSrb.create()
self.m_fullscreenQuadPipeline = self.m_rhi.newGraphicsPipeline()
stages = [
QRhiShaderStage(QRhiShaderStage.Vertex, getShader(":/quad.vert.qsb")),
QRhiShaderStage(QRhiShaderStage.Fragment, getShader(":/quad.frag.qsb"))
]
self.m_fullscreenQuadPipeline.setShaderStages(stages)
layout = QRhiVertexInputLayout()
self.m_fullscreenQuadPipeline.setVertexInputLayout(layout)
self.m_fullscreenQuadPipeline.setShaderResourceBindings(self.m_fullscreenQuadSrb)
self.m_fullscreenQuadPipeline.setRenderPassDescriptor(self.m_rp)
self.m_fullscreenQuadPipeline.create()
def customRender(self):
resourceUpdates = self.m_rhi.nextResourceUpdateBatch()
if self.m_initialUpdates:
resourceUpdates.merge(self.m_initialUpdates)
self.m_initialUpdates = None
self.m_rotation += 1.0
modelViewProjection = self.m_viewProjection
modelViewProjection.rotate(self.m_rotation, 0, 1, 0)
projection = numpy.array(modelViewProjection.data(),
dtype=numpy.float32)
resourceUpdates.updateDynamicBuffer(self.m_ubuf, 0, 64,
projection.tobytes())
self.m_opacity += self.m_opacityDir * 0.005
if self.m_opacity < 0.0 or self.m_opacity > 1.0:
self.m_opacityDir *= -1
self.m_opacity = max(0.0, min(1.0, self.m_opacity))
opacity = numpy.array([self.m_opacity], dtype=numpy.float32)
resourceUpdates.updateDynamicBuffer(self.m_ubuf, 64, 4,
opacity.tobytes())
cb = self.m_sc.currentFrameCommandBuffer()
outputSizeInPixels = self.m_sc.currentPixelSize()
# (re)create the texture with a size matching the output surface size,
# when necessary.
self.ensureFullscreenTexture(outputSizeInPixels, resourceUpdates)
cv = QRhiDepthStencilClearValue(1.0, 0)
cb.beginPass(self.m_sc.currentFrameRenderTarget(), Qt.black,
cv, resourceUpdates)
cb.setGraphicsPipeline(self.m_fullscreenQuadPipeline)
viewport = QRhiViewport(0, 0, outputSizeInPixels.width(),
outputSizeInPixels.height())
cb.setViewport(viewport)
cb.setShaderResources()
cb.draw(3)
cb.setGraphicsPipeline(self.m_colorPipeline)
cb.setShaderResources()
vbufBinding = (self.m_vbuf, 0)
cb.setVertexInput(0, [vbufBinding])
cb.draw(3)
cb.endPass()
<!DOCTYPE RCC><RCC version="1.0">
<qresource>
<file alias="color.vert.qsb">shaders/prebuilt/color.vert.qsb</file>
<file alias="color.frag.qsb">shaders/prebuilt/color.frag.qsb</file>
<file alias="quad.vert.qsb">shaders/prebuilt/quad.vert.qsb</file>
<file alias="quad.frag.qsb">shaders/prebuilt/quad.frag.qsb</file>
</qresource>
</RCC>
#version 440
layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
mat4 mvp;
float opacity;
};
void main()
{
fragColor = vec4(v_color * opacity, opacity);
}
#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;
layout(std140, binding = 0) uniform buf {
mat4 mvp;
float opacity;
};
void main()
{
v_color = color;
gl_Position = mvp * position;
}
#version 440
layout(location = 0) in vec2 v_uv;
layout(location = 0) out vec4 fragColor;
layout(binding = 0) uniform sampler2D tex;
void main()
{
vec4 c = texture(tex, v_uv);
fragColor = vec4(c.rgb * c.a, c.a);
}
#version 440
layout (location = 0) out vec2 v_uv;
void main()
{
// https://www.saschawillems.de/blog/2016/08/13/vulkan-tutorial-on-rendering-a-fullscreen-quad-without-buffers/
v_uv = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
gl_Position = vec4(v_uv * 2.0 - 1.0, 0.0, 1.0);
}