diff options
| -rw-r--r-- | examples/quick3d/xr_simple/doc/src/qtquick3d-examples-xrsimple.qdoc | 4 | ||||
| -rw-r--r-- | src/quick3d/doc/qtquick3d.qdocconf | 2 | ||||
| -rw-r--r-- | src/quick3d/doc/src/qtquick3d-index.qdoc | 6 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-apple-vision-pro-quick-start.qdoc | 37 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-examples.qdoc | 18 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-installing.qdoc | 63 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-known-issues.qdoc | 26 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-overview.qdoc | 109 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-permissions.qdoc | 26 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-qml-module.qdoc | 11 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-quick-starter-guide.qdoc | 40 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-supported-platforms.qdoc | 32 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr-toc.qdoc | 69 | ||||
| -rw-r--r-- | src/quick3d/doc/src/xr/qt3dxr.qdoc | 45 |
14 files changed, 487 insertions, 1 deletions
diff --git a/examples/quick3d/xr_simple/doc/src/qtquick3d-examples-xrsimple.qdoc b/examples/quick3d/xr_simple/doc/src/qtquick3d-examples-xrsimple.qdoc index 2cc68349..73abd8bd 100644 --- a/examples/quick3d/xr_simple/doc/src/qtquick3d-examples-xrsimple.qdoc +++ b/examples/quick3d/xr_simple/doc/src/qtquick3d-examples-xrsimple.qdoc @@ -4,8 +4,12 @@ /*! \example xr_simple \ingroup quick3d-examples + \ingroup qt3dxr-examples \title Qt Quick 3D - XR Simple Example \examplecategory {3D} \brief Demonstrates setting up a simple VR scene with Qt Quick 3D XR. \image xrsimple-example.jpg + + As with any XR application the root item of our main.qml is an XrView. + */ diff --git a/src/quick3d/doc/qtquick3d.qdocconf b/src/quick3d/doc/qtquick3d.qdocconf index 49207555..610a5f13 100644 --- a/src/quick3d/doc/qtquick3d.qdocconf +++ b/src/quick3d/doc/qtquick3d.qdocconf @@ -80,7 +80,7 @@ navigation.qmltypespage = "Qt Quick 3D QML Types" navigation.cppclassespage = "Qt Quick 3D C++ Classes" tagfile = qtquick3d.tags - +macro.qxr = "Qt Quick 3D Xr" # Fail the documentation build if warnings exceed the limit # src/quick3d/qquick3dtexture.cpp:653: (qdoc) warning: Can't link to 'RenderExtension' warninglimit = 1 diff --git a/src/quick3d/doc/src/qtquick3d-index.qdoc b/src/quick3d/doc/src/qtquick3d-index.qdoc index 94ab989f..a85d3f30 100644 --- a/src/quick3d/doc/src/qtquick3d-index.qdoc +++ b/src/quick3d/doc/src/qtquick3d-index.qdoc @@ -13,6 +13,8 @@ provides extensions to the existing \l{Qt Quick Scene Graph} for spatial content and a renderer for that extended scene graph. When using the spatial scene graph, it's possible to mix Qt Quick 2D content with 3D content. +Qt Quick 3D also provides for XR and VR applications with \l{\qxr}. + \image dragon.jpg \section1 Using the Module @@ -27,6 +29,7 @@ The following module imports provide additional functionality: import QtQuick3D.AssetUtils import QtQuick3D.Helpers import QtQuick3D.Particles3D +import QtQuick3D.Xr \endqml \section2 C++ API @@ -76,6 +79,7 @@ and functionality that were done for the Qt 6 series of Qt. \li \l{Qt Quick 3D Level of Detail}{Level of Detail} \li \l{Custom Material Editor}{Custom Material Editor} \li \l{quick3d-lightmap}{Lightmaps and Global Illumination} + \li \l{\qxr Overview} \endlist \section1 Examples @@ -94,6 +98,7 @@ and functionality that were done for the Qt 6 series of Qt. \li \l{Qt Quick 3D - Custom Geometry Example}{Adding Custom Geometry from C++} \li \l{Qt Quick 3D - Procedural Texture Example}{Adding Custom Texture Data from C++} \li \l{Qt Quick 3D - Baked Lightmap Example}{Using baked lightmaps} + \li \l{Qt Quick 3D - XR Simple Example}{Demonstrates setting up a simple VR scene} \li \l{Qt Quick 3D Examples and Tutorials}{All examples} \endlist @@ -105,6 +110,7 @@ and functionality that were done for the Qt 6 series of Qt. \li \l{QtQuick3D.AssetUtils QML Types} {Qt Quick 3D Asset Utility QML Types} \li \l{Qt Quick 3D Particles3D QML Types} + \li \l{\qxr} \endlist \section1 Related Modules diff --git a/src/quick3d/doc/src/xr/qt3dxr-apple-vision-pro-quick-start.qdoc b/src/quick3d/doc/src/xr/qt3dxr-apple-vision-pro-quick-start.qdoc new file mode 100644 index 00000000..7a78c825 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-apple-vision-pro-quick-start.qdoc @@ -0,0 +1,37 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \page qt3dxr-quick-start-guide-applevisionpro.html + \title Getting Started With the Apple Vision Pro + + \summary This topic provides instructions on how to get up and running + with \qxr on an Apple Vision Pro. + + + For the Meta Quest 3 see \l{\qxr Quick Starter Guide}. + The video below demonstrates the process. + + //!TODO Add video link + + \section1 Download and installation + + Complete the steps on the \l{Installing \qxr} page. + + \section1 Setting up the Simple Example Project + \list 1 + \li Open the example project from the qt creator welcome screen. + \li Configure the project settings (Projects mode: Ctrl+5 by default) + \list 1 + \li Confirm that the applicable Android Kit for your target device is + chosen for compilation. + \li Choose the target , This can be quickly selected from the deploy widget, + as shown below: + \endlist + \endlist + + \section1 Deploy the app + + Click \uicontrol{Run}. This will complete the build, and install the device + to the headset and run it. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-examples.qdoc b/src/quick3d/doc/src/xr/qt3dxr-examples.qdoc new file mode 100644 index 00000000..97040e1a --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-examples.qdoc @@ -0,0 +1,18 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \page qt3dxr-examples.html + \title \qxr Examples + \brief This page lists the examples and information common to them. + + This is a list of all examples included in \qxr: + + \annotatedlist qt3dxr-examples + + \target qt3dxr-app-specifics + + \include examples-run.qdocinc + + Make sure you have selected the correct target device and kit combination. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-installing.qdoc b/src/quick3d/doc/src/xr/qt3dxr-installing.qdoc new file mode 100644 index 00000000..8a73e232 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-installing.qdoc @@ -0,0 +1,63 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \page qt3dxr-installing.html + \title Installing \qxr + \previouspage \qxr Quick Starter Guide + + \brief Covers the steps required to install \qxr . + + Before starting, check if there are any instructions regarding the current + \l{\qxr Known Issues and Limitations} that are relevant to installation. + + \section1 Quick install with the Qt Online Installer + + Go to \l{Get and Install Qt} and follow the instructions there, making sure + at \e{step 3} to select \uicontrol{Qt Quick 3d XR} under the relevant Qt Version. + + Then move on to \l{Installing 3rd Party Dependencies}. + + \section1 Custom install with the Qt Online Installer + + If you want to install additional Qt modules or tools at the same time, then + this method is for you. + + Go to \l{Get and Install Qt} and follow the instructions there, except now + as opposed to the quick install method, making sure at \e{step 3} to select + \uicontrol{Custom Installation} and then select the following components: + + \list + \li \qxr + \li Under the same \c{Qt Version} that you selected for \qxr, select: + \list + \li Qt for Android. (If developing for the Meta Quest 3) + \li Qt Quick 3D + \endlist + \endlist + + Then, select other Qt modules or tools that are available to you. + + \section1 Installing 3rd Party Dependencies + + The following dependencies are required: + + \section2 Meta devices + + Meta's SDK is based on the \l OpenXR API, and as such, \qxr has been designed + to support that SDK. It is also Meta's ongoing supported SDK. + + \list + \li The \l{Oculus OpenXR Mobile SDK} + \endlist + + \section2 Apple devices + + \section3 Host Environment + + \section2 Android-based devices + + If this is your first time developing with Qt for Android or using Qt Creator, + you must complete some additional steps to set up your build environment. + See \l{Getting Started with Qt for Android} for more information. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-known-issues.qdoc b/src/quick3d/doc/src/xr/qt3dxr-known-issues.qdoc new file mode 100644 index 00000000..a06a7f8a --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-known-issues.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial + +/*! + \page qt3dxr-known-issues.html + \title \qxr Known Issues and Limitations + + \section1 Known limitations + \qxr at the current stage has the following limitations: + + \list + \li \qxr is in technology preview in this release. + \endlist + + \section1 Known issues, bugs, and defects + + All known issues, bugs, and defects with this patch release are listed here. + + \generatelist qtxr-has-known-issues + + \section1 Reporting issues + + Please log any issues you may find by following the instructions at + \l{Reporting}. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-overview.qdoc b/src/quick3d/doc/src/xr/qt3dxr-overview.qdoc new file mode 100644 index 00000000..de8a71a6 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-overview.qdoc @@ -0,0 +1,109 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \page qtxr-overview.html + \title \qxr Overview + \brief This page describes the architecture and features of this module and + is intended for developers. + + \qxr allows you to leverage the many features of the Qt framework while still + being able to deploy a native application to a compatible VR or XR headset. Or + run an application on a host that streams to a headset. + + \section1 Concepts and Technologies + There are many concepts and technologies in the fragmented XR technology landscape. + This section will define and distinguish between key concepts essential to + understanding \qxr. + + \section2 Types of immersion + + Here, we talk about the different immersion levels that exist. + + \section3 Virtual Reality (VR) + + Perhaps the first and most ambitious level of immersion, replacing a person's visual + and auditory input with a computer-generated environment that matches the motion of + their head, eyes, or both. + + \section3 Extended Reality (XR) + + \note Sometimes referred to as Spatial Reality + + Coined initially as augmented reality (AR), then mixed reality (MR), this type of + immersion combines virtual information (either 2D or 3D content) with live visual + information of the user's real-world environment. It can provide the information + as an overlay on a translucent screen or onto a display that masks the real world entirely. + + \section2 Head-mounted displays and degrees of freedom + + //!TODO Add images explaining 3 DOF 6 DOF and how that applies to head-mounted displays. + + \section2 Interaction Types + + \section3 Controllers + + \section3 Hand tracking + + \section3 Body tracking + + \section1 Marketing jargon + + //!TODO + + \section1 Under the hood + + It is essential that developers understand the API platform landscape in the XR world. + //!TODO + //!TODOOpenXR, OpenXR implementations, OpenXR vs. the real underlying APIs (evolution, OpenVR, + //!TODOstandardization, concepts such as API versus runtime. + //!TODO(see \l https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#_what_is_openxr ), etc.) + + //!TODO\list + //!TODO \li The relation to 3D graphics APIs. + //!TODO \li Practical implications, OpenXR headers, loader library, extensions + //!TODO (link to Khronos upstream repo), explain the basic build process. + //!TODO //!TODO \li Explain the vendor-specific loader issue and the need, for the time being, + //!TODO to use vendor-specific libraries during the Qt and application build process. + //!TODO \li Advanced (smaller priority since PCVR is not our primary focus with the Quest 3): + //!TODO \list + //!TODO \li PCVR vs. native application on the device story. + //!TODO \li Wired and wireless streaming solutions. With concrete examples + //!TODO \endlist + //!TODO (e.g. demonstrate that Quest 3 can be used in both ways, while, for example, Varjo is a + //!TODO PCVR-only solution) + //!TODO \li Non-OpenXR-based platforms: a brief introduction to Apple's Vision Pro architecture. + + //!TODO Two good resources are the old readme to be fully incorporated into the docs eventually + //!TODO\l https://git.qt.io/annichol/qtquick3dxr/-/blob/6.7/README.md?ref_type=heads and + //!TODO\l https://github.com/mbucchia/VirtualDesktop-OpenXR/wiki is an excellent introduction + //!TODOto the PCVR world. + //!TODO\endlist + + \section1 Support + + The support case for devices in this area is evolving rapidly as the market + expands, support is added when parity exists between two types of headsets. + + Currently, this is split between OpenXR, Apple, and Google/Samsung devices. + + \table + \header Feature Matrix + \header \li Feature \li Apple \li Meta \li Samsung + \row \li Pass-through \li No \li Yes \li NA + \row \li Controller input \li No \li No \li NA + \row \li \li No \li No \li NA + \row \li Haptic Feedback \li No \li No \li NA + \row \li Hand Interaction \li No \li No \li NA + \row \li Body Tracking \li No \li No \li NA + \endtable + + The OpenXR SDK for your target headset and if developing a native application for an + Android-based headset, you will need \l{Qt for Android}. + + \section1 Where to go from here? + + Head to the \l{\qxr Quick Starter Guide}, \l{\qxr Examples}{examples}, + or head back to the \l{\qxr}{home page} where you will find what's new and + other important information in this version. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-permissions.qdoc b/src/quick3d/doc/src/xr/qt3dxr-permissions.qdoc new file mode 100644 index 00000000..83643f65 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-permissions.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial + +/*! + \title Android Manifests and \qxr features + \brief Permissions needed by \qxr on certain headsets. + \page qt3dxr-permissions.html + //!TODO + //!Briefly discusses how \qxr knows where to find the manifest file and where the user + //!needs to look for it to manually add the permissions for the features they want to use. + //!Unfortunately, there is no good link to a table of what permissions the Meta OpenXR SDK + //!uses, but we could link to the feature page for each type that uses it. + \section1 Meta Quest 3 + + See \l{https://developer.oculus.com/documentation/native/android/mobile-native-manifest/}{Meta's Manifest docs} + for details about what is needed for every app targeting a Meta platform. + The following table details what is needed by specific \qxr features. + \table + \header \li QML Type \li Android Manifest Entry Needed + \row \li \li + \row \li \li + \row \li \li + \row \li \li + \endtable + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-qml-module.qdoc b/src/quick3d/doc/src/xr/qt3dxr-qml-module.qdoc new file mode 100644 index 00000000..53f687a3 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-qml-module.qdoc @@ -0,0 +1,11 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmlmodule QtQuick3D.Xr + \title \qxr QML Types + \brief Types for leveraging XR device features. + + This module provides QML types that enable you to use the features + on XR platforms. +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-quick-starter-guide.qdoc b/src/quick3d/doc/src/xr/qt3dxr-quick-starter-guide.qdoc new file mode 100644 index 00000000..82c91dc6 --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-quick-starter-guide.qdoc @@ -0,0 +1,40 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \page qt3dxr-quick-start-guide.html + \title \qxr Quick Starter Guide + + \brief This topic provides instructions on how to get up and running + on a meta quest headset. + + This page lists all the instructions you need to get up an running with + \qxr. It uses Qt Creator for automated setup where possible and assumes you + have a Meta Quest 3 device. For the Apple Vision Pro, see + \l{Getting Started With the Apple Vision Pro}. + + The video below demonstrates the process. + + //!TODO Add video link( once recorded) + + \section1 Download and installation + + Complete the steps on the \l{Installing \qxr} page. + + \section1 Setting up the Simple Example Project + \list 1 + \li Open the example project from the qt creator welcome screen. + \li Configure the project settings (Projects mode: Ctrl+5 by default) + \list 1 + \li Confirm that the applicable Android Kit for your target device is + chosen for compilation. + \li Choose the target , This can be quickly selected from the deploy widget, + as shown below: + \endlist + \endlist + + \section1 Deploy the app + + Click \uicontrol{Run}. This will complete the build, and install the device + to the headset and run it. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-supported-platforms.qdoc b/src/quick3d/doc/src/xr/qt3dxr-supported-platforms.qdoc new file mode 100644 index 00000000..96a3660f --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-supported-platforms.qdoc @@ -0,0 +1,32 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial + +/*! + \page qt3dxr-supported-platforms.html + \title Supported Headsets + \target Supported Platforms + + This page outlines the combinations of use cases that are supported. + + \section1 Supported hardware + + \table + \header Support matrix + \header \li Platform \li PCVR Streaming \li Native \li Debugging + \row \li Quest 2 \li Yes \li Yes \li Yes + \row \li Quest 3 \li Yes \li Yes \li Yes + \row \li Quest Pro \li Yes \li Yes \li Yes + \row \li Varjo \li Yes \li NA \li Na + \row \li Apple Vision Pro \li Na \li Yes \li No + \endtable + + This hardware is used when developing \qxr. + + \section1 Supported development host environments + + \qxr supports the same host platforms that \l Qt supports. + + If you need to run applications for other host architectures or operating + systems, contact \l{contact Qt sales}{the Qt Company}. + +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr-toc.qdoc b/src/quick3d/doc/src/xr/qt3dxr-toc.qdoc new file mode 100644 index 00000000..b6a2b10b --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr-toc.qdoc @@ -0,0 +1,69 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial + +/*! + \page qtaa-toc.html + \title All Topics + + List of all topics in \qxr documentation. + + \list + +//! [listitems-platforms-and-toolchains] + \li Platforms and Toolchains + \list + \li \l{Supported Headsets} + \li \l{Android Manifests and \qxr features} + \endlist +//! [listitems-platforms-and-toolchains] + +//! [listitems-getting-started] + \li Getting Started + \list + \li \l{\qxr Quick Starter Guide} + \li \l{\qxr Overview} + \li \l{Installing \qxr} + \endlist +//! [listitems-getting-started] + +//! [listitems-api-reference] + \li API Reference + \list + \li \l{\qxr QML Types} + \endlist +//! [listitems-api-reference] + + +//! [listitems-examples] + \li \l{\qxr Examples}{Examples} + \list + \li \l{Qt Quick 3D - XR Simple Example} + \endlist +//! [listitems-examples] + +//! [tools-ide] + \li Tools and IDEs + \list + \li \l{CMake Manual} + \li \l{Qt Creator Manual} + \li \l{Qt Design Studio} + \endlist +//! [tools-ide] + +//! [developing-applications] + \li Developing XR Applications + \list + \li \l{Locomotion} + \li \l{Interaction} + \li \l{Comfort and Accessibility} + \endlist +//! [developing-applications] + +//! [listitems-quick-links] + \li \l{Supported Headsets} + \li \l{\qxr Known Issues and Limitations} + \li \l{\qxr Quick Starter Guide} +//! [listitems-quick-links] + + \endlist +*/ diff --git a/src/quick3d/doc/src/xr/qt3dxr.qdoc b/src/quick3d/doc/src/xr/qt3dxr.qdoc new file mode 100644 index 00000000..da23083e --- /dev/null +++ b/src/quick3d/doc/src/xr/qt3dxr.qdoc @@ -0,0 +1,45 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial +/*! + \nextpage \qxr Overview + \page qt-quick-3d-xr.html + \title \qxr + //! A placeholder image, using exising image + \image dragon.jpg + + \qxr allows you to develop Qt applications for extended reality + devices that take full advantage of the different immersion levels and + human-machine interface styles offered + + The \l{\qxr Overview} page discusses the different approaches to modifying a + users perceived reality and clarified the concepts and technologies that are + referenced throughout this documentation. + + \section1 Quick Links + + \list + \include qt3dxr-toc.qdoc listitems-quick-links + \endlist + + //! NOTE: This table refers to list items in qt3dxr-toc.qdoc - add new items there + //! Using existing placeholder images for now + \table + \header + \li \image quick3d-custom-cube1-small.jpg + \li \image quick3d-custom-cube1-small.jpg + \li \image quick3d-custom-cube1-small.jpg + \row + \include qt3dxr-toc.qdoc listitems-platforms-and-toolchains + \include qt3dxr-toc.qdoc listitems-getting-started + \include qt3dxr-toc.qdoc listitems-api-reference + \header + \li \image quick3d-custom-cube1-small.jpg + \li \image quick3d-custom-cube1-small.jpg + \li \image quick3d-custom-cube1-small.jpg + \row + \include qt3dxr-toc.qdoc listitems-examples + \include qt3dxr-toc.qdoc tools-ide + \include qt3dxr-toc.qdoc developing-applications + \endtable + +*/ |