From ed56f16c4b1bb61a459a005d64794fec5d4aa19e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niklas=20S=C3=B6derlund?= <niklas.soderlund@ragnatech.se>
Date: Sat, 25 May 2019 00:11:44 +0200
Subject: libcamera: geometry: SizeRange: Extend with step information
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The size range described might be subject to certain step
limitations. Make it possible to record this information.

Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 src/libcamera/geometry.cpp | 49 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 3 deletions(-)

(limited to 'src/libcamera/geometry.cpp')

diff --git a/src/libcamera/geometry.cpp b/src/libcamera/geometry.cpp
index 26a05b9e..1ea10293 100644
--- a/src/libcamera/geometry.cpp
+++ b/src/libcamera/geometry.cpp
@@ -186,9 +186,29 @@ bool operator<(const Size &lhs, const Size &rhs)
  * \struct SizeRange
  * \brief Describe a range of sizes
  *
- * SizeRange describes a range of sizes included in the [min, max]
- * interval for both the width and the height. If the minimum and
- * maximum sizes are identical it represents a single size.
+ * A SizeRange describes a range of sizes included in the [min, max] interval
+ * for both the width and the height. If the minimum and maximum sizes are
+ * identical it represents a single size.
+ *
+ * Size ranges may further limit the valid sizes through steps in the horizontal
+ * and vertical direction. The step values represent the increase in pixels
+ * between two valid width or height values, starting from the minimum. Valid
+ * sizes within the range are thus expressed as
+ *
+ *	width = min.width + hStep * x
+ *	height = min.height + vStep * y
+ *
+ *	Where
+ *
+ *	width <= max.width
+ *	height < max.height
+ *
+ * Note that the step values are not equivalent to alignments, as the minimum
+ * width or height may not be a multiple of the corresponding step.
+ *
+ * The step values may be zero when the range describes only minimum and
+ * maximum sizes without implying that all, or any, intermediate size is valid.
+ * SizeRange instances the describe a single size have both set values set to 1.
  */
 
 /**
@@ -213,6 +233,19 @@ bool operator<(const Size &lhs, const Size &rhs)
  * \param[in] maxH The maximum height
  */
 
+/**
+ * \fn SizeRange::SizeRange(unsigned int minW, unsigned int minH,
+ *			    unsigned int maxW, unsigned int maxH,
+ *			    unsigned int hstep, unsigned int vstep)
+ * \brief Construct an initialized size range
+ * \param[in] minW The minimum width
+ * \param[in] minH The minimum height
+ * \param[in] maxW The maximum width
+ * \param[in] maxH The maximum height
+ * \param[in] hstep The horizontal step
+ * \param[in] vstep The vertical step
+ */
+
 /**
  * \var SizeRange::min
  * \brief The minimum size
@@ -223,6 +256,16 @@ bool operator<(const Size &lhs, const Size &rhs)
  * \brief The maximum size
  */
 
+/**
+ * \var SizeRange::hStep
+ * \brief The horizontal step
+ */
+
+/**
+ * \var SizeRange::vStep
+ * \brief The vertical step
+ */
+
 /**
  * \brief Compare size ranges for equality
  * \return True if the two size ranges are equal, false otherwise
-- 
cgit v1.2.1