#include <qquick3dscenerenderer_p.h>

Inheritance diagram for QQuick3DSGRenderNode:

Collaboration diagram for QQuick3DSGRenderNode:

Public Member Functions
	~QQuick3DSGRenderNode ()

void	prepare () override
	Called from the frame preparation phase.

StateFlags	changedStates () const override
	When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the \l render() function:

void	render (const RenderState *state) override
	This function is called by the renderer and should paint this node with directly invoking commands in the graphics API (OpenGL, Direct3D, etc.) currently in use.

void	releaseResources () override
	This function is called when all custom graphics resources allocated by this node have to be freed immediately.

RenderingFlags	flags () const override

Public Member Functions inherited from QSGRenderNode
	QSGRenderNode ()

	~QSGRenderNode () override
	Destructs the render node.

virtual StateFlags	changedStates () const
	When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the \l render() function:

virtual void	prepare ()
	Called from the frame preparation phase.

virtual void	render (const RenderState *state)=0
	This function is called by the renderer and should paint this node with directly invoking commands in the graphics API (OpenGL, Direct3D, etc.) currently in use.

virtual void	releaseResources ()
	This function is called when all custom graphics resources allocated by this node have to be freed immediately.

virtual RenderingFlags	flags () const

virtual QRectF	rect () const

const QMatrix4x4 *	projectionMatrix () const

const QMatrix4x4 *	matrix () const

const QSGClipNode *	clipList () const

qreal	inheritedOpacity () const

QRhiRenderTarget *	renderTarget () const

QRhiCommandBuffer *	commandBuffer () const

Public Member Functions inherited from QSGNode
	QSGNode ()
	Constructs a new node.

virtual	~QSGNode ()
	Destroys the node.

QSGNode *	parent () const
	Returns the parent node of this node.

void	removeChildNode (QSGNode *node)
	Removes node from this node's list of children.

void	removeAllChildNodes ()
	Removes all child nodes from this node's list of children.

void	prependChildNode (QSGNode *node)
	Prepends node to this node's the list of children.

void	appendChildNode (QSGNode *node)
	Appends node to this node's list of children.

void	insertChildNodeBefore (QSGNode node, QSGNode before)
	Inserts node to this node's list of children before the node specified with before.

void	insertChildNodeAfter (QSGNode node, QSGNode after)
	Inserts node to this node's list of children after the node specified with after.

void	reparentChildNodesTo (QSGNode *newParent)

int	childCount () const
	Returns the number of child nodes.

QSGNode *	childAtIndex (int i) const
	Returns the child at index i.

QSGNode *	firstChild () const
	Returns the first child of this node.

QSGNode *	lastChild () const
	Returns the last child of this node.

QSGNode *	nextSibling () const
	Returns the node after this in the parent's list of children.

QSGNode *	previousSibling () const
	Returns the node before this in the parent's list of children.

NodeType	type () const
	Returns the type of this node.

QT_DEPRECATED void	clearDirty ()

void	markDirty (DirtyState bits)
	Notifies all connected renderers that the node has dirty bits.

QT_DEPRECATED DirtyState	dirtyState () const

virtual bool	isSubtreeBlocked () const
	Returns whether this node and its subtree is available for use.

Flags	flags () const
	Returns the set of flags for this node.

void	setFlag (Flag, bool=true)
	Sets the flag f on this node if enabled is true; otherwise clears the flag.

void	setFlags (Flags, bool=true)
	Sets the flags f on this node if enabled is true; otherwise clears the flags.

virtual void	preprocess ()
	Override this function to do processing on the node before it is rendered.

Public Attributes
QQuickWindow *	window = nullptr

QQuick3DSceneRenderer *	renderer = nullptr

Additional Inherited Members
Public Types inherited from QSGRenderNode
enum	StateFlag { DepthState = 0x01 , StencilState = 0x02 , ScissorState = 0x04 , ColorState = 0x08 , BlendState = 0x10 , CullState = 0x20 , ViewportState = 0x40 , RenderTargetState = 0x80 }
	This enum is a bit mask identifying several states. More...

enum	RenderingFlag { BoundedRectRendering = 0x01 , DepthAwareRendering = 0x02 , OpaqueRendering = 0x04 , NoExternalRendering = 0x08 }
	Possible values for the bitmask returned from flags(). More...

Public Types inherited from QSGNode
enum	NodeType { BasicNodeType , GeometryNodeType , TransformNodeType , ClipNodeType , OpacityNodeType , RootNodeType , RenderNodeType }
	Can be used to figure out the type of node. More...

enum	Flag { OwnedByParent = 0x0001 , UsePreprocess = 0x0002 , OwnsGeometry = 0x00010000 , OwnsMaterial = 0x00020000 , OwnsOpaqueMaterial = 0x00040000 , IsVisitableNode = 0x01000000 }
	The QSGNode::Flag enum describes flags on the QSGNode. More...

enum	DirtyStateBit { DirtySubtreeBlocked = 0x0080 , DirtyMatrix = 0x0100 , DirtyNodeAdded = 0x0400 , DirtyNodeRemoved = 0x0800 , DirtyGeometry = 0x1000 , DirtyMaterial = 0x2000 , DirtyOpacity = 0x4000 , DirtyForceUpdate = 0x8000 , DirtyUsePreprocess = UsePreprocess , DirtyPropagationMask }
	Used in QSGNode::markDirty() to indicate how the scene graph has changed. More...

Protected Member Functions inherited from QSGNode
	QSGNode (NodeType type)
	Constructs a new node with the given node type.

	QSGNode (QSGNodePrivate &dd, NodeType type)
	Constructs a new node with the given node type.

Protected Attributes inherited from QSGNode
QScopedPointer< QSGNodePrivate >	d_ptr

Detailed Description

Definition at line 162 of file qquick3dscenerenderer_p.h.

Constructor & Destructor Documentation

◆ ~QQuick3DSGRenderNode()

QQuick3DSGRenderNode::~QQuick3DSGRenderNode ( )

Definition at line 1341 of file qquick3dscenerenderer.cpp.

References renderer.

Member Function Documentation

◆ changedStates()

QSGRenderNode::StateFlags QQuick3DSGRenderNode::changedStates ( ) const

overridevirtual

When the underlying rendering API is OpenGL, this function should return a mask where each bit represents graphics states changed by the \l render() function:

\value DepthState depth write mask, depth test enabled, depth comparison function \value StencilState stencil write masks, stencil test enabled, stencil operations, stencil comparison functions \value ScissorState scissor enabled, scissor test enabled \value ColorState clear color, color write mask \value BlendState blend enabled, blend function \value CullState front face, cull face enabled \value ViewportState viewport \value RenderTargetState render target

With APIs other than OpenGL, the only relevant values are the ones that correspond to dynamic state changes recorded on the command list/buffer. For example, RSSetViewports, RSSetScissorRects, OMSetBlendState, OMSetDepthStencilState in case of D3D11, or vkCmdSetViewport, vkCmdSetScissor, vkCmdSetBlendConstants, vkCmdSetStencilRef in case of Vulkan, and only when such commands were added to the scenegraph's command list queried via the QSGRendererInterface::CommandList resource enum. States set in pipeline state objects do not need to be reported here. Similarly, draw call related settings (pipeline states, descriptor sets, vertex or index buffer bindings, root signature, descriptor heaps, etc.) are always set again by the scenegraph so render() can freely change them.

Note: RenderTargetState is no longer supported with APIs like Vulkan. This is by nature. render() is invoked while the Qt Quick scenegraph's main command buffer is recording a renderpass, so there is no possibility of changing the target and starting another renderpass (on that command buffer at least). Therefore returning a value with RenderTargetState set is not sensible.

The software backend exposes its QPainter and saves and restores before and after invoking render(). Therefore reporting any changed states from here is not necessary.

The function is called by the renderer so it can reset the states after rendering this node. This makes the implementation of render() simpler since it does not have to query and restore these states.

The default implementation returns 0, meaning no relevant state was changed in render().

Note: This function may be called before render().

Reimplemented from QSGRenderNode.

Definition at line 1272 of file qquick3dscenerenderer.cpp.

References QSGRenderNode::BlendState, QSGRenderNode::ColorState, QSGRenderNode::CullState, QSGRenderNode::DepthState, QSGRenderNode::RenderTargetState, QSGRenderNode::ScissorState, QSGRenderNode::StencilState, and QSGRenderNode::ViewportState.

◆ flags()

QSGRenderNode::RenderingFlags QQuick3DSGRenderNode::flags ( ) const

overridevirtual

Returns: flags describing the behavior of this render node.

The default implementation returns 0.

See also: RenderingFlag, rect()

Reimplemented from QSGRenderNode.

Definition at line 1390 of file qquick3dscenerenderer.cpp.

References QSGRenderNode::NoExternalRendering.

◆ prepare()

void QQuick3DSGRenderNode::prepare ( )

overridevirtual

Called from the frame preparation phase.

There is a call to this function before each invocation of render().

Unlike render(), this function is called before the scenegraph starts recording the render pass for the current frame on the underlying command buffer. This is useful when doing rendering with graphics APIs, such as Vulkan, where copy type of operations will need to be recorded before the render pass.

The default implementation is empty.

Since: 6.0

Reimplemented from QSGRenderNode.

Definition at line 1346 of file qquick3dscenerenderer.cpp.

References QQuick3DSceneRenderer::beginFrame(), dpr(), QRect::height(), QMatrix4x4::mapRect(), QSGRenderNode::matrix(), Q_QUICK3D_PROFILE_END_WITH_ID, Q_QUICK3D_PROFILE_START, Q_TRACE_SCOPE, renderer, QQuick3DSceneRenderer::rhiPrepare(), QQuick3DSceneRenderer::surfaceSize(), viewport(), QRect::width(), and window.

Here is the call graph for this function:

◆ releaseResources()

void QQuick3DSGRenderNode::releaseResources ( )

overridevirtual

This function is called when all custom graphics resources allocated by this node have to be freed immediately.

In case the node does not directly allocate graphics resources (buffers, textures, render targets, fences, etc.) through the graphics API that is in use, there is nothing to do here.

Failing to release all custom resources can lead to incorrect behavior in graphics device loss scenarios on some systems since subsequent reinitialization of the graphics system may fail.

Note: Some scenegraph backends may choose not to call this function. Therefore it is expected that QSGRenderNode implementations perform cleanup both in their destructor and in releaseResources().

Unlike with the destructor, it is expected that render() can reinitialize all resources it needs when called after a call to releaseResources().

With OpenGL, the scenegraph's OpenGL context will be current both when calling the destructor and this function.

Reimplemented from QSGRenderNode.

Definition at line 1386 of file qquick3dscenerenderer.cpp.

◆ render()

void QQuick3DSGRenderNode::render ( const RenderState * state )

overridevirtual

This function is called by the renderer and should paint this node with directly invoking commands in the graphics API (OpenGL, Direct3D, etc.) currently in use.

The effective opacity can be retrieved with \l inheritedOpacity().

The projection matrix is available through state, while the model-view matrix can be fetched with \l matrix(). The combined matrix is then the projection matrix times the model-view matrix. The correct stacking of the items in the scene is ensured by the projection matrix.

When using the provided matrices, the coordinate system for vertex data follows the usual QQuickItem conventions: top-left is (0, 0), bottom-right is the corresponding QQuickItem's width() and height() minus one. For example, assuming a two float (x-y) per vertex coordinate layout, a triangle covering half of the item can be specified as (width - 1, height - 1), (0, 0), (0, height - 1) using counter-clockwise direction.

Note: QSGRenderNode is provided as a means to implement custom 2D or 2.5D Qt Quick items. It is not intended for integrating true 3D content into the Qt Quick scene. That use case is better supported by QQuickFramebufferObject, QQuickWindow::beforeRendering(), or the equivalents of those for APIs other than OpenGL.; QSGRenderNode can perform significantly better than texture-based approaches (such as, QQuickFramebufferObject), especially on systems where the fragment processing power is limited. This is because it avoids rendering to a texture and then drawing a textured quad. Rather, QSGRenderNode allows recording draw calls in line with the scenegraph's other commands, avoiding an additional render target and the potentially expensive texturing and blending.

Clip information is calculated before the function is called. Implementations wishing to take clipping into account can set up scissoring or stencil based on the information in state. The stencil buffer is filled with the necessary clip shapes, but it is up to the implementation to enable stencil testing.

Some scenegraph backends, software in particular, use no scissor or stencil. There the clip region is provided as an ordinary QRegion.

With the legacy, direct OpenGL based renderer, the following states are set on the render thread's context before this function is called:

\list

glColorMask(true, true, true, true)
glDepthMask(false)
glDisable(GL_DEPTH_TEST)
glStencilFunc(GL_EQUAL, state.stencilValue, 0xff); glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP) depending on clip
glScissor(state.scissorRect.x(), state.scissorRect.y(), state.scissorRect.width(), state.scissorRect.height()) depending on clip
glEnable(GL_BLEND)
glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA)
glDisable(GL_CULL_FACE) \endlist

States that are not listed above, but are covered by \l StateFlags, can have arbitrary values.

Note: There is no state set with other graphics APIs, considering that many of them do not have a concept of the traditional OpenGL state machine. Rather, it is up to the implementation to create pipeline state objects with the desired blending, scissor, and stencil tests enabled. Note that this also includes OpenGL via the RHI. New QSGRenderNode implementations are recommended to set all scissor, stencil and blend state explicitly (as shown in the above list), even if they are targeting OpenGL.

\l changedStates() should return which states this function changes. If a state is not covered by \l StateFlags, the state should be set to the default value according to the OpenGL specification. For other APIs, see the documentation for changedStates() for more information.

Note: Depth writes are disabled when this function is called (glDepthMask(false) with OpenGL). Enabling depth writes can lead to unexpected results, depending on the scenegraph backend in use and the content in the scene, so exercise caution with this.

For APIs other than OpenGL, it will likely be necessary to query certain API-specific resources (for example, the graphics device or the command list/buffer to add the commands to). This is done via QSGRendererInterface.

Assume nothing about the pipelines and dynamic states bound on the command list/buffer when this function is called.

With some graphics APIs it can be necessary to reimplement prepare() in addition, or alternatively connect to the QQuickWindow::beforeRendering() signal. These are called/emitted before recording the beginning of a renderpass on the command buffer (vkCmdBeginRenderPass with Vulkan, or starting to encode via MTLRenderCommandEncoder in case of Metal. Recording copy operations cannot be done inside render() with such APIs. Rather, do such operations either in prepare() or the slot connected to beforeRendering (with DirectConnection).