Camera QML Type

Defines a Camera for viewing the content of a 3D scene. More...

Import Statement: import QtQuick3D 1.0
Inherits:

Node

Properties

Methods

Detailed Description

A Camera is always necessary view the content of a 3D scene. A camera defines how to project the content of a 3D scene into a 2D coordinate space which can then be used on a 2D surface. When a camera is present in the scene it can be used to direct what is displayed in a View3D.

To determine the projection of this camera a high level API is provided. First it is possible to position this Camera like any other spatial Node in the scene. This determines where the Camera is in the scene, and what direction it is facing. The default direction of the camera is such that the forward vector is looking up the +Z axis, and the up direction vector is up the +Y axis. With this in mind any transformation applied to the camera as well as the transformations inherited from it's parent Nodes you can define exactly where and in what direction your camera is facing.

The second part of determining the projection of the camera is defining the frustum that defines the what parts of the scenes are visible, as well as how they are visible. The Camera API provides multiple levels of abstraction to determine the shape of the Camera's frustum. By setting the Camera::projectionMode property it is possible to control what type of projection is created and how much control is needed.

The high level API for Camera is used by either selection the Camera::Perspective or Camera::Orthographic projectionModes. This allows for a sensible default for either of the two main projection types.

For finer grain control of how the frustum is defined, there is the Camera::Frustum projectionMode. This allows for setting the Camera::frustumTop, Camera::frustumBottom, Camera::frustomRight, and Camera::frustumLeft properties. This is useful in creating asymetrical frustums.

If you need full-control over how the projection matrix is created there is also the Camera::Custom mode which lets you define the projection matrix directly.

Property Documentation

clipFar : real

This property holds the far value of the camara's view frustum. This value determines what the furthest distance to the camera that items will be shown.


clipNear : real

This property holds the near value of the camara's view frustum. This value determines what the closest distance to the camera that items will be shown.


customProjection : float

This property defines a custom projection matrix. This property should only be used for handling more advanced projections.

Note: This property only has an effect when using Camera.Custom for the Camera::projectionMode property


enableFrustumCulling : bool

When enabled this property determines whether frustum culling is enabled for this camera. What this means is that when the scene is being rendered only items that are within the bounds of the fustum are rendered. For scenes where there are lots of expensive items outside of the view of the camera time will not be spent rendering content that will never be shown. There is however a cost for doing this as the scene has to be iterated on the CPU to determine what is and isn't inside the frustum. If you know that everything in the scene will always be indie the camera frustum, this step is an unnecessary use of resources.

There are also cases with shadowing where shadows can disapear before they are out of view because the item causing the shadow is outside of the camera frustum, but the shadow it is casting still is.


fieldOfView : real

This property holds the field of view of the camera in degrees. This can be either the vertical or horizontal field of view depending on if the isFieldOfViewHorizontal property is set to true or not.


frustumBottom : float

This property defines the bottom plane of the camera view frustum.

Note: This property only has an effect when using Camera.Frustum for the Camera::projectionMode property


frustumLeft : float

This property defines the left plane of the camera view frustum.

Note: This property only has an effect when using Camera.Frustum for the Camera::projectionMode property


frustumRight : float

This property defines the right plane of the camera view frustum.

Note: This property only has an effect when using Camera.Frustum for the Camera::projectionMode property


frustumTop : float

This property defines the top plane of the camera view frustum.

Note: This property only has an effect when using Camera.Frustum for the Camera::projectionMode property


isFieldOfViewHorizontal : bool

This property determines if the field of view property reflects the horizontal field of view. If this value is false then it is assumed field of view is vertical.


projectionMode : enumeration

This property defines the type of projection that will be to render the scene. The most common cases are Camera.Perspective and Camera.Orthographic which will automatically generate a projection matrix.

It also possible to use either Camera.Frustum or Camera.Custom to have finer control over how the projection is defined.

  • Camera.Perspective
  • Camera.Orthographic
  • Camera.Frustum
  • Camera.Custom

Method Documentation

vector3d mapFromViewport(viewportPos)

Transforms viewportPos from viewport space (2D) into global scene space (3D). The x-, and y values of viewportPos needs to be normalized, with the top-left of the viewport being [0,0] and the bottom-right being [1,1]. The z value should be the distance from the near side of the frustum (clipNear) into the scene in scene coordinates. If viewportPos cannot be mapped to a position in the scene, a position of [0, 0, 0] is returned.

Note: the returned position will be in the same orientation as the camera.

See also QQuick3DCamera::mapToViewport() and QQuick3DViewport::mapTo3DScene().


vector3d mapToViewport(scenePos)

Transforms scenePos from global scene space (3D) into viewport space (2D). The returned position is normalized, with the top-left of the viewport being [0,0] and the bottom-right being [1,1]. The returned z value will contain the distance from the near side of the frustum (clipNear) to scenePos in view coordinates. If scenePos cannot be mapped to a position in the viewport, a position of [0, 0, 0] is returned.

Note: scenePos should be in the same orientation as the camera.

See also QQuick3DCamera::mapFromViewport() and QQuick3DViewport::mapFrom3DScene().