Commit c5a4a7fe authored by Laszlo Agocs's avatar Laszlo Agocs

Start adding rhi docs

parent a7a76303
......@@ -31,7 +31,7 @@ qhp.QtRhi.subprojects.examples.selectors = fake:example
tagfile = ../../../doc/qtrhi/qtrhi.tags
depends += qtcore qtgui
depends += qtcore qtgui qtshadertools
headerdirs += ..
......
......@@ -29,6 +29,67 @@
\title Qt Rendering Hardware Interface
\page qtrhi-index.html
\section1 Introduction
The Qt Rendering Hardware Interface is an abstraction for hardware accelerated
graphics APIs, such as, \l{https://www.khronos.org/opengl/}{OpenGL},
\l{https://www.khronos.org/opengles/}{OpenGL ES},
\l{https://docs.microsoft.com/en-us/windows/desktop/direct3d}{Direct3D},
\l{https://developer.apple.com/metal/}{Metal}, and
\l{https://www.khronos.org/vulkan/}{Vulkan}.
Some of the main design goals are:
\list
\li Simple, minimal, understandable, extensible. Follow the proven path of the
Qt Quick scenegraph.
\li Aim to be a product - and in the bigger picture, part of a product (Qt) -
that is usable out of the box both by internal (such as, Qt Quick) and,
eventually, external users.
\li Not a complete 1:1 wrapper for any of the underlying APIs. The feature set
is tuned towards the needs of Qt's 2D and 3D offering (QPainter, Qt Quick, Qt
3D Studio). Iterate and evolve in a sustainable manner.
\li Intrinsically cross-platform, without reinventing: abstracting
cross-platform aspects of certain APIs (such as, OpenGL context creation and
windowing system interfaces, Vulkan instance and surface management) is not in
scope here. These are delegated to the existing QtGui facilities (QWindow,
QOpenGLContext, QVulkanInstance) and its backing QPA architecture.
\endlist
The main class in the module is QRhi. 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.
The available backends currently are:
\list
\li OpenGL 2.1 or OpenGL ES 2.0 or newer. Some extensions are utilized when
present, for example to enable multisample framebuffers.
\li Direct3D 11.1
\li Metal
\li Vulkan 1.0, optionally with some extensions that are part of Vulkan 1.1
\li Null - A "dummy" backend that issues no graphics calls at all.
\endlist
Managing shader code and dealing with shading language differences is not in
the scope of this module. Rather, it is delegated to the \l{Qt Shader Tools}
module. Classes like QRhiGraphicsPipeline and QRhiGraphicsShaderStage are
prepared to work directly with QBakedShader instances.
\section1 Table of Contents
\list
......
......@@ -56,6 +56,80 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhi
\inmodule QtRhi
\brief Accelerated 2D/3D graphics API abstraction.
*/
/*!
\enum QRhi::Implementation
Describes which graphics API-specific backend gets used by a QRhi instance.
\value Null
\value Vulkan
\value OpenGLES2
\value D3D11
\value Metal
*/
/*!
\enum QRhi::Flag
Describes what special features to enable.
\value EnableProfiling Enables gathering timing (CPU, GPU) and resource
(QRhiBuffer, QRhiTexture, etc.) information and additional metadata. See
QRhiProfiler. Avoid enabling in production builds as it may involve a
performance penalty.
\value EnableDebugMarkers Enables debug marker groups. Without this frame
debugging features like making debug groups and custom resource name
visible in external GPU debugging tools will not be available and functions
like QRhiCommandBuffer::debugMarkBegin() will become a no-op. Avoid
enabling in production builds as it may involve a performance penalty.
*/
/*!
\enum QRhi::FrameOpResult
Describes the result of operations that can have a soft failure.
\value FrameOpSuccess Success
\value FrameOpError Unspecified error
\value FrameOpSwapChainOutOfDate The swapchain is in an inconsistent state
internally. This can be recoverable by attempting to repeat the operation
(such as, beginFrame()) later.
\value FrameOpDeviceLost The graphics device was lost. This can be
recoverable by attempting to repeat the operation (such as, beginFrame())
and releasing and reinitializing all objects backed by native graphics
resources.
*/
/*!
\enum QRhi::Feature
Flag values to indicate what features are supported by the backend currently in use.
\value MultisampleTexture Textures with sample count larger than 1 are supported.
\value MultisampleRenderBuffer Renderbuffers with sample count larger than 1 are supported.
\value DebugMarkers Debug marker groups (and so QRhiCommandBuffer::debugMarkBegin()) are supported.
\value Timestamps Command buffer timestamps are supported. Relevant for QRhiProfiler::gpuFrameTimes().
\value Instancing Instanced drawing is supported.
\value CustomInstanceStepRate Instance step rate other than 1 is supported.
*/
/*!
\enum QRhi::ResourceSizeLimit
Describes the resource limit to query.
\value TextureSizeMin Minimum texture width and height. This is typically
1. The minimum texture size is handled gracefully, meaning attempting to
create a texture with an empty size will instead create a texture with the
minimum size.
\value TextureSizeMax Maximum texture width and height. This depends on the
graphics API and sometimes the platform or implementation as well.
Typically the value is in the range 4096 - 16384. Attempting to create
textures larger than this is expected to fail.
*/
/*!
......
......@@ -39,6 +39,13 @@
QT_BEGIN_NAMESPACE
/*!
\class QRhiProfiler
\inmodule QtRhi
\brief Collects resource and timing information from an active QRhi
*/
QRhiProfiler::QRhiProfiler()
: d(new QRhiProfilerPrivate)
{
......
......@@ -191,10 +191,10 @@ QShaderBaker::~QShaderBaker()
The supported file extensions are:
\list
\li \c{.vert} - vertex shader
\li \c{.frag} - fragment shader
\li \c{.tesc} - tessellation control (hull)
\li \c{.tese} - tessellation evaluation (domain)
\li \c{.geom} - geometry
\li \c{.frag} - fragment (pixel) shader
\li \c{.tesc} - tessellation control (hull) shader
\li \c{.tese} - tessellation evaluation (domain) shader
\li \c{.geom} - geometry shader
\li \c{.comp} - compute shader
\endlist
*/
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment