Your first 3D scene

Your sandbox opens a window with the word Ready in it. By the end of this lesson it holds a red cube, lit from above, seen through a perspective camera. That is not much to look at, and it is also every Qt Quick 3D application in miniature: a viewport, a camera, a light, and something to draw.

A viewport is an ordinary QML item

View3D is the bridge between the flat QML item tree you already know and a 3D scene. It sizes and anchors like a Rectangle: give it anchors.fill: parent and it takes the window. Everything 3D lives inside it.

Replace the Text element with a View3D, and add the QtQuick3D import that makes the type available:

import QtQuick
import QtQuick3D

Window {
    id: window
    width: 1280
    // ...
    visible: true
    title: "Qt Quick 3D Foundations"
    color: "#1a1a2e"

    Text {
        anchors.centerIn: parent
        color: "white"
        text: "Ready."
    View3D {
        id: view
        anchors.fill: parent

        environment: SceneEnvironment {
            clearColor: "#1a1a2e"
            backgroundMode: SceneEnvironment.Color
            antialiasingMode: SceneEnvironment.MSAA
            antialiasingQuality: SceneEnvironment.High   // explicit: states the sample count beside the mode it belongs to
        }
    }
}

SceneEnvironment decides what the viewport looks like before anything is drawn in it. backgroundMode: SceneEnvironment.Color fills it with clearColor; the alternative, Transparent, lets 2D content behind the viewport show through, which is not what we want here. MSAA smooths jagged edges by sampling each pixel several times, and is the line that matters: anti-aliasing is off by default. antialiasingQuality is spelled out beside it so you can see what it costs, but High, meaning four samples under MSAA, is already the default.

Build and run. You get a dark blue rectangle. That is correct: a viewport with nothing in it.

A camera to look from, a light to see by

Without a camera there is no point of view, and Qt Quick 3D draws nothing at all. Without a light every surface returns black, which looks identical to drawing nothing and is the source of most of the confusion in anyone’s first week.

Add both, inside the View3D:

            backgroundMode: SceneEnvironment.Color
            antialiasingMode: SceneEnvironment.MSAA
            antialiasingQuality: SceneEnvironment.High   // explicit: states the sample count beside the mode it belongs to
        }

        PerspectiveCamera {
            z: 300
        }

        DirectionalLight {
            color: "#fff5e6"
            eulerRotation.x: -45
        }
    }
}

Qt Quick 3D uses a right-handed coordinate system with Y up, and positive Z coming towards you. So z: 300 puts the camera 300 units in front of the origin, looking back at it. The light needs no position at all: a DirectionalLight is a direction, like the sun, and eulerRotation.x: -45 tilts it down at forty-five degrees. The warm tint is late afternoon.

Run it again. Still a dark blue rectangle, because there is nothing in the scene yet for the camera to see or the light to fall on.

Something to draw

A Model is geometry plus a material. Qt Quick 3D ships a handful of built-in meshes you reference with a # prefix, so you can build a scene before you own a single asset. #Cube is 100 units on a side, centred on the origin.

        DirectionalLight {
            color: "#fff5e6"
            eulerRotation.x: -45
        }

        Model {
            source: "#Cube"
            eulerRotation.y: 30
            materials: PrincipledMaterial {
                baseColor: "#e74c3c"
            }
        }
    }
}

The 30-degree turn is so you see two faces instead of staring flat at one, since a cube face-on is indistinguishable from a square. PrincipledMaterial is physically based: baseColor is the colour it reflects, and everything else about it we leave at its default for now.

If the window is empty

Exercises

1. Move the camera to z: 150 and then z: 600. At which distance does the cube stop looking like a cube and start looking like a flat square?

2. Set backgroundMode: SceneEnvironment.Transparent and give the Window a color: "darkgreen". What shows through, and what does that tell you about where the viewport sits in the QML item tree?

3. Delete the DirectionalLight and run it. Then, instead of putting it back, set the material’s baseColor to "#e74c3c" and add lighting: PrincipledMaterial.NoLighting.

Summary

• View3D puts a 3D scene inside the 2D QML item tree, and anchors like any other item.
• SceneEnvironment owns the background and the anti-aliasing.
• A scene needs a camera and a light before anything is visible. Missing either one renders black, and the two failures look the same.
• Model is geometry plus material; built-in meshes like #Cube are 100 units and need no asset files.
• Y is up, positive Z is towards you.

Next we take this scene apart on purpose. There are exactly five ways to make it render nothing, and knowing them by sight is worth more than any amount of reading.