Commit e0d99517 authored by Laszlo Agocs's avatar Laszlo Agocs

Add docs for initparams structs

parent c5a4a7fe
......@@ -135,171 +135,210 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhiInitParams
\inmodule QtRhi
\brief Base class for backend-specific initialization parameters.
*/
/*!
\class QRhiColorClearValue
\inmodule QtRhi
\brief Specifies a clear color for a color buffer.
*/
/*!
\class QRhiDepthStencilClearValue
\inmodule QtRhi
\brief Specifies clear values for a depth or stencil buffer.
*/
/*!
\class QRhiViewport
\inmodule QtRhi
\brief Specifies a viewport rectangle.
*/
/*!
\class QRhiScissor
\inmodule QtRhi
\brief Specifies a scissor rectangle.
*/
/*!
\class QRhiVertexInputLayout
\inmodule QtRhi
\brief Describes the layout of vertex inputs consumed by a vertex shader.
*/
/*!
\class QRhiVertexInputLayout::Binding
\inmodule QtRhi
\brief Describes a vertex input binding.
*/
/*!
\class QRhiVertexInputLayout::Attribute
\inmodule QtRhi
\brief Describes a single vertex input element.
*/
/*!
\class QRhiGraphicsShaderStage
\inmodule QtRhi
\brief Specifies the type and the shader code for a shader stage in the graphics pipeline.
*/
/*!
\class QRhiShaderResourceBinding
\inmodule QtRhi
\brief Specifies the shader resources that are made visible to one or more shader stages.
*/
/*!
\class QRhiTextureRenderTargetDescription
\inmodule QtRhi
\brief Describes the color and depth or depth/stencil attachments of a render target.
*/
/*!
\class QRhiTextureRenderTargetDescription::ColorAttachment
\inmodule QtRhi
\brief Describes the color attachments of a render target.
*/
/*!
\class QRhiTextureUploadDescription
\inmodule QtRhi
\brief Describes a texture upload operation.
*/
/*!
\class QRhiTextureUploadDescription::Layer
\inmodule QtRhi
\brief Describes one layer (face for cubemaps) in a texture upload operation.
*/
/*!
\class QRhiTextureUploadDescription::Layer::MipLevel
\inmodule QtRhi
\brief Describes one mip level in a layer in a texture upload operation.
*/
/*!
\class QRhiTextureCopyDescription
\inmodule QtRhi
\brief Describes a texture-to-texture copy operation.
*/
/*!
\class QRhiReadbackDescription
\inmodule QtRhi
\brief Describes a readback (reading back texture contents from possibly GPU-only memory) operation.
*/
/*!
\class QRhiReadbackResult
\inmodule QtRhi
\brief Describes the results of a potentially asynchronous readback operation.
*/
/*!
\class QRhiNativeHandles
\inmodule QtRhi
\brief Base class for classes exposing backend-specific collections of native resource objects.
*/
/*!
\class QRhiResource
\inmodule QtRhi
\brief Base class for classes encapsulating native resource objects.
*/
/*!
\class QRhiBuffer
\inmodule QtRhi
\brief Vertex, index, or uniform (constant) buffer resource.
*/
/*!
\class QRhiTexture
\inmodule QtRhi
\brief Texture resource.
*/
/*!
\class QRhiSampler
\inmodule QtRhi
\brief Sampler resource.
*/
/*!
\class QRhiRenderBuffer
\inmodule QtRhi
\brief Renderbuffer resource.
*/
/*!
\class QRhiRenderPassDescriptor
\inmodule QtRhi
\brief Render pass resource.
*/
/*!
\class QRhiRenderTarget
\inmodule QtRhi
\brief Represents an onscreen (swapchain) or offscreen (texture) render target.
*/
/*!
\class QRhiTextureRenderTarget
\inmodule QtRhi
\brief Texture render target resource.
*/
/*!
\class QRhiShaderResourceBindings
\inmodule QtRhi
\brief Encapsulates resources for making buffer, texture, sampler resources visible to shaders.
*/
/*!
\class QRhiGraphicsPipeline
\inmodule QtRhi
\brief Graphics pipeline state resource.
*/
/*!
\class QRhiGraphicsPipeline::TargetBlend
\inmodule QtRhi
\brief Describes the blend state for one color attachment.
*/
/*!
\class QRhiGraphicsPipeline::StencilOpState
\inmodule QtRhi
\brief Describes the stencil operation state.
*/
/*!
\class QRhiSwapChain
\inmodule QtRhi
\brief Swapchain resource.
*/
/*!
\class QRhiCommandBuffer
\inmodule QtRhi
\brief Command buffer resource.
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().
*/
/*!
\class QRhiResourceUpdateBatch
\inmodule QtRhi
\brief Records upload and copy type of operations.
*/
QRhiResource::QRhiResource(QRhiImplementation *rhi_)
......
......@@ -57,16 +57,54 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhiD3D11InitParams
\inmodule QtRhi
\brief Direct3D 11 specific initialization parameters.
A D3D11-based QRhi needs no special parameters for initialization. If
desired, enableDebugLayer can be set to \c true to enable the Direct3D
debug layer. This can be useful during development, but should be avoided
in production builds.
\badcode
QRhiD3D11InitParams params;
params.enableDebugLayer = true;
rhi = QRhi::create(QRhi::D3D11, &params);
\endcode
\note QRhiSwapChain should only be used in combination with QWindow
instances that have their surface type set to QSurface::OpenGLSurface.
There are currently no Direct3D specifics in the Windows platform support
of Qt and therefore there is no separate QSurface type available.
\section2 Working with existing Direct3D 11 devices
When interoperating with another graphics engine, it may be necessary to
get a QRhi instance that uses the same Direct3D device and device context.
This can be achieved by setting importExistingDevice to \c true and
providing both dev and context.
\note QRhi works with immediate contexts only. Deferred contexts are not
used in any way.
\note The class uses \c{void *} as the type since including the COM-based
\c{d3d11.h} headers is not acceptable here. The actual types are
\c{ID3D11Device *} and \c{ID3D11DeviceContext *}.
\note Regardless of using an imported or a QRhi-created device context,
\c ID3D11DeviceContext1 must be supported. Initialization will fail otherwise.
The QRhi does not take ownership of any of the external objects.
*/
/*!
\class QRhiD3D11NativeHandles
\inmodule QtRhi
\brief Holds the D3D device and device context used by the QRhi.
*/
/*!
\class QRhiD3D11TextureNativeHandles
\inmodule QtRhi
\brief Holds the D3D texture object that is backing a QRhiTexture instance.
*/
QRhiD3D11::QRhiD3D11(QRhiInitParams *params)
......
......@@ -61,16 +61,48 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhiGles2InitParams
\inmodule QtRhi
\brief OpenGL specific initialization parameters.
An OpenGL-based QRhi needs an already initialized QOpenGLContext and
QOffscreenSurface. Additionally, while optional, it is recommended that the
QWindow the first QRhiSwapChain will target is passed in as well.
\badcode
context = new QOpenGLContext;
if (!context->create())
qFatal("Failed to get OpenGL context");
fallbackSurface = new QOffscreenSurface;
fallbackSurface->setFormat(context->format());
fallbackSurface->create();
QRhiGles2InitParams params;
params.context = context;
params.window = window;
params.fallbackSurface = fallbackSurface;
rhi = QRhi::create(QRhi::OpenGLES2, &params);
\endcode
\note The example here shows the creation of the context and fallback
surface as well. Watch out for the fact that, unlike QOpenGLContext, a
QOffscreenSurface can only be created on the gui/main thread.
\note QRhiSwapChain can only target QWindow instances that have their
surface type set to QSurface::OpenGLSurface.
The QRhi does not take ownership of any of the external objects.
*/
/*!
\class QRhiGles2NativeHandles
\inmodule QtRhi
\brief Holds the OpenGL context used by the QRhi.
*/
/*!
\class QRhiGles2TextureNativeHandles
\inmodule QtRhi
\brief Holds the OpenGL texture object that is backing a QRhiTexture instance.
*/
QRhiGles2::QRhiGles2(QRhiInitParams *params)
......
......@@ -68,16 +68,46 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhiMetalInitParams
\inmodule QtRhi
\brief Metal specific initialization parameters.
A Metal-based QRhi needs no special parameters for initialization.
\badcode
QRhiMetalInitParams params;
rhi = QRhi::create(QRhi::Metal, &params);
\endcode
\note Metal API validation cannot be enabled by the application. Instead,
run the debug build of the application in XCode. Generating a
\c{.xcodeproj} file via \c{qmake -spec macx-xcode} provides a convenient
way to enable this.
\note QRhiSwapChain can only target QWindow instances that have their
surface type set to QSurface::MetalSurface.
\section2 Working with existing Metal devices
When interoperating with another graphics engine, it may be necessary to
get a QRhi instance that uses the same Metal device. This can be achieved
by setting importExistingDevice to \c true and providing dev.
\note The class uses \c{void *} as the type since including the Objective C
headers is not acceptable here. The actual type is \c{id<MTLDevice>} or
\c{MTLDevice *}.
The QRhi does not take ownership of any of the external objects.
*/
/*!
\class QRhiMetalNativeHandles
\inmodule QtRhi
\brief Holds the Metal device used by the QRhi.
*/
/*!
\class QRhiMetalTextureNativeHandles
\inmodule QtRhi
\brief Holds the Metal texture object that is backing a QRhiTexture instance.
*/
struct QRhiMetalData
......
......@@ -38,19 +38,35 @@
QT_BEGIN_NAMESPACE
/*
/*!
\class QRhiNullInitParams
\inmodule QtRhi
\brief Null backend specific initialization parameters.
A Null QRhi needs no special parameters for initialization.
\badcode
QRhiNullInitParams params;
rhi = QRhi::create(QRhi::Null, &params);
\endcode
The Null backend does not issue any graphics calls and creates no
resources. All QRhi operations will succeed as normal so applications can
still be run, albeit potentially at an unthrottled speed, depending on
their frame rendering strategy. The backend reports resources to
QRhiProfiler as usual.
*/
/*!
\class QRhiNullNativeHandles
\inmodule QtRhi
\brief Empty.
*/
/*!
\class QRhiNullTextureNativeHandles
\inmodule QtRhi
\brief Empty.
*/
QRhiNull::QRhiNull(QRhiInitParams *params)
......
......@@ -43,7 +43,7 @@ QT_BEGIN_NAMESPACE
\class QRhiProfiler
\inmodule QtRhi
\brief Collects resource and timing information from an active QRhi
\brief Collects resource and timing information from an active QRhi.
*/
QRhiProfiler::QRhiProfiler()
......
......@@ -61,16 +61,95 @@ QT_BEGIN_NAMESPACE
/*!
\class QRhiVulkanInitParams
\inmodule QtRhi
\brief Vulkan specific initialization parameters.
A Vulkan-based QRhi needs at minimum a valid QVulkanInstance. It is up to
the user to ensure this is available and initialized. This is typically
done in main() similarly to the following:
\badcode
int main(int argc, char **argv)
{
...
QVulkanInstance inst;
#ifndef Q_OS_ANDROID
inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");
#else
inst.setLayers(QByteArrayList()
<< "VK_LAYER_GOOGLE_threading"
<< "VK_LAYER_LUNARG_parameter_validation"
<< "VK_LAYER_LUNARG_object_tracker"
<< "VK_LAYER_LUNARG_core_validation"
<< "VK_LAYER_LUNARG_image"
<< "VK_LAYER_LUNARG_swapchain"
<< "VK_LAYER_GOOGLE_unique_objects");
#endif
inst.setExtensions(QByteArrayList()
<< "VK_KHR_get_physical_device_properties2");
if (!inst.create())
qFatal("Vulkan not available");
...
}
\endcode
The example here has two optional aspects: it enables the
\l{https://github.com/KhronosGroup/Vulkan-ValidationLayers}{Vulkan
validation layers}, when they are available, and also enables the
VK_KHR_get_physical_device_properties2 extension (part of Vulkan 1.1), when
available. The former is useful during the development phase (remember that
QVulkanInstance conveniently redirects messages and warnings to qDebug).
Avoid enabling it in production builds, however. The latter is important in
order to make QRhi::CustomInstanceStepRate available with Vulkan since
VK_EXT_vertex_attribute_divisor (part of Vulkan 1.1) depends on it. It can
be omitted when instanced drawing with a non-one step rate is not used.
Once this is done, a Vulkan-based QRhi can be created by passing the
instance and a QWindow with its surface type set to
QSurface::VulkanSurface:
\badcode
QRhiVulkanInitParams params;
params.inst = vulkanInstance;
params.window = window;
rhi = QRhi::create(QRhi::Vulkan, &params);
\endcode
The window is optional and can be omitted. This is not recommended however
because there is then no way to ensure presenting is supported while
choosing a graphics queue.
\note Even when a window is specified, QRhiSwapChain objects can be created
for other windows as well, as long as they all have their
QWindow::surfaceType() set to QSurface::VulkanSurface.
\section2 Working with existing Vulkan devices
When interoperating with another graphics engine, it may be necessary to
get a QRhi instance that uses the same Vulkan device. This can be achieved
by setting importExistingDevice to \c true and providing the already
created physical device and device objects. In addition, either the
graphics queue family index or the graphics queue object itself is
required. Prefer the former, whenever possible since deducing the index is
not possible afterwards. Optionally, an existing command pool object can be
specified as well. Finally, vmemAllocator can be used to share the same
\l{https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator}{Vulkan
memory allocator} between two QRhi instances.
The QRhi does not take ownership of any of the external objects.
*/
/*!
\class QRhiVulkanNativeHandles
\inmodule QtRhi
\brief Collects device, queue, and other Vulkan objects that are used by the QRhi.
*/
/*!
\class QRhiVulkanTextureNativeHandles
\inmodule QtRhi
\brief Holds the Vulkan image object that is backing a QRhiTexture instance.
*/
static inline VkDeviceSize aligned(VkDeviceSize v, VkDeviceSize byteAlign)
......
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