Harmonize slide indexing between Q3DSPresentation and Q3DSSceneElement

Make SceneElement slide indexing follow the original NDD scheme where slide
index 1 corresponds to the first slide. (Note that this requires changes
to applications relying on SceneElement client API.) Fix autotests. Add a
remark about indexing in docs.

Task-id: QT3DS-4034
Change-Id: I12328830193a148e2198ad74c450163e9e4600c9
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>

3 files changed, 21 insertions, 17 deletions

diff --git a/src/api/studio3d/q3dspresentation.cpp b/src/api/studio3d/q3dspresentation.cpp
index ad8413d..3b02e01 100644
--- a/src/api/studio3d/q3dspresentation.cpp
+++ b/src/api/studio3d/q3dspresentation.cpp
@@ -823,7 +823,7 @@ void Q3DSPresentation::setShaderCacheFile(const QUrl &fileName)
 
     Requests a time context (a Scene or a Component object) to change
     to a specific slide by \a index. If the context is already on that
-    slide, playback will start over.
+    slide, playback will start over. Slide indexing starts from one.
 
     If \a elementPath points to a time context, that element is
     controlled. For all other element types the time context owning
@@ -1597,7 +1597,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     Emitted when a slide in a presentation or component is entered. \a elementPath
     specifies the slide path. \a index and \a name contain the index and
-    the name of the entered slide.
+    the name of the entered slide. Slide indexing starts from one.
 
     This signal is emitted for each component, meaning that it can be emitted multiple
     times on one slide change.
@@ -1608,7 +1608,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     Emitted when a slide in a presentation or component is entered. \a elementPath
     specifies the slide path. \a index and \a name contain the index and
-    the name of the entered slide.
+    the name of the entered slide. Slide indexing starts from one.
 
     This signal is emitted for each component, meaning that it can be emitted multiple
     times on one slide change.
@@ -1619,7 +1619,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     Emitted when a slide in a presentation or component is exited. \a elementPath
     specifies the slide path. \a index and \a name contain the index and
-    the name of the exited slide.
+    the name of the exited slide. Slide indexing starts from one.
 
     This signal is emitted for each component, meaning that it can be emitted multiple
     times on one slide change.
@@ -1630,7 +1630,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     Emitted when a slide in a presentation or component is exited. \a elementPath
     specifies the slide path. \a index and \a name contain the index and
-    the name of the exited slide.
+    the name of the exited slide. Slide indexing starts from one.
 
     This signal is emitted for each component, meaning that it can be emitted multiple
     times on one slide change.
diff --git a/src/api/studio3d/q3dssceneelement.cpp b/src/api/studio3d/q3dssceneelement.cpp
index 8de03eb..f241d95 100644
--- a/src/api/studio3d/q3dssceneelement.cpp
+++ b/src/api/studio3d/q3dssceneelement.cpp
@@ -112,6 +112,7 @@ Q3DSSceneElement::~Q3DSSceneElement()
     \qmlproperty int SceneElement::currentSlideIndex
 
     Holds the index of the currently active slide of the tracked time context.
+    Slide indexing starts from one.
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
@@ -125,6 +126,7 @@ Q3DSSceneElement::~Q3DSSceneElement()
     \property Q3DSSceneElement::currentSlideIndex
 
     Holds the index of the currently active slide of the tracked time context.
+    Slide indexing starts from one.
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
@@ -132,6 +134,8 @@ Q3DSSceneElement::~Q3DSSceneElement()
     desired one. This happens in order to ensure we end up with the index of
     the slide that is actually shown even if the slide specified in the initial
     declaration is invalid.
+
+    \sa Q3DSPresentation::slideEntered()
 */
 int Q3DSSceneElement::currentSlideIndex() const
 {
@@ -144,13 +148,13 @@ void Q3DSSceneElement::setCurrentSlideIndex(int currentSlideIndex)
     Q_D(Q3DSSceneElement);
     if (d->m_viewerApp) {
         const QByteArray path(d->m_elementPath.toUtf8());
-        d->m_viewerApp->GoToSlideByIndex(path, currentSlideIndex + 1);
+        d->m_viewerApp->GoToSlideByIndex(path, currentSlideIndex);
     } else if (d->m_commandQueue) {
         d->m_commandQueue->queueCommand(d->m_elementPath, CommandType_GoToSlide,
-                                            int(currentSlideIndex + 1));
+                                        currentSlideIndex);
     } else {
         // Store desired slide until we have either app or queue. Only name or index can be set.
-        d->m_initialSlideIndex = currentSlideIndex + 1;
+        d->m_initialSlideIndex = currentSlideIndex;
         d->m_initialSlideName.clear();
     }
 }
@@ -218,7 +222,7 @@ void Q3DSSceneElement::setCurrentSlideName(const QString &currentSlideName)
     } else {
         // Store desired slide until we have either app or queue. Only name or index can be set.
         d->m_initialSlideName = currentSlideName;
-        d->m_initialSlideIndex = 0;
+        d->m_initialSlideIndex = 1;
     }
 }
 
@@ -366,12 +370,12 @@ void Q3DSSceneElementPrivate::setViewerApp(Q3DSViewer::Q3DSViewerApp *app)
 
         // If user has set current slide before viewer app has been set for the first time,
         // we will switch to the desired slide after we initialize.
-        if (m_initialSlideIndex != 0)
-            q->setCurrentSlideIndex(m_initialSlideIndex - 1);
+        if (m_initialSlideIndex != 1)
+            q->setCurrentSlideIndex(m_initialSlideIndex);
         else if (!m_initialSlideName.isEmpty())
             q->setCurrentSlideName(m_initialSlideName);
 
-        m_initialSlideIndex = 0;
+        m_initialSlideIndex = 1;
         m_initialSlideName.clear();
     }
 }
@@ -396,12 +400,12 @@ void Q3DSSceneElementPrivate::setCommandQueue(CommandQueue *queue)
         m_slideInfoRequestPending = true;
         // If user has set current slide before the queue has been set for the first time,
         // we will switch to the desired slide after we initialize.
-        if (m_initialSlideIndex != 0)
-            q->setCurrentSlideIndex(m_initialSlideIndex - 1);
+        if (m_initialSlideIndex != 1)
+            q->setCurrentSlideIndex(m_initialSlideIndex);
         else if (!m_initialSlideName.isEmpty())
             q->setCurrentSlideName(m_initialSlideName);
 
-        m_initialSlideIndex = 0;
+        m_initialSlideIndex = 1;
         m_initialSlideName.clear();
     }
 }
diff --git a/tests/auto/studio3d/q3dssurfaceviewer/tst_q3dssurfaceviewer.cpp b/tests/auto/studio3d/q3dssurfaceviewer/tst_q3dssurfaceviewer.cpp
index ccda520..a4b5aa2 100644
--- a/tests/auto/studio3d/q3dssurfaceviewer/tst_q3dssurfaceviewer.cpp
+++ b/tests/auto/studio3d/q3dssurfaceviewer/tst_q3dssurfaceviewer.cpp
@@ -1249,7 +1249,7 @@ void tst_Q3DSSurfaceViewer::testSceneElement()
     QCOMPARE(spy1.count(), 6);
     QCOMPARE(spy2.count(), 6);
 
-    scene->setCurrentSlideIndex(0);
+    scene->setCurrentSlideIndex(1);
     checkPixel(m_viewer, Qt::red);
 
     QCOMPARE(spy1.count(), 7);
@@ -1305,7 +1305,7 @@ void tst_Q3DSSurfaceViewer::testSceneElement()
     QCOMPARE(spy2.count(), 11);
 
     // Back to first slide for further tests
-    scene->setCurrentSlideIndex(0);
+    scene->setCurrentSlideIndex(1);
     checkPixel(m_viewer, Qt::red);
 
     QCOMPARE(spy1.count(), 12);