Add QML doc for textures

Change-Id: I649cf174ff59c64358d13c762eeb500521f712ce
Reviewed-by: Michael Brasser <michael.brasser@live.com>

2 files changed, 185 insertions, 0 deletions

diff --git a/src/render/texture/qabstracttexture.cpp b/src/render/texture/qabstracttexture.cpp
index 751b6691f..3d7d751a1 100644
--- a/src/render/texture/qabstracttexture.cpp
+++ b/src/render/texture/qabstracttexture.cpp
@@ -103,6 +103,27 @@ void QAbstractTexturePrivate::setDataFunctor(const QTextureGeneratorPtr &generat
  */
 
 /*!
+    \qmltype AbstractTexture
+    \instantiates Qt3DRender::QAbstractTexture
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief A base class to be used to provide textures.
+
+    The AbstractTexture class shouldn't be used directly but rather through one
+    of its subclasses. Each subclass implements a given texture target (2D,
+    2DArray, 3D, CubeMap ...) Each subclass provides a set of functors for each
+    layer, cube map face and mipmap level. In turn the backend uses those
+    functor to properly fill a corresponding OpenGL texture with data. It is
+    expected the functor does as minimal processing as possible so as not to
+    slow down textures generation and upload. If the content of a texture is
+    the result of a slow procedural generation process, it is recommended not
+    to implement this directly in a functor.
+
+    All textures are unique. If you instantiate twice the same texture this
+    will create 2 identical textures on the GPU, no sharing will take place.
+ */
+
+/*!
     \enum Qt3DRender::QAbstractTexture::CubeMapFace
 
     This enum identifies the faces of a cube map texture
@@ -371,6 +392,12 @@ void QAbstractTexture::setSize(int w, int h, int d)
     Holds the width of the texture provider.
  */
 /*!
+    \qmlproperty int Qt3DRender::QAbstractTexture::width
+
+    Holds the width of the texture provider.
+ */
+
+/*!
     Set the width of the texture provider to \a width.
 */
 void QAbstractTexture::setWidth(int width)
@@ -388,6 +415,11 @@ void QAbstractTexture::setWidth(int width)
     Holds the height of the texture provider.
  */
 /*!
+    \qmlproperty int Qt3DRender::QAbstractTexture::height
+
+    Holds the height of the texture provider.
+ */
+/*!
     Set the height to \a height.
 */
 void QAbstractTexture::setHeight(int height)
@@ -405,6 +437,11 @@ void QAbstractTexture::setHeight(int height)
     Holds the depth of the texture provider.
  */
 /*!
+    \qmlproperty int Qt3DRender::QAbstractTexture::depth
+
+    Holds the depth of the texture provider.
+ */
+/*!
     Set the depth of the texture to \a depth.
 */
 void QAbstractTexture::setDepth(int depth)
@@ -453,6 +490,15 @@ int QAbstractTexture::depth() const
     array target formats.
  */
 /*!
+    \qmlproperty int Qt3DRender::QAbstractTexture::layers
+
+    Holds the maximum layer count of the texture provider. By default, the
+    maximum layer count is 1.
+
+    \note this has a meaning only for texture providers that have 3D or
+    array target formats.
+ */
+/*!
     Set the maximum layer count to \a layers.
 */
 void QAbstractTexture::setLayers(int layers)
@@ -486,6 +532,15 @@ int QAbstractTexture::layers() const
     formats.
  */
 /*!
+    \qmlproperty int Qt3DRender::QAbstractTexture::samples
+
+    Holds the number of samples per texel for the texture provider.
+    By default, the number of samples is 1.
+
+    \note this has a meaning only for texture providers that have multisample
+    formats.
+ */
+/*!
     Set the number of samples per texel to \a samples.
 */
 void QAbstractTexture::setSamples(int samples)
@@ -515,6 +570,11 @@ int QAbstractTexture::samples() const
     Holds the format of the texture provider.
  */
 /*!
+    \qmlproperty TextureFormat Qt3DRender::QAbstractTexture::format
+
+    Holds the format of the texture provider.
+ */
+/*!
     Set the texture format to \a format.
 */
 void QAbstractTexture::setFormat(TextureFormat format)
@@ -540,6 +600,11 @@ QAbstractTexture::TextureFormat QAbstractTexture::format() const
 
     Holds the current status of the texture provider.
  */
+/*!
+    \qmlproperty Status Qt3DRender::QAbstractTexture::status readonly
+
+    Holds the current status of the texture provider.
+ */
 
 /*!
     \enum Qt3DRender::QAbstractTexture::Status
@@ -608,6 +673,13 @@ QAbstractTexture::Status QAbstractTexture::status() const
     \note The target format can only be set once.
  */
 /*!
+    \qmlproperty Target Qt3DRender::QAbstractTexture::target readonly
+
+    Holds the target format of the texture provider.
+
+    \note The target format can only be set once.
+ */
+/*!
     \enum Qt3DRender::QAbstractTexture::Target
 
     \value TargetAutomatic
@@ -709,6 +781,11 @@ QVector<QAbstractTextureImage *> QAbstractTexture::textureImages() const
     Holds whether the texture provider should auto generate mipmaps.
  */
 /*!
+    \qmlproperty bool Qt3DRender::QAbstractTexture::generateMipMaps
+
+    Holds whether the texture provider should auto generate mipmaps.
+ */
+/*!
     Boolean parameter \a gen sets a flag indicating whether the
     texture provider should generate mipmaps or not.
 */
@@ -733,6 +810,11 @@ bool QAbstractTexture::generateMipMaps() const
     Holds the minification filter of the texture provider.
  */
 /*!
+    \qmlproperty Filter Qt3DRender::QAbstractTexture::minificationFilter
+
+    Holds the minification filter of the texture provider.
+ */
+/*!
     Set the minification filter to the specified value \a f.
 */
 void QAbstractTexture::setMinificationFilter(Filter f)
@@ -767,6 +849,11 @@ void QAbstractTexture::setMinificationFilter(Filter f)
     Holds the magnification filter of the texture provider.
  */
 /*!
+    \qmlproperty Filter Qt3DRender::QAbstractTexture::magnificationFilter
+
+    Holds the magnification filter of the texture provider.
+ */
+/*!
     Set the magnification filter to \a f.
 */
 void QAbstractTexture::setMagnificationFilter(Filter f)
@@ -796,6 +883,11 @@ QAbstractTexture::Filter QAbstractTexture::magnificationFilter() const
     Holds the wrap mode of the texture provider.
  */
 /*!
+    \qmlproperty QTextureWrapMode Qt3DRender::QAbstractTexture::wrapMode
+
+    Holds the wrap mode of the texture provider.
+ */
+/*!
     Set the wrapmode to the value specified in \a wrapMode.
 */
 void QAbstractTexture::setWrapMode(const QTextureWrapMode &wrapMode)
@@ -836,6 +928,11 @@ QTextureWrapMode *QAbstractTexture::wrapMode()
     Holds the maximum anisotropy of the texture provider.
  */
 /*!
+    \qmlproperty bool Qt3DRender::QAbstractTexture::maximumAnisotropy
+
+    Holds the maximum anisotropy of the texture provider.
+ */
+/*!
     Sets the maximum anisotropy to \a anisotropy.
 */
 void QAbstractTexture::setMaximumAnisotropy(float anisotropy)
@@ -862,6 +959,11 @@ float QAbstractTexture::maximumAnisotropy() const
     Holds the comparison function of the texture provider.
  */
 /*!
+    \qmlproperty ComparisonFunction Qt3DRender::QAbstractTexture::ComparisonFunction
+
+    Holds the comparison function of the texture provider.
+ */
+/*!
     Set the comparison function to \a function.
 */
 void QAbstractTexture::setComparisonFunction(QAbstractTexture::ComparisonFunction function)
@@ -887,6 +989,12 @@ QAbstractTexture::ComparisonFunction QAbstractTexture::comparisonFunction() cons
 
     Holds the comparison mode of the texture provider.
  */
+
+/*!
+    \qmlproperty ComparisonMode Qt3DRender::QAbstractTexture::ComparisonMode
+
+    Holds the comparison mode of the texture provider.
+ */
 /*!
     Set the comparison mode to \a mode.
 */
diff --git a/src/render/texture/qtexture.cpp b/src/render/texture/qtexture.cpp
index 59857ea53..78a995b5d 100644
--- a/src/render/texture/qtexture.cpp
+++ b/src/render/texture/qtexture.cpp
@@ -1041,6 +1041,13 @@ void TextureDownloadRequest::onCompleted()
     \since 5.5
     \brief A QAbstractTexture with a Target1D target format.
  */
+/*!
+    \qmltype Texture1D
+    \instantiates Qt3DRender::QTexture1D
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target1D target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture1D instance with \a parent as parent.
@@ -1062,6 +1069,13 @@ QTexture1D::~QTexture1D()
     \since 5.5
     \brief A QAbstractTexture with a Target1DArray target format.
  */
+/*!
+    \qmltype Texture1DArray
+    \instantiates Qt3DRender::QTexture1DArray
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target1DArray target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture1DArray instance with \a parent as parent.
@@ -1083,6 +1097,13 @@ QTexture1DArray::~QTexture1DArray()
     \since 5.5
     \brief A QAbstractTexture with a Target2D target format.
  */
+/*!
+    \qmltype Texture2D
+    \instantiates Qt3DRender::QTexture2D
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target2D target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture2D instance with \a parent as parent.
@@ -1104,6 +1125,13 @@ QTexture2D::~QTexture2D()
     \since 5.5
     \brief A QAbstractTexture with a Target2DArray target format.
  */
+/*!
+    \qmltype Texture2DArray
+    \instantiates Qt3DRender::QTexture2DArray
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target2DArray target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture2DArray instance with \a parent as parent.
@@ -1125,6 +1153,13 @@ QTexture2DArray::~QTexture2DArray()
     \since 5.5
     \brief A QAbstractTexture with a Target3D target format.
  */
+/*!
+    \qmltype Texture3D
+    \instantiates Qt3DRender::QTexture3D
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target3D target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture3D instance with \a parent as parent.
@@ -1146,6 +1181,13 @@ QTexture3D::~QTexture3D()
     \since 5.5
     \brief A QAbstractTexture with a TargetCubeMap target format.
  */
+/*!
+    \qmltype TextureCubeMap
+    \instantiates Qt3DRender::QTextureCubeMap
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a TargetCubeMap target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTextureCubeMap instance with \a parent as parent.
@@ -1167,6 +1209,13 @@ QTextureCubeMap::~QTextureCubeMap()
     \since 5.5
     \brief A QAbstractTexture with a TargetCubeMapArray target format.
  */
+/*!
+    \qmltype TextureCubeMapArray
+    \instantiates Qt3DRender::QTextureCubeMapArray
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a TargetCubeMapArray target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTextureCubeMapArray instance with \a parent as parent.
@@ -1188,6 +1237,13 @@ QTextureCubeMapArray::~QTextureCubeMapArray()
     \since 5.5
     \brief A QAbstractTexture with a Target2DMultisample target format.
  */
+/*!
+    \qmltype Texture2DMultisample
+    \instantiates Qt3DRender::QTexture2DMultisample
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target2DMultisample target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture2DMultisample instance with \a parent as parent.
@@ -1209,6 +1265,13 @@ QTexture2DMultisample::~QTexture2DMultisample()
     \since 5.5
     \brief A QAbstractTexture with a Target2DMultisampleArray target format.
  */
+/*!
+    \qmltype Texture2DMultisampleArray
+    \instantiates Qt3DRender::QTexture2DMultisampleArray
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a Target2DMultisampleArray target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTexture2DMultisampleArray instance with \a parent as parent.
@@ -1230,6 +1293,13 @@ QTexture2DMultisampleArray::~QTexture2DMultisampleArray()
     \since 5.5
     \brief A QAbstractTexture with a TargetRectangle target format.
  */
+/*!
+    \qmltype TextureRectangle
+    \instantiates Qt3DRender::QTextureRectangle
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a TargetRectangle target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTextureRectangle instance with \a parent as parent.
@@ -1251,6 +1321,13 @@ QTextureRectangle::~QTextureRectangle()
     \since 5.5
     \brief A QAbstractTexture with a TargetBuffer target format.
  */
+/*!
+    \qmltype TextureBuffer
+    \instantiates Qt3DRender::QTextureBuffer
+    \inqmlmodule Qt3D.Render
+    \since 5.5
+    \brief An AbstractTexture with a TargetBuffer target format.
+ */
 
 /*!
     Constructs a new Qt3DRender::QTextureBuffer instance with \a parent as parent.