From e553cb973c789b89b3932d97d35eb596377d7043 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Wed, 8 Jan 2025 17:49:27 +0100
Subject: [PATCH] Document why Image*::size() is returning a const&.

---
 src/Magnum/Image.h           | 6 ++++++
 src/Magnum/ImageView.h       | 6 ++++++
 src/Magnum/Trade/ImageData.h | 3 +++
 3 files changed, 15 insertions(+)

diff --git a/src/Magnum/Image.h b/src/Magnum/Image.h
index 0e923e9ce..2eda2e841 100644
--- a/src/Magnum/Image.h
+++ b/src/Magnum/Image.h
@@ -405,6 +405,9 @@ template<UnsignedInt dimensions> class Image {
         UnsignedInt pixelSize() const { return _pixelSize; }
 
         /** @brief Image size in pixels */
+        /* Unlike other getters this one is a const& so it's possible to slice
+           to the sizes when all images are in an array, for example for use
+           in TextureTools atlas APIs */
         const VectorTypeFor<dimensions, Int>& size() const { return _size; }
 
         /**
@@ -661,6 +664,9 @@ template<UnsignedInt dimensions> class CompressedImage {
         CompressedPixelFormat format() const { return _format; }
 
         /** @brief Image size in pixels */
+        /* Unlike other getters this one is a const& so it's possible to slice
+           to the sizes when all images are in an array, for example for use
+           in TextureTools atlas APIs */
         const VectorTypeFor<dimensions, Int>& size() const { return _size; }
 
         /**
diff --git a/src/Magnum/ImageView.h b/src/Magnum/ImageView.h
index 18067f7d7..b34ec85b7 100644
--- a/src/Magnum/ImageView.h
+++ b/src/Magnum/ImageView.h
@@ -452,6 +452,9 @@ template<UnsignedInt dimensions, class T> class ImageView {
         UnsignedInt pixelSize() const { return _pixelSize; }
 
         /** @brief Image size in pixels */
+        /* Unlike other getters this one is a const& so it's possible to slice
+           to the sizes when all images are in an array, for example for use
+           in TextureTools atlas APIs */
         const VectorTypeFor<dimensions, Int>& size() const { return _size; }
 
         /**
@@ -837,6 +840,9 @@ template<UnsignedInt dimensions, class T> class CompressedImageView {
         CompressedPixelFormat format() const { return _format; }
 
         /** @brief Image size in pixels */
+        /* Unlike other getters this one is a const& so it's possible to slice
+           to the sizes when all images are in an array, for example for use
+           in TextureTools atlas APIs */
         const VectorTypeFor<dimensions, Int>& size() const { return _size; }
 
         /**
diff --git a/src/Magnum/Trade/ImageData.h b/src/Magnum/Trade/ImageData.h
index 3f7584495..21b51ae3a 100644
--- a/src/Magnum/Trade/ImageData.h
+++ b/src/Magnum/Trade/ImageData.h
@@ -757,6 +757,9 @@ template<UnsignedInt dimensions> class ImageData {
         UnsignedInt pixelSize() const;
 
         /** @brief Image size in pixels */
+        /* Unlike other getters this one is a const& so it's possible to slice
+           to the sizes when all images are in an array, for example for use
+           in TextureTools atlas APIs */
         const VectorTypeFor<dimensions, Int>& size() const { return _size; }
 
         /**