Merge branch '1.0'

Change-Id: If4c3a20161e5120b85aba0ee30a38ab6cca0fa16

11 files changed, 402 insertions, 91 deletions

diff --git a/doc/qt3dstudio-project.qdocconf b/doc/qt3dstudio-project.qdocconf
index 130eb14c..189cf4ff 100644
--- a/doc/qt3dstudio-project.qdocconf
+++ b/doc/qt3dstudio-project.qdocconf
@@ -3,7 +3,7 @@ description             = Qt 3D Studio Reference Manual
 version                 = $QT_VERSION
 
 sources.fileextensions  = "*.qdoc *.html"
-sourcedirs              = ./src \
+sourcedirs              = . \
                           ../src/Viewer
 
 headerdirs              = ../src/Viewer
@@ -42,7 +42,7 @@ qhp.Qt3DStudio.subprojects.classes.sortPages  = true
 
 
 # Add an .html file with sidebar content, used in the online style
-#HTML.stylesheets             += style/qt5-sidebar.html
+HTML.stylesheets             += style/qt5-sidebar.html
 
 # ensure all images are included
 #HTML.extraimages             += ./src/static/Runtime-AODistances.jpg
@@ -52,3 +52,9 @@ navigation.homepage            = Qt 3D Studio
 navigation.cppclassespage      = Qt 3D Studio C++ Classes
 navigation.qmltypespage        = Qt 3D Studio QML Types
 buildversion                   = "Qt 3D Studio $QT_VER Manual"
+
+examplesinstallpath     = studio3d
+exampledirs            += ../examples/studio3d
+
+manifestmeta.highlighted.names = \
+                "QtStudio3D/Qt 3D Studio: Dynamic Keyframes Example"
diff --git a/doc/src/00-concepts.qdoc b/doc/src/00-concepts.qdoc
index 0fbad4d4..bec19c93 100644
--- a/doc/src/00-concepts.qdoc
+++ b/doc/src/00-concepts.qdoc
@@ -46,35 +46,42 @@
     \li \l {Integrating with Qt 3D Studio}
     \endomit
     \li \l {Best Practices}
-    \omit
+    \li \l {Requirements}
+    \li \l {Examples}
     \li \l {Copyright Notices}
-    \endomit
 \endlist
 
 \section1 Applications
 
 The Qt 3D Studio suite includes:
-
-\section2 Studio
-
-\image studio_128.png
-
-An authoring tool for creating interactive 3D presentations and applications. Studio is exclusively
-available for Windows PCs.
-
-\section2 Viewer
-
-\image viewer_128.png
-
-A runtime player to test and deploy interfaces created in Studio. The Viewer is currently available
-for PC, with more devices planned.
+\table
+  \header
+    \li \section2 Studio
+    \li \section2 Viewer
+  \row
+    \li \inlineimage studio_128.png
+    \li \inlineimage viewer_128.png
+  \row
+    \li An authoring tool for creating interactive 3D presentations and applications.
+    \li A runtime player to test and deploy interfaces created in Studio.
+  \row
+    \li
+      \list
+        \li \l {Getting started}
+        \li \l {Studio Index}
+      \endlist
+    \li
+      \list
+        \li \l {Viewer Index}
+      \endlist
+\endtable
 
 \section1 Concepts
 
 \section2 Project
 
 A \e{\"project\"} is simply a folder on your computer holding all the art and other assets needed
-for your application. You can create a \e project by creating folders on your favorite OS, or you
+for your application. You can create a \e project by creating folders in your file system, or you
 can also have a template project created for you (with suggested folders for organization) from
 \l Studio application.
 
diff --git a/doc/src/05-runtime/1-event-processing.qdoc b/doc/src/05-runtime/1-event-processing.qdoc
index 8cbae5ee..73f613e1 100644
--- a/doc/src/05-runtime/1-event-processing.qdoc
+++ b/doc/src/05-runtime/1-event-processing.qdoc
@@ -32,47 +32,6 @@
 \page runtime-event-processing.html
 \ingroup qt3dstudio-runtime
 
-\omit
-There are three different event systems in
-the Qt 3D Studio Runtime:
-
-\list
-\li
-  \e{External Events} arrive from outside the
-  system (e.g. from the CAN bus, a keyboard, a game controller) via
-  plugins that expose a queue of events each frame to your application.
-  These events must be explicitly received and handled by your
-  application.
-\li
-  \e{State Machine Events} occur within each
-  state machine running in your application, possibly causing the state
-  machine to possibly change states.
-\li
-  \l{presentation-events}{Presentation Events} occur within each
-  presentation (e.g. touch events, slide changes, Lua script), bubbling
-  up the scene graph of elements within the presentation.
-\endlist
-
-\target external-events
-\section1 External Events
-
-\list
-\li
-  \e{TODO: document the handling of events, with an example App.lua
-  with links to the Lua functions and also to the reference for writing
-  plugins.}
-\endlist
-
-\target state-machine-events
-\section1 State Machine Events
-
-\list
-\li
-  \e{TODO: document the firing of events on state machines, with
-  links to the Lua functions.}
-\endlist
-\endomit
-
 \target presentation-events
 \section1 Presentation Events
 
@@ -136,13 +95,10 @@ runtime, a piece of logic gets created representing this action. When
 the onSelect event is fired and later processed, the interested logic
 will be notified and the slide change will occur.
 
-\omit
-TODO: Needs to be rewritten?
-Note that behavior event registrations (created with Lua's
+\note Behavior event registrations (created with \l {Behavior}{QML Behavior}
 registerForEvent) work similarly to the logic described above. If a
-script registers explicitly for a certain event and in the handler calls
+behavior registers explicitly for a certain event and in the handler calls
 goToSlide, essentially the same things happen.
-\endomit
 
 \section3 Changing Properties
 
@@ -154,40 +110,34 @@ will result in changed properties if a master object inside of Studio
 has one or more of its properties unlinked from the master slide and
 that property is changed per-slide.
 
-\omit
-\section3 Executing Script
+\section3 Executing Behavior Callbacks
 
-Processing an event can result in arbitrary script code being executed.
-An event registration can be created by using the registerForEvent
+Processing an event can result in arbitrary QML Behavior callback code
+being executed. An event registration can be created by using the registerForEvent
 function to listen for a specific event on a specific element. The
 registration also has a callback function associated with it and when
-that specific event targeting that element is processed, the script
+that specific event targeting that element is processed, the behavior
 callback function will be executed.
 
-Of course, script can inspect and change properties on various elements,
-affect slide changes, fire more events, etc. Being able to respond to
-events being processed really empowers scripting.
-\endomit
+Of course, behavior can inspect and change properties on various elements,
+affect slide changes, fire more events, etc.
 
-\omit
-TODO: Needs to be rewritten.
 \section3 Firing More Events (Cascading)
 
 There are two ways a presentation may fire an event in response to
-another event. The first way is through script as described above, and
+another event. The first way is through behaviors as described above, and
 the second way is through the action palette.
 
 Behaviors in Studio can have arbitrary Custom Events associated with
 them by adding these custom events in the header section of the
-behavior's .lua file. When a behavior with one or more Custom Events is
+behavior's .qml file. When a behavior with one or more Custom Events is
 the target of an action in the action palette Studio will offer the Fire
 Event action. By using this action, arbitrary cascading events can be
-set up to fire by pointing and clicking. (as opposed to scripting).
+set up to fire by pointing and clicking.
 
-It's worth repeating that these cascading events will all be processed
+\note These cascading events will all be processed
 in the same frame. The event processor doesn't stop processing events
 until there are none left to process.
-\endomit
 
 \section2 How Your Application (C++) Interacts with Event Processing
 
diff --git a/doc/src/06-qml-reference/Behavior.qdoc b/doc/src/06-qml-reference/Behavior.qdoc
new file mode 100644
index 00000000..da14c638
--- /dev/null
+++ b/doc/src/06-qml-reference/Behavior.qdoc
@@ -0,0 +1,209 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype Behavior
+    \brief Technology Preview Behavior Integration
+
+    This is a technology preview (API may change in upcoming version) of how
+    Qt 3D Studio could support writing custom behavior scripts using QML and
+    JavaScript. It enables interacting with the runtime using the Behavior
+    QML class exposed to each behavior script.
+
+    In QML behavior script, the integration to Qt 3D Studio is established by using
+    the metadata tag system similar to the \l {file-formats-effects.html}{effect}
+    and \l {file-formats-material.html}{material} files.
+
+    \badcode
+[[
+<Property name="somePropertyName" ... />
+
+<Handler name="someHandlerName" ... />
+
+<Event name="onSomeEvent" ... />
+...
+]]
+    \endcode
+
+    Secondly, the QML behavior script needs access to the QML module.
+    \badcode
+import QtStudio3D.Behavior 1.0
+    \endcode
+
+    Finally, the Behavior type needs to be implemented in the qml script.
+    \badcode
+Behavior {
+    id: mybehavior
+
+    function onInitialize() {
+        ...
+    }
+
+    function onActivate() {
+        ...
+    }
+
+    function onUpdate() {
+        ...
+    }
+
+    function onDeactivate() {
+        ...
+    }
+
+    function someHandlerName() {
+        ...
+        fireEvent("onSomeEvent")
+    }
+}
+    \endcode
+*/
+
+/*!
+    \qmlmethod float Behavior::getDeltaTime()
+
+    Returns the delta time between this and previous frame in milliseconds.
+*/
+
+/*!
+    \qmlmethod float Behavior::getAttribute(string attribute)
+
+    Returns the value of the given \a attribute.
+*/
+
+/*!
+    \qmlmethod void Behavior::setAttribute(string attribute, var value)
+
+    Sets the \a value of the given \a attribute.
+*/
+
+/*!
+    \qmlmethod void Behavior::setAttribute(string handle, string attribute, var value)
+
+    Sets the \a value of the given \a attribute for a given \a handle.
+*/
+
+/*!
+    \qmlmethod void Behavior::fireEvent(string event)
+
+    Fires the given \a event.
+*/
+
+/*!
+    \qmlmethod void Behavior::registerForEvent(string event, QJSValue function)
+
+    Registers the script for an \a event with the handler \a function.
+*/
+
+/*!
+    \qmlmethod void Behavior::registerForEvent(string handle, string event, QJSValue function)
+
+    Registers the script for an \a event with the handler \a function for a given \a handle.
+*/
+
+/*!
+    \qmlmethod void Behavior::unregisterForEvent(string event)
+
+    Unregisters the script from an \a event.
+*/
+
+/*!
+    \qmlmethod void Behavior::unregisterForEvent(string handle, string event)
+
+    Unregisters the script from an \a event for a given \a handle.
+*/
+
+/*!
+    \qmlmethod vector2d Behavior::getMousePosition()
+
+    Returns the current position of the mouse in presentation coordinates.
+*/
+
+/*!
+    \qmlmethod matrix4 Behavior::calculateGlobalTransform(string handle)
+
+    Returns the current global transformation of the element specified by the
+    \a handle or parent element if the handle is empty string.
+*/
+
+/*!
+    \qmlmethod vector3d Behavior::lookAt(vector3d target)
+
+    Returns the rotation angles of the look at \a target.
+*/
+
+/*!
+    \qmlmethod string Behavior::getParent(string handle)
+
+    Returns the parent of the given \a handle or parent element if the handle is
+    empty string.
+*/
+
+/*!
+    \qmlmethod vector3d Behavior::matrixToEuler(matrix4 matrix)
+
+    Returns the euler angles extracted from the \a matrix rotations.
+*/
+
+/*!
+    \qmlsignal void Behavior::onInitialize()
+
+    This signal is emitted when the script becomes active the first time.
+    If multiple behaviors match this, the signal for parent elements will
+    occur before their children/descendants. \note Each behavior will
+    only have its \c{onInitialize} signaled once, even if it is deactivated and
+    later reactivated.
+ */
+
+/*!
+    \qmlsignal void Behavior::onActivate()
+
+    This signal is emitted when the script becomes active.
+    Any behaviors which were not active last frame that are active
+    this frame will have their \c{onActivate} signaled. If
+    multiple behaviors match this, the signal for parent elements will
+    occur before their descendants.
+ */
+
+/*!
+    \qmlsignal void Behavior::onDeactivate()
+
+    This signal is emitted when the script becomes inactive.
+    Any behaviors which were active last frame that are not active
+    this frame will have their \c{onDeactivate} signaled. If
+    multiple behaviors match this, the signal for parent elements will
+    occur before their descendants.
+ */
+
+/*!
+    \qmlsignal void Behavior::onUpdate()
+
+    This signal is emitted on each frame when the script is active.
+    Any behaviors that are active this frame will have their
+    \c{onUpdate} signaled. If multiple behaviors match this, the signal
+    for parent elements will occur before their descendants.
+ */
diff --git a/doc/src/06-qml-reference/Qt3DS_QML_Texture_Streaming.qdoc b/doc/src/06-qml-reference/Qt3DS_QML_Texture_Streaming.qdoc
index 2f7fe2af..e58ad402 100644
--- a/doc/src/06-qml-reference/Qt3DS_QML_Texture_Streaming.qdoc
+++ b/doc/src/06-qml-reference/Qt3DS_QML_Texture_Streaming.qdoc
@@ -28,9 +28,9 @@
 /*!
     \qmltype SubPresentationSettings
     \inqmlmodule QtStudio3D 1.0
-    \brief Settings for subpresentations.
+    \brief Settings for sub-presentations.
 
-    This type enables specifying settings for the subpresentations
+    This type enables specifying settings for the sub-presentations
     from Qt Quick application.
 
     \note Currently only 'presentation-qml' settings can be set.
@@ -61,7 +61,7 @@
 /*!
     \qmlproperty list<QmlStream> SubPresentationSettings::qmlStreams
 
-    Holds the list of settings for 'presentation-qml' subpresentations.
+    Holds the list of settings for \c presentation-qml sub-presentations.
  */
 
 /*!
@@ -69,10 +69,10 @@
     \inqmlmodule QtStudio3D
     \brief QML stream.
 
-    This type allows attaching qml-subpresentation with a quick item. The item is rendered to a
+    This type allows attaching QML sub-presentation with a quick item. The item is rendered to a
     texture and used as a part of a Qt 3D Studio presentation.
 
-    The subpresentation element must be specified in the \e assets element of the presentation
+    The sub-presentation element must be specified in the \e assets element of the presentation
     .uia file:
 
      \badcode
@@ -81,22 +81,22 @@
      </assets>
      \endcode
 
-    The 'presentation-id' attribute must contain a unique ID of the subpresentation.
-    The 'args' attribute may contain an optional preview version of the item, which is only
+    The \c presentation-id attribute must contain a unique ID of the sub-presentation.
+    The \c args attribute may contain an optional preview version of the item, which is only
     used in the Viewer application.
  */
 
 /*!
     \qmlproperty string QmlStream::presentationId
 
-    Holds the string ID of the subpresentation the item is attached to. The id must be one of
-    the 'presentation-qml' IDs specified in the .uia file.
+    Holds the string ID of the sub-presentation the item is attached to. The id must be one of
+    the \c presentation-qml IDs specified in the .uia file.
  */
 
 /*!
     \qmlproperty Item QmlStream::item
 
-    Holds the item attached to the subpresentation. The item size is used as the the size of the
+    Holds the item attached to the sub-presentation. The item size is used as the the size of the
     texture the item is rendered to. Default values \c{(256, 256)} are used if the item doesn't
     specify a size.
  */
diff --git a/doc/src/06-qml-reference/qml-index.qdoc b/doc/src/06-qml-reference/qml-index.qdoc
index 97fabb75..e8b690ff 100644
--- a/doc/src/06-qml-reference/qml-index.qdoc
+++ b/doc/src/06-qml-reference/qml-index.qdoc
@@ -44,6 +44,10 @@ import QtStudio3D 1.0
 
 \generatelist {qmltypesbymodule QtStudio3D}
 
+\section1 QML Behavior Script
+
+\l Behavior
+
 \section1 Additional Information
 
 //! [toc]
diff --git a/doc/src/examples-index.qdoc b/doc/src/examples-index.qdoc
new file mode 100644
index 00000000..e4ad81b8
--- /dev/null
+++ b/doc/src/examples-index.qdoc
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title Examples
+\ingroup qml-examples
+\page qtstudio3d-qml-examples.html
+\noautolist
+
+\section1 QML Examples
+
+\list
+     \li \l {Qt 3D Studio: Dynamic Keyframes Example}
+     \li \l {Qt 3D Studio: QML Streamer Example}
+\endlist
+
+*/
diff --git a/doc/src/images/studio_128.png b/doc/src/images/studio_128.png
index ae896d0a..a6a90b51 100644
--- a/doc/src/images/studio_128.png
+++ b/doc/src/images/studio_128.png
diff --git a/doc/src/images/viewer_128.png b/doc/src/images/viewer_128.png
index 19f52b12..c3d89639 100644
--- a/doc/src/images/viewer_128.png
+++ b/doc/src/images/viewer_128.png
diff --git a/doc/src/requirements.qdoc b/doc/src/requirements.qdoc
new file mode 100644
index 00000000..8ddcd950
--- /dev/null
+++ b/doc/src/requirements.qdoc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\title Requirements
+\page requirements.html
+
+\section1 Supported Target HW Operating Systems and HW Requirements
+
+\section2 Qt 3D Studio 1.0 Editor
+
+The editor for desktop has been tested to work with OpenGL 4.1 and later. If you experience any
+issues or graphical glitches, please update your graphics driver to the latest version.
+We have found that this resolves most of the problems immediately.
+
+Tested operating systems for the editor:
+\list
+  \li Windows 10
+  \li macOS High Sierra (10.13)
+  \li macOS Sierra (10.12)
+  \li macOS El Capitan (10.11)
+\endlist
+
+\section2 Qt 3D Studio 1.0 Runtime
+
+The QML runtime component requires OpenGL ES 3.1 to work reliably. While there was some work done to
+enable at least partial support for OpenGL ES 2, we do not recommend using it at this point due
+to its maturity.
+
+Tested operating systems for the runtime:
+\list
+  \li Windows 10 + MSVC 2015
+  \li Windows 7 + mingw32
+  \li macOS Sierra (10.12)
+  \li macOS El Capitan (10.11)
+  \li Android 8.0 (ARMv7)
+  \li QNX 7.0 (x64)
+  \li GHS Integrity
+\endlist
+
+Tested target devices:
+\list
+  \li Google Pixel C with Android 8.0
+  \li NVIDIA Jetson TX1 with Boot2Qt
+  \li Intel NUC (NUC6CAY) with Boot2Qt
+  \li NVIDIA drive CX1
+\endlist
+
+*/
diff --git a/doc/style/qt5-sidebar.html b/doc/style/qt5-sidebar.html
new file mode 100644
index 00000000..fb25b054
--- /dev/null
+++ b/doc/style/qt5-sidebar.html
@@ -0,0 +1,20 @@
+<div class="sectionlist normallist">
+    <div class="heading">
+        <a name="reference"></a>
+        <h2 id="reference">Qt 3D Studio</h2>
+    </div>
+    <div class="indexboxcont indexboxbar">
+      <ul>
+        <li><a href="getting-started.html">Getting Started</a></li>
+        <li><a href="qt3dstudio-studio.html">Studio</a></li>
+        <li><a href="qt3dstudio-viewer.html">Viewer</a></li>
+        <li><a href="qtstudio3d-qmlmodule.html">QML API Reference</a></li>
+        <li><a href="qtstudio3d-module.html">C++ API Reference</a></li>
+        <li><a href="qt3dstudio-runtime.html">Runtime</a></li>
+        <li><a href="qt3dstudio-file-formats.html">File Formats</a></li>
+        <li><a href="qt3dstudio-best-practices.html">Best Practices</a></li>
+        <li><a href="requirements.html">Requirements</a></li>
+        <li><a href="qtstudio3d-qml-examples.html">Examples</a></li>
+        <li><a href="copyright-notices.html">Copyright Notices</a></li>
+      </ul>
+    </div>