dali/internal/common/image-attributes.h

   1 #ifndef DALI_INTERNAL_IMAGE_ATTRIBUTES_H
   2 #define DALI_INTERNAL_IMAGE_ATTRIBUTES_H
   3
   4 /*
   5  * Copyright (c) 2021 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <stdint.h>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/images/image-operations.h>
  26 #include <dali/public-api/images/pixel.h>
  27 #include <dali/public-api/math/rect.h>
  28 #include <dali/public-api/math/vector2.h>
  29
  30 namespace Dali
  31 {
  32 namespace Internal
  33 {
  34 /**
  35  * @brief Describes Image properties like dimensions and pixel format and
  36  * operations to be applied to images during the load process.
  37  *
  38  * ImageAttributes is used to define a set of properties of an image and a
  39  * sequence of operations to be applied when loading it.
  40  *
  41  * The overall order of operations which can be applied is:
  42  *   1. Determine the desired dimensions for the final bitmap.
  43  *   2. Scale the image to fit the desired dimensions.
  44  *
  45  * The default for each stage is to do nothing.
  46  * To enable a calculation of desired final image dimensions and fitting to it, SetSize() must be called.
  47  *
  48  * The loader does not guarantee to rescale a loaded image to the exact desired dimensions, but it will make a best effort to downscale images.
  49  * The fitting to destination dimensions controlled by the ScalingMode may choose to fit to a larger area with an equivalent aspect ratio.
  50  * If the requested dimensions are larger than the loaded ones, it will never upscale on load to fill them but will instead fit to smaller dimensions of identical aspect ratio.
  51  * This is transparent to an application as the upscaling can happen during rendering.
  52  *
  53  * To enable scaling of images on load, desired dimensions must be set using SetSize().
  54  * Only one of the dimensions need be supplied, in which case, the other is calculated based on the aspect ratio of the raw loaded image.
  55  * The desired dimensions 2-tuple 'd' is determined as follows for loaded image dimensions 'l' and 's', the dimensions tuple set with SetSize():
  56  *   *  `d = s, if s.x != 0 & s.y != 0, else:`
  57  *   *  `d = [s.x, s.x * (l.y / l.x)], if s.x != 0 & s.y = 0, else:`
  58  *   *  `d = [s.y * (l.x / l.y), s.y], if s.x = 0 & s.y != 0, else:`
  59  *   *  `d = l, otherwise.`
  60  *
  61  * Use cases for scaling images on load include:
  62  *   1. Full-screen image display: Limit loaded image resolution to device resolution using ShrinkToFit mode.
  63  *   2. Thumbnail gallery grid: Limit loaded image resolution to screen tile using ScaleToFill mode.
  64  *   3. Image columns: Limit loaded image resolution to column width using FitWidth mode.
  65  *   4. Image rows: Limit loaded image resolution to row height using FitHeight mode.
  66  *
  67  * @note The aspect ratio of image contents is preserved by all scaling modes, so for example squares in input images stay square after loading.
  68  */
  69 class ImageAttributes
  70 {
  71 public:
  72   /**
  73    * @brief Scaling options, used when resizing images on load to fit desired dimensions.
  74    *
  75    * A scaling mode controls the region of a loaded image to be mapped to the
  76    * desired image rectangle specified using ImageAttributes.SetSize().
  77    * All scaling modes preserve the aspect ratio of the image contents.
  78    */
  79   typedef Dali::FittingMode::Type ScalingMode;
  80
  81   /**
  82    * @brief Filtering options, used when resizing images on load to sample original pixels.
  83    *
  84    * A FilterMode controls how pixels in the raw image on-disk are sampled and
  85    * combined to generate each pixel of the destination loaded image.
  86    *
  87    * @note NoFilter and Box modes do not guarantee that the loaded pixel array
  88    * exactly matches the rectangle specified by the desired dimensions and
  89    * ScalingMode, but all other filter modes do if the desired dimensions are
  90    * `<=` the raw dimensions of the image file.
  91    */
  92   using FilterMode = Dali::SamplingMode::Type;
  93
  94   static const ImageAttributes DEFAULT_ATTRIBUTES; ///< Default attributes have no size
  95
  96   /**
  97    * @brief Default constructor, initializes to default values.
  98    */
  99   ImageAttributes();
 100
 101   /**
 102    * @brief This copy constructor is required for correctly copying internal implementation.
 103    *
 104    * @param [in] rhs A reference to the copied handle
 105    */
 106   ImageAttributes(const ImageAttributes& rhs);
 107
 108   /**
 109    * @brief This assignment operator is required for correctly handling the internal implementation.
 110    *
 111    * @param [in] rhs  A reference to the copied handle
 112    * @return a reference to this object
 113    */
 114   ImageAttributes& operator=(const ImageAttributes& rhs);
 115
 116   /**
 117    * @brief Default destructor.
 118    */
 119   ~ImageAttributes();
 120
 121   /**
 122    * @brief Create an initialised image attributes object.
 123    *
 124    * @return A handle to a newly allocated object
 125    */
 126   static ImageAttributes New();
 127
 128   /**
 129    * @brief Set the size properties.
 130    *
 131    * By default width and height are set to zero which means the image loaded has the original size.
 132    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 133    * the one that is set and the aspect ratio of the image.
 134    *
 135    * @param [in] width  desired width.
 136    * @param [in] height desired height
 137    */
 138   void SetSize(uint32_t width, uint32_t height);
 139
 140   /**
 141    * @brief Set the image dimension properties.
 142    *
 143    * By default, width and height are set to zero which means the image loaded has the original size.
 144    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 145    * the one that is set and the aspect ratio of the image.
 146    *
 147    * @param [in] size desired size.
 148    */
 149   void SetSize(const Size& size);
 150
 151   /**
 152    * @brief Set the scale field of the image attributes.
 153    *
 154    * By default, ShrinkToFit is set.
 155    * @param [in] scalingMode The desired scaling mode
 156    */
 157   void SetScalingMode(ScalingMode scalingMode);
 158
 159   /**
 160    * @brief Setter for the FilterMode.
 161    * By default, Box is set.
 162    * @param [in] filterMode The desired filter mode.
 163    */
 164   void SetFilterMode(FilterMode filterMode);
 165
 166   /**
 167    * @brief Set whether the image will be rotated/flipped back into portrait orientation.
 168    *
 169    * This will only be necessary if metadata indicates that the
 170    * image has a different viewing orientation.
 171    *
 172    * This metadata, optionally present in formats that use exif for example,
 173    * can encode the physical orientation of the camera which took the picture,
 174    * establishing which directions in the image correspond to real-world "up"
 175    * and the horizon.
 176    * By default the metadata is ignored, but if this function is called with
 177    * the value "true", the pixels of an image are reordered at load time to reflect
 178    * the orientation in the metadata.
 179    *
 180    * @param [in] enabled If true, the image orientation metadata will be used to
 181    *                     transform the pixels of the image as laid-out in memory.
 182    */
 183   void SetOrientationCorrection(bool enabled);
 184
 185   /**
 186    * @brief Change all members in one operation.
 187    * @param[in] dimensions width and height
 188    * @param[in] scaling Scaling mode for resizing loads.
 189    * @param[in] sampling Sampling mode.
 190    * @param[in] orientation Orientation correction toggle.
 191    */
 192   void Reset(ImageDimensions dimensions = ImageDimensions(0, 0), ScalingMode scaling = ScalingMode(), FilterMode sampling = FilterMode(), bool orientationCorrection = true);
 193
 194   /**
 195    * @brief Return the width currently represented by the attribute.
 196    *
 197    * @return width
 198    */
 199   unsigned int GetWidth() const;
 200
 201   /**
 202    * @brief Return the height currently represented by the attribute.
 203    *
 204    * @return height
 205    */
 206   unsigned int GetHeight() const;
 207
 208   /**
 209    * @brief Return the size currently represented by the attribute.
 210    *
 211    * @return size
 212    */
 213   Size GetSize() const;
 214
 215   /**
 216    * @brief Return the scale currently represented by the attribute.
 217    *
 218    * @return scale
 219    */
 220   ScalingMode GetScalingMode() const;
 221
 222   /**
 223    * @brief Getter for the FilterMode
 224    *
 225    * @return The FilterMode previously set, or the default value if none has
 226    *         been.
 227    */
 228   FilterMode GetFilterMode() const;
 229
 230   /**
 231    * @brief Whether to correct for physical orientation of an image.
 232    *
 233    * @return Whether image pixels should be transformed according to the
 234    *         orientation metadata, if any.
 235    */
 236   bool GetOrientationCorrection() const;
 237
 238   /**
 239    * @brief Less then comparison operator.
 240    *
 241    * @param [in] a parameter tested
 242    * @param [in] b parameter tested
 243    * @return true if a is less than b
 244    */
 245   friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 246
 247   /**
 248    * @brief Equal to comparison operator.
 249    *
 250    * @param [in] a parameter tested for equality
 251    * @param [in] b parameter tested for equality
 252    * @return true if a is equal to b
 253    */
 254   friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 255
 256   /**
 257    * @brief Not equal to comparison operator.
 258    *
 259    * @param [in] a parameter tested for equality
 260    * @param [in] b parameter tested for equality
 261    * @return true if a is not equal to b
 262    */
 263   friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 264
 265 private:
 266   struct ImageAttributesImpl;
 267   ImageAttributesImpl* impl; ///< Implementation pointer
 268 };
 269
 270 /**
 271  * @brief Less then comparison operator.
 272  *
 273  * @param [in] a parameter tested
 274  * @param [in] b parameter tested
 275  * @return true if a is less than b
 276  */
 277 bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 278
 279 /**
 280  * @brief Equal to comparison operator.
 281  *
 282  * @param [in] a parameter tested for equality
 283  * @param [in] b parameter tested for equality
 284  * @return true if a is equal to b
 285  */
 286 bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 287
 288 /**
 289  * @brief Not equal to comparison operator.
 290  *
 291  * @param [in] a parameter tested for equality
 292  * @param [in] b parameter tested for equality
 293  * @return true if a is not equal to b
 294  */
 295 bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 296
 297 } // namespace Internal
 298 } // namespace Dali
 299
 300 #endif // DALI_INTERNAL_IMAGE_ATTRIBUTES_H