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) 2014 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 DALI_IMPORT_API 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 Create an initialised image attributes object.
 132    *
 133    * @param [in] width         desired width.
 134    * @param [in] height        desired height
 135    * @return A handle to a newly allocated object
 136    */
 137    static ImageAttributes New(unsigned int width, unsigned int height);
 138
 139   /**
 140    * @brief Set the size properties.
 141    *
 142    * By default width and height are set to zero which means the image loaded has the original size.
 143    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 144    * the one that is set and the aspect ratio of the image.
 145    *
 146    * @param [in] width  desired width.
 147    * @param [in] height desired height
 148    */
 149   void SetSize(unsigned int width, unsigned int height);
 150
 151   /**
 152    * @brief Set the image dimension properties.
 153    *
 154    * By default, width and height are set to zero which means the image loaded has the original size.
 155    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 156    * the one that is set and the aspect ratio of the image.
 157    *
 158    * @param [in] size desired size.
 159    */
 160   void SetSize( const Size& size );
 161
 162   /**
 163    * @brief Set the scale field of the image attributes.
 164    *
 165    * By default, ShrinkToFit is set.
 166    * @param [in] scalingMode The desired scaling mode
 167    */
 168   void SetScalingMode( ScalingMode scalingMode );
 169
 170   /**
 171    * @brief Setter for the FilterMode.
 172    * By default, Box is set.
 173    * @param [in] filterMode The desired filter mode.
 174    */
 175   void SetFilterMode( FilterMode filterMode );
 176
 177   /**
 178    * @brief Set whether the image will be rotated/flipped back into portrait orientation.
 179    *
 180    * This will only be necessary if metadata indicates that the
 181    * image has a different viewing orientation.
 182    *
 183    * This metadata, optionally present in formats that use exif for example,
 184    * can encode the physical orientation of the camera which took the picture,
 185    * establishing which directions in the image correspond to real-world "up"
 186    * and the horizon.
 187    * By default the metadata is ignored, but if this function is called with
 188    * the value "true", the pixels of an image are reordered at load time to reflect
 189    * the orientation in the metadata.
 190    *
 191    * @param [in] enabled If true, the image orientation metadata will be used to
 192    *                     transform the pixels of the image as laid-out in memory.
 193    */
 194   void SetOrientationCorrection(bool enabled);
 195
 196   /**
 197    * @brief Change all members in one operation.
 198    * @param[in] dimensions width and height
 199    * @param[in] scaling Scaling mode for resizing loads.
 200    * @param[in] sampling Sampling mode.
 201    * @param[in] orientation Orientation correction toggle.
 202    */
 203   void Reset( ImageDimensions dimensions = ImageDimensions(0, 0), ScalingMode scaling = ScalingMode(), FilterMode sampling = FilterMode(), bool orientationCorrection = true );
 204
 205
 206   /**
 207    * @brief Return the width currently represented by the attribute.
 208    *
 209    * @return width
 210    */
 211   unsigned int GetWidth() const;
 212
 213   /**
 214    * @brief Return the height currently represented by the attribute.
 215    *
 216    * @return height
 217    */
 218   unsigned int GetHeight() const;
 219
 220   /**
 221    * @brief Return the size currently represented by the attribute.
 222    *
 223    * @return size
 224    */
 225   Size GetSize() const;
 226
 227   /**
 228    * @brief Return the scale currently represented by the attribute.
 229    *
 230    * @return scale
 231    */
 232   ScalingMode GetScalingMode() const;
 233
 234   /**
 235    * @brief Getter for the FilterMode
 236    *
 237    * @return The FilterMode previously set, or the default value if none has
 238    *         been.
 239    */
 240   FilterMode GetFilterMode() const;
 241
 242   /**
 243    * @brief Whether to correct for physical orientation of an image.
 244    *
 245    * @return Whether image pixels should be transformed according to the
 246    *         orientation metadata, if any.
 247    */
 248   bool GetOrientationCorrection() const;
 249
 250   /**
 251    * @brief Less then comparison operator.
 252    *
 253    * @param [in] a parameter tested
 254    * @param [in] b parameter tested
 255    * @return true if a is less than b
 256    */
 257   friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 258
 259   /**
 260    * @brief 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 equal to b
 265    */
 266   friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 267
 268   /**
 269    * @brief Not equal to comparison operator.
 270    *
 271    * @param [in] a parameter tested for equality
 272    * @param [in] b parameter tested for equality
 273    * @return true if a is not equal to b
 274    */
 275   friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 276
 277 private:
 278   struct ImageAttributesImpl;
 279   ImageAttributesImpl* impl; ///< Implementation pointer
 280 };
 281
 282 /**
 283  * @brief Less then comparison operator.
 284  *
 285  * @param [in] a parameter tested
 286  * @param [in] b parameter tested
 287  * @return true if a is less than b
 288  */
 289 DALI_IMPORT_API bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 290
 291 /**
 292  * @brief 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 equal to b
 297  */
 298 DALI_IMPORT_API bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 299
 300 /**
 301  * @brief Not equal to comparison operator.
 302  *
 303  * @param [in] a parameter tested for equality
 304  * @param [in] b parameter tested for equality
 305  * @return true if a is not equal to b
 306  */
 307 DALI_IMPORT_API bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 308
 309 } // namespace Internal
 310 } // namespace Dali
 311
 312 #endif // __DALI_INTERNAL_IMAGE_ATTRIBUTES_H__