Back to Qt.io
Contact Us Blog Download Qt
Auf dieser Seite

Model QML Type

Ermöglicht das Laden von 3D-Modelldaten. Mehr...

Import Statement: import QtQuick3D
Inherits:

Node

Inherited By:

XrHandModel

Eigenschaften

Ausführliche Beschreibung

Das Element „Model“ ermöglicht es, ein Mesh zu laden und dessen Schattierung durch Hinzufügen von Materialien zu ändern. Damit ein Modell gerendert werden kann, benötigt es mindestens ein Mesh und ein Material.

Mesh-Format und integrierte Primitive

Das Modell kann statische Meshes aus dem Speicher oder einen der integrierten Primitivtypen laden. Das verwendete Mesh-Format ist ein für die Engine natives Laufzeitformat, doch über das Asset-Import-Tool „Balsam“ werden weitere Formate unterstützt.

Die integrierten Primitive können geladen werden, indem die Eigenschaft „ source “ auf einen der folgenden Werte gesetzt wird: „ #Rectangle, #Sphere, #Cube, #Cylinder or #Cone “.

Model {
    source: "#Sphere"
}

Die folgende Tabelle beschreibt die integrierten Meshes im Detail.

NameBeschreibungAnzahl der Flächen
#ConeEin Kegel mit einer Höhe und einem Durchmesser von 100. Die Grundfläche liegt am Ursprung, und der Kegel zeigt nach oben in y-Richtung.78
#WürfelEin Würfel, dessen Mittelpunkt im Ursprung liegt und dessen Seiten entlang der x-, y- und z-Achse jeweils 100 lang sind.12
#ZylinderEin Zylinder mit einer Höhe und einem Durchmesser von 100, dessen Mittelpunkt im Ursprung liegt und der sich in y-Richtung erstreckt.316
#RechteckEin Rechteck mit den Abmessungen 100 in Breite und Höhe, dessen Mittelpunkt im Ursprung liegt und das in der xy-Ebene liegt.2
#KugelEine Kugel mit den 100 em Durchmesser und dem Ursprung als Mittelpunkt.4900

Benutzerdefinierte Geometrie

Zusätzlich zur Verwendung statischer Meshes können Sie einen „ custom geometry “-Provider implementieren, der dem Modell zur Laufzeit benutzerdefinierte Vertex-Daten bereitstellt. Im Beispiel „Custom Geometry“ finden Sie eine Anleitung zum Erstellen und Verwenden eines benutzerdefinierten Materials für Ihr Modell.

Materialien

Ein Modell kann aus mehreren Teil-Meshes bestehen, von denen jedes ein eigenes Material haben kann. Das Teil-Mesh verwendet ein Material aus der Liste „ materials “, das seinem Index entspricht. Wenn die Anzahl der Materialien geringer ist als die der Teil-Meshes, wird das letzte Material in der Liste für nachfolgende Teil-Meshes verwendet. Dies wird im Beispiel „Sub-mesh“ veranschaulicht.

Sie können die folgenden Materialien mit dem Modellelement verwenden: „ PrincipledMaterial “, „ DefaultMaterial “ und „ CustomMaterial “.

Picking

Unter „Picking“ versteht man den Vorgang, bei dem ein Strahl von einer Startposition aus durch die Szene gesendet wird, um zu ermitteln, welche Modelle den Strahl schneiden. In „ Qt Quick 3D “ wird der Strahl normalerweise von der Ansicht aus anhand von 2D-Koordinaten gesendet, die aus einem Touch- oder Mausereignis resultieren. Wurde ein Modell vom Strahl getroffen, wird „ pickResult “ mit einem Handle zum Modell und Informationen darüber zurückgegeben, an welcher Stelle der Strahl das Modell getroffen hat. Bei Modellen, die „ custom geometry “ verwenden, ist die Auswahl weniger genau als bei statischen Mesh-Daten, da die Auswahl nur anhand der „ bounding volume “ des Modells erfolgt. Durchdringt der Strahl mehr als ein Modell, wird das nächstgelegene „ pickable “-Modell ausgewählt.

Beachten Sie, dass Modelle, die „ pickable “ sein sollen, die Eigenschaft „ pickable “ auf „ true “ gesetzt haben müssen. Weitere Informationen finden Sie unter Qt Quick 3D – Beispiel zur Auswahl.

Dokumentation zu den Eigenschaften

bakedLightmap : BakedLightmap

Wenn diese Eigenschaft auf ein gültiges, aktiviertes „ BakedLightmap “-Objekt gesetzt wird, wird beim Baking der Beleuchtung eine Lightmap für das Modell generiert, die anschließend dauerhaft gespeichert wird. Beim Rendern lädt das Modell die zugehörige Lightmap und verwendet sie. Der Standardwert ist null.

Hinweis: Wenn eine dauerhaft gespeicherte Lightmap für ein Modell generiert werden soll, müssen sowohl „bakedLightmap“ als auch „ usedInBakedLighting “ für das Modell gesetzt werden, um anzugeben, dass das Modell nicht nur Teil der Lightmap-Szene ist, sondern auch möchte, dass eine vollständige Lightmap gebacken und gespeichert wird.

Weitere Informationen zum Baken von Lightmaps finden Sie in der Dokumentation zu „ Lightmapper “.

Diese Eigenschaft ist sowohl beim Erstellen als auch bei der Verwendung von Lightmaps relevant. Ein konsistenter Zustand zwischen dem Erstellungsvorgang und den nachfolgenden Durchläufen, die die generierten Daten verwenden, ist unerlässlich. Wenn Sie beispielsweise den Lightmap-Schlüssel ändern, können die zuvor generierten Daten nicht mehr geladen werden. Eine Ausnahme bildet „ enabled “, mit dem sich die Verwendung von Lightmaps (außerhalb des Baking-Laufs) dynamisch umschalten lässt; beachten Sie jedoch, dass die gerenderten Ergebnisse von den Einstellungen unter „ bakeMode “ der Lichter in der Szene abhängen.

Siehe auch „ usedInBakedLighting “ und „ Lightmapper “.

bounds : Bounds [read-only]

Die Begrenzungen des Modells beschreiben die Ausdehnung des umgebenden Begrenzungsvolumens.

Hinweis: Die Begrenzungen sind möglicherweise nicht sofort verfügbar, wenn das Modell erst geladen werden muss.

castsReflections : bool [since 6.4]

Wenn diese Eigenschaft auf „ true “ gesetzt ist, wird das Modell durch Reflexionssonden gerendert und ist in den Reflexionen zu sehen.

Diese Eigenschaft wurde in Qt 6.4 eingeführt.

castsShadows : bool

Wenn diese Eigenschaft auf „ true “ gesetzt ist, wird die Geometrie dieses Modells beim Rendern in die Schattenkarten verwendet und erzeugt auch Schatten bei der „Baked Lighting“-Methode.

Der Standardwert ist „ true “.

depthBias : real

Speichert den Tiefen-Offset des Modells. Der Tiefen-Offset wird beim Sortieren von Objekten zur Entfernung des Objekts von der Kamera addiert. Dies kann verwendet werden, um die Darstellungsreihenfolge zwischen Objekten zu erzwingen, die nahe beieinander liegen und andernfalls in verschiedenen Frames in unterschiedlicher Reihenfolge dargestellt würden. Negative Werte bewirken, dass sich der Sortierwert näher an die Kamera bewegt, während positive Werte ihn weiter von der Kamera entfernen.

geometry : Geometry

Legen Sie eine benutzerdefinierte Geometrie für das Modell fest. Die „ Model::source “ muss leer sein, wenn eine benutzerdefinierte Geometrie verwendet wird.

instanceRoot : QtQuick3D::Node

Diese Eigenschaft definiert den Ursprung des Koordinatensystems der Instanz.

Eine ausführliche Erläuterung finden Sie in der Übersichtsdokumentation.

Siehe auch instancing und Instancing.

instancing : QtQuick3D::Instancing

Wenn diese Eigenschaft gesetzt ist, wird das Modell nicht wie üblich gerendert. Stattdessen werden mehrere Instanzen des Modells gerendert, wie in der Instanztabelle definiert.

Siehe auch „ Instancing “.

instancingLodFactor : real [default: 0.0, since 6.12]

Diese Eigenschaft ermöglicht die manuelle Festlegung des Detaillierungsgrades (LOD) für bestimmte Ebenen von instanzierten Modellen.

In Fällen, in denen eine Szene mehrere LOD-Stufen für große Instanztabellen enthält, ist es erforderlich, die am besten geeignete Detailstufe manuell auszuwählen. Dies ist notwendig, da die automatische LOD-Verwaltung die Detailstufe für einzelne Instanzen nicht korrekt berechnen kann, da deren Transformationsdaten erst während der GPU-Rendering-Phase verfügbar werden.

Um den Geometrie-Overhead auf bestimmten LOD-Stufen zu reduzieren, können Sie „ instancingLodFactor “ manuell festlegen. Je näher der Wert an „ 1.0 “ liegt, desto weniger Geometrie wird für das Objekt gerendert. Ein Wert von „ 0.0 “ bedeutet, dass die gesamte Geometrie mit voller Detailgenauigkeit ausgelagert bzw. gerendert wird.

Hinweis: Diese Eigenschaft wird speziell verwendet, um die automatische LOD-Berechnung zu überschreiben, wenn die Entfernung einzelner Instanzen zur Kamera nicht vorab festgelegt ist.

Diese Eigenschaft wurde in Qt 6.12 eingeführt.

Siehe auch levelOfDetailBias.

instancingLodMax : real

Legt die maximale Entfernung von der Kamera fest, in der eine Instanz dieses Modells angezeigt wird. Wird für die Implementierung der Detailstufe verwendet.

instancingLodMin : real

Legt den Mindestabstand zur Kamera fest, ab dem eine Instanz dieses Modells angezeigt wird. Wird für die Umsetzung der Detailstufe verwendet.

inverseBindPoses : List<matrix4x4>

Diese Eigenschaft enthält eine Liste von „Inverse Bind Pose“-Matrizen, die für die Skelettanimation verwendet werden. Jede „inverseBindPose“-Matrix entspricht der Umkehrung der globalen Transformation des jeweiligen „ Joint::index “ in „ skeleton “, die zunächst verwendet wird.

Hinweis: Diese Eigenschaft wird nur verwendet, wenn die „ Model::skeleton “ gültig ist.

Hinweis: Wenn einige der Matrizen nicht festgelegt sind, werden Identitätswerte verwendet.

Siehe auch „ Joint::index “.

levelOfDetailBias : real [since 6.5]

Diese Eigenschaft legt fest, welche Größe das Modell beim Rendern haben muss, bevor die automatischen Detailebenen-Meshes verwendet werden. Jedes generierte Detailebenen-Mesh enthält einen Wert für die ideale Größe, in der die jeweilige Ebene dargestellt werden soll; dieser Wert gibt an, zu welchem Anteil das Mesh die gerenderte Szene ausmacht. Ein Modell, das auf dem Bildschirm nur wenige Pixel einnimmt, benötigt nicht die vollständige Geometrie, um korrekt dargestellt zu werden; daher wird in diesem Fall stattdessen ein Mesh mit geringerer Detailstufe verwendet. Dieser Wert dient als Abweichung vom Idealwert, sodass ein Wert kleiner als 1.0 eine noch kleinere gerenderte Größe erfordert, bevor auf eine geringere Detailstufe umgeschaltet wird. Werte über „ 1.0 “ führen dazu, dass niedrigere Detailstufen früher verwendet werden. Ein Wert von „ 0.0 “ deaktiviert die Verwendung von Detailstufen vollständig.

Der Standardwert lautet 1.0

Hinweis: Diese Eigenschaft wirkt sich nur aus, wenn die Geometrie des Modells Detailstufen enthält.

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

Siehe auch Camera::levelOfDetailBias.

materials : List<QtQuick3D::Material>

Diese Eigenschaft enthält eine Liste der Materialien, die zum Rendern der bereitgestellten Geometrie verwendet werden. Um etwas rendern zu können, muss mindestens ein Material vorhanden sein. Normalerweise sollte es für jedes in der Quellgeometrie enthaltene Teilnetz ein Material geben.

Siehe auch Qt Quick 3D – Beispiel für Teilnetze.

morphTargets : List<QtQuick3D::MorphTarget>

Diese Eigenschaft enthält eine Liste von „ MorphTarget“, die zum Rendern der bereitgestellten Geometrie verwendet werden. Meshes sollten mindestens ein Attribut aus den Kategorien „Positionen“, „Normalen“, „Tangenten“, „Binormalen“, „Texturkoordinaten“ und „Vertexfarben“ für die Morph-Ziele aufweisen.

Siehe auch „ MorphTarget “.

motionVectorEnabled : bool [default: true, since 6.11]

Legt fest, ob das Modell am Bewegungsvektor-Durchlauf teilnimmt.

Wenn diese Eigenschaft auf „ true “ gesetzt ist, trägt das Modell seine Bewegungsinformationen zum Bewegungsvektor-Puffer bei. Dies wird von Temporal Anti-Aliasing (TAA) und anderen Effekten genutzt, die auf pixelgenauen Bewegungsdaten basieren.

Bei der Einstellung „ false “ wird das Modell von der Erzeugung von Bewegungsvektoren ausgeschlossen.

Diese Eigenschaft wurde in Qt 6.11 eingeführt.

Siehe auch „ Model::motionVectorScale “.

motionVectorScale : real [default: 1.0, since 6.11]

Legt einen Skalierungsfaktor fest, der auf die vom Modell generierten Bewegungsvektoren angewendet wird.

Ein Wert von 1.0 bewahrt die tatsächliche Bewegung des Modells bei, während Werte größer als 1.0 die Bewegungsvektoren übertreiben und Werte kleiner als 1.0 sie reduzieren. Dies kann für stilisierte Effekte oder zur Feinabstimmung des visuellen Verhaltens bei Effekten nützlich sein, die auf dem Bewegungsvektor-Puffer basieren.

Diese Eigenschaft wurde in Qt 6.11 eingeführt.

Siehe auch Model::motionVectorEnabled.

pickable : bool

Diese Eigenschaft legt fest, ob das Modell ausgewählt werden kann oder nicht. Setzen Sie diese Eigenschaft auf „ true “, um das Modell auswählbar zu machen. Standardmäßig sind Modelle nicht auswählbar.

Siehe auch „ View3D::pick “.

receivesReflections : bool

Wenn diese Eigenschaft auf „ true “ gesetzt ist, beziehen die Materialien des Modells den Reflexionsanteil aus einer Reflexionssonde. Befindet sich das Modell gleichzeitig in mehr als einer Reflexionssonde, wird die nächstgelegene Reflexionssonde berücksichtigt.

receivesShadows : bool

Wenn diese Eigenschaft auf „ true “ gesetzt ist, berücksichtigen die Materialien des Modells den Schattenbeitrag von schattenwerfenden Lichtquellen.

Hinweis: Wenn für dieses Modell das Lightmapping aktiviert ist, erzeugen vollständig gebackene Lichtquellen, bei denen „ Light::bakeMode “ auf „Light.BakeModeAll“ gesetzt ist, immer (gebackene) Schatten auf dem Modell, unabhängig vom Wert dieser Eigenschaft.

Der Standardwert ist „ true “.

skeleton : Skeleton

Enthält das Skelett für das Modell. Das Skelett wird zusammen mit „ inverseBindPoses “ für das Skinning verwendet.

Hinweis: Die Meshes des Modells müssen sowohl Gelenk- als auch Gewichtsattribute aufweisen.

Hinweis: Wenn diese Eigenschaft gesetzt ist, ist die Skinning-Animation aktiviert. Das bedeutet, dass „ Model “ basierend auf „ Skeleton “ transformiert wird, wobei die globale Transformation des Modells ignoriert wird.

Siehe auch „ Model::inverseBindPoses “ und „Qt Quick 3D – Einfaches Skinning-Beispiel“.

skin : Skin

Enthält das Skelett des Modells. Das Skelett wird für das Skinning verwendet.

Hinweis: Die Meshes des Modells müssen sowohl Gelenk- als auch Gewichtsattribute aufweisen.

Hinweis: Wenn diese Eigenschaft gesetzt ist, ist die Skinning-Animation aktiviert. Das bedeutet, dass das „ Model “ basierend auf „ Skin::joints “ transformiert wird und die globale Transformation des Modells ignoriert wird.

Hinweis: Verfügt ein Modell sowohl über ein Skelett als auch über eine Skin, wird die Skin verwendet.

Siehe auch Qt Quick 3D - Simple Skinning Example.

source : url

Diese Eigenschaft definiert den Speicherort der Mesh-Datei, die die Geometrie dieses Modells oder eines der unten aufgeführten integrierten Primitiv-Meshes enthält, wie unter Mesh format and built-in primitives beschrieben.

  • „#Rectangle“
  • „#Sphere“
  • „#Cube“
  • „#Cone“
  • „#Cylinder“

texelsPerUnit : real [default: 0.0, since 6.10]

Ein Wert größer als Null bedeutet, dass dieser Wert beim Lightmap-Baking den Wert „ Lightmapper::texelsPerUnit “ für dieses spezifische Modell überschreibt.

Diese Eigenschaft wurde in Qt 6.10 eingeführt.

Siehe auch „ Lightmapper::texelsPerUnit “.

usedInBakedLighting : bool

Wenn diese Eigenschaft auf „ true “ gesetzt ist, trägt das Modell zur gebackenen Beleuchtung bei, wie z. B. bei Lightmaps, beispielsweise in Form von Schattenwurf oder indirektem Licht. Diese Einstellung ist unabhängig von der Steuerung der Lightmap-Erzeugung für das Modell; verwenden Sie hierfür „ bakedLightmap “.

Der Standardwert ist „ false “.

Hinweis: Der Standardwert ist „false“, da Designer und Entwickler stets für jedes Modell einzeln prüfen müssen, ob das Objekt für die Teilnahme an der „Baked Lighting“ geeignet ist.

Warnung: Modelle mit sich dynamisch ändernden Eigenschaften, zum Beispiel animierte Position, Rotation oder andere Eigenschaften, sind nicht für die Teilnahme an der „Baked Lighting“-Funktion geeignet.

Weitere Informationen zum Baken von Lightmaps finden Sie in der Dokumentation zu „ Lightmapper “.

Diese Eigenschaft ist nur beim Baken von Lightmaps relevant. Sie hat danach keine Auswirkung mehr, wenn die generierten Lightmaps beim Rendern verwendet werden.

Siehe auch „ Light::bakeMode“ , „ bakedLightmap “, „ Lightmapper “ sowie „Lightmaps and Global Illumination“.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.