dali-toolkit/devel-api/image-atlas/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.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
  29 namespace Dali
  30 {
  31
  32 namespace Toolkit
  33 {
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class ImageAtlas;
  37 }
  38
  39 /**
  40  * @brief An ImageAtlas is a large image containing multiple smaller images.
  41  *
  42  * Only images with url provided are supported for uploading.
  43  * The image are loaded by a worker thread to avoid blocking the main event thread.
  44  */
  45 class DALI_IMPORT_API ImageAtlas : public BaseHandle
  46 {
  47 public:
  48
  49   typedef uint32_t SizeType;
  50
  51 public:
  52
  53   /**
  54    * @brief Create a new ImageAtlas.
  55    *
  56    * @param [in] width          The atlas width in pixels.
  57    * @param [in] height         The atlas height in pixels.
  58    * @param [in] pixelFormat    The pixel format (rgba 32 bit by default).
  59    * @return A handle to a new ImageAtlas.
  60    */
  61   static ImageAtlas New( SizeType width, SizeType height,
  62                          Pixel::Format pixelFormat = Pixel::RGBA8888 );
  63
  64   /**
  65    * @brief Create an empty handle.
  66    *
  67    * Calling member functions of an empty handle is not allowed.
  68    */
  69   ImageAtlas();
  70
  71   /**
  72    * @brief Destructor.
  73    */
  74   ~ImageAtlas();
  75
  76   /**
  77    * @brief This copy constructor is required for (smart) pointer semantics.
  78    *
  79    * @param [in] handle A reference to the copied handle
  80    */
  81   ImageAtlas( const ImageAtlas& handle );
  82
  83   /**
  84    * @brief This assignment operator is required for (smart) pointer semantics.
  85    *
  86    * @param [in] handle  A reference to the copied handle
  87    * @return A reference to this
  88    */
  89   ImageAtlas& operator=( const ImageAtlas& handle );
  90
  91   /**
  92    * @brief Get the atlas image.
  93    *
  94    * This atlas image is still valid after destroying the ImageAtlas object.
  95    *
  96    * @return the atlas image with type of Dali::Atlas
  97    */
  98   Image GetAtlas();
  99
 100   /**
 101    * @brief Set the broken image which is used to replace the image if loading fails.
 102    *
 103    * @param[in] brokenImageUrl The url of the broken image.
 104    */
 105   void SetBrokenImage( const std::string& brokenImageUrl );
 106
 107   /**
 108    * @brief Upload a resource image to the atlas.
 109    *
 110    * @note To make the atlasing efficient, an valid size should be provided.
 111    *       If size is not provided, then the image file will be opened to read the actual size for loading.
 112    *       Do not set a size that is bigger than the actual image size, as the up-scaling is not available,
 113    *       the content of the area not covered by actual image is undefined, it will not be cleared.
 114    *
 115    * SamplingMode::BOX_THEN_LINEAR is used to sampling pixels from the input image while fitting it to desired size.
 116    *
 117    * @param [out] textureRect The texture area of the resource image in the atlas.
 118    * @param [in] url The URL of the resource image file to use.
 119    * @param [in] size The width and height to fit the loaded image to.
 120    * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
 121    * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
 122    * @return True if there is enough space to fit this image in,false otherwise.
 123    */
 124   bool Upload( Vector4& textureRect,
 125                const std::string& url,
 126                ImageDimensions size = ImageDimensions(),
 127                FittingMode::Type fittingMode = FittingMode::DEFAULT,
 128                bool orientationCorrection = true );
 129
 130   /**
 131    * @brief Upload a pixel buffer to atlas
 132    *
 133    * @param [out] textureRect The texture area of the resource image in the atlas.
 134    * @param [in] pixelData The pixel data.
 135    */
 136   bool Upload( Vector4& textureRect, PixelData pixelData );
 137
 138   /**
 139    * @brief Remove the image at the given rectangle.
 140    *
 141    * The rectangular area is marked unoccupied, so new image can be added to this area.
 142    *
 143    * @param [in] textureRect The texture area to be removed.
 144    */
 145   void Remove( const Vector4& textureRect );
 146
 147 public: // Not intended for developer use
 148
 149   explicit DALI_INTERNAL ImageAtlas( Internal::ImageAtlas* impl );
 150 };
 151
 152 } // namespace Toolkit
 153
 154 } // namespace Dali
 155
 156 #endif // DALI_TOOLKIT_IMAGE_ATLAS_H