dali/public-api/images/image-attributes.h

   1 #ifndef __DALI_IMAGE_ATTRIBUTES_H__
   2 #define __DALI_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 // INTERNAL INCLUDES
  22 #include <dali/public-api/images/pixel.h>
  23 #include <dali/public-api/math/rect.h>
  24 #include <dali/public-api/math/vector2.h>
  25
  26 namespace Dali
  27 {
  28
  29 class ImageAttributes;
  30
  31 /**
  32  * @brief Describes Image properties like dimensions and pixel format and
  33  * operations to be applied to images during the load process.
  34  *
  35  * ImageAttributes is used to define a set of properties of an image and a
  36  * sequence of operations to be applied when loading it.
  37  *
  38  * The overall order of operations which can be applied is:
  39  *   1. Determine the desired dimensions for the final bitmap.
  40  *   2. Scale the image to fit the desired dimensions.
  41  *
  42  * The default for each stage is to do nothing.
  43  * To enable a calculation of desired final image dimensions and fitting to it, SetSize() must be called.
  44  *
  45  * 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.
  46  * The fitting to destination dimensions controlled by the ScalingMode may choose to fit to a larger area with an equivalent aspect ratio.
  47  * 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.
  48  * This is transparent to an application as the upscaling can happen during rendering.
  49  *
  50  * To enable scaling of images on load, desired dimensions must be set using SetSize().
  51  * 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.
  52  * The desired dimensions 2-tuple 'd' is determined as follows for loaded image dimensions 'l' and 's', the dimensions tuple set with SetSize():
  53  *   *  `d = s, if s.x != 0 & s.y != 0, else:`
  54  *   *  `d = [s.x, s.x * (l.y / l.x)], if s.x != 0 & s.y = 0, else:`
  55  *   *  `d = [s.y * (l.x / l.y), s.y], if s.x = 0 & s.y != 0, else:`
  56  *   *  `d = l, otherwise.`
  57  *
  58  * Use cases for scaling images on load include:
  59  *   1. Full-screen image display: Limit loaded image resolution to device resolution using ShrinkToFit mode.
  60  *   2. Thumbnail gallery grid: Limit loaded image resolution to screen tile using ScaleToFill mode.
  61  *   3. Image columns: Limit loaded image resolution to column width using FitWidth mode.
  62  *   4. Image rows: Limit loaded image resolution to row height using FitHeight mode.
  63  *
  64  * @note The aspect ratio of image contents is preserved by all scaling modes, so for example squares in input images stay square after loading.
  65  */
  66 class DALI_IMPORT_API ImageAttributes
  67 {
  68 public:
  69
  70   /**
  71    * @brief Scaling options, used when resizing images on load to fit desired dimensions.
  72    *
  73    * A scaling mode controls the region of a loaded image to be mapped to the
  74    * desired image rectangle specified using ImageAttributes.SetSize().
  75    * All scaling modes preserve the aspect ratio of the image contents.
  76    */
  77   enum ScalingMode
  78   {
  79     ShrinkToFit, ///< Fit full image inside desired width & height, potentially not filling one of either the desired image width or height with pixels.
  80     ScaleToFill, ///< Image fills whole desired width & height with image data. The image is centred in the desired dimensions, exactly touching in one dimension, with image regions outside the other desired dimension cropped away.
  81     FitWidth,    ///< Image fills whole width. Height is scaled proportionately to maintain aspect ratio.
  82     FitHeight    ///< Image fills whole height. Width is scaled proportionately to maintain aspect ratio.
  83   };
  84
  85   /**
  86    * @brief Filtering options, used when resizing images on load to sample original pixels.
  87    *
  88    * A FilterMode controls how pixels in the raw image on-disk are sampled and
  89    * combined to generate each pixel of the destination loaded image.
  90    *
  91    * @note NoFilter and Box modes do not guarantee that the loaded pixel array
  92    * exactly matches the rectangle specified by the desired dimensions and
  93    * ScalingMode, but all other filter modes do if the desired dimensions are
  94    * `<=` the raw dimensions of the image file.
  95    */
  96   enum FilterMode
  97   {
  98     Box,            ///< Iteratively box filter to generate an image of 1/2, 1/4, 1/8, ... width and height and
  99                     ///  approximately the desired size, then if the ScaleToFill scaling mode is enabled, cut away the
 100                     ///  top/bottom or left/right borders of the image to match the aspect ratio of desired dimensions.
 101                     ///  This is the default.
 102     Nearest,        ///< For each output pixel, read one input pixel.
 103     Linear,         ///< For each output pixel, read a quad of four input pixels and write a weighted average of them.
 104     BoxThenNearest, ///< Iteratively box filter to generate an image of 1/2, 1/4, 1/8, ... width and height and
 105                     ///  approximately the desired size, then for each output pixel, read one pixel from the last level
 106                     ///  of box filtering.
 107     BoxThenLinear,  ///< Iteratively box filter to almost the right size, then for each output pixel, read four pixels
 108                     ///  from the last level of box filtering and write their weighted average.
 109     NoFilter,       ///< No filtering is performed. If the ScaleToFill scaling mode is enabled, the borders of the
 110                     ///  image may be trimmed to match the aspect ratio of the desired dimensions.
 111     DontCare        ///< For when the client strongly prefers a cache-hit. Defaults to Box.
 112   };
 113
 114   static const ImageAttributes DEFAULT_ATTRIBUTES; ///< Default attributes have no size
 115
 116   /**
 117    * @brief Default constructor, initializes to default values.
 118    */
 119   ImageAttributes();
 120
 121   /**
 122    * @brief This copy constructor is required for correctly copying internal implementation.
 123    *
 124    * @param [in] rhs A reference to the copied handle
 125    */
 126   ImageAttributes(const ImageAttributes& rhs);
 127
 128   /**
 129    * @brief This assignment operator is required for correctly handling the internal implementation.
 130    *
 131    * @param [in] rhs  A reference to the copied handle
 132    * @return a reference to this object
 133    */
 134   ImageAttributes& operator=(const ImageAttributes& rhs);
 135
 136   /**
 137    * @brief Default destructor.
 138    */
 139   ~ImageAttributes();
 140
 141   /**
 142    * @brief Create an initialised image attributes object.
 143    *
 144    * @return A handle to a newly allocated object
 145    */
 146   static ImageAttributes New();
 147
 148   /**
 149    * @brief Create an initialised image attributes object.
 150    *
 151    * @param [in] width         desired width.
 152    * @param [in] height        desired height
 153    * @param [in] format        desired pixelformat
 154    * @return A handle to a newly allocated object
 155    */
 156   static ImageAttributes New(unsigned int width, unsigned int height, Pixel::Format format);
 157
 158   /**
 159    * @brief Create an initialised image attributes object for distance field generation
 160    * using default parameters.
 161    *
 162    * @return A handle to a newly allocated object
 163    */
 164   static ImageAttributes NewDistanceField();
 165
 166   /**
 167    * @brief Create an initialised image attributes object for distance field generation.
 168    *
 169    * @param [in] fieldRadius The minimum search radius to check for differing pixels
 170    * @param [in] fieldBorder The amount of distancefield cells to add around the data (for glow/shadow effects)
 171    * @return A handle to a newly allocated object
 172    */
 173   static ImageAttributes NewDistanceField(float fieldRadius, int fieldBorder);
 174
 175   /**
 176    * @brief Set the size properties.
 177    *
 178    * By default width and height are set to zero which means the image loaded has the original size.
 179    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 180    * the one that is set and the aspect ratio of the image.
 181    *
 182    * @param [in] width  desired width.
 183    * @param [in] height desired height
 184    */
 185   void SetSize(unsigned int width, unsigned int height);
 186
 187   /**
 188    * @brief Set the image dimension properties.
 189    *
 190    * By default, width and height are set to zero which means the image loaded has the original size.
 191    * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
 192    * the one that is set and the aspect ratio of the image.
 193    *
 194    * @param [in] size desired size.
 195    */
 196   void SetSize( const Size& size );
 197
 198   /**
 199    * @brief Set the pixelformat field of the image attributes.
 200    *
 201    * By default is set to Pixel::RGBA8888.
 202    * @param [in] format desired pixelformat
 203    */
 204   void SetPixelFormat(Pixel::Format format);
 205
 206   /**
 207    * @brief Set the scale field of the image attributes.
 208    *
 209    * By default, ShrinkToFit is set.
 210    * @param [in] scalingMode The desired scaling mode
 211    */
 212   void SetScalingMode(ScalingMode scalingMode);
 213
 214   /**
 215    * @brief Setter for the FilterMode.
 216    * By default, Box is set.
 217    * @param [in] filterMode The desired filter mode.
 218    */
 219   void SetFilterMode( FilterMode filterMode );
 220
 221   /**
 222    * @brief Set whether the image will be rotated/flipped back into portrait orientation.
 223    *
 224    * This will only be necessary if metadata indicates that the
 225    * image has a different viewing orientation.
 226    *
 227    * This metadata, optionally present in formats that use exif for example,
 228    * can encode the physical orientation of the camera which took the picture,
 229    * establishing which directions in the image correspond to real-world "up"
 230    * and the horizon.
 231    * By default the metadata is ignored, but if this function is called with
 232    * the value "true", the pixels of an image are reordered at load time to reflect
 233    * the orientation in the metadata.
 234    *
 235    * @param [in] enabled If true, the image orientation metadata will be used to
 236    *                     transform the pixels of the image as laid-out in memory.
 237    */
 238   void SetOrientationCorrection(bool enabled);
 239
 240
 241   /**
 242    * @brief Return the width currently represented by the attribute.
 243    *
 244    * @return width
 245    */
 246   unsigned int GetWidth() const;
 247
 248   /**
 249    * @brief Return the height currently represented by the attribute.
 250    *
 251    * @return height
 252    */
 253   unsigned int GetHeight() const;
 254
 255   /**
 256    * @brief Return the size currently represented by the attribute.
 257    *
 258    * @return size
 259    */
 260   Size GetSize() const;
 261
 262   /**
 263    * @brief Return the pixel format currently represented by the attribute.
 264    *
 265    * @return pixel format
 266    */
 267   Pixel::Format GetPixelFormat() const;
 268
 269   /**
 270    * @brief Return the scale currently represented by the attribute.
 271    *
 272    * @return scale
 273    */
 274   ScalingMode GetScalingMode() const;
 275
 276   /**
 277    * @brief Getter for the FilterMode
 278    *
 279    * @return The FilterMode previously set, or the default value if none has
 280    *         been.
 281    */
 282   FilterMode GetFilterMode() const;
 283
 284   /**
 285    * @brief Return if the attribute set up as a distance field.
 286    *
 287    * @return true, if the attribute is a distance field.
 288    */
 289   bool IsDistanceField() const;
 290
 291   /**
 292    * @brief Return the field border currently represented by the attribute.
 293    *
 294    * @return field border
 295    */
 296   int GetFieldBorder() const;
 297
 298   /**
 299    * @brief Return the field search radius currently represented by the attribute.
 300    *
 301    * @return field radius
 302    */
 303   float GetFieldRadius() const;
 304
 305   /**
 306    * @brief Whether to correct for physical orientation of an image.
 307    *
 308    * @return Whether image pixels should be transformed according to the
 309    *         orientation metadata, if any.
 310    */
 311   bool GetOrientationCorrection() const;
 312
 313   /**
 314    * @brief Less then comparison operator.
 315    *
 316    * @param [in] a parameter tested
 317    * @param [in] b parameter tested
 318    * @return true if a is less than b
 319    */
 320   friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 321
 322   /**
 323    * @brief Equal to comparison operator.
 324    *
 325    * @param [in] a parameter tested for equality
 326    * @param [in] b parameter tested for equality
 327    * @return true if a is equal to b
 328    */
 329   friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 330
 331   /**
 332    * @brief Not equal to comparison operator.
 333    *
 334    * @param [in] a parameter tested for equality
 335    * @param [in] b parameter tested for equality
 336    * @return true if a is not equal to b
 337    */
 338   friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 339
 340 private:
 341   struct ImageAttributesImpl;
 342   ImageAttributesImpl* impl; ///< Implementation pointer
 343 };
 344
 345 /**
 346  * @brief Less then comparison operator.
 347  *
 348  * @param [in] a parameter tested
 349  * @param [in] b parameter tested
 350  * @return true if a is less than b
 351  */
 352 DALI_IMPORT_API bool operator<(const ImageAttributes& a, const ImageAttributes& b);
 353
 354 /**
 355  * @brief Equal to comparison operator.
 356  *
 357  * @param [in] a parameter tested for equality
 358  * @param [in] b parameter tested for equality
 359  * @return true if a is equal to b
 360  */
 361 DALI_IMPORT_API bool operator==(const ImageAttributes& a, const ImageAttributes& b);
 362
 363 /**
 364  * @brief Not equal to comparison operator.
 365  *
 366  * @param [in] a parameter tested for equality
 367  * @param [in] b parameter tested for equality
 368  * @return true if a is not equal to b
 369  */
 370 DALI_IMPORT_API bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
 371
 372 } // namespace Dali
 373
 374 #endif // __DALI_IMAGE_ATTRIBUTES_H__