1 files changed, 107 insertions, 4 deletions
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index d45fb31fd9..b8362c9dac 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -397,7 +397,7 @@ void QQuickItemKeyFilter::componentComplete()
     \c KeyNavigation.BeforeItem allows the event to be used for key navigation
     before the item, rather than after.
 
-    If item to which the focus is switching is not enabled or visible, an attempt will
+    If the item to which the focus is switching is not enabled or visible, an attempt will
     be made to skip this item and focus on the next. This is possible if there are
     a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled
     or visible, they will also be skipped.
@@ -405,7 +405,7 @@ void QQuickItemKeyFilter::componentComplete()
     KeyNavigation will implicitly set the other direction to return focus to this item. So if you set
     \l left to another item, \l right will be set on that item's KeyNavigation to set focus back to this
     item. However, if that item's KeyNavigation has had right explicitly set then no change will occur.
-    This means that the above example could have been written, with the same behaviour, without specifying
+    This means that the example above could achieve the same behavior without specifying
     KeyNavigation.right or KeyNavigation.down for any of the items.
 
     \sa {Keys}{Keys attached property}
@@ -887,6 +887,8 @@ bool QQuickKeysAttached::isConnected(const char *signalName)
     handling.  If the item accepts the key event it will not be
     handled by the Keys attached property handler.
     \endlist
+
+    \sa {Key Handling Priorities}
 */
 
 /*!
@@ -914,6 +916,9 @@ bool QQuickKeysAttached::isConnected(const char *signalName)
         focus: true
     }
     \endqml
+
+    To see the order in which events are received when using forwardTo, see
+    \l {Key Handling Priorities}.
 */
 
 /*!
@@ -1833,6 +1838,101 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     their layouts.
 
     See LayoutMirroring for more details.
+
+    \section1 Item Layers
+
+    An Item will normally be rendered directly into the window it
+    belongs to. However, by setting \l layer.enabled, it is possible
+    to delegate the item and its entire subtree into an offscreen
+    surface. Only the offscreen surface, a texture, will be then drawn
+    into the window.
+
+    If it is desired to have a texture size different from that of the
+    item, this is possible using \l layer.textureSize. To render only
+    a section of the item into the texture, use \l
+    layer.sourceRect. It is also possible to specify \l
+    layer.sourceRect so it extends beyond the bounds of the item. In
+    this case, the exterior will be padded with transparent pixels.
+
+    The item will use linear interpolation for scaling if
+    \l layer.smooth is set to \c true and will use mipmap for
+    downsampling if \l layer.mipmap is set to \c true. Mipmapping may
+    improve visual quality of downscaled items. For mipmapping of
+    single Image items, prefer Image::mipmap.
+
+    \section2 Layer Opacity vs Item Opacity
+
+    When applying \l opacity to an item hierarchy the opacity is
+    applied to each item individually. This can lead to undesired
+    visual results when the opacity is applied to a subtree. Consider
+    the following example:
+
+    \table
+    \row
+      \li \inlineimage qml-blending-nonlayered.png
+      \li \b {Non-layered Opacity} \snippet qml/layerblending.qml non-layered
+    \endtable
+
+    A layer is rendered with the root item's opacity being 1, and then
+    the root item's opacity is applied to the texture when it is
+    drawn. This means that fading in a large item hierarchy from
+    transparent to opaque, or vice versa, can be done without the
+    overlap artifacts that the normal item by item alpha blending
+    has. Here is the same example with layer enabled:
+
+    \table
+    \row
+      \li \image qml-blending-layered.png
+      \li \b {Layered Opacity} \snippet qml/layerblending.qml layered
+    \endtable
+
+    \section2 Combined with ShaderEffects
+
+    Setting \l layer.enabled to true will turn the item into a \l
+    {QQuickItem::isTextureProvider}{texture provider}, making it
+    possible to use the item directly as a texture, for instance
+    in combination with the ShaderEffect type.
+
+    It is possible to apply an effect on a layer at runtime using
+    layer.effect:
+
+    \snippet qml/layerwitheffect.qml 1
+
+    In this example, we implement the shader effect manually. The \l
+    {Qt Graphical Effects} module contains a suite of ready-made
+    effects for use with Qt Quick.
+
+    See ShaderEffect for more information about using effects.
+
+    \note \l layer.enabled is actually just a more convenient way of using
+    ShaderEffectSource.
+
+
+    \section2 Memory and Performance
+
+    When an item's layer is enabled, the scene graph will allocate memory
+    in the GPU equal to \c {width x height x 4}. In memory constrained
+    configurations, large layers should be used with care.
+
+    In the QPainter / QWidget world, it is some times favorable to
+    cache complex content in a pixmap, image or texture. In Qt Quick,
+    because of the techniques already applied by the \l {Qt Quick
+    Scene Graph Renderer} {scene graph renderer}, this will in most
+    cases not be the case. Excessive draw calls are already reduced
+    because of batching and a cache will in most cases end up blending
+    more pixels than the original content. The overhead of rendering
+    to an offscreen and the blending involved with drawing the
+    resulting texture is therefore often more costly than simply
+    letting the item and its children be drawn normally.
+
+    Also, an item using a layer can not be \l {Batching} {batched} during
+    rendering. This means that a scene with many layered items may
+    have performance problems.
+
+    Layering can be convenient and useful for visual effects, but
+    should in most cases be enabled for the duration of the effect and
+    disabled afterwards.
+
 */
 
 /*!
@@ -7481,12 +7581,15 @@ void QQuickItemLayer::setMipmap(bool mipmap)
     allow you to save some texture memory.
 
     \list
-    \li ShaderEffectSource.Alpha - GL_ALPHA
+    \li ShaderEffectSource.Alpha - GL_ALPHA;
     \li ShaderEffectSource.RGB - GL_RGB
     \li ShaderEffectSource.RGBA - GL_RGBA
     \endlist
 
-    \note Some OpenGL implementations do not support the GL_ALPHA format.
+    \note ShaderEffectSource.RGB and ShaderEffectSource.Alpha should
+    be used with caution, as support for these formats in the underlying
+    hardare and driver is often not present.
+
  */
 
 void QQuickItemLayer::setFormat(QQuickShaderEffectSource::Format f)