diff options
Diffstat (limited to 'doc')
28 files changed, 1058 insertions, 101 deletions
diff --git a/doc/src/00-concepts.qdoc b/doc/src/00-concepts.qdoc index fa16e676..ef65f215 100644 --- a/doc/src/00-concepts.qdoc +++ b/doc/src/00-concepts.qdoc @@ -48,7 +48,6 @@ interactive presentations, UIs and applications. \div {align="center"} \image animation-index.png \enddiv - \row \li \b {\l{Getting Started}} \list @@ -61,10 +60,11 @@ interactive presentations, UIs and applications. \endlist \li \b {\l{Graphics}} \list + \li \l{2D Assets} \li \l{Working with 3D Content}{3D Assets} \li \l{Layers} \li \l{Materials and Shaders} - \li \l{Light Properties}{Lights} + \li \l{Lights} \li \l{Using Sub-Presentations}{Sub-Presentations} \li \l{Stereoscopic Rendering} \endlist @@ -99,10 +99,11 @@ interactive presentations, UIs and applications. \endlist \li \b {\l{Getting Help}} \list + \li \l{Known Issues} + \li \l{Glossary} \li \l{Studio Keyboard Shortcuts} \li \l{Viewer Keyboard Shortcuts} \endlist - \row \li {3,1} \note To report bugs and suggestions to the Qt Bug Tracker, visit \l https://bugreports.qt.io. diff --git a/doc/src/03-studio/5-timeline-palette.qdoc b/doc/src/03-studio/5-timeline-palette.qdoc index f385ebbd..cf0c7739 100644 --- a/doc/src/03-studio/5-timeline-palette.qdoc +++ b/doc/src/03-studio/5-timeline-palette.qdoc @@ -171,6 +171,9 @@ cause an element to not appear on only certain slides, place your element on the master slide and then eyeball it off on slides where it should not be present. +\note The visible property is disabled on the master slide, it can only be controlled +on a per-slide basis. + The active state of an element controls more than just visibility. Elements that are not active do not receive update notifications each frame. which is particularly important for presentation behaviors. diff --git a/doc/src/03-studio/7-inspector-palette.qdoc b/doc/src/03-studio/7-inspector-palette.qdoc index 354d0580..70cc9f59 100644 --- a/doc/src/03-studio/7-inspector-palette.qdoc +++ b/doc/src/03-studio/7-inspector-palette.qdoc @@ -32,7 +32,7 @@ \page studio-inspector-palette.html \ingroup qt3dstudio-studio - The Inspector palette is the most-used +The Inspector palette is the most-used palette in Studio. It is used to control which properties are animated or change on a per-slide basis and the values for each of those properties. @@ -116,7 +116,7 @@ shown in the Inspector palette \e{specific to the active slide}: over at time 0. \li \c{PingPong} - Upon reaching the final time the playhead starts - playing backwards; upon reaching time 0 the playeah starts playing + playing backwards; upon reaching time 0 the playhead starts playing forwards again. \li \c{Ping} - Similar to \e{PingPong}, but when the playhead @@ -134,6 +134,10 @@ shown in the Inspector palette \e{specific to the active slide}: \b{Pause} setting is particularly useful when QML application is going to control the time for the context and you don't need or want the runtime attempting to do its own work. +\li + \b{Use Background} - Clear the contents to a solid color before each frame. +\li + \b{Background Color} - Color to use for the background. \endlist \target layer-properties @@ -144,23 +148,6 @@ in the Inspector palette: \list \li - \b{Disable Depth Test} - Controls whether depth-testing is used - when rendering objects in the layer. For details see the discussion on - the - \e{\l{best-practices-disable-depth-test.html}{Disable Depth Test}} page. -\li - \b{Progressive AA} - Controls whether progressive anti-aliasing - is used when rendering the layer. For details see the discussion on - \e{\l{best-practices-antialiasing.html#progressive-aa}{Progressive Anti-Aliasing}}. -\li - \b{Multisample AA} - Controls whether multisample anti-aliasing - is used when rendering the layer. For details see the discussion on - \e{\l{best-practices-antialiasing.html#multisample-aa}{Multisample Anti-Aliasing}}. -\li - \b{Temporal AA} - Controls whether temporal anti-aliasing is used - when rendering the layer. For details see the discussion on - \e{\l{best-practices-antialiasing.html#temporal-aa}{Temporal Anti-Aliasing}}. -\li \b{Layer Background} - Controls how the layer clears when it starts to render each frame: \list @@ -168,14 +155,14 @@ in the Inspector palette: \c{Transparent} - Clear the layer to transparent each frame so that content behind it can be seen. \li - \c{Unspecified} - Do not clear layer each frame. This provides a - slight performance boost if the layer is filled with content, and - hence will fully overwrite the previous result. -\li \c{Solid Color} - Clear this layer to a non-transparent color. This provides a slight performance boost if the layer fills the viewport \b{and} if you turn off \"Enable Background Color\" for the Scene. +\li + \c{Unspecified} - Do not clear layer each frame. This provides a + slight performance boost if the layer is filled with content, and + hence will fully overwrite the previous result. \endlist \li \b{Blend Mode} - Controls how colors in the active layer blends with colors in the background @@ -202,6 +189,23 @@ in the Inspector palette: than \c Screen. \endlist \li + \b{Sub-Presentation} - Select a presentation (\.uip) or QML (\c.qml) file to render as a + sub-presentation on this layer. Other objects on the layer will not render when a sub-presentation + is applied. For more information, see + \e{\l{Using Sub-Presentations}}. +\li + \b{Progressive AA} - Controls whether progressive anti-aliasing + is used when rendering the layer. For details see the discussion on + \e{\l{best-practices-antialiasing.html#progressive-aa}{Progressive Anti-Aliasing}}. +\li + \b{Multisample AA} - Controls whether multisample anti-aliasing + is used when rendering the layer. For details see the discussion on + \e{\l{best-practices-antialiasing.html#multisample-aa}{Multisample Anti-Aliasing}}. +\li + \b{Temporal AA} - Controls whether temporal anti-aliasing is used + when rendering the layer. For details see the discussion on + \e{\l{best-practices-antialiasing.html#temporal-aa}{Temporal Anti-Aliasing}}. +\li \b{Horizontal Fields} - Choose which two fields of \c{Left}, \c{Width}, and \c{Right} are used to control the horizontal placement and sizing of the layer within the presentation. @@ -232,11 +236,6 @@ in the Inspector palette: presentation and the layer, either in pixels or as a percentage of the presentation's height. \li - \b{Sub-Presentation} - Select a presentation (\.uip) or QML (\c.qml) file to render as a - sub-presentation on this layer. Other objects on the layer will not render when a sub-presentation - is applied. For more information, see - \e{\l{Using Sub-Presentations}}. -\li \b{Ambient Occlusion} - Controls the strength of ambient occlusion (AO). AO is a form of approximated global illumination which causes non-directional self-shadowing where objects are close @@ -305,35 +304,6 @@ in the Inspector palette: to your content. \endlist \li - \b{Shadow Strength} - Controls the strength of directional - occlusion (DO). DO is a form of approximated directional shadowing. A - value of \c{100} causes full darkness shadows; lower values cause - the shadowing to appear lighter. A value of \c{0} disables DO - entirely, improving performance at a cost to the visual realism of 3D - objects rendered in the layer. All values other than \c{0} have - the same impact to the performance. - \list - \li - \note Directional occlusion will only render on \e{Standard Materials} - that have the \l{standard-materials}{Lighting property} set to \c{Pixel}. - \endlist -\li - \b{Shadow Distance} - Roughly how far (in world units) the faked - shadows spread away from objects. -\li - \b{Shadow Softness} - Crossfade amount between sharp shadows and - smooth gradations. -\li - \b{Shadow Threshold} - A cutoff distance preventing objects from - self-shadowing. Higher values increase the distance required between - objects before DO is seen. - \list - \li - \note If you see DO shadowing in regions where there should be - no shadowing, increase the Shadow Threshold value slightly to clip - away close results. - \endlist -\li \b{Light Probe} - Select an image (preferably a high dynamic range image (\c{.hdr})) to use to light the scene, either instead of or in addition to standard lights. If selected, note that this image will @@ -352,6 +322,14 @@ in the Inspector palette: \b{Secondary Light Probe} - Select an image to use as secondary IBL light source. \li \b{Probe Crossfade} - The blend amount between the primary and secondary light probes. +\li + \b{Disable Depth Test} - Controls whether depth-testing is used + when rendering objects in the layer. For details see the discussion on + the + \e{\l{best-practices-disable-depth-test.html}{Disable Depth Test}} page. +\li + \b{Disable Depth Prepass} - Controls whether depth prepassing is used when rendering objects + in the layer. Can be enabled to optimize render speed on layers with low depth complexity. \endlist \target transform-properties @@ -547,7 +525,7 @@ in the Inspector palette (in addition to the - Simulate shadows using this light? \li - \b{Shadow Darkness} - How dark should the cast shadows be? + \b{Shadow Darkness} - Darkness of the shadows. \li \b{Shadow Softness} - Amount of blur applied to the shadows. \li @@ -750,8 +728,8 @@ about working with materials, see \l {Materials and Shaders}. by the Bump Amount property. \list \li - \e{Tip: Bump maps will not affect the silhouette of a model. Use a - displacement map if this is required.} + \note Bump maps will not affect the silhouette of a model. Use a + displacement map if this is required. \endlist \li \b{Normal Map} - An RGB image used to \e{simulate} fine @@ -760,8 +738,8 @@ about working with materials, see \l {Materials and Shaders}. controlled by the Bump Amount property. \list \li - \e{Tip: Normal maps will not affect the silhouette of a model. Use - a displacement map if this is required.} + \note Normal maps will not affect the silhouette of a model. Use + a displacement map if this is required. \endlist \li \b{Bump Amount} - Controls the amount of simulated displacement @@ -773,14 +751,12 @@ about working with materials, see \l {Materials and Shaders}. surface of the material. Brighter pixels indicate raised regions. \list \li - \e{Tip: Displacement maps require vertices to offset. If your model - is not high-enough resolution you may need to dynamically generate - additional vertices by using the - \l{model-properties}{Tessellation properties} on the model.} + \note Displacement maps require vertices to offset. I.e. the result will be + more accurate on a high poly model than on a low poly model. \li - \e{Tip: Displacement maps do not affect the normals of your + \note Displacement maps do not affect the normals of your geometry. To look correct with lighting or reflections you will likely - want to also add a matching bump map or normal map to your material.} + want to also add a matching bump map or normal map to your material. \endlist \li \b{Displacement Amount} - Controls the offset amount for the displacement map. @@ -789,7 +765,7 @@ about working with materials, see \l {Materials and Shaders}. from the model. \list \li - Note: Setting the opacity of a \e{model} very low (below 1\% or + \note Setting the opacity of a \e{model} very low (below 1\% or less) will prevent it from receiving touch events, but setting the opacity of its \e{material} very low still allows touch events to occur. @@ -829,7 +805,7 @@ about working with materials, see \l {Materials and Shaders}. \b{Diffuse Light Wrap} - The amount of light wrap for the translucency map. A value of 0 will not wrap the light at all while a value of 1 will wrap the light all around the object. \endlist -Note that the Runtime custom-compiles shaders for each unique +\note The Runtime custom-compiles shaders for each unique combination of material properties used. Each additional material feature that you use results in a (slight) additional performance hit. @@ -851,11 +827,13 @@ The Inspector palette shows only a single property: \li \b{Referenced Material} - a picker for selecting an animatable material within the presentation. -\li - \e{Tip: the material you reference does \b{not} have to be - visible or even active for this to work. It is valid to have a small - pile of models with custom materials on them all eyeballed off, and - then reference those materials for rendering on other objects.} + \list + \li + \note The material you reference does \b{not} have to be + visible or even active for this to work. It is valid to have a small + pile of models with custom materials on them all eyeballed off, and + then reference those materials for rendering on other objects.} + \endlist \endlist \section1 Image Properties @@ -927,12 +905,9 @@ properties in the Inspector palette (in addition to the \b{Text String} - The text to display for the text element. \list \li - \e{Note: Qt 3D Studio does not (currently) support styled + \note Qt 3D Studio does not (currently) support styled text. There is no way to make one word in a paragraph bold, larger, or a different color.} -\li - \e{Note: Qt 3D Studio also does not (currently) support automatically - wrapping text; you must manually inject line breaks to wrap your text.} \endlist \li \b{Text Color} - The color for the text. @@ -957,7 +932,7 @@ TODO: Only one font for now. More to be added? also type a new value for the font. \list \li - \e{Tip: Although the font size is just a number, it is + \note Although the font size is just a number, it is intentionally not animatable. Each time the font size changes a rather expensive rasterization of the text string occurs. You should animate the scale of the text element instead.} @@ -977,6 +952,36 @@ TODO: Only one font for now. More to be added? \li \b{Tracking} - Controls the amount of extra (or negative) horizontal spacing between every character pair. +\li + \b{Text Area} - Define size of fixed text area. If no values are set, the text size will + grow with the text. +\li + \b{Word Wrapping} - Define how text will be wrapped when using a fixed text area size. + \list + \li + \c Clip - Cut the text if it doesn't fit in the text area. + \li + \c WrapWord - Wraps between words, if possible. + \li + \c WrapAnywhere - Wraps anywhere, also in the middle of words. + \endlist +\li + \b{Eliding} - Elide text that does not fit into a fixed size text area. + \list + \li + \note Text eliding does not work with distance field rendering disabled or when + drop shadows are used. + \endlist +\li + \b{Drop-Shadow} - Add a drop shadow to the text. The drop shadow will be a darker shade of the + text color. +\li + \b{Shadow Darkness} - Darkness of the drop shadow. 100 is black and 0 is the same color as the + text. +\li + \b{Horizonal Offset} - Horizontal offset of the shadow. The offset is relative to the font size. +\li + \b{Vertical Offset} - Vertical offset of the shadow. The offset is relative to the font size. \endlist diff --git a/doc/src/2d-assets.qdoc b/doc/src/2d-assets.qdoc new file mode 100644 index 00000000..d048959f --- /dev/null +++ b/doc/src/2d-assets.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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$ +** +****************************************************************************/ + +/*! +\page 2d-assets.html +\title 2D Assets + +In Studio, you can import images to use as textures. The following image file formats +are supported: + +\table + \header + \li File format + \li Extensions + \row + \li PNG + \li \c{.png} + \row + \li JPEG + \li \c{.jpg}, \c{.jpeg} + \row + \li DirectDraw Surface + \li \c{.dds} + \row + \li BMP + \li \c{.bmp} + \row + \li GIF + \li \c{.gif} + \row + \li HDRI (High Dynamic Range Imaging) + \li \c{.hdr} + \row + \li Khronos texture container + \li \c{.ktx} +\endtable + +\section1 Using Textures on Materials +Images can be used as the following textures on materials: + +\list + \li + Diffuse Map + \li + Roughness Map + \li + Opacity Map + \li + Emissive Map + \li + Bump Map + \li + Normal Map + \li + Displacement Map + \li + Translucency Map + \li + Specular Map + \li + Specular Reflection + \li + Indirect Lightmap + \li + Shadow Lightmap + \li + IBL Override +\endlist + +Read more about working with \l Materials. + +\section1 Compressed Textures + +Qt 3D Studio supports the Khronos texture container file format \e ktx. You can apply \e ktx files +as texture maps just as any other file format. However, if your system does not support the \e ktx +format, the textures will not be visible in Qt 3D Studio. + +If you enable the \uicontrol {Use ktx textures if available} feature, you can use \e png +images in Studio, and then use \e ktx images in their place in the Viewer. + +\list 1 + \li In the Studio menu, click \uicontrol{Edit > Presentation Settings} + \li Check the \uicontrol {Use ktx textures if available} check box. +\endlist + +\section1 Optimizing Images + +Optimizing the images in your presentation can substantially improve both the startup and runtime +performance of your application, as well as the visual quality in certain situations. Read more +about \l{Optimizing Images}. + +\section1 Image-Based Lighting + +HDR images can be used as light probes for environment lighting in Studio. Read more about +\l{Image-Based Lighting}. + +*/ diff --git a/doc/src/about-qt3dstudio.qdoc b/doc/src/about-qt3dstudio.qdoc index 4e0560a5..ecfe6683 100644 --- a/doc/src/about-qt3dstudio.qdoc +++ b/doc/src/about-qt3dstudio.qdoc @@ -70,6 +70,10 @@ The Qt 3D Studio suite includes: For software and hardware requirements, see the \l{Requirements} page. For list of third-party modules and copyright notices, see the \l{Copyright Notices} page. +\section1 Qt 3D vs. Qt 3D Studio +See the \l{Comparison of Qt 3D and Qt 3D Studio} section for a full comparison of Qt 3D and +Qt 3D Studio. + \section1 Concepts \section2 Project @@ -109,22 +113,4 @@ are then composited with items on upper layers drawing on top of the content on A Studio presentation combines 3D assets with animations and \e{slides}. Slides can be thought of as states and provide visual variations within the presentation. - -\section1 Known Issues - -\section2 Possible problems after automatic mesh optimization - -When loading a presentation made with an earlier version (2.0 beta2 or older) of Qt 3D Studio -which has imported FBX or DAE models, you may see the following messagebox: - -\image {mesh_optimization.png}{Old presentation version} - -If your \b{imported} models are not visible in the Viewer after seeing the message, you need to -edit your \c{*.uip} file(s) manually. Some older versions of Studio referenced meshes with revision -number in the \c{*.uip} file, and that revision causes it to be missing in the scope of the -Viewer. - -You'll need to find all occurrences of \c{.mesh#<revision_number>} from you \c{*.uip} and -replace them with \c{.mesh}. - */ diff --git a/doc/src/comparison.qdoc b/doc/src/comparison.qdoc new file mode 100644 index 00000000..372c4508 --- /dev/null +++ b/doc/src/comparison.qdoc @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 Comparison of Qt 3D and Qt 3D Studio +\page comparison-qt3d-qt3dstudio.html + +In short, Qt 3D Studio is built on top of Qt 3D. The flexible architecture of Qt 3D makes it +suitable to build 3D runtimes, or engines, such as Qt 3D Studio. + +\section1 Qt 3D + +Qt 3D is programmer-oriented engine building toolkit and great for both simple and complex scenes. +Qt 3D simplifies the implementation of advanced rendering techniques. + +\section1 Qt 3D Studio + +Qt 3D Studio consists of both a 3D editor and a 3D runtime. Qt 3D Studio is designer-oriented +and makes it easy to build complex 3D scenes with states and transitions that can be used in +and controlled by Qt applications. + +\section1 Use Case Comparison + +Whether you should use Qt 3D or Qt 3D Studio for your project depends on your use case. +Below, we list some common use cases and how they apply to the two: + +\section2 Creating 3D Scenes + +\table + \header + \li + Use Case + \li + Qt 3D + \li + Qt 3D Studio + \row + \li + Graphically editing a 3D scene for use in a Qt application. + \li + No built-in editor. Support for importing common 3D formats. + \li + Yes, use the Qt 3D Studio Editor. + \row + \li + Creating a 3D scene programmatically. + \li + Suitable. + \li + Not possible. + \row + \li + Using existing materials and effects. + \li + Some available in Qt3D.Extras. + \li + Many available in the Qt 3D Studio editor. + \row + \li + Combine existing materials and effects. + \li + May require rewriting some of the shaders from Qt3D.Extras to form custom + combinations. + \li + Suitable. +\endtable + +\section2 Effects + +\table + \header + \li + Use Case + \li + Qt 3D + \li + Qt 3D Studio + \row + \li + Creating a simple multi-pass rendering pipeline. + \li + Suitable. + \li + Suitable. + \row + \li + Using custom shaders. + \li + Suitable. + \li + Suitable. + \row + \li + Layer-based compositing. + \li + Suitable. + \li + Suitable. + \row + \li + Implementing custom rendering techniques such as volumetric rendering. + \li + Suitable. + \li + Not suitable. +\endtable + +\section2 Formats + +\table + \header + \li + Use Case + \li + Qt 3D + \li + Qt 3D Studio + \row + \li + Importing external formats. + \li + All formats supported by plugins such as Assimp. See + \l{https://doc.qt.io/qt-5/qml-qt3d-render-sceneloader.html}{SceneLoader} for a full list. + \li + A number of formats are supported. See \l{2D Assets} and + \l{Working with 3D Content}{3D Assets} for details. +\endtable + +\section2 Creating 3D Engines and Editors + +\table + \header + \li + Use Case + \li + Qt 3D + \li + Qt 3D Studio + \row + \li + Creating a custom graphical 3D editor. + \li + Suitable. + \li + Not possible. + \row + \li + Creating a custom 3D engine. + \li + Suitable. + \li + Not possible. +\endtable + +*/ diff --git a/doc/src/glossary.qdoc b/doc/src/glossary.qdoc new file mode 100644 index 00000000..950b64be --- /dev/null +++ b/doc/src/glossary.qdoc @@ -0,0 +1,314 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 Glossary +\page glossary.html + +This page provides short explanations of terms used in Qt 3D Studio. + +\table + \header + \li + Term + \li + Meaning + \row + \li + \l{Studio: Action Palette}{Action} + \li + Actions provide a way to create interactivity in a \l presentation without scripting. + \row + \li + \l{Studio: Action Palette}{Action palette} + \li + The action palette is used to manage \l {action}{actions} for the selected element. + \row + \li + \target {animation portion} + \l{Studio: Timeline Palette#Animation portion}{Animation Portion} + \li + To the right of the \l{scene graph} in the \l{timeline palette} is the actual \l timeline. + The \l{time bar}{time bars} for each element control element lifespan. + The \l keyframe markers control the timing of the animation. The \l playhead allows the + preview of animation effects. + \row + \li + \target application + \l{About Qt 3D Studio#Concepts}{Application} + \li + Your application is the entry point of your \l project. It is represented by a single + \l{uia}{.uia file} at the root of your project folder. This file references the + \l presentation and \l{sub-presentation}{sub-presentations} in your project. + The application is what is displayed by the \l Viewer. + \row + \li + \target asset + Asset + \li + Assets are elements which you can use in your \l presentation. Assets can be images, 3D + models, \l{effect}{effects}, fonts, \l{material}{materials}, \l{shader}{shaders}, + \l {behavior}{scripts} and \l{sub-presentation}{sub-presentations}. + \row + \li + Asset library + \li + Included in \l studio is a set of \l{asset}{assets} ranging from images to 3d models. + \row + \li + \l{Studio: Basic Objects Palette}{Basic objects palette} + \li + The Basic objects palette provides a mechanism for creating objects unique to a + \l presentation, not represented by a file on disk in your \l {project palette}. + \row + \li + \target behavior + \l{Using Behavior Scripts}{Behavior} + \li + Behavior scripts can be applied to objects to give the specific object a certain behavior. + \row + \li + \l{Studio: Basic Objects Palette#Component}{Component} + \li + Components are somewhat like mini-scenes. Although they are 3D geometry (not a 2D + composition of rendered layers), they have their own \l {slide}{slides} and + \l {timeline}{timelines}. + \row + \li + \l{Using Data Inputs}{Data input} + \li + This makes it possible to control \l timeline animations, object properties and + \l{slide}{slides} with data. + \row + \li + \l{Studio: Toolbar#Edit Cameras}{Edit cameras} + \li + Sometimes you want to move around the 3D space of your scene in the editor without + adjusting the final rendered view. \l Studio calls this concept edit cameras. + \row + \li + \target effect + \l{Applying Layer Effects}{Effect} + \li + Each \l layer in a \l presentation may have one or more post-processing effects + applied to the visual result + \row + \li + \l{Studio: Basic Objects Palette#Group}{Group} + \li + A group is an empty transform element. Attaching models to the group + (placing them as children of the group in the \l {timeline palette}) allows you to + move/rotate/scale/hide the group and have this affect all items within it. + \row + \li + .import file + \li + When importing 3D models of \e .fbx and \e .dae format to \l studio, they are converted to + \e .import files. + \row + \li + \l{Studio: Inspector Palette}{Inspector palette} + \li + The inspector palette is used to control values and animations of element properties. + \row + \li + \l{Animations#Interpolation}{Interpolation} + \li + Interpolation defines the easing of \l keyframe animations. + \row + \li + \target keyframe + \l{Animations}{Keyframe} + \li + A keyframe is a a time marker that stores the value of a property. + A keyframe can for example define the X position for an element. To create an animation, + add another keyframe for the X position of the same element but in another position on the + \l timeline. \l Studio will determine the correct X position for all frames between the + two keyframes. + \row + \li + \target layer + \l{About Qt 3D Studio#Concepts}{Layer} + \li + A single Studio \l presentation combines one or more layers. The visual result of each + layer comes from rendering a 3D scene, 2D scene (via an orthographic camera), + or \l{sub-presentation}{sub-presentation}. Layers are then composited with items on upper + layers drawing on top of the content on lower layers. + \row + \li + \l{Studio: Slide Palette#The Master Slide}{Master slide} + \li + Each scene and \l component have one master slide. + Elements placed on this \l slide exist on all slides of that scene or \l component. + \row + \li + \l{Materials and Shaders#Materials}{Material} + \li + Materials define how object surfaces are rendered in \l studio and \l viewer. You can create + your own basic materials, save them in your \l project, and assign them to objects. + \row + \li + \l{Studio: Scene View and Matte#Matte}{Matte} + \li + Surrounding the \l {scene view} is the matte. The matte may not be visible if your + \l presentation is larger than the available space. + \row + \li + Mesh + \li + The actual geometry of a 3D shape. + \row + \li + \target playhead + \l{Animations}{Playhead} + \li + The playhead in the \l timeline is used to set the time for new keyframes, and for previewing + animations. + \row + \li + \target presentation + \l{About Qt 3D Studio#Concepts}{Presentation} + \li + Presentations are represented by \l{uip}{.uip files} in your project. A presentation + has one or more \l{layer}{layers} composited to the screen, comprised of 2D assets + and 3D assets created in other applications. + + Each application can only have one main presentation shown on screen (specified by the + \l {uia}{.uia file}) but this presentation may reference other + \l{sub-presentation}{sub-presentations}, either on flat layers or as images and textures + drawn in a scene. + \row + \li + \target project + \l{About Qt 3D Studio#Concepts}{Project} + \li + A project is simply a folder on your computer holding all the assets needed for your + \l application. When you start a new project, a default folder structure will be created. + \row + \li + \target {project palette} + \l{Studio: Project Palette}{Project palette} + \li + The project palette displays the files and folders on disk for your \l project. + Only files usable by \l Studio are displayed in the palette. + \row + \li + QML Stream + \li + A QML stream is a \e .qml file used as a \l{sub-presentation}. + \row + \li + \l{Studio: Scene Camera Palette}{Scene Camera palette} + \li + The scene camera palette allows you to zoom in to pixel perfect level with the scene camera. + \row + \li + \target {scene graph} + \l{Studio: Timeline Palette#Scene Graph}{Scene graph} + \li + The left half of the \l{timeline palette} shows the scene graph where all elements in your + \l presentation for the current \l slide. + \row + \li + \target {scene view} + \l{Studio: Scene View and Matte#Scene View}{Scene view} + \li + The scene view is the center region of \l Studio, showing you the visual result of rendering + and compositing the \l{layer}{layers} of your \l presentation, and also allowing you to + select and transform elements graphically. + \row + \li + \target shader + \l{Materials}{Shader} + \li + Shaders are arbitrary GLSL Shaders, wrapped in a file format providing an artist-friendly + interface for adjusting properties in \l studio. + \row + \li + \l{Studio:Slide Palette}{Slide} + \li + A Studio \l presentation combines 3D assets with animations and slides. + Slides can be thought of as states and provide visual variations within the \l presentation. + \row + \li + \l{Studio:Slide Palette}{Slide palette} + \li + The slide palette shows all slides in a \l presentation or a \l component. + \row + \li + \target studio + \l{About Qt 3D Studio#Concepts}{Studio} + \li + An authoring tool for creating interactive 3D presentations and applications. + \row + \li + \target {sub-presentation} + \l{Using Sub-Presentations}{Sub-presentation} + \li + Sub-Presentations is a feature which allows a \l studio \l presentation (\l{uia}{.uia file}) + or a QML file to be embedded in a \l studio \l presentation. + \row + \li + \target {time bar} + \l{Studio: Timeline Palette#Adjusting Time Bars}{Time bar} + \li + Each element has a time bar in the \l timeline. The time bar control the lifespan + during which the element is active. + \row + \li + \target {timeline palette} + \l{Studio: Timeline Palette}{Timeline palette} + \li + The timeline palette provides direct access to all elements in your scene, + and also gives you control over the animation and timing within a \l slide. + + The timeline palette is comprised of two connected sections: the \l {scene graph} and the + \l {animation portion}. + \row + \li + \target uia + \l{About Qt 3D Studio#Concepts}{.uia file} + \li + The \e .uia file is the application file, it is by default located in the root folder of + your \l project. + \row + \li + \target uip + \l{About Qt 3D Studio#Concepts}{.uip file} + \li + The \e .iup file is a presentation file. A \l project can have one or more presentation files + located in \e presentations folder of your \l project. + \row + \li + \target viewer + \l{About Qt 3D Studio#Concepts}{Viewer} + \li + A runtime player to test and deploy interfaces created in \l Studio. +\endtable + +*/ diff --git a/doc/src/images/area-light.png b/doc/src/images/area-light.png Binary files differnew file mode 100644 index 00000000..f26e9bc1 --- /dev/null +++ b/doc/src/images/area-light.png diff --git a/doc/src/images/directional-light-scene.png b/doc/src/images/directional-light-scene.png Binary files differnew file mode 100644 index 00000000..5e98c40d --- /dev/null +++ b/doc/src/images/directional-light-scene.png diff --git a/doc/src/images/directional-light.png b/doc/src/images/directional-light.png Binary files differnew file mode 100644 index 00000000..21ab865a --- /dev/null +++ b/doc/src/images/directional-light.png diff --git a/doc/src/images/exponential-fade-100.png b/doc/src/images/exponential-fade-100.png Binary files differnew file mode 100644 index 00000000..1202f85c --- /dev/null +++ b/doc/src/images/exponential-fade-100.png diff --git a/doc/src/images/exponential-fade-20.png b/doc/src/images/exponential-fade-20.png Binary files differnew file mode 100644 index 00000000..b1d40645 --- /dev/null +++ b/doc/src/images/exponential-fade-20.png diff --git a/doc/src/images/exponential-fade-200.png b/doc/src/images/exponential-fade-200.png Binary files differnew file mode 100644 index 00000000..7e6c2518 --- /dev/null +++ b/doc/src/images/exponential-fade-200.png diff --git a/doc/src/images/exponential-fade-50.png b/doc/src/images/exponential-fade-50.png Binary files differnew file mode 100644 index 00000000..cdad9cc6 --- /dev/null +++ b/doc/src/images/exponential-fade-50.png diff --git a/doc/src/images/linear-fade-100.png b/doc/src/images/linear-fade-100.png Binary files differnew file mode 100644 index 00000000..3e0e2d4a --- /dev/null +++ b/doc/src/images/linear-fade-100.png diff --git a/doc/src/images/linear-fade-20.png b/doc/src/images/linear-fade-20.png Binary files differnew file mode 100644 index 00000000..4e3cb80d --- /dev/null +++ b/doc/src/images/linear-fade-20.png diff --git a/doc/src/images/linear-fade-200.png b/doc/src/images/linear-fade-200.png Binary files differnew file mode 100644 index 00000000..76b191bd --- /dev/null +++ b/doc/src/images/linear-fade-200.png diff --git a/doc/src/images/linear-fade-50.png b/doc/src/images/linear-fade-50.png Binary files differnew file mode 100644 index 00000000..aca3ab33 --- /dev/null +++ b/doc/src/images/linear-fade-50.png diff --git a/doc/src/images/point-light-scene.png b/doc/src/images/point-light-scene.png Binary files differnew file mode 100644 index 00000000..6e019a50 --- /dev/null +++ b/doc/src/images/point-light-scene.png diff --git a/doc/src/images/point-light.png b/doc/src/images/point-light.png Binary files differnew file mode 100644 index 00000000..70d198bc --- /dev/null +++ b/doc/src/images/point-light.png diff --git a/doc/src/images/variant-tags-layer.png b/doc/src/images/variant-tags-layer.png Binary files differnew file mode 100644 index 00000000..f77527b5 --- /dev/null +++ b/doc/src/images/variant-tags-layer.png diff --git a/doc/src/images/variant-tags-slide.png b/doc/src/images/variant-tags-slide.png Binary files differnew file mode 100644 index 00000000..ecf868d4 --- /dev/null +++ b/doc/src/images/variant-tags-slide.png diff --git a/doc/src/images/variant-tags.png b/doc/src/images/variant-tags.png Binary files differnew file mode 100644 index 00000000..3eedc308 --- /dev/null +++ b/doc/src/images/variant-tags.png diff --git a/doc/src/known-issues.qdoc b/doc/src/known-issues.qdoc new file mode 100644 index 00000000..6eb002bf --- /dev/null +++ b/doc/src/known-issues.qdoc @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 Known Issues +\page known-issues.html + +This section lists known issues in Qt 3D Studio. The development team is aware of them, +and therefore, you do not need to report them as bugs. + +\section1 Possible Problems After Automatic Mesh Optimization + +When loading a presentation made with an earlier version (2.0 beta2 or older) of Qt 3D Studio +which has imported FBX or DAE models, you may see the following message box: + +\image {mesh_optimization.png}{Old presentation version} + +If your \b{imported} models are not visible in the Viewer after seeing the message, you need to +edit your \e .uip files manually. Some older versions of Studio referenced meshes with revision +number in the \e .uip file, and that revision causes it to be missing in the scope of the +Viewer. + +You need to find all occurrences of \c{.mesh#<revision_number>} from your \e .uip files and +replace them with \c{.mesh}. + +\section1 QML Stream with Window Element Causes Viewer Crash + +Opening a project that has a QML stream including a Window element causes the viewer to crash. + +\section1 Changes to Material Definitions Saved Separately from the Project + +When importing a 3D model to your project, a material definition file is created for each material +in the model. Material definitions are stored separately from the project, meaning that all +changes to these materials are saved even if the project is not saved. + +Refreshing the 3D model import file resets the material properties. + +*/ diff --git a/doc/src/layers.qdoc b/doc/src/layers.qdoc index 1128e0c1..6bec78dc 100644 --- a/doc/src/layers.qdoc +++ b/doc/src/layers.qdoc @@ -112,4 +112,8 @@ the colors of the background layer or object. The \l{Disable Depth Test} property can be used to simultaneously override depth testing and the order objects are rendered. +\section2 Variant Tags +\l{Using Variant Tags}{Variant tags} makes it possible to exclude layers during loading to +optimize performance. + */ diff --git a/doc/src/lights.qdoc b/doc/src/lights.qdoc new file mode 100644 index 00000000..2776f8c9 --- /dev/null +++ b/doc/src/lights.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 Lights +\page lights.html + +Lights are the primary source to provide lighting in a Studio scene. Another way to light a +scene is \l{Using Image-based Lighting}{Image Based Lighting}. + +By default, all new presentations will be created with one directional light in them. Additionally, +all layers created will be created with one directional light on them. The default scope of a light +is the layer they are located on, meaning that all objects on that layer will be effected by the +light. + +\note Each additional light will reduce rendering performance of your presentation. Keep it +as simple as possible and use lights sparingly. + +\section1 Light Types + +\section2 Directional + +The directional light emits light in one direction from a unidentifiable source located infinitely +far away. This is similar to the way sun light works in real life. If +\l {light properties}{Cast Shadows} is enabled, shadows will be parallel to the light direction. +A directional light has infinite range and does not diminish. + +\image directional-light.png + +Moving a directional light does not have any effect. The light will always +be emitted in the direction of the lights Z axis, rotating the light along its X or Y axis will +change the direction the light is emitted. + +Scaling a directional light will only have an effect in the following cases: + +\list + \li + If Z scale is set to a negative number, the light will be emitted in opposite direction. + \li + If the scale of any axis is set to 0, the light will be emitted along the world's Z axis. + Rotating the light will then have no effect. +\endlist + +\image directional-light-scene.png + +By default, all new light objects created in Studio will be directional lights. + +\section2 Point + +The point light can be described as a sphere, emitting light with equal strength in all directions +from the center of the light. This is similar to the way a light bulb emits light. + +\image point-light.png + +Rotating or scaling a point light does not have any effect. Moving a point light will change the +position from where the light is emitted. + +\image point-light-scene.png + +By default, a point light has infinite range and does not diminish. However, the fade-off +(and range) can be controlled with the \l {light properties}{Linear Fade} +and \l {light properties}{Exponential Fade} properties. + +The table below shows the difference between linear and exponential fade. In this example the Z +position of the light is 0, while the Z position of the cubes are 200, 400 and 700 +respectively. The brightness of the light is 200. + +\table + \header + \li + \li {4,1} Fade value + \row + \li + \li 20 + \li 50 + \li 100 + \li 200 + \row + \li Linear fade + \li \image linear-fade-20.png + \li \image linear-fade-50.png + \li \image linear-fade-100.png + \li \image linear-fade-200.png + \row + \li Exponential fade + \li \image exponential-fade-20.png + \li \image exponential-fade-50.png + \li \image exponential-fade-100.png + \li \image exponential-fade-200.png +\endtable + +\section2 Area + +The area light is similar to the directional light, but instead of emitting equally bright light +across the whole scene, the area light emits directional light from a rectangle shaped object. Aside +from the size, an area light has the same characteristics and properties as the directional light. + +The image below shows an example on how to light an object with different colors using two +different area lights. + +\image area-light.png + +Rotating, scaling and moving actions will all effect an area light. + +\section1 Working with Lights + +\section2 Add Lights + +To add a light to a layer, drag it from the basic objects palette to either the scene graph or the +scene view. + +\section2 Delete Lights +To delete a light, do one of the following: + +\list 1 + \li Select the light in the scene graph or scene view, next press the \c Del key. + \li Right-click the light in the scene graph, next select \uicontrol {Delete Object} from the + context menu. +\endlist + +\section1 Animating Lights + +It is possible to animate most of the properties for lights. To read more about animations, see +the \l {Animations} section. + +\section1 Light Properties + +For full details on all light properties, see the +\l{studio-inspector-palette.html#light-properties}{inspector palette documentation}. + +*/ diff --git a/doc/src/tutorials.qdoc b/doc/src/tutorials.qdoc index c7b4d4ab..32ab7bc0 100644 --- a/doc/src/tutorials.qdoc +++ b/doc/src/tutorials.qdoc @@ -52,6 +52,10 @@ \l {Using Behavior Scripts} Learn how to use behavior scripts in your project. + \li + \l {Using Variant Tags} + + Learn how to use variant tags to exclude parts of a presentation during loading. \endlist */ diff --git a/doc/src/variant-tags.qdoc b/doc/src/variant-tags.qdoc new file mode 100644 index 00000000..142bce50 --- /dev/null +++ b/doc/src/variant-tags.qdoc @@ -0,0 +1,120 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 Using Variant Tags +\page using-variant-tags.html + +The variant tags feature in 3D Studio enables excluding parts of a presentation during loading. +With variant tags you can avoid parsing and loading objects that are not needed in the presentation +for certain variants, saving on loading time and resource usage. + +This makes it possible to create multiple variations of a product UI with one single Qt 3D Studio +presentation. + +This page explains how to define and use variant tags in the editor. The variant tags will then +be loaded from the QML application. + +\image variant-tags.png + +\section1 Create Variant Groups and Tags + +Variant filtering is done on layer level, to add a variant group and tags to that group, +select a layer in the scene graph and follow the steps below: + +\list 1 + \li In the inspector palette, press \uicontrol {+ Group} in the Variant Tags section. + \li Enter a group name, and press \uicontrol {Ok}. + \note Group names must be unique to the project. +\endlist + +Once you have created a variant group, you can create variant tags under it. To do so, +follow the steps below: + +\list 1 + \li In the inspector palette, press the \uicontrol {+ Tag} next to the variant group name. + \li Enter a tag name, and press \uicontrol {Ok}. + \note Tag names must be unique to the variant group. +\endlist + +\section1 Using Variant Tags + +To use a variant tag on a layer, follow the steps below: + +\list 1 + \li In the scene graph, select desired layer + \li In the inspector palette, under the variant tag section, click desired variant tags to use + them on the layer. +\endlist + +Once you have assigned variant tags to a layer, it is indicated in the scene graph which layers +are using tags from which variant groups. + +\image variant-tags-layer.png + +It is also indicated in the slide palette, which slides are using tags from which variant groups. +Here you can see the number of tags from each variant group used on each slide. + +\image variant-tags-slide.png + +\section1 Edit Variant Groups and Tags + +\section2 Edit a Variant Group + +You can edit name and color of a variant group. To do so, right-click the name of it in the +inspector palette and select desired action from the context menu. + +\section2 Edit a Variant Tag +You can edit the name of a variant tag. To do so, right-click the name of it in the inspector +palette and select \uicontrol {Rename Tag} from the context menu. + +\section2 Delete a Variant Tag or Group + +You can delete a variant tag or group by right-clicking the name of it in the inspector palette and +select \uicontrol {Delete Tag/Group}. + +\section1 Importing and Exporting Variant Groups + +You can import and export variant groups. Exporting will export all variant groups and tags to a +\c {.variants} file, default location for the export file is the project's \e presentation folder. + +\section2 Export Variant Groups + +To export variant groups, select the \uicontrol {Export} button in the variant tags section +in the inspector palette. Next, browse to the desired location, enter a file name, +and press \uicontrol {Save}. + +\section2 Import Variant Groups + +To import variant groups, select the \uicontrol {Import} button in the variant tags section +in the inspector palette. Next, browse to the desired \c .variants or \c .uia file and select +\uicontrol{Ok}. + +When importing variant tags, imported tags will be merged with already existing tags. + +*/ |
