--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title QML Scene Graph
+\page qmlscenegraph.html
+
+Qt Quick 2 makes use of a dedicated scene graph based on OpenGL ES 2.0
+or OpenGL 2.0 for its rendering. Using a scene graph for graphics
+rather than the traditional imperative painting systems (QPainter and
+similar), means the scene to be rendered can be retained between
+frames and the complete set of primitives to render is known before
+rendering starts. This opens up for a number of optimizations, such as
+batch rendering to minimize state changes and discarding obscured primitives.
+
+The scene graph is closely tied to QML and can not be used as
+stand-alone. The scene graph is managed and rendered by the
+QQuickCanvas class and custom QML elements will add their graphical
+primitives into the scene graph through a call to
+QQuickItem::updatePaintNode().
+
+The QML scene graph is a graphical representation of the QML scene. It
+can be thought of as a graphical deep copy, an independent structure that
+contains enough information to render the QML Scene. Once it has been set
+up, it can be manipulated and rendered independently of the state of
+the QML scene. On some platforms, the scene graph will even be
+rendered on a dedicated render thread.
+
+
+
+\section1 Scene Graph Nodes
+
+The scene graph can only contain a predefined set of node types, each
+serving a dedicated purpose.
+
+\list
+
+\li QSGGeometryNode - for all rendered content in the scene
+graph. In most cases, it will be enough for a custom QQuickItem object to
+simply return a single QSGGeometryNode object from the
+QQuickItem::updatePaintNode() call.
+
+\li QSGTransformNode - implements transformations in the scene
+graph. Nested transforms are multiplied together.
+
+\li QSGOpacityNode - for node opacity changes. Nested opacity nodes have
+cumulative effect.
+
+\li QSGClipNode - implements clipping in the scene graph. Nested clips
+are intersected.
+
+\li QSGNode - base class for all nodes in the scene graph. Its primary purpose
+is provide the ability to insert nodes into the scene graph that do not affect
+the rendering, such as the shared root for a subtree of geometry nodes.
+
+\endlist
+
+
+
+\section1 Rendering
+
+The rendering of the scene graph happens internally in the
+QQuickCanvas class and is described under the \l{Scene Graph and
+Rendering} section.
+
+How to integrate QPainter based graphics is explained in \l{Custom
+Items using QPainter}.
+
+
+
+\section1 Scene Graph Backend
+
+In addition to the public API, the scene graph has an adaptation layer
+which opens up the implementation to do hardware specific
+adaptations. This is an undocumented, internal and private plugin API,
+which lets hardware adaptation teams make the most of their hardware.
+It includes:
+
+\list
+
+\li Custom textures; specifically the implementation of
+QQuickCanvas::createTextureFromImage and the internal representation
+of the texture used by \l Image and \l BorderImage elements.
+
+\li Custom renderer; the adaptation layer lets the plugin decide how
+the scene graph is traversed and rendered, making it possible to
+optimize the rendering algorithm for a specific hardware or to make
+use of extensions which improve performance.
+
+\li Custom scene graph implementation of many of the default QML
+elements, including its text and font rendering.
+
+\li Custom animation driver; allows the animation system to hook
+into the low-level display vertical refresh to get smooth rendering.
+
+\li Custom render loop; allows better control over how QML deals
+with multiple windows.
+
+\endlist
+
+*/
\li \l{UI Creation with Qt Quick}
\endlist
+\section1 QML Scene Graph
+
+Qt Quick features a high-performance rendering scene graph based on OpenGL.
+The scene graph offers a C++ API which allows developers to create their own unique
+and stunning graphical elements.
+
+ \list
+ \li \l{QML Scene Graph}
+ \endlist
+
\section1 QML Engine
There is a QML engine which runs QML applications. It includes C++ classes
that loads and initializes QML code and a JavaScript engine for running
/*!
\class QQuickCanvas
\since QtQuick 2.0
+
+ \inmodule QtQuick
+
\brief The QQuickCanvas class provides the canvas for displaying a graphical QML scene
QQuickCanvas provides the graphical scene management needed to interact with and display
The rendering of each frame is broken down into the following
steps, in the given order:
- \list
+ \list 1
\li The QQuickCanvas::beforeSynchronizing() signal is emitted.
Applications can make direct connections (Qt::DirectConnection)
to this signal to do any preparation required before calls to
QQuickItem::updatePaintNode().
- \li Synchronzation of the QML state into the scene graph. This is
+ \li Synchronization of the QML state into the scene graph. This is
done by calling the QQuickItem::updatePaintNode() function on all
items that have changed since the previous frame. When a dedicated
rendering thread is used, the GUI thread is blocked during this
/*!
\class QQuickItem
- \brief Provides the most basic of all visual items in QML
+ \brief The QQuickItem class provides the most basic of all visual items in QML
\inmodule QtQuick
if (state & rebuildBits)
m_rebuild_lists = true;
-
- if (state & (rebuildBits | QSGNode::DirtyClipList))
- m_needs_sorting = true;
}
void QSGDefaultRenderer::render()
/*!
+ \class QSGGeometry::Attribute
+ \brief The QSGGeometry::Attribute describes a single vertex attribute in a QSGGeometry
+ \inmodule QtQuick
+
+ The QSGGeometry::Attribute struct describes the attribute register position,
+ the size of the attribute tuple and the attribute type.
+
+ It also contains a hint to the renderer if this attribute is the attribute
+ describing the position. The scene graph renderer may use this information
+ to perform optimizations.
+
+ It contains a number of bits which are reserved for future use.
+
+ \sa QSGGeometry
+ */
+
+/*!
+ \fn QSGGeometry::Attribute QSGGeometry::Attribute::create(int pos, int tupleSize, int primitiveType, bool isPosition)
+
+ Creates a new QSGGeometry::Attribute for attribute register \a pos with \a
+ tupleSize. The \a primitiveType can be any of the supported OpenGL types,
+ such as \c GL_FLOAT or \c GL_UNSIGNED_BYTE.
+
+ If the attribute describes the position for the vertex, the \a isPosition hint
+ should be set to \c true. The scene graph renderer may use this information
+ to perform optimizations.
+
+ Use the create function to construct the attribute, rather than an
+ initialization list, to ensure that all fields are initialized.
+ */
+
+
+/*!
+ \class QSGGeometry::AttributeSet
+ \brief The QSGGeometry::AttributeSet describes how the vertices in a QSGGeometry
+ are built up.
+ \inmodule QtQuick
+
+ \sa QSGGeometry
+ */
+
+
+/*!
+ \class QSGGeometry::Point2D
+ \brief The QSGGeometry::Point2D struct is a convenience struct for accessing
+ 2D Points.
+
+ \inmodule QtQuick
+ */
+
+
+/*!
+ \fn void QSGGeometry::Point2D::set(float x, float y)
+
+ Sets the x and y values of this point to \a x and \a y.
+ */
+
+
+/*!
+ \class QSGGeometry::ColoredPoint2D
+ \brief The QSGGeometry::ColoredPoint2D struct is a convenience struct for accessing
+ 2D Points with a color.
+
+ \inmodule QtQuick
+ */
+
+
+/*!
+ \fn void QSGGeometry::ColoredPoint2D::set(float x, float y, uchar red, uchar green, uchar blue, uchar alpha)
+
+ Sets the position of the vertex to \a x and \a y and the color to \a red, \a
+ green, \a blue, and \a alpha.
+ */
+
+
+/*!
+ \class QSGGeometry::TexturedPoint2D
+ \brief The QSGGeometry::TexturedPoint2D struct is a convenience struct for accessing
+ 2D Points with texture coordinates.
+
+ \inmodule QtQuick
+ */
+
+
+/*!
+ \fn void QSGGeometry::TexturedPoint2D::set(float x, float y, float tx, float ty)
+
+ Sets the position of the vertex to \a x and \a y and the texture coordinate
+ to \a tx and \a ty.
+ */
+
+
+
+/*!
\class QSGGeometry
- \brief The QSGGeometry class provides low-level storage for graphics primitives
- in the QML Scene Graph.
- The QSGGeometry class provides a few convenience attributes and attribute accessors
- by default. The defaultAttributes_Point2D() function returns attributes to be used
- in normal solid color rectangles, while the defaultAttributes_TexturedPoint2D function
- returns attributes to be used for the common pixmap usecase.
+ \brief The QSGGeometry class provides low-level
+ storage for graphics primitives in the \l{QML Scene Graph}.
+
+ \inmodule QtQuick
+
+ The QSGGeometry class stores the geometry of the primitives
+ rendered with the scene graph. It contains vertex data and
+ optionally index data. The mode used to draw the geometry is
+ specified with setDrawingMode(), which maps directly to the OpenGL
+ drawing mode, such as \c GL_TRIANGLE_STRIP, \c GL_TRIANGLES, or
+ \c GL_POINTS.
+
+ Vertices can be as simple as points defined by x and y values or
+ can be more complex where each vertex contains a normal, texture
+ coordinates and a 3D position. The QSGGeometry::AttributeSet is
+ used to describe how the vertex data is built up. The attribute
+ set can only be specified on construction. The QSGGeometry class
+ provides a few convenience attributes and attribute sets by
+ default. The defaultAttributes_Point2D() function returns an
+ attribute set to be used in normal solid color rectangles, while
+ the defaultAttributes_TexturedPoint2D function returns attributes
+ to be used for textured 2D geometry. The vertex data is internally
+ stored as a \c {void *} and is accessible with the vertexData()
+ function. Convenience accessors for the common attribute sets are
+ availble with vertexDataAsPoint2D() and
+ vertexDataAsTexturedPoint2D(). Vertex data is allocated by passing
+ a vertex count to the constructor or by calling allocate() later.
+
+ The QSGGeometry can optionally contain indices of either unsigned
+ 32-bit, unsigned 16-bit, or unsigned 8-bit integers. The index type
+ must be specified during construction and cannot be changed.
+
+ Below is a snippet illustrating how a geometry composed of
+ position and color vertices can be built.
+
+ \code
+ struct MyPoint2D {
+ float x;
+ float y;
+ float r;
+ float g;
+ float b;
+ float a;
+
+ void set(float x_, float y_, float r_, float g_, float b_, float a_) {
+ x = x_;
+ y = y_;
+ r = r_;
+ g = g_;
+ b = b_;
+ a = a_;
+ }
+ };
+
+ QSGGeometry::Attribute MyPoint2D_Attributes[] = {
+ QSGGeometry::Attribute::create(0, 2, GL_FLOAT, true),
+ QSGGeometry::Attribute::create(1, 4, GL_FLOAT, false)
+ };
+
+ QSGGeometry::AttributeSet MyPoint2D_AttributeSet = {
+ 2,
+ sizeof(MyPoint2D),
+ MyPoint2D_Attributes
+ };
+
+ ...
+
+ geometry = new QSGGeometry(MyPoint2D_AttributeSet, 2);
+ geometry->setDrawingMode(GL_LINES);
+
+ MyPoint2D *vertices = static_cast<MyPoint2D *>(geometry->vertexData());
+ vertices[0].set(0, 0, 1, 0, 0, 1);
+ vertices[1].set(width(), height(), 0, 0, 1, 1);
+ \endcode
+
+ The QSGGeometry is a software buffer and client-side in terms of
+ OpenGL rendering, as the buffers used in 2D graphics typically consist of
+ many small buffers that change every frame and do not benefit from
+ being uploaded to graphics memory. However, the QSGGeometry
+ supports hinting to the renderer that a buffer should be
+ uploaded using the setVertexDataPattern() and
+ setIndexDataPattern() functions. Whether this hint is respected or
+ not is implementation specific.
+
+ \sa QSGGeometryNode
+
+ */
+
+/*!
+ \fn int QSGGeometry::attributeCount() const
+
+ Returns the number of attributes in the attrbute set used by this geometry.
+ */
+
+/*!
+ \fn QSGGeometry::Attribute *QSGGeometry::attributes() const
+
+ Returns an array with the attributes of this geometry. The size of the array
+ is given with attributeCount().
+ */
+
+/*!
+ \fn uint *QSGGeometry::indexDataAsUInt()
+
+ Convenience function to access the index data as a mutable array of
+ 32-bit unsigned integers.
+ */
+
+/*!
+ \fn const uint *QSGGeometry::indexDataAsUInt() const
+
+ Convenience function to access the index data as an immutable array of
+ 32-bit unsigned integers.
+ */
+
+/*!
+ \fn quint16 *QSGGeometry::indexDataAsUShort()
+
+ Convenience function to access the index data as a mutable array of
+ 16-bit unsigned integers.
+ */
+
+/*!
+ \fn const quint16 *QSGGeometry::indexDataAsUShort() const
+
+ Convenience function to access the index data as an immutable array of
+ 16-bit unsigned integers.
+ */
+
+/*!
+ \fn const QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D() const
+
+ Convenience function to access the vertex data as an immuatble
+ array of QSGGeometry::ColoredPoint2D.
+ */
+
+/*!
+ \fn QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D()
+
+ Convenience function to access the vertex data as a muatble
+ array of QSGGeometry::ColoredPoint2D.
+ */
+
+/*!
+ \fn const QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D() const
+
+ Convenience function to access the vertex data as an immuatble
+ array of QSGGeometry::TexturedPoint2D.
+ */
+
+/*!
+ \fn QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D()
+
+ Convenience function to access the vertex data as a muatble
+ array of QSGGeometry::TexturedPoint2D.
+ */
+
+/*!
+ \fn const QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D() const
+
+ Convenience function to access the vertex data as an immuatble
+ array of QSGGeometry::Point2D.
+ */
+
+/*!
+ \fn QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D()
+
+ Convenience function to access the vertex data as a muatble
+ array of QSGGeometry::Point2D.
*/
/*!
Constructs a geometry object based on \a attributes.
- The object allocate space for \a vertexCount vertices based on the accumulated
- size in \a attributes and for \a indexCount.
+ The object allocate space for \a vertexCount vertices based on the
+ accumulated size in \a attributes and for \a indexCount.
- Geometry objects are constructed with GL_TRIANGLE_STRIP as default drawing mode.
+ The \a indexType maps to the OpenGL index type and can be
+ \c GL_UNSIGNED_SHORT and \c GL_UNSIGNED_BYTE. On OpenGL implementations that
+ support it, such as desktop OpenGL, \c GL_UNSIGNED_INT can also be used.
+
+ Geometry objects are constructed with \c GL_TRIANGLE_STRIP as default
+ drawing mode.
The attribute structure is assumed to be POD and the geometry object
assumes this will not go away. There is no memory management involved.
Returns the byte size of the index type.
- This value is either 1 when index type is GL_UNSIGNED_BYTE or 2 when
- index type is GL_UNSIGNED_SHORT. For Desktop OpenGL, GL_UNSIGNED_INT
- with the value 4 is also supported.
+ This value is either \c 1 when index type is \c GL_UNSIGNED_BYTE or \c 2
+ when index type is \c GL_UNSIGNED_SHORT. For Desktop OpenGL,
+ \c GL_UNSIGNED_INT with the value \c 4 is also supported.
+ */
+
+/*!
+ Destroys the geometry object and the vertex and index data it has allocated.
*/
QSGGeometry::~QSGGeometry()
Returns a pointer to the raw vertex data of this geometry object.
- \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
+ \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D()
*/
/*!
Returns a pointer to the raw vertex data of this geometry object.
- \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
+ \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D()
*/
/*!
}
/*!
- Sets the drawing mode to be used for this geometry.
+ Sets the \a mode to be used for drawing this geometry.
- The default value is GL_TRIANGLE_STRIP.
+ The default value is \c GL_TRIANGLE_STRIP.
*/
void QSGGeometry::setDrawingMode(GLenum mode)
{
Gets the current line width to be used for this geometry. This property only
applies where the drawingMode is GL_LINES or a related value.
- The default value is 1.0
+ The default value is \c 1.0
\sa setLineWidth(), drawingMode()
*/
}
/*!
- Sets the line width to be used for this geometry. This property only applies
- where the drawingMode is GL_LINES or a related value.
+ Sets the line width to be used for this geometry to \a width. The line width
+ only applies where the drawingMode is \c GL_LINES or a related value.
\sa lineWidth(), drawingMode()
*/
-void QSGGeometry::setLineWidth(float w)
+void QSGGeometry::setLineWidth(float width)
{
- m_line_width = w;
+ m_line_width = width;
}
/*!
Returns the drawing mode of this geometry.
- The default value is GL_TRIANGLE_STRIP.
+ The default value is \c GL_TRIANGLE_STRIP.
*/
/*!
/*!
\enum QSGGeometry::DataPattern
- The DataPattern enum is used to specify the use pattern for the vertex
- and index data in a geometry object.
+ The DataPattern enum is used to specify the use pattern for the
+ vertex and index data in a geometry object.
+
+ \value AlwaysUploadPattern The data is always uploaded. This means
+ that the user does not need to explicitly mark index and vertex
+ data as dirty after changing it. This is the default.
- \value AlwaysUploadPattern The data is always uploaded. This means that
- the user does not need to explicitly mark index and vertex data as
- dirty after changing it. This is the default.
+ \value DynamicPattern The data is modified repeatedly and drawn
+ many times. This is a hint that may provide better
+ performance. When set the user must make sure to mark the data as
+ dirty after changing it.
- \value DynamicPattern The data is modified repeatedly and drawn many times.
- This is a hint that may provide better performance. When set
- the user must make sure to mark the data as dirty after changing it.
+ \value StaticPattern The data is modified once and drawn many
+ times. This is a hint that may provide better performance. When
+ set the user must make sure to mark the data as dirty after
+ changing it.
- \value StaticPattern The data is modified once and drawn many times. This is
- a hint that may provide better performance. When set the user must make sure
- to mark the data as dirty after changing it.
+ \value StreamPattern The data is modified for almost every time it
+ is drawn. This is a hint that may provide better performance. When
+ set, the user must make sure to mark the data as dirty after
+ changing it.
*/
\class QSGMaterialShader
\brief The QSGMaterialShader class represents an OpenGL shader program
in the renderer.
+ \inmodule QtQuick
The QSGMaterialShader API is very low-level. A more convenient API, which
provides almost all the same features, is available through
to render that material, such as a shader to flat coloring of geometry.
Each QSGGeometryNode can have a unique QSGMaterial containing the
how the shader should be configured when drawing that node, such as
- the actual color to used to render the geometry.
+ the actual color used to render the geometry.
- An instance of QSGMaterialShader is never created explicitely by the user,
+ An instance of QSGMaterialShader is never created explicitly by the user,
it will be created on demand by the scene graph through
QSGMaterial::createShader(). The scene graph will make sure that there
is only one instance of each shader implementation through a scene graph.
{
}
+/*!
+ \fn QSGMaterialShader::~QSGMaterialShader()
+ \internal
+ */
+
+/*!
+ \fn char const *const *QSGMaterialShader::attributeNames() const
+
+ Returns a zero-terminated array describing the names of the
+ attributes used in the vertex shader.
+
+ This function is called when the shader is compiled to specify
+ which attributes exist. The order of the attribute names
+ defines the attribute register position in the vertex shader.
+ */
+
+
+/*!
+ \fn const char *QSGMaterialShader::vertexShader() const
+
+ Called when the shader is being initialized to get the vertex
+ shader source code.
+
+ The contents returned from this function should never change.
+*/
/*!
- \fn QOpenGLShaderProgram *QSGMaterialShader::program() const
+ \fn const char *QSGMaterialShader::fragmentShader() const
+
+ Called when the shader is being initialized to get the fragment
+ shader source code.
+
+ The contents returned from this function should never change.
+*/
+
+
+/*!
+ \fn QOpenGLShaderProgram *QSGMaterialShader::program()
Returns the shader program used by this QSGMaterialShader.
*/
+/*!
+ \fn void QSGMaterialShader::initialize()
+
+ Reimplement this function to do one-time initialization when the
+ shader program is compiled. The OpenGL shader program is compiled
+ and linked, but not bound, when this function is called.
+ */
+
/*!
This function is called by the scene graph to indicate that geometry is
/*!
\fn bool QSGMaterialShader::RenderState::isMatrixDirty() const
- Convenience function to check if the dirtyStates() indicates that the matrix
- needs to be updated.
+ Returns \c true if the dirtyStates() contain the dirty matrix state,
+ otherwise returns \c false.
*/
/*!
\fn bool QSGMaterialShader::RenderState::isOpacityDirty() const
- Conveience function to check if the dirtyStates() indicates that the opacity
- needs to be updated.
+ Returns \c true if the dirtyStates() contains the dirty opacity state,
+ otherwise returns \c false.
*/
/*!
- Returns the accumulated opacity to be used for rendering
+ Returns the accumulated opacity to be used for rendering.
*/
float QSGMaterialShader::RenderState::opacity() const
}
/*!
- Returns the modelview determinant to be used for rendering
+ Returns the modelview determinant to be used for rendering.
*/
float QSGMaterialShader::RenderState::determinant() const
/*!
\class QSGMaterialType
\brief The QSGMaterialType class is used as a unique type token in combination with QSGMaterial.
+ \inmodule QtQuick
It serves no purpose outside the QSGMaterial::type() function.
*/
/*!
\class QSGMaterial
\brief The QSGMaterial class encapsulates rendering state for a shader program.
+ \inmodule QtQuick
The QSGMaterial API is very low-level. A more convenient API, which
provides almost all the same features, is available through
and cannot be used from the GUI thread.
*/
+/*!
+ \internal
+ */
+
QSGMaterial::QSGMaterial()
: m_flags(0)
{
#endif
}
+
+/*!
+ \internal
+ */
+
QSGMaterial::~QSGMaterial()
{
#ifndef QT_NO_DEBUG
the full matrix of the geometry nodes for rendering.
*/
+/*!
+ \fn QSGMaterial::Flags QSGMaterial::flags() const
+
+ Returns the material's flags.
+ */
+
/*!
The QSGNode class can be used as a child container. Children are added with
the appendChildNode(), prependChildNode(), insertChildNodeBefore() and
- insertChildNodeAfter(). Ordering of nodes is important as geometry nodes
- will be rendered in the order they are added to the scene graph.
- Actually, the scene may reorder nodes freely, but the resulting visual
- order is still guaranteed.
+ insertChildNodeAfter(). The order of nodes is important as geometry nodes
+ are rendered according to their ordering in the scene graph.
The scene graph nodes contains a mechanism to describe which
parts of the scene has changed. This includes the combined matrices,
- accumulated opacity, changes to the node hierarchy, etc. This information
- can be used for optimizations inside the scene graph renderer. For
- the renderer to properly render the nodes, it is important that users
+ accumulated opacity, changes to the node hierarchy, and so on. This
+ information can be used for optimizations inside the scene graph renderer.
+ For the renderer to properly render the nodes, it is important that users
call QSGNode::markDirty() with the correct flags when nodes are changed.
- Most of the functions on the node classes will implicitly call markDirty(),
- e.g. QSGNode::appendChildNode() will call markDirty() passing in
+ Most of the functions on the node classes will implicitly call markDirty().
+ For example, QSGNode::appendChildNode() will call markDirty() passing in
QSGNode::DirtyNodeAdded.
If nodes change every frame, the preprocess() function can be used to
- apply changes to a node for every frame its rendered. The use of preprocess()
- must be explicitly enabled by setting the QSGNode::UsePreprocess flag
- on the node.
+ apply changes to a node for every frame it is rendered. The use of
+ preprocess() must be explicitly enabled by setting the
+ QSGNode::UsePreprocess flag on the node.
The virtual isSubtreeBlocked() function can be used to disable a subtree all
together. Nodes in a blocked subtree will not be preprocessed() and not
rendered.
- \warning Anything related to QSGNode should happen on the scene graph rendering thread.
+ \warning Anything related to QSGNode should happen on the scene graph
+ rendering thread.
*/
+/*!
+ \enum QSGNode::DirtyStateBit
+
+ Used in QSGNode::markDirty() to indicate how the scene graph has changed.
+
+ \value DirtyMatrix The matrix in a QSGTransformNode has changed.
+ \value DirtyNodeAdded A node was added.
+ \value DirtyNodeRemoved A node was removed.
+ \value DirtyGeometry The geometry of a QSGGeometryNode has changed.
+ \value DirtyMaterial The material of a QSGGeometryNode has changed.
+ \value DirtyOpacity The opacity of a QSGOpacityNode has changed.
+
+ \sa QSGNode::markDirty()
+ */
+
+/*!
+ \enum QSGNode::Flag
+
+ The QSGNode::Flag enum describes flags on the QSGNode
+
+ \value OwnedByParent The node is owned by its parent and will be deleted
+ when the parent is deleted.
+ \value UsePreprocess The node's virtual preprocess() function will be called
+ before rendering starts.
+ \value OwnsGeometry Only valid for QSGGeometryNode and QSGClipNode.
+ The node has ownership over the QSGGeometry instance and will
+ delete it when the node is destroyed.
+ \value OwnsMaterial Only valid for QSGGeometryNode. The node has ownership
+ over the material and will delete it when the node is destroyed.
+ \value OwnsOpaqueMaterial Only valid for QSGGeometryNode. The node has
+ ownership over the opaque material and will delete it when the node is
+ destroyed.
+ */
+
+/*!
+ \enum QSGNode::NodeType
+
+ Can be used to figure out the type of node.
+
+ \value BasicNodeType The type of QSGNode
+ \value GeometryNodeType The type of QSGGeometryNode
+ \value TransformNodeType The type of QSGTransformNode
+ \value ClipNodeType The type of QSGClipNode
+ \value OpacityNodeType The type of QSGOpacityNode
+
+ \sa type()
+ */
+
+/*!
+ \fn QSGNode *QSGNode::childAtIndex(int i) const
+
+ Returns the child at index \a i.
+
+ Children are stored internally as a linked list, so iterating
+ over the children via the index is suboptimal.
+ */
+
+/*!
+ \fn int QSGNode::childCount() const
+
+ Returns the number of child nodes.
+ */
+
+/*!
+ \fn void QSGNode::clearDirty()
+
+ \internal
+ */
+
+/*!
+ \fn QSGNode *QSGNode::firstChild() const
+
+ Returns the first child of this node.
+
+ The children are stored in a linked list.
+ */
+
+/*!
+ \fn QSGNode *QSGNode::lastChild() const
+
+ Returns the last child of this node.
+
+ The children are stored as a linked list.
+ */
+
+/*!
+ \fn QSGNode::Flags QSGNode::flags() const
+
+ Returns the set of flags for this node.
+ */
+
+/*!
+ \fn QSGNode *QSGNode::nextSibling() const
+
+ Returns the node after this in the parent's list of children.
+
+ The children are stored as a linked list.
+ */
+
+/*!
+ \fn QSGNode *QSGNode::previousSibling() const
+
+ Returns the node before this in the parent's list of children.
+
+ The children are stored as a linked list.
+ */
+
+/*!
+ \fn QSGNode::Type QSGNode::type() const
+
+ Returns the type of this node. The node type must be one of the
+ predefined types defined in QSGNode::NodeType and can safely be
+ used to cast to the corresponding class.
+ */
+
+/*!
+ \fn QSGNode::DirtyState QSGNode::dirtyState() const
+
+ \internal
+ */
+
+/*!
+ \fn QSGNode *QSGNode::parent() const
+
+ Returns the parent node of this node.
+ */
+
+
+/*!
+ * Constructs a new node
+ */
QSGNode::QSGNode()
: m_parent(0)
, m_type(BasicNodeType)
init();
}
+/*!
+ * Constructs a new node with the given node type.
+ *
+ * \internal
+ */
QSGNode::QSGNode(NodeType type)
: m_parent(0)
, m_type(type)
init();
}
+/*!
+ * \internal
+ */
void QSGNode::init()
{
#ifndef QT_NO_DEBUG
#endif
}
+/*!
+ * Destroys the node.
+ *
+ * Every child of this node that has the flag QSGNode::OwnedByParent set,
+ * will also be deleted.
+ */
QSGNode::~QSGNode()
{
#ifndef QT_NO_DEBUG
/*!
- Marks this node with the states in \a flags as dirty.
+ Marks this node with the states in \a bits as dirty.
- When a node is marked dirty, it recursively mark the parent chain
+ When a node is marked dirty, it recursively marks the parent chain
as dirty and notify all connected renderers that the has dirty states.
*/
/*!
\class QSGBasicGeometryNode
- \brief The QSGBasicGeometryNode class serves as a baseclass for geometry based nodes
+ \brief The QSGBasicGeometryNode class serves as a baseclass for geometry based nodes.
\inmodule QtQuick
/*!
- Creates a new basic geometry node.
+ Creates a new basic geometry node of type \a type
+
+ \internal
*/
QSGBasicGeometryNode::QSGBasicGeometryNode(NodeType type)
: QSGNode(type)
/*!
- \fn QSGGeometry *QSGBasicGeometryNode::geometry() const
+ \fn QSGGeometry *QSGBasicGeometryNode::geometry()
Returns this node's geometry.
The geometry is null by default.
*/
+/*!
+ \fn const QSGGeometry *QSGBasicGeometryNode::geometry() const
+
+ Returns this node's geometry.
+
+ The geometry is null by default.
+ */
+
+/*!
+ \fn QMatrix4x4 *QSGBasicGeometryNode::matrix() const
+
+ Will be set during rendering to contain transformation of the geometry
+ for that rendering pass.
+
+ \internal
+ */
+
+/*!
+ \fn QSGClipNode *QSGBasicGeometryNode::clipList() const
+
+ Will be set during rendering to contain the clip of the geometry
+ for that rendering pass.
+
+ \internal
+ */
+
/*!
Sets the geometry of this node to \a geometry.
If the geometry is changed whitout calling setGeometry() again, the user
must also mark the geometry as dirty using QSGNode::markDirty().
- \sa markDirty
+ \sa markDirty()
*/
void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry)
\internal
*/
+/*!
+ \fn QSGMaterial *QSGGeometryNode::material() const
+
+ Returns the material of the QSGGeometryNode.
+
+ \sa setMaterial()
+ */
+
+/*!
+ \fn QSGMaterial *QSGGeometryNode::opaqueMaterial() const
+
+ Returns the opaque material of the QSGGeometryNode.
+
+ \sa setOpaqueMaterial()
+ */
+
+/*!
+ \fn qreal QSGGeometryNode::inheritedOpacity() const
+
+ Set during rendering to specify the inherited opacity for that
+ rendering pass.
+
+ \internal
+ */
+
/*!
Sets the render order of this node to be \a order.
- GeometryNodes are rendered in an order that visually looks like
+ Geometry nodes are rendered in an order that visually looks like
low order nodes are rendered prior to high order nodes. For opaque
geometry there is little difference as z-testing will handle
the discard, but for translucent objects, the rendering should
normally be specified in the order of back-to-front.
- The default render order is 0.
+ The default render order is \c 0.
\internal
*/
be done with some care.
*/
+
+/*!
+ Create a new QSGTransformNode with its matrix set to the identity matrix.
+ */
+
QSGTransformNode::QSGTransformNode()
: QSGNode(TransformNodeType)
{
markDirty(DirtyMatrix);
}
+/*!
+ \fn const QMatrix4x4 &QSGTransformNode::combinedMatrix() const
+
+ Set during rendering to the combination of all parent matrices for
+ that rendering pass.
+
+ \internal
+ */
+
+
/*!
Sets the combined matrix of this matrix to \a transform.
public:
enum NodeType {
BasicNodeType,
- RootNodeType,
GeometryNodeType,
TransformNodeType,
ClipNodeType,
OpacityNodeType,
-#ifndef Q_QDOC
- RenderNodeType, // internal
+#ifndef qdoc
+ RootNodeType,
+ RenderNodeType
#endif
- UserNodeType = 1024
};
enum Flag {
Q_DECLARE_FLAGS(Flags, Flag)
enum DirtyStateBit {
- DirtyUsePreprocess = UsePreprocess,
-
DirtyMatrix = 0x0100,
- DirtyClipList = 0x0200,
DirtyNodeAdded = 0x0400,
DirtyNodeRemoved = 0x0800,
DirtyGeometry = 0x1000,
DirtyMaterial = 0x2000,
DirtyOpacity = 0x4000,
+
+#ifndef qdoc
DirtyForceUpdate = 0x8000,
+ DirtyUsePreprocess = UsePreprocess,
+
DirtyPropagationMask = DirtyMatrix
- | DirtyClipList
| DirtyNodeAdded
| DirtyOpacity
| DirtyForceUpdate
+#endif
};
Q_DECLARE_FLAGS(DirtyState, DirtyStateBit)
void *m_reserved;
};
-Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::DirtyState)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::Flags)
-
class Q_QUICK_EXPORT QSGBasicGeometryNode : public QSGNode
{
public:
-// enum UsagePattern {
-// Static,
-// Dynamic,
-// Stream
-// };
-// void setUsagePattern(UsagePattern pattern);
-// UsagePattern usagePattern() const { return m_pattern; }
-
~QSGBasicGeometryNode();
void setGeometry(QSGGeometry *geometry);
const QMatrix4x4 *m_matrix;
const QSGClipNode *m_clip_list;
-
-// UsagePattern m_pattern;
};
class QSGMaterial;
#endif
+Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::DirtyState)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::Flags)
+
QT_END_NAMESPACE
QT_END_HEADER
qDebug() << "enter clip:" << c;
#endif
- if (c->dirtyState() & QSGNode::DirtyClipList)
- ++m_force_update;
-
c->m_matrix = m_combined_matrix_stack.isEmpty() ? 0 : m_combined_matrix_stack.last();
c->m_clip_list = m_current_clip;
m_current_clip = c;
qDebug() << "leave clip:" << c;
#endif
- if (c->dirtyState() & QSGNode::DirtyClipList)
- --m_force_update;
-
m_current_clip = c->m_clip_list;
}
/*!
\class QSGFlatColorMaterial
+
\brief The QSGFlatColorMaterial class provides a convenient way of rendering
solid colored geometry in the scene graph.
set compatible with this material.
The flat color material respects both current opacity and current matrix
- when updating it's rendering state.
+ when updating its rendering state.
*/
/*!
- \fn QColor QSGFlatColorMaterial::color() const
+ \fn const QColor &QSGFlatColorMaterial::color() const
Returns this flat color material's color.
}
+/*!
+ \internal
+ */
+
int QSGFlatColorMaterial::compare(const QSGMaterial *other) const
{
const QSGFlatColorMaterial *flat = static_cast<const QSGFlatColorMaterial *>(other);
/*!
\class QSGSimpleMaterialShader
- \brief The QSGSimpleMaterialShader provides a convenient way of
+ \brief The QSGSimpleMaterialShader class provides a convenient way of
building custom materials for the scene graph.
\inmodule QtQuick
renderer internally uses to identify this shader. For this reason,
the unique QSGSimpleMaterialShader implemenation must be
instantiated with a unique C++ type.
-
*/
/*!
- \fn QList<QByteArray> QSGSimpleMaterialShader::attributes() const
+ \fn char const *const *QSGSimpleMaterialShader::attributeNames() const
+ \internal
+ */
- Returns a list of names, declaring the vertex attributes in the
- vertex shader.
-*/
+/*!
+ \fn void QSGSimpleMaterialShader::initialize()
+ \internal
+ */
/*!
- \fn void QSGSimpleMaterialShader::updateState(const State *newState, const State *oldState)
+ \fn void QSGSimpleMaterialShader::resolveUniforms()
+ \internal
+ */
- Called whenever the state of this shader should be updated,
- typical for each new set of geometries being drawn.
+/*!
+ \fn const char *QSGSimpleMaterialShader::uniformMatrixName() const
+ \internal
+ */
- Both the old and the new state are passed in so that the
- implementation can compare and minimize the state changes when
- applicable.
-*/
+/*!
+ \fn const char *QSGSimpleMaterialShader::uniformOpacityName() const
+ \internal
+ */
/*!
- \fn const char *QSGSimpleMaterialShader::vertexShader() const
+ \fn void QSGSimpleMaterialShader::updateState(const RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
+ \internal
+ */
- Called when the shader is being initialized to get the vertex
- shader source code.
- The contents returned from this function should never change.
-*/
+/*!
+ \fn QList<QByteArray> QSGSimpleMaterialShader::attributes() const
+ Returns a list of names, declaring the vertex attributes in the
+ vertex shader.
+*/
/*!
- \fn const char *QSGSimpleMaterialShader::fragmentShader() const
+ \fn void QSGSimpleMaterialShader::updateState(const State *newState, const State *oldState)
- Called when the shader is being initialized to get the vertex
- shader source code.
+ Called whenever the state of this shader should be updated from
+ \a oldState to \a newState, typical for each new set of
+ geometries being drawn.
- The contents returned from this function should never change.
+ Both the old and the new state are passed in so that the
+ implementation can compare and minimize the state changes when
+ applicable.
*/
/*!
\class QSGSimpleMaterial
+ \inmodule QtQuick
+
\brief The QSGSimpleMaterial class is a template generated class
used to store the state used with a QSGSimpleMateralShader.
*/
-
-
-
-
-
template <typename State>
class QSGSimpleMaterial : public QSGMaterial
{
-
public:
+#ifndef qdoc
QSGSimpleMaterial(const State &state, PtrShaderCreateFunc func)
: m_state(state)
, m_func(func)
State *state() { return &m_state; }
const State *state() const { return &m_state; }
+#endif
private:
static QSGMaterialType m_type;
\class QSGDynamicTexture
\brief The QSGDynamicTexture class serves as a baseclass for dynamically changing textures,
such as content that is rendered to FBO's.
+ \inmodule QtQuick
To update the content of the texture, call updateTexture() explicitly. Simply calling bind()
will not update the texture.
The default mipmap filtering and filtering mode is set to
QSGTexture::Nearest. The default wrap modes is set to
- QSGTexture::ClampToEdge.
+ \c QSGTexture::ClampToEdge.
*/
QSGOpaqueTextureMaterial::QSGOpaqueTextureMaterial()
Returns this material's mipmap filtering mode.
- The default mipmap mode is QSGTexture::Nearest.
+ The default mipmap mode is \c QSGTexture::Nearest.
*/
/*!
- \fn QSGTexture::Filtering filtering() const
+ \fn QSGTexture::Filtering QSGOpaqueTextureMaterial::filtering() const
Returns this material's filtering mode.
- The default filtering is QSGTexture::Nearest.
+ The default filtering is \c QSGTexture::Nearest.
*/
/*!
- \fn void setHorizontalWrapMode(QSGTexture::WrapMode mode)
+ \fn void QSGOpaqueTextureMaterial::setHorizontalWrapMode(QSGTexture::WrapMode mode)
Sets the horizontal wrap mode to \a mode.
/*!
- \fn QSGTexture::WrapMode horizontalWrapMode() const
+ \fn QSGTexture::WrapMode QSGOpaqueTextureMaterial::horizontalWrapMode() const
Returns this material's horizontal wrap mode.
- The default horizontal wrap mode is QSGTexutre::ClampToEdge
+ The default horizontal wrap mode is \c QSGTexutre::ClampToEdge.
*/
/*!
- \fn void setVerticalWrapMode(QSGTexture::WrapMode mode)
+ \fn void QSGOpaqueTextureMaterial::setVerticalWrapMode(QSGTexture::WrapMode mode)
Sets the vertical wrap mode to \a mode.
/*!
- \fn QSGTexture::WrapMode verticalWrapMode() const
+ \fn QSGTexture::WrapMode QSGOpaqueTextureMaterial::verticalWrapMode() const
Returns this material's vertical wrap mode.
- The default vertical wrap mode is QSGTexutre::ClampToEdge
+ The default vertical wrap mode is \c QSGTexutre::ClampToEdge.
*/
*/
+/*!
+ Creates a new vertex color material.
+ */
+
QSGVertexColorMaterial::QSGVertexColorMaterial()
{
setFlag(Blending, true);
projects / konrad/qtdeclarative.git / commitdiff