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