View3D QML Type | Qt Quick 3D 5.15.0

- Qt 5.15
- Qt Quick 3D
- QML Types
- View3D QML Type
- Qt Quick 3D | Commercial or GPLv3

# View3D QML Type

Provides a viewport on which to render a 3D scene. More...

Import Statement: | import QtQuick3D 1.15

- List of all members, including inherited members

## Properties

- camera : QtQuick3D::Camera
- environment : QtQuick3D::SceneEnvironment
- importScene : QtQuick3D::Node
- renderMode : enumeration
- renderStats : QtQuick3D::RenderStats
- scene : QtQuick3D::Node

## Methods

- vector3d mapFrom3DScene(scenePos)
- vector3d mapTo3DScene(viewPos)
- PickResult pick(x, float y)

## Detailed Description

View3D provides a 2D surface for 3D content to be rendered to. Before 3D content can be displayed in a Qt Quick scene, it must first be flattend.

There are two ways to define a 3D scene for View3D to view. The first and easiest is to just define a higharchy of Node based items as children of the View3D. This becomes the implicit scene of the viewport.

It is also possible to reference an existing scene by using the importScene property of the scene you want to render. This scene does not have to exist as a child of the current View3D.

There is also a combination approach where you define both a scene with children nodes, as well as define a scene that is being referenced. In this case you can treat the referenced scene as a sibling of the child scene.

This is demonstrated in View3D example

To control how a scene is rendered, it is necessary to define a SceneEnvironment to the environment property.

To project a 3D scene to a 2D viewport, it is necessary to view the scene from a camera. If a scene has more than one camera it is possible to set which camera is used to render the scene to this viewport by setting the camera property.

It is also possible to define where the 3D scene is rendered to using the renderMode property. This can be necessary for performance reasons on certain platforms where it is expensive to render to intermediate offscreen surfaces. There are certain tradeoffs to rendering directly to the window though, so this is not the default.

## Property Documentation

camera : QtQuick3D::Camera

This property specifies which camera is used to render the scene. It is possible for this value to be undefined, in which case the first enabled camera in the scene will be used instead.

If it is desired to not render anything in the scene, then make sure all cameras are disabled.

See also PerspectiveCamera, OrthographicCamera, FrustumCamera, and CustomCamera.

environment : QtQuick3D::SceneEnvironment

This property specifies the SceneEnvironment used to render the scene.

See also SceneEnvironment.

importScene : QtQuick3D::Node

This property defines the reference node of the scene to render to the viewport. The node does not have to be a child of the View3D. This referenced node becomes sibling with possible child nodes of View3D.

Note: This property can only be set once, not removed or changed later.

See also Node.

renderMode : enumeration

This property determines how the scene is rendered to the viewport.

Constant | Description
--- | ---
`View3D.Offscreen` | Scene is rendered to a texture. Comes with no limitations.
`View3D.Underlay` | Scene is rendered directly to the window before Qt Quick is rendered.
`View3D.Overlay` | Scene is rendered directly to the window after Qt Quick is rendered.
`View3D.Inline` | Scene is rendered to the current render target using QSGRenderNode.

The default mode is `View3D.Offscreen` as this is the offers the best compatibility.

renderStats : QtQuick3D::RenderStats

Accessor to RenderStats, which can be used to gain information of fps, frameTime, renderTime, syncTime, and maxFrameTime.

scene : QtQuick3D::Node

Holds the root scene of the View3D.

See also importScene.

## Method Documentation

vector3d mapFrom3DScene(scenePos)

Transforms scenePos from scene space (3D) into view space (2D). The returned x- and y-values will be be in view coordinates. The returned z-value will contain the distance from the near side of the frustum (clipNear) to scenePos in scene coordinates. If the distance is negative, the point is behind the camera. If scenePos cannot be mapped to a position in the scene, a position of [0, 0, 0] is returned. This function requires that a camera is assigned to the view.

See also mapTo3DScene() and Camera.mapToViewport().

vector3d mapTo3DScene(viewPos)

Transforms viewPos from view space (2D) into scene space (3D). The x- and y-values of viewPos should be in view coordinates. The z-value should be the distance from the near side of the frustum (clipNear) into the scene in scene coordinates. If viewPos cannot be mapped to a position in the scene, a position of [0, 0, 0] is returned.

See also mapFrom3DScene() and Camera.mapFromViewport().

PickResult pick(x, float y)

Transforms the screen space coordinates x and y to a ray cast towards that position in scene space. Returns information about the ray hit.