QGLSceneNode Class

 foreach (QGLSceneNode *node, scene.allChildren())
     node->setNormalViewEnabled(true);

 int index = d->palette->indexOf(material);
 if (index == -1)
     index = d->palette->addMaterial(material);
 setBackMaterialIndex(index);

 int index = d->palette->indexOf(material);
 if (index == -1)
     index = d->palette->addMaterial(material);
 setMaterialIndex(index);

Member Function Documentation

QGLSceneNode::QGLSceneNode(QObject * parent = 0)

Constructs a new scene node and attaches it to parent. If parent is a QGLSceneNode then this node is added to it as a child.

QGLSceneNode::QGLSceneNode(const QGeometryData & geometry, QObject * parent = 0)

Constructs a new scene node referencing geometry and attaches it to parent. If parent is a QGLSceneNode then this node is added to it as a child.

QGLSceneNode::~QGLSceneNode() [virtual]

Destroys this scene node.

void QGLSceneNode::addNode(QGLSceneNode * node)

Adds the node to the list of child nodes for this node.

This function does nothing if node is null or is already a child of this node. If the node is the node itself, a warning about an attempt to add a node to itself is printed, and no add takes place.

If the aim is to have the same geometry displayed several times under a given node, each time with different transformations, use the clone() call to create copies of the node and then apply the transformations to the copies.

Alternatively, create modifier nodes with the transformations and add the geometry bearing node to each with addNode():

 QGLBuilder builder;
 builder << CarWheel(5.0f); // some car wheel geometry
 QGLSceneNode wheel = builder.finalizedSceneNode();
 QGLSceneNode frontLeft = new QGLSceneNode(m_sceneRoot);
 frontLeft->addNode(wheel);
 frontLeft->setPosition(QVector3D(1.0f, 2.0f, 0.0f));
 QGLSceneNode frontRight = new QGLSceneNode(m_sceneRoot);
 frontRight->addNode(wheel);
 frontRight->setPosition(QVector3D(-1.0f, 2.0f, 0.0f));
 QGLSceneNode backLeft = new QGLSceneNode(m_sceneRoot);
 backLeft->addNode(wheel);
 backLeft->setPosition(QVector3D(1.0f, -2.0f, 0.0f));
 QGLSceneNode backRight = new QGLSceneNode(m_sceneRoot);
 backRight->addNode(wheel);
 backRight->setPosition(QVector3D(-1.0f, -2.0f, 0.0f));

Because a child node can be validly added to many different nodes, calling addNode() does not normally affect the QObject::parent() ownership. However, if node does not currently have a QObject::parent(), the parent will be set to this node.

See also removeNode(), clone(), and addNodes().

void QGLSceneNode::addNodes(const QList<QGLSceneNode *> & nodes)

Adds the members of nodes to the list of child nodes for this node.

See also addNode() and removeNodes().

void QGLSceneNode::addTransform(QQuickQGraphicsTransform3D * transform)

Adds a single transform to this node, to be applied to the node after all current members of transformations() have been applied.

In the mathematical sense, transform is applied to the modelview matrix before the current members of transformations() are applied in reverse order.

See also transforms() and setTransforms().

QList<QGLSceneNode *> QGLSceneNode::allChildren() const

Returns a list including recursively all child nodes under this node. Each child node only appears once, even if it is included multiple times in the scene graph.

See also children().

QGLSceneNode * QGLSceneNode::allExcept(const QString & name, QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry and have all effects, transforms and other properties copied from this node.

The copy returned will have the same child nodes, except all child nodes whose objectName() is equal to name.

See also clone() and only().

QGLSceneNode * QGLSceneNode::allExcept(const QStringList & names, QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry and have all effects, transforms and other properties copied from this node.

The copy returned will have the same child nodes, except all child nodes whose objectName() is in the list of names.

See also clone() and only().

int QGLSceneNode::backMaterialIndex() const

Returns the back material index for this scene node.

See also setBackMaterialIndex().

QBox3D QGLSceneNode::boundingBox() const

Returns a bounding box for the portion of the geometry referenced by this scene node. If the value of start() is 0, and count() is the same as geometry()->size() then the bounding box will be the same as geometry()->boundingBox(). However if the scene node only references some part of the geometry, a bounding box for this section is calculated.

If this scene node has child nodes then the bounding box will be the calculated union of the bounding box for this nodes geometry (if any) and the bounding boxes of the children.

The calculated value is cached and returned on subsequent calls, but could be expensive to calculate initially.

QList<QGLSceneNode *> QGLSceneNode::children() const

Returns a list of the child nodes for this node. This list is not recursively generated, it includes only the nodes which are immediate children of this node.

See also allChildren().

QGLSceneNode * QGLSceneNode::clone(QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry, child nodes, and have all effects, transforms and other properties copied from this node. The only property that is not copied is pickNode().

See also cloneNoChildren().

QGLSceneNode * QGLSceneNode::cloneNoChildren(QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry, and have all effects, transforms and other properties copied from this node. The children() and pickNodes() are not cloned.

See also clone().

QGLSceneNode * QGLSceneNode::cloneWithChildren(QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry, will create clones of all of the child nodes, and have all effects, transforms and other properties copied from this node. The only property that is not copied is pickNode().

See also cloneNoChildren().

int QGLSceneNode::count() const

Returns the count of the vertices to render from geometry() for this scene node. The default is zero, meaning that this node uses all vertices from start() up to the last logical vertex in the underlying geometry().

See also setCount() and start().

void QGLSceneNode::culled() [signal]

Signals that the node was culled due to falling wholly outside the view frustum. This signal can only fire if both QGLSceneNode::CullBoundingBox and QGLSceneNode::ReportCulling options are both set.

void QGLSceneNode::displayed() [signal]

Signals that the node was displayed - or at least its geometry was sent to the GPU for rendering, since the GPU might still clip or occlude the node. This signal can only fire if both QGLSceneNode::CullBoundingBox and QGLSceneNode::ReportCulling options are both set.

void QGLSceneNode::draw(QGLPainter * painter) [virtual]

Draws this scene node and its children on the painter.

In detail this function:

• ensures the effect specified by effect() is current on the painter
• sets the nodes materials onto the painter, if valid materials are present
• moves the model-view to the x, y, z position
• applies any local transforms() that may be set for this node
• calls draw() for all the child nodes
• calls draw(start, count) on this nodes geometry object (if any)
• restores the geometry's original materials if they were changed
• restores the model-view matrix if any local transform was applied

Note that the draw() method does not restore the effect. If the first step above results in a change to the current QGL::Standard effect then it will remain set to that effect. In general any painting method should ensure the effect it requires is current.

The way draw is implemented ensures that this nodes effects, materials and transformations will apply by default to its child nodes. Transformations are cumulative, but effects and materials override those of any parent node.

Note that if the HideNode option is set for this node, neither it nor its children will be drawn.

void QGLSceneNode::drawGeometry(QGLPainter * painter) [virtual protected]

Draws the geometry of the node onto the painter.

This is the function which performs the actual drawing step in the draw function below.

• calls draw(start, count) on this nodes geometry object (if any)

Override this function to perform special processing on this node, after transformation & culling are applied and before sequencing of materials & effects are done; but just before (or after) the actual draw step.

This default implementation simply draws the nodes geometry onto the painter.

Example:

 void MySpecialNode::geometryDraw(QGLPainter *painter)
 {
     // at this point the node has survived culling, the model-view
     // matrix is transformed into this nodes frame of reference,
     // materials & effects have been applied as this node appears
     // in its place in the render sequence

     doMySpecialProcessing();

     // call parent implementation to do actual draw
     QGLSceneNode::geometryDraw(painter);
 }

QGL::DrawingMode QGLSceneNode::drawingMode() const

Returns the drawing mode to use to render geometry(). The default is QGL::Triangles.

See also setDrawingMode().

qreal QGLSceneNode::drawingWidth() const

Returns the drawing width for this node.

Drawing width is used only when drawing lines or points (ie. when the drawing mode is points, lines, line-strips, etc).

See also setDrawingWidth() and drawingMode().

QGL::StandardEffect QGLSceneNode::effect() const

Returns the local effect associated with this node. The default value is QGL::FlatColor. If the value of hasEffect() is false, then this the value of effect() is ignored.

See also setEffect() and hasEffect().

QGLSceneNode * QGLSceneNode::except(const QString & name, QObject * parent = 0)

This function creates a copy of the scenegraph with its root at the current node, with a specific sub-branch specified by name removed from it. The exact node from which to prune is specified by the double-colon separated path described by name.

The function will create a copy of the scenegraph using the cloneWithChildren() method, from which the specified sub-branch shall be removed.

If a parent is specified then the sub-node will have that parent added to it.

The inverse of this function, get(), will return only the sub-branch, leaving the current scengraph intact.

For example, consider the following scenegraph:

      Node 1 - Node 2
     /
 Root
     \
      Node 3 - Node 4

By using the following code:

 QString branch("Root::Node1");
 QGLSceneNode *newGraph = except(branch);

We can create a copy of the scenegraph with the branch pruned, as shown below:

 Root
     \
      Node 3 - Node 4

See also findSceneNode(), clone(), cloneWithChildren(), and get().

QGLSceneNode * QGLSceneNode::except(const QStringList & names, QObject * parent = 0)

Like the previous version of except, this creates a copy of the scenegraph with its root at the current node. However, this version allows users to prune multiple sub-branches using the list of sub-branches specified by the names list.

Thus for the scenegraph:

      Node 1 - Node 2 - Node 3
     /
 Root
     \
      Node 4 - Node 5 - Node 6

The code:

 QString branch1("Root::Node1::Node2");
 QString branch2("Root::Node4::Node5}");
 QStringList branchList;
 branchList << branch1 << branch2;
 QGLSceneNode *newGraph = except(branchList);

Would yield the scenegraph:

      Node 1
     /
 Root
     \
      Node 4

Once again, this copy will be reparented with the parameter parent if it exists.

See also findSceneNode(), clone(), cloneWithChildren(), and get().

QGLSceneNode * QGLSceneNode::findSceneNode(QString & nodePath)

Return a specific scene node based on a unqiue path specified by nodePath. This path contains the names of the nodes in the scene-graph from the root node through to a specific target node.

Individual node names are separated by a double colon "::".

For example, given the following scene graph:

       Item2
      /
 Item1
      \
       Item3 - Item4

We could get the QGLSceneNode for "Item4" using the following function call:

 QString searchPath("Item1::Item3::Item4");
 QGLSceneNode * targetNode = findSceneNode(searchPath);

The function will automatically skip unnamed nodes. For example, consider this scene graph:

                   Item2
                  /
 <unnamed> - Item1
                  \
                   Item3 - <unnamed> - Item4

The function nodePath will return the QGLSceneNode for node "Item4".

 "Item1::Item3::Item4"

This is because the unnamed nodes are skipped. Likewise blank or unnamed nodes in the search path will be ignored, so the following string will give the same result as the previous example:

 "::Item1::Item3::::Item4"

The function assumes that there are no repeated instances of the same name at any given ply of the scenegraph. For example, the following scenegraph is invalid because of the repeat of Sphere1 in the same layer of the graph:

       Sphere1
      /
 Cube1
      \
       Sphere1

The function also assumes that the names of nodes do not contain double colons. For example, a node with the name: "Sphere::1" would result in an invalid graph.

If a third party model contains such names it is still possible to retrieve the nodes by using the variant of findSceneNode() which takes a list of node-names rather than the double-colon separated string in nodePath.

See also findSceneNode().

QGLSceneNode * QGLSceneNode::findSceneNode(QStringList & nodePath)

This functions exactly the same way as the previous findSceneNode function except in this case the nodePath is specified as a QStringList composed of the individual nodes along the path to the target node.

The other findSceneNode function acts by splitting its nodePath into a QStringList wherever a double colon (::) is found and passing the result to this function.

See also findSceneNode().

QGeometryData QGLSceneNode::geometry() const

Returns the geometry associated with this node, or a null QGeometryData if no geometry has been associated with it.

See also setGeometry().

QGLSceneNode * QGLSceneNode::get(const QString & name, QObject * parent = 0, bool forceCopy = false)

This function retrieve a sub-branch of the scenegraph with its root at the current node. The exact node to retrieve is specified by the double-colon separated path described by name.

This node will be located using the method described by findSceneNode() and will be copied using the clone() function.

If a parent is specified then the sub-node will have that parent added to it.

If the user sets the forceCopy parameter to true then the cloneWithChildren() function shall be used instead of the clone() function while copying. This will result in all of the child-nodes being forcibly copied as well resulting in less efficient memory usage, though allowing the modification of the newly created branch without altering the original in any way.

The inverse of this function, except(), can be used to get everything except a specific sub-branch.

See also findSceneNode(), clone(), cloneWithChildren(), get(), and except().

QGLSceneNode * QGLSceneNode::get(const QStringList & names, QObject * parent = 0, bool forceCopy = false)

This function is similar to the previous instance of the get() function. In this case, however, the user can specify multiple node-paths to get.

These nodes will be cloned in an identical way to the single-node instance of get, using the parent and forceCopy parameters in the same way.

The resulting set of branches will then be added to a newly created root node, creating a composite branch. For example, consider the simple scenegraph below:

      Node 1 - Node 2 - Node 3
     /
 Root
     \
      Node 4 - Node 5 - Node 6

If we now call the get() function with the following code.

 QString branch1("Root::Node 1::Node 2");
 QString branch2("Root::Node 4::Node 5");
 QStringList branchList;
 branchList << branch1 << branch2;
 QGLSceneNode *newBranch = get(branchList);

In this case the function will create a new root node for the output, and graft the two branches onto it, as follows:

          Node 2 - Node 3
         /
 New-Root
         \
          Node 5 - Node 6

See also findSceneNode(), clone(), cloneWithChildren(), get(), and except().

bool QGLSceneNode::hasEffect() const

Returns true if the local effect on this node is enabled, otherwise returns false.

See also setEffectEnabled() and setEffect().

QMatrix4x4 QGLSceneNode::localTransform() const

Returns the local transform associated with this node. If no local transform has been explicitly set, this method returns a QMatrix4x4 set to the identity matrix.

The local transform is typically set during model loading or geometry construction, and is a feature of the geometry.

In general to change the location or orientation of the node use the position() or transforms() properties instead.

See also setLocalTransform(), position(), and transforms().

int QGLSceneNode::materialIndex() const

Returns the material index for this scene node.

See also setMaterialIndex().

QGLSceneNode * QGLSceneNode::only(const QString & name, QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry and have all effects, transforms and other properties copied from this node.

The copy returned will have only one child node. This child node will be the first child node of this one which has its objectName() equal to name.

See also clone() and allExcept().

QGLSceneNode * QGLSceneNode::only(const QStringList & names, QObject * parent = 0) const

Creates a new QGLSceneNode that is a copy of this scene node, with parent as the parent of the new copy. If parent is NULL then parent is set to this nodes parent.

The copy will reference the same underlying geometry and have all effects, transforms and other properties copied from this node.

The copy returned will have only the child nodes from this whose objectName() is in the list of names.

See also clone() and allExcept().

QSharedPointer<QGLMaterialCollection> QGLSceneNode::palette() const

Returns the palette of materials used by this scene node, or NULL if no palette has been set.

See also setPalette().

QGLPickNode * QGLSceneNode::pickNode() const

Returns the pick node for this scene node, if one was set; otherwise NULL (0) is returned.

See also setPickNode().

void QGLSceneNode::removeNode(QGLSceneNode * node)

Removes the child node matching node from this node.

If the QObject::parent() ownership of node was set to this node, then its parent will be changed to another parent node if it had multiple parents.

If node had only a single parent, then its parent will be set to null, effectively detaching it from the QObject ownership rules of the scene graph. The caller is then responsible for deleting node.

If the QObject::parent() of node was not a scene node parent, then it will be left unmodified.

See also addNode() and removeNodes().

void QGLSceneNode::removeNodes(const QList<QGLSceneNode *> & nodes)

Removes the members of nodes from the list of child nodes for this node.

See also removeNode() and addNodes().

void QGLSceneNode::setBackMaterialIndex(int material)

Sets the back material index for this scene node to material.

See also backMaterialIndex() and materialIndex().

void QGLSceneNode::setCount(int count)

Sets the count of the vertices to render from geometry() for this scene node.

See also count() and setStart().

void QGLSceneNode::setDrawingMode(QGL::DrawingMode mode)

Sets the drawing mode to use to render geometry().

Note: this function changes the drawing mode, but the underlying geometry() still consists of the triangles that were added. Thus, this function is only useful for converting the drawing mode into QGL::Points to display the geometry() as a point cloud instead of a triangle mesh. The other enums from QGL::DrawingMode will give unpredictable results.

See also drawingMode().

void QGLSceneNode::setDrawingWidth(qreal width)

Sets the drawing width to the given value.

Drawing width is used only when drawing lines or points (ie. when the drawing mode is points, lines, line-strips, etc).

See also drawingWidth() and drawingMode().

void QGLSceneNode::setEffect(QGL::StandardEffect effect)

Sets the local effect associated with this node to be effect. hasEffect() will return true after calling this method.

The QGLSceneNode::draw() function will ensure that effect is applied to the QGLPainter before drawing any geometry.

See also effect() and hasEffect().

void QGLSceneNode::setEffectEnabled(bool enabled)

Sets whether the current value of effect() or userEffect() will be applied to the QGLPainter prior to drawing. If enabled is true, then the effect is applied, otherwise it is not.

See also setEffect(), effect(), and hasEffect().

void QGLSceneNode::setGeometry(QGeometryData geometry)

Sets the geometry associated with this node to be geometry. Typically the geometry will be some type of mesh object. The default implementation of the QGLSceneNode::draw() method will call the geometry's draw() method.

See also geometry().

void QGLSceneNode::setLocalTransform(const QMatrix4x4 & transform)

Sets the local transform associated with this node to be transform. The default implementation of the QGLSceneNode::draw() method will apply this transform to the QGLPainter before drawing any geometry.

See also localTransform().

void QGLSceneNode::setMaterialIndex(int material)

Sets the material index for this scene node to material.

See also materialIndex().

void QGLSceneNode::setOption(QGLSceneNode::Option option, bool value)

Enables or disables option according to value.

See also options() and setOptions().

void QGLSceneNode::setPalette(QSharedPointer<QGLMaterialCollection> palette)

Sets the palette of materials for this scene node to palette.

See also palette().

void QGLSceneNode::setPickNode(QGLPickNode * node)

Sets the pick node for this scene node to node.

See also pickNode().

void QGLSceneNode::setStart(int start)

Sets the start index within geometry() that should be used to render fragments for this scene node.

See also start() and setCount().

void QGLSceneNode::setTransforms(const QList<QQuickQGraphicsTransform3D *> & transforms)

Sets the list of transformations to apply to this node to transforms.

The transformations are applied to the node itself, so a QGraphicsScale3D followed by a QGraphicsTranslation3D will first scale the node in its local co-ordinate system, and then translate the node a new location.

In the mathematical sense, the transformations are applied to the modelview matrix in the reverse order in which they appear in transforms.

The position() is applied after all other transformations have been applied.

See also transforms(), addTransform(), and position().

void QGLSceneNode::setUserEffect(QGLAbstractEffect * effect)

Sets the local effect associated with this node to be the custom effect. hasEffect() will return true after calling this method.

This custom effect will supersede any standard effect.

The default implementation of QGLSceneNode::apply() will set this effect during initialization of the model.

The default implementation of the QGLSceneNode::draw() method will ensure that effect is applied to the QGLPainter before drawing any geometry.

See also userEffect() and hasEffect().

int QGLSceneNode::start() const

Returns the starting index within geometry() that should be used to render fragments for this scene node. The default value is 0, indicating that the 0'th logical vertex in geometry() is the start.

See also setStart() and count().

QList<QQuickQGraphicsTransform3D *> QGLSceneNode::transforms() const

Returns the list of transformations to apply to this node. The default is the empty list.

The transformations are applied to the node itself, so a QGraphicsScale3D followed by a QGraphicsTranslation3D will first scale the node in its local co-ordinate system, and then translate the node a new location.

In the mathematical sense, the transformations are applied to the modelview matrix in the reverse order in which they appear in this list.

The position() is applied after all other transformations have been applied.

See also setTransforms(), addTransform(), and position().

QGLAbstractEffect * QGLSceneNode::userEffect() const

Returns the user effect associated with this node, or NULL if one is not set. The default value is NULL. If the value of hasEffect() is false, then this effect is ignored.

See also setUserEffect() and hasEffect().