From f7647d5adaaed4c651cb2e65c7ce66d7ef6639f1 Mon Sep 17 00:00:00 2001
From: Shawn Rutledge <shawn.rutledge@qt.io>
Date: Mon, 23 Dec 2019 08:39:26 +0100
Subject: Add Image.sourceClipRect property
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since we set sourceSize, we expect to use that coordinate system in
sourceClipRect too.  Therefore we use QImageReader::setScaledClipRect(),
not setClipRect().

[ChangeLog][QtQuick][Image] Image now has a sourceClipRect property
to render a clipped image from a region of the sourceSize.

Change-Id: If08277df772c2ab1063dd88572e49de41b97bca4
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
---
 src/quick/items/qquickimage.cpp | 54 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 3 deletions(-)

(limited to 'src/quick/items/qquickimage.cpp')

diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp
index fccacdcce8..1882ec8997 100644
--- a/src/quick/items/qquickimage.cpp
+++ b/src/quick/items/qquickimage.cpp
@@ -427,10 +427,10 @@ qreal QQuickImage::paintedHeight() const
 /*!
     \qmlproperty QSize QtQuick::Image::sourceSize
 
-    This property holds the actual width and height of the loaded image.
+    This property holds the scaled width and height of the full-frame image.
 
     Unlike the \l {Item::}{width} and \l {Item::}{height} properties, which scale
-    the painting of the image, this property sets the actual number of pixels
+    the painting of the image, this property sets the maximum number of pixels
     stored for the loaded image so that large images do not use more
     memory than necessary. For example, this ensures the image in memory is no
     larger than 1024x1024 pixels, regardless of the Image's \l {Item::}{width} and
@@ -455,7 +455,7 @@ qreal QQuickImage::paintedHeight() const
     other dimension is set in proportion to preserve the source image's aspect ratio.
     (The \l fillMode is independent of this.)
 
-    If both the sourceSize.width and sourceSize.height are set the image will be scaled
+    If both the sourceSize.width and sourceSize.height are set, the image will be scaled
     down to fit within the specified size (unless PreserveAspectCrop or PreserveAspectFit
     are used, then it will be scaled to match the optimal size for cropping/fitting),
     maintaining the image's aspect ratio.  The actual
@@ -470,6 +470,9 @@ qreal QQuickImage::paintedHeight() const
     be no greater than this property specifies. For some formats (currently only JPEG),
     the whole image will never actually be loaded into memory.
 
+    If the \l sourceClipRect property is also set, \c sourceSize determines the scale,
+    but it will be clipped to the size of the clip rectangle.
+
     sourceSize can be cleared to the natural size of the image
     by setting sourceSize to \c undefined.
 
@@ -477,6 +480,51 @@ qreal QQuickImage::paintedHeight() const
     potentially even from the network, if it is not in the disk cache.}
 */
 
+/*!
+    \qmlproperty rect QtQuick::Image::sourceClipRect
+    \since 5.15
+
+    This property, if set, holds the rectangular region of the source image to
+    be loaded.
+
+    The \c sourceClipRect works together with the \l sourceSize property to
+    conserve system resources when only a portion of an image needs to be
+    loaded.
+
+    \code
+    Rectangle {
+        width: ...
+        height: ...
+
+        Image {
+           anchors.fill: parent
+           source: "reallyBigImage.svg"
+           sourceSize.width: 1024
+           sourceSize.height: 1024
+           sourceClipRect: Qt.rect(100, 100, 512, 512)
+        }
+    }
+    \endcode
+
+    In the above example, we conceptually scale the SVG graphic to 1024x1024
+    first, and then cut out a region of interest that is 512x512 pixels from a
+    location 100 pixels from the top and left edges. Thus \c sourceSize
+    determines the scale, but the actual output image is 512x512 pixels.
+
+    Some image formats are able to conserve CPU time by rendering only the
+    specified region. Others will need to load the entire image first and then
+    clip it to the specified region.
+
+    This property can be cleared to reload the entire image by setting
+    \c sourceClipRect to \c undefined.
+
+    \note \e {Changing this property dynamically causes the image source to be reloaded,
+    potentially even from the network, if it is not in the disk cache.}
+
+    \note Sub-pixel clipping is not supported: the given rectangle will be
+    passed to \l QImageReader::setScaledClipRect().
+*/
+
 /*!
     \qmlproperty url QtQuick::Image::source
 
-- 
cgit v1.2.3