|
|
              
Item3DThe Item3D item encapsulates 3D objects and contains all of the properties and methods needed for simple 3D operations. part of a QML/3d script. More... Inherits Item Inherited by Cube, Line, Point, Quad, SphereMesh, and Teapot. This type was introduced in Qt 4.8. Properties
Signals
Detailed DescriptionSimple 3D Object DefinitionThe most basic use case for the Item3D class is the creation and display of a single simple item in the 3D environment. Many such items within a 3D environment are defined as a single logical component mesh which is treated as a stand-alone object for the purposes of rotation, scaling, and user interaction via "picking". Such an object can easily be defined in QML using the following code: Item3D {
id: teapot
mesh: Mesh { source: "teapot.bez" }
effect: Effect {}
cullFaces: "CullBackFaces"
}
This simple code will create a 3D item based on the teapot.bez mesh using back-face culling. Notice that in this case the effect and mesh are defined within the body of the item definition. Where there is little complexity, this method of defining items simplifies the resultant code and makes modification of the QML easier. Embedding Item3D ObjectsConsider the following: Item3D {
id: cup
mesh: Mesh { source: "teacup.bez" }
effect: Effect {}
cullFaces: "CullBackFaces"
Item3D {
id: saucer
mesh: Mesh { source: "saucer.bez" }
cullFaces: "CullBackFaces"
}
position: Qt.vector3d(10, -10, -10)
}
This demonstrates the capability of embedding one Item3D within another. In this case the saucer item is a child of the cup item. All transformations applied to the parent item are also applied to the child, so in this case both the cup and saucer will be translated based on the position vector defined in the cup item's definition. In this case any additional transformations applied to the child item will not affect the parent, and are local only to that item (and to its children if any exist). This allows a user to group together items logically so that transformations and user interactions can be applied to groups of objects as if they were a whole. Using Sub-nodes of 3D ObjectsIn more complex applications the user may wish to load a complex mesh which is made up of a number of components or nodes which may be organised into a tree like structure. In this case they may wish to interact with, animate, or otherwise modify individual sub-nodes of a mesh. Item3D leverages the existing Qt Object Model in order to allow QML/3d users this type of control over their 3D items. Consider the following QML script: Item3D {
id: helicoptor
mesh: helicoptorMesh
effect: Effect {}
cullFaces: "CullBackFaces"
transform: [
Rotation3D {
id: rotate1
angle: 5
axis: Qt.vector3d(1, 0, 0)
},
Rotation3D {
id: rotate2
angle: 5
axis: Qt.vector3d(0, 1, 0)
},
Rotation3D {
id: rotate3
angle: 45
axis: Qt.vector3d(0, 0, 1)
}
]
Item3D {
id: rotor
property bool spin: false
meshNode: "rotorBladesNode"
Item3D {meshNode: "rotorHubNode"}
transform: [
Rotation3D {
id: rotateBlades
angle: 0
axis: Qt.vector3d(0, 0, 1)
}
]
onClicked: { rotor.spin=true }
SequentialAnimation {
running: rotor.spin
NumberAnimation {
target: rotateBlades
property: "angle"
to: 360.0
duration: 750
easing.type:"OutQuad"
}
onCompleted: rotor.spin = false
}
}
}
Mesh {
id: helicoptorMesh
source: "bellUH1.3ds"
}
Obviously this example is much more complex both in structure and behaviour. In this case the mesh describes a .3ds file of a helicoptor, which is broken down discrete sub-components (engine nacelles, rotor, rotor hub, etc), which the user may wish to modify or animate individually. Each child item in this case does not have a mesh explicitly defined, but rather inherits the mesh from the parent. However each child item does define a mesh node which is part of the parent mesh. All transformations carried out on the parent item will also be applied to the child. Child items can, as shown here, have their own local transformations and user interactions applied. These will be applied only to the node of the mesh which is defined for that item. In cases where the mesh is defined heirarchically as a tree of nodes, this transformation will therefore be applied to all items in that tree which are children of the defined node. Likewise if the user explicitly declares a child item, such as has been done here with the rotorHubNode, then the transformations will apply to this item as well (and its children, and so on). It should be noted that no support is currently provided for skeleton animation or kinematic control of items. This is left to the user to implement as required. Using QML Data Models With Item3DQQuickItem3D supports standard QML Data Models with a few caveats. QQuickItem3D derives from QQuickItem, and interacts with the Component element normally. However, there is a delay between between removing an item from a model and the cleaning up the corresponding Item3D, so it is recommended that Item3D based delegates hide themselves when their index is -1 as shown in the photoroom example: However Item3D does not use the width or height properties, so most positioners and views will not work. Use a Repeater element to generate Item3Ds from model data. For example: Models can be used normally, so ListModel, QStringList etc. work just like they would with two dimensional Items. For example: See also QML Data Models. Property DocumentationThe children property contains a list of all QQuickItem derived child items for this item. This provides logical grouping of items in a scene. Transformations that are applied to this item will also affect child items. Note that children that are not derived from QQuickItem3D will not be rendered at draw time, but will interact normally otherwise (e.g. parenting, signal passing etc). Use a qobject_cast if you need to check whether a child is an Item3D. The resources property holds all other children that do not directly inherit from QQuickItem, such as effects, meshes, and other supporting objects. Normally it isn't necessary to assign to the children or resources properties directly as the QML syntax will take care of the assignment depending upon the object's type. See also transform. This property defines the culling method to be use on fragments within the item's mesh. Culling of an item in 3D space can be carried out in a number of ways:
This property exists to allow future expansion of the Item3D class to include additional data and resources. Currently there is no underlying implementation for this. QML 3D items support the use of effects for modifying the display of items - texture effects, fog effects, material effects, and so on. The exact effects correlated with an item are set using this property. The default value for this propertly is null, and so an effect - even an empty one - must be defined if the mesh does not contain its own effects. This property should be set to true to enable the drawing of this item and its children. Set this property to false to disable drawing. The default value is true. See also mesh. Users are able to interact with 3d items in a scene through (for example) the use of the mouse. These, and other, Qt events can be captured by an Item3D using the same underlying QObject architecture shared by all of Qt. Often a user will only want an item to capture mouse events for itself, leaving child items to handle their mouse events locally. Under many circumstances, however, it is necessary for a parent object to collect all mouse events for itself and its child items. Usually this inheritance of events is only defined at initialisation for an Item3D The inheritEvents property, however, is a simple boolean property which provides a mechanism for both initialisation time and programmatic modification of this. Setting the property to true connects the signals for all child items to the appropriate signals for the item itself. Conversely setting the property to false disconnects the events. The default value for this property is false. This property defines an item-specific light that will be used intead of Viewport::light for rendering this item and its children if the value is not null. See also Viewport::light. Objects in most 3D environments are almost invariably defined as meshes - sets of vertices which when linked as polygons form a recognisable 3D object. Qt3D currently supports a number of these scene formats, including .obj file, bezier patches (.bez), and .3ds files. These meshes are abstracted into the Mesh class, which is defined for an Item3D through this property. The default value for this property is null, so a mesh must be defined in order for the item to be displayed See also effect. The transformations to apply before all others. When a model is loaded from an external source such as a 3D modeling package, it is usually in an unconventional orientation and position. The first step is to rotate, scale, and translate it to make it suitable for use as a QML object. The purpose of the pretransform property is to perform such "model correction" transformations before scale, transform, and position are applied to place the model in its final orientation and position in the QML application. By default this list of transformations is empty. The scaling factor to apply to the item after the transformations from the Item3D::transform property. The default value for this property is 1. See also transform. This property defines the sorting mode to apply to child Item3D elements when they are drawn.
Generally objects in 3D space will have undergone some number of 3D transformation prior to display. Examples of such transformations include rotations about the x, y, and z axes, translation, and so on. Each Item3D maintains a list of transforms to apply to it through this property. In scripting terms a transform can be applied as follows: Item3D {
id: teapot
mesh: Mesh { source: "teapot.bez" }
transform: [
Rotation3D {
id: teapot_rotate1
angle: 0
axis: Qt.vector3d(0, 1, 0)
},
Rotation3D {
id: teapot_rotate2
angle: 0
axis: Qt.vector3d(0, 0, 1)
}
]
}
In this example we have two transformations in our list - a rotation around the y axis (teapot_rotate1), and a rotation about the z axis (teapot_rotate2). These transformations can be accessed via standard QML scripting methods to achieve animations and other effects. By default this list of transformations is empty. See also Rotation3D, Scale3D, Translation3D, scale, position, and pretransform. Signal DocumentationThis signal is emitted when the item is clicked. Picking must be enabled for this to have any effect. This signal is emitted when the item is double clicked. Picking must be enabled for this to have any effect. This signal is emitted when a mouseover of the item is detected. It relies on object picking to be of use. This signal is emitted when the mouseover of the item ceases. It relies on object picking to be used. This signal is emitted when the item detects a mouse-button-down event. Picking must be enabled for this to have any effect. This signal is emitted when the item detects a mouse-button-released event. Picking must be enabled for this to have any effect. |
