dali-toolkit/devel-api/image-loader/image-atlas.h

   1 #ifndef DALI_TOOLKIT_IMAGE_ATLAS_H
   2 #define DALI_TOOLKIT_IMAGE_ATLAS_H
   3 /*
   4  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 // EXTERNAL INCLUDES
  21 #include <dali/public-api/common/vector-wrapper.h>
  22 #include <dali/public-api/images/image-operations.h>
  23 #include <dali/public-api/images/pixel-data.h>
  24 #include <dali/public-api/images/pixel.h>
  25 #include <dali/public-api/object/base-handle.h>
  26 #include <dali/public-api/rendering/texture.h>
  27 #include <stdint.h>
  28 #include <string>
  29
  30 // INTERNAL INCLUDES
  31 #include <dali-toolkit/devel-api/image-loader/atlas-upload-observer.h>
  32
  33 namespace Dali
  34 {
  35 namespace Toolkit
  36 {
  37 namespace Internal DALI_INTERNAL
  38 {
  39 class ImageAtlas;
  40 }
  41
  42 /**
  43  * @brief An ImageAtlas is a large texture containing multiple smaller images.
  44  *
  45  * Only images with url provided or pixel data are supported for uploading.
  46  * The images are loaded by a worker thread to avoid blocking the main event thread.
  47  */
  48 class DALI_TOOLKIT_API ImageAtlas : public BaseHandle
  49 {
  50 public:
  51   typedef uint32_t SizeType;
  52
  53 public:
  54   /**
  55    * @brief Pack a group of  pixel data into atlas.
  56    * @param[in] pixelData The group of the pixel data to be packed into the atlas.
  57    * @param[out] textureRects The list of texture areas where each frame is located inside the atlas.
  58    * @return The atlas texture.
  59    */
  60   static Texture PackToAtlas(const std::vector<PixelData>& pixelData, Dali::Vector<Vector4>& textureRects);
  61
  62   /**
  63    * @brief Create a new ImageAtlas.
  64    *
  65    * @param [in] width          The atlas width in pixels.
  66    * @param [in] height         The atlas height in pixels.
  67    * @param [in] pixelFormat    The pixel format (rgba 32 bit by default).
  68    * @return A handle to a new ImageAtlas.
  69    */
  70   static ImageAtlas New(SizeType width, SizeType height, Pixel::Format pixelFormat = Pixel::RGBA8888);
  71
  72   /**
  73    * @brief Create an empty handle.
  74    *
  75    * Calling member functions of an empty handle is not allowed.
  76    */
  77   ImageAtlas();
  78
  79   /**
  80    * @brief Destructor.
  81    */
  82   ~ImageAtlas();
  83
  84   /**
  85    * @brief This copy constructor is required for (smart) pointer semantics.
  86    *
  87    * @param [in] handle A reference to the copied handle
  88    */
  89   ImageAtlas(const ImageAtlas& handle);
  90
  91   /**
  92    * @brief This assignment operator is required for (smart) pointer semantics.
  93    *
  94    * @param [in] handle  A reference to the copied handle
  95    * @return A reference to this
  96    */
  97   ImageAtlas& operator=(const ImageAtlas& handle);
  98
  99   /**
 100    * @brief Get the atlas image.
 101    *
 102    * This atlas texture is still valid after destroying the ImageAtlas object.
 103    *
 104    * @return The atlas texture
 105    */
 106   Texture GetAtlas();
 107
 108   /*
 109    * @brief Query what percentage of space is been occupied in the atlas.
 110    *
 111    * @return The occupancy rate of the atlas.
 112    */
 113   float GetOccupancyRate() const;
 114
 115   /**
 116    * @brief Set the broken image which is used to replace the image if loading fails.
 117    *
 118    * @param[in] brokenImageUrl The url of the broken image.
 119    */
 120   void SetBrokenImage(const std::string& brokenImageUrl);
 121
 122   /**
 123    * @brief Upload a resource image to the atlas.
 124    *
 125    * @note To make the atlasing efficient, a valid size should be provided.
 126    *       If size is not provided, then the image file will be opened to read the actual size for loading.
 127    *       Do not set a size that is bigger than the actual image size, as the up-scaling is not available,
 128    *       the content of the area not covered by actual image is undefined, it will not be cleared.
 129    *
 130    * SamplingMode::BOX_THEN_LINEAR is used to sampling pixels from the input image while fitting it to desired size.
 131    *
 132    * @param [out] textureRect The texture area of the resource image in the atlas.
 133    * @param [in] url The URL of the resource image file to use.
 134    * @param [in] size The width and height to fit the loaded image to.
 135    * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
 136    * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
 137    * @return True if there is enough space to fit this image in,false otherwise.
 138    */
 139   bool Upload(Vector4&           textureRect,
 140               const std::string& url,
 141               ImageDimensions    size                  = ImageDimensions(),
 142               FittingMode::Type  fittingMode           = FittingMode::DEFAULT,
 143               bool               orientationCorrection = true);
 144
 145   /**
 146    * @brief Upload a resource image to the atlas.
 147    *
 148    * @note To make the atlasing efficient, a valid size should be provided.
 149    *       If size is not provided, then the image file will be opened to read the actual size for loading.
 150    *       Do not set a size that is bigger than the actual image size, as the up-scaling is not available,
 151    *       the content of the area not covered by actual image is undefined, it will not be cleared.
 152    *
 153    * SamplingMode::BOX_THEN_LINEAR is used to sampling pixels from the input image while fitting it to desired size.
 154    *
 155    * @param [out] textureRect The texture area of the resource image in the atlas.
 156    * @param [in] url The URL of the resource image file to use.
 157    * @param [in] size The width and height to fit the loaded image to.
 158    * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
 159    * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
 160    * @param[in] atlasUploadObserver The observer to observe the upload state inside the ImageAtlas.
 161    * @return True if there is enough space to fit this image in,false otherwise.
 162    * @note The valid callback function here is required to have the signature of void( void ).
 163    */
 164   bool Upload(Vector4&             textureRect,
 165               const std::string&   url,
 166               ImageDimensions      size,
 167               FittingMode::Type    fittingMode,
 168               bool                 orientationCorrection,
 169               AtlasUploadObserver* atlasUploadObserver);
 170
 171   /**
 172    * @brief Upload a pixel buffer to atlas
 173    *
 174    * @param [out] textureRect The texture area of the resource image in the atlas.
 175    * @param [in] pixelData The pixel data.
 176    */
 177   bool Upload(Vector4& textureRect, PixelData pixelData);
 178
 179   /**
 180    * @brief Remove the image at the given rectangle.
 181    *
 182    * The rectangular area is marked unoccupied, so new image can be added to this area.
 183    *
 184    * @param [in] textureRect The texture area to be removed.
 185    */
 186   void Remove(const Vector4& textureRect);
 187
 188 public: // Not intended for developer use
 189   explicit DALI_INTERNAL ImageAtlas(Internal::ImageAtlas* impl);
 190 };
 191
 192 } // namespace Toolkit
 193
 194 } // namespace Dali
 195
 196 #endif // DALI_TOOLKIT_IMAGE_ATLAS_H