Revision control
Copy as Markdown
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example extensions/stenciloutline3d
\ingroup quick3d-examples
\title Qt Quick 3D - Stencil Outline Extension Example
\examplecategory {3D}
\brief Demonstrates how the QtQuick3D Render Extension can be used to implement stencil outlining.
\image stencil_outline.jpg
{Three monkey head models in pink, red, and green with blue
stencil outline on pink model}
This example shows how the QtQuick3D Render Extensions can be used to add support for stencil outlining.
The first step is to implement the front-end item by creating a new \l {QQuick3DRenderExtension}{Render Extension} item which exposes
the properties needed to QML.
In this example we expose 3 properties, a \c target which takes the \l {QtQuick3D::Model}{model} we want to outline,
the \l {QtQuick3D::Material}{material} we want to use for the outline, and a \c scale value for adjusting the size of the outline.
\snippet extensions/stenciloutline3d/outlinerenderextension.h extension front
The second step is to implement the back-end \l {QSSGRenderExtension}{Render Extension} class, this is the class that contains
the code that will be run by QtQuick3D.
For this extension we'll be rendering \c after the built-in color-pass, and we'll want to render as part of the main render pass,
so we'll return \l {QSSGRenderExtension::RenderStage::PostColor}{PostColor} and \l {QSSGRenderExtension::RenderMode::Main}{Main} in
in our \l QSSGRenderExtension::stage() and QSSGRenderExtension::mode() functions respectively.
\snippet extensions/stenciloutline3d/outlinerenderextension.cpp extension back
The next function that needs to be implement is QSSGRenderExtension::prepareData(), this function should collect and set-up the data
this extension will be using for rendering. If there's nothing to render this function should return \c false.
\snippet extensions/stenciloutline3d/outlinerenderextension.cpp extension back_prepareData
If QSSGRenderExtension::prepareData() returned \c true the next function to be called is QSSGRenderExtension::prepareRender().
In this function we'll set-up the \l {QSSGRhiGraphicsPipelineState}{pipeline state} for our two renderables and tell QtQuick3D to
prepare the primitives etc. for the renderables by calling QSSGRenderHelpers::prepareRenderables().
\snippet extensions/stenciloutline3d/outlinerenderextension.cpp extension back_prepareRender
When the engine is ready to record the rendering calls for our extension it will call the virtual QSSGRenderExtension::render() function.
In this example we can simply call QSSGRenderHelpers::renderRenderables() for the two models, they will then
be rendered just the same way as QtQuick3D would have done internally, only this time with our settings.
\snippet extensions/stenciloutline3d/outlinerenderextension.cpp extension back_render
The \c OutlineRenderExtension is made active by adding it to the \l {QtQuick3D::View3D}{View3D's}
\l {QtQuick3D::View3D::extensions}{extensions} property.
\snippet extensions/stenciloutline3d/Main.qml 1
Now when a \c model is picked we just need to set the picked \c model as the \c target for the \c OutlineRenderExtension
to have it rendered with an outline.
\snippet extensions/stenciloutline3d/Main.qml 2
*/