Qmlshadersplugin API documentation enhancements.

Added a link from qml element index, removed some unnecessary doc markings, added missing example image and some other minor fixes.

Reviewed-by: Kim Gronholm

5 files changed, 21 insertions, 124 deletions

diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index a861a66..6b7a5fc 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -175,6 +175,8 @@ Elements that animate properties based on data types
 \o \l {ParticleMotionLinear} - Adds linear motion behavior to \l {Particles}
 \o \l {ParticleMotionGravity} - Adds gravitational motion to \l {Particles}
 \o \l {ParticleMotionWander} - Adds varied motions to \l {Particles}
+\o \l {ShaderEffectItem} - Enables the use of OpenGL Shading Language together with QML
+\o \l {ShaderEffectSource} - Encapsulates QML item tree as a source item for \l {ShaderEffectItem}
 \endlist
 
 \section1 Add-On Elements
@@ -321,3 +323,14 @@ should first be obtained and installed.
     \generatelist{related}
 
 */
+
+/*!
+    \group qml-shader-elements
+    \title QML Shader Elements
+    \ingroup qml-groups
+
+    \brief Elements for using OpenGL shading language code together with the QML code.
+
+    \generatelist{related}
+
+*/
diff --git a/doc/src/declarative/pics/shaderexample.png b/doc/src/declarative/pics/shaderexample.png
new file mode 100644
index 0000000..dbc7291
--- /dev/null
+++ b/doc/src/declarative/pics/shaderexample.png
diff --git a/src/imports/shaders/scenegraph/qsggeometry.cpp b/src/imports/shaders/scenegraph/qsggeometry.cpp
index 05c111a..08ac10e 100644
--- a/src/imports/shaders/scenegraph/qsggeometry.cpp
+++ b/src/imports/shaders/scenegraph/qsggeometry.cpp
@@ -44,11 +44,6 @@
 QT_BEGIN_NAMESPACE
 
 
-/*!
-    Convenience function which returns attributes to be used for 2D solid
-    color drawing.
- */
-
 const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_Point2D()
 {
     static Attribute data[] = {
@@ -58,9 +53,6 @@ const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_Point2D()
     return attrs;
 }
 
-/*!
-    Convenience function which returns attributes to be used for textured 2D drawing.
- */
 
 const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_TexturedPoint2D()
 {
@@ -72,9 +64,6 @@ const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_TexturedPoint2D(
     return attrs;
 }
 
-/*!
-    Convenience function which returns attributes to be used for per vertex colored 2D drawing.
- */
 
 const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_ColoredPoint2D()
 {
@@ -87,29 +76,6 @@ const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_ColoredPoint2D()
 }
 
 
-/*!
-    \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.
- */
-
-
-/*!
-    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.
-
-    Geometry objects are constructed with 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.
- */
 
 QSGGeometry::QSGGeometry(const QSGGeometry::AttributeSet &attributes,
                          int vertexCount,
@@ -138,41 +104,6 @@ QSGGeometry::~QSGGeometry()
         qFree(m_data);
 }
 
-/*!
-    \fn int QSGGeometry::vertexCount() const
-
-    Returns the number of vertices in this geometry object.
- */
-
-/*!
-    \fn int QSGGeometry::indexCount() const
-
-    Returns the number of indices in this geometry object.
- */
-
-
-
-/*!
-    \fn void *QSGGeometry::vertexData()
-
-    Returns a pointer to the raw vertex data of this geometry object.
-
-    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
- */
-
-/*!
-    \fn const void *QSGGeometry::vertexData() const
-
-    Returns a pointer to the raw vertex data of this geometry object.
-
-    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
- */
-
-/*!
-    Returns a pointer to the raw index data of this geometry object.
-
-    \sa indexDataAsUShort(), indexDataAsUInt()
- */
 void *QSGGeometry::indexData()
 {
     return m_index_data_offset < 0
@@ -180,11 +111,6 @@ void *QSGGeometry::indexData()
             : ((char *) m_data + m_index_data_offset);
 }
 
-/*!
-    Returns a pointer to the raw index data of this geometry object.
-
-    \sa indexDataAsUShort(), indexDataAsUInt()
- */
 const void *QSGGeometry::indexData() const
 {
     return m_index_data_offset < 0
@@ -192,38 +118,11 @@ const void *QSGGeometry::indexData() const
             : ((char *) m_data + m_index_data_offset);
 }
 
-/*!
-    Sets the drawing mode to be used for this geometry.
-
-    The default value is GL_TRIANGLE_STRIP.
- */
 void QSGGeometry::setDrawingMode(GLenum mode)
 {
     m_drawing_mode = mode;
 }
 
-/*!
-    \fn int QSGGeometry::drawingMode() const
-
-    Returns the drawing mode of this geometry.
-
-    The default value is GL_TRIANGLE_STRIP.
- */
-
-/*!
-    \fn int QSGGeometry::indexType() const
-
-    Returns the primitive type used for indices in this
-    geometry object.
- */
-
-
-/*!
-    Resizes the vertex and index data of this geometry object to fit \a vertexCount
-    vertices and \a indexCount indices.
-
-    Vertex and index data will be invalidated after this call and the caller must
- */
 void QSGGeometry::allocate(int vertexCount, int indexCount)
 {
     if (vertexCount == m_vertex_count && indexCount == m_index_count)
@@ -252,12 +151,6 @@ void QSGGeometry::allocate(int vertexCount, int indexCount)
 
 }
 
-/*!
-    Updates the geometry \a g with the coordinates in \a rect.
-
-    The function assumes the geometry object contains a single triangle strip
-    of QSGGeometry::Point2D vertices
- */
 void QSGGeometry::updateRectGeometry(QSGGeometry *g, const QRectF &rect)
 {
     Point2D *v = g->vertexDataAsPoint2D();
@@ -274,15 +167,6 @@ void QSGGeometry::updateRectGeometry(QSGGeometry *g, const QRectF &rect)
     v[3].y = rect.bottom();
 }
 
-/*!
-    Updates the geometry \a g with the coordinates in \a rect and texture
-    coordinates from \a textureRect.
-
-    \a textureRect should be in normalized coordinates.
-
-    \a g is assumed to be a triangle strip of four vertices of type
-    QSGGeometry::TexturedPoint2D.
- */
 void QSGGeometry::updateTexturedRectGeometry(QSGGeometry *g, const QRectF &rect, const QRectF &textureRect)
 {
     TexturedPoint2D *v = g->vertexDataAsTexturedPoint2D();
diff --git a/src/imports/shaders/shadereffectitem.cpp b/src/imports/shaders/shadereffectitem.cpp
index 5bb906c..48c842a 100644
--- a/src/imports/shaders/shadereffectitem.cpp
+++ b/src/imports/shaders/shadereffectitem.cpp
@@ -72,7 +72,7 @@ static const char qt_emptyAttributeName[] = "";
 
 /*!
     \qmlclass ShaderEffectItem ShaderEffectItem
-    \ingroup qmlshadersplugin
+    \ingroup qml-shader-elements
     \brief The ShaderEffectItem object alters the output of given item with OpenGL shaders.
     \inherits Item
 
@@ -84,7 +84,7 @@ static const char qt_emptyAttributeName[] = "";
     and may be heavily changed or removed in later versions.
 
     Requirement for the use of shaders is that the application is either using
-    Qt OpenGL graphicssystem or is forced to use OpenGL by setting QGLWidget as the viewport to QDeclarativeView (recommened way).
+    Qt OpenGL graphicssystem or is using OpenGL by setting QGLWidget as the viewport to QDeclarativeView (depending on which one is the recommened way in the targeted platform).
 
     ShaderEffectItem internal behaviour is such that during the paint event it first renders its
     ShaderEffectSource items into a OpenGL framebuffer object which can be used as a texture. If the ShaderEffectSource is defined to be an image,
@@ -195,7 +195,7 @@ Rectangle {
     }
 }
     \endqml
-    \image Example1.png
+    \image shaderexample.png
 
 */
 
diff --git a/src/imports/shaders/shadereffectsource.cpp b/src/imports/shaders/shadereffectsource.cpp
index dec3bb0..e6dbc73 100644
--- a/src/imports/shaders/shadereffectsource.cpp
+++ b/src/imports/shaders/shadereffectsource.cpp
@@ -48,7 +48,7 @@
 
 /*!
     \qmlclass ShaderEffectSource ShaderEffectSource
-    \ingroup qmlshadersplugin
+    \ingroup qml-shader-elements
     \brief The ShaderEffectSource object encapsulates the source content for the ShaderEffectItem.
 
     ShaderEffectSource is available in the \bold{Qt.labs.shaders 1.0} module.
@@ -273,10 +273,10 @@ void ShaderEffectSource::setHideSource(bool hide)
     This property defines the wrap parameter for the source after it has been mapped as a texture.
 
     \list
-    \o WrapMode.ClampToEdge - Causes texturecoordinates to be clamped to the range [ 1/2*N , 1 - 1/2*N ], where N is the texture width.
-    \o WrapMode.RepeatHorizontally - Causes the integer part of the horizontal texturecoordinate to be ignored; the GL uses only the fractional part, thereby creating a horizontal repeating pattern.
-    \o WrapMode.RepeatVertically - Causes the integer part of the vertical texturecoordinate to be ignored; the GL uses only the fractional part, thereby creating a vertical repeating pattern.
-    \o WrapMode.Repeat - Causes the integer part of both the horizontal and vertical texturecoordinates to be ignored; the GL uses only the fractional part, thereby creating a repeating pattern.
+    \o ShaderEffectSource.ClampToEdge - Causes texturecoordinates to be clamped to the range [ 1/2*N , 1 - 1/2*N ], where N is the texture width.
+    \o ShaderEffectSource.RepeatHorizontally - Causes the integer part of the horizontal texturecoordinate to be ignored; the GL uses only the fractional part, thereby creating a horizontal repeating pattern.
+    \o ShaderEffectSource.RepeatVertically - Causes the integer part of the vertical texturecoordinate to be ignored; the GL uses only the fractional part, thereby creating a vertical repeating pattern.
+    \o ShaderEffectSource.Repeat - Causes the integer part of both the horizontal and vertical texturecoordinates to be ignored; the GL uses only the fractional part, thereby creating a repeating pattern.
     \endlist
 
     The default value is ClampToEdge.