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