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