From 17b2060c1e899842be8c952afc8e0a3329178bc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antti=20M=C3=A4=C3=A4tt=C3=A4?= Date: Fri, 2 Sep 2016 11:17:42 +0300 Subject: Update QTextureImage docs Update QTextureImage docs and add documentation for QTextureImageDataGenerator and QAbstractFunctor Change-Id: Ia2067ee5ee9283727f4f37e342068a02eda4a901 Reviewed-by: Paul Lemire --- src/render/frontend/qabstractfunctor.cpp | 36 +++++++++++++ src/render/texture/qabstracttextureimage.cpp | 41 ++++++++++++++ src/render/texture/qtextureimage.cpp | 81 ++++++++++++++++++++-------- 3 files changed, 137 insertions(+), 21 deletions(-) diff --git a/src/render/frontend/qabstractfunctor.cpp b/src/render/frontend/qabstractfunctor.cpp index f3367a2b5..817d06a27 100644 --- a/src/render/frontend/qabstractfunctor.cpp +++ b/src/render/frontend/qabstractfunctor.cpp @@ -43,8 +43,44 @@ QT_BEGIN_NAMESPACE namespace Qt3DRender { +/*! + \class Qt3DRender::QAbstractFunctor + \inmodule Qt3DRender + \since 5.7 + \brief QAbstractFunctor is an abstract base class for all functors. + + The QAbstractFunctor is used as a base class for all functors and data + generators in Qt3DRender module. + + When user defines a new functor or generator, they need to implement the + \l QAbstractFunctor::id() method, which should be done using the \c {QT3D_FUNCTOR} + macro in the class definition. + */ +/*! + \fn qintptr QAbstractFunctor::id() const + */ +/*! + \macro QT3D_FUNCTOR(Class) + \relates Qt3DRender::QAbstractFunctor + + This macro assigns functor id to the \a Class, which is used by QAbstractFunctor::functor_cast + to determine if the cast can be done. + */ + +/*! + \fn const T *QAbstractFunctor::functor_cast(const QAbstractFunctor *other) const + + This method is used to cast functor \a other to type T if the other is of + type T (or of subclass); otherwise returns 0. This method works similarly + to \l QObject::qobject_cast, except with functors derived from QAbstractFunctor. + + \warning If T was not declared with \l QT3D_FUNCTOR macro, then the results are undefined. + */ + +/*! Desctructor */ QAbstractFunctor::~QAbstractFunctor() { + } } // Qt3D diff --git a/src/render/texture/qabstracttextureimage.cpp b/src/render/texture/qabstracttextureimage.cpp index d3694efc9..42e78ced6 100644 --- a/src/render/texture/qabstracttextureimage.cpp +++ b/src/render/texture/qabstracttextureimage.cpp @@ -48,6 +48,40 @@ using namespace Qt3DCore; namespace Qt3DRender { +/*! + \class Qt3DRender::QTextureImageDataGenerator + \inmodule Qt3DRender + \since 5.7 + \brief Provides texture image data for QAbstractTextureImage + + QTextureImageDataGenerator is a data provider for QAbstractTexture. + QTextureImageDataGenerator can be used to expand Qt3D with more ways to load + texture image data as well as support user-defined formats and formats Qt3D + does not natively support. The data is returned by the QTextureImageDataPtr + which contains the data that will be loaded to the texture. + QTextureImageDataGenerator is executed by Aspect jobs in the backend. + */ +/*! + \typedef Qt3DRender::QTextureImageDataPtr + \relates Qt3DRender::QTextureImageDataGenerator + + Shared pointer to \l QTextureImageData. +*/ + +/*! + \fn QTextureImageDataPtr QTextureImageDataGenerator::operator()() + + Implement the method to return the texture image data. +*/ + +/*! + \fn bool QTextureImageDataGenerator::operator ==(const QTextureImageDataGenerator &other) const + + Implement the method to compare this texture data generator to \a other. + The operator is used to check if the \l QAbstractTextureImage needs to reload + the \l QTextureImageData. +*/ + QAbstractTextureImagePrivate::QAbstractTextureImagePrivate() : QNodePrivate(), m_mipLevel(0), @@ -89,6 +123,13 @@ QAbstractTextureImagePrivate::~QAbstractTextureImagePrivate() behavior at best if this rule is not respected. */ +/*! + \fn QTextureImageDataGeneratorPtr QAbstractTextureImage::dataGenerator() const + + Implement this method to return the \l QTextureImageDataGeneratorPtr, which will + provide the data for the texture image. +*/ + /*! Constructs a new QAbstractTextureImage instance with \a parent as parent. */ diff --git a/src/render/texture/qtextureimage.cpp b/src/render/texture/qtextureimage.cpp index dab92082a..dbe0ff05c 100644 --- a/src/render/texture/qtextureimage.cpp +++ b/src/render/texture/qtextureimage.cpp @@ -70,6 +70,59 @@ namespace Qt3DRender { image from an image source. */ +/*! + \enum QTextureImage::Status + + This enumeration specifies the status values for texture image loading. + + \value None The texture image loading has not been started yet. + \value Loading The texture image loading has started, but not finised. + \value Ready The texture image loading has finished. + \value Error The texture image loading confronted an error. +*/ + +/*! + \qmlproperty url TextureImage::source + + This property holds the source url from which data for the texture + image will be loaded. +*/ + +/*! + \qmlproperty enumeration TextureImage::status + + This property holds the status of the texture image loading. + + \list + \li TextureImage.None + \li TextureImage.Loading + \li TextureImage.Ready + \li TextureImage.Error + \endlist + \readonly +*/ + +/*! + \property QTextureImage::source + + This property holds the source url from which data for the texture + image will be loaded. +*/ + +/*! + \property QTextureImage::status + + This property holds the status of the texture image loading. + + \list + \li TextureImage.None + \li TextureImage.Loading + \li TextureImage.Ready + \li TextureImage.Error + \endlist + \readonly +*/ + /*! Constructs a new Qt3DRender::QTextureImage instance with \a parent as parent. */ @@ -93,7 +146,7 @@ QUrl QTextureImage::source() const } /*! - * \return the current status. + \return the current status. */ QTextureImage::Status QTextureImage::status() const { @@ -101,20 +154,6 @@ QTextureImage::Status QTextureImage::status() const return d->m_status; } -/*! - \property Qt3DRender::QTextureImage::source - - This property holds the source url from which data for the texture - image will be loaded. -*/ - -/*! - \qmlproperty url Qt3D.Render::TextureImage::source - - This property holds the source url from which data for the texture - image will be loaded. -*/ - /*! Sets the source url of the texture image to \a source. \note This triggers a call to update() @@ -130,8 +169,8 @@ void QTextureImage::setSource(const QUrl &source) } /*! - * Sets the status to \a status. - * \param status + Sets the status to \a status. + \param status */ void QTextureImage::setStatus(Status status) { @@ -152,8 +191,8 @@ QTextureImageDataGeneratorPtr QTextureImage::dataGenerator() const } /*! - * Sets the scene change event to \a change. - * \param change + Sets the scene change event to \a change. + \param change */ void QTextureImage::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change) { @@ -164,8 +203,8 @@ void QTextureImage::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change) } /*! - * The constructor creats a new QImageTextureDataFunctor::QImageTextureDataFunctor - * instance with the specified \a url. + The constructor creates a new QImageTextureDataFunctor::QImageTextureDataFunctor + instance with the specified \a url. */ QImageTextureDataFunctor::QImageTextureDataFunctor(const QUrl &url) : QTextureImageDataGenerator() -- cgit v1.2.3