dali/devel-api/images/atlas.h

   1 #ifndef __DALI_ATLAS_H__
   2 #define __DALI_ATLAS_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // EXTERNAL INCLUDES
  22 #include <stdint.h>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/common/dali-common.h>
  26 #include <dali/public-api/images/image.h>
  27 #include <dali/public-api/images/buffer-image.h>
  28 #include <dali/devel-api/images/pixel-data.h>
  29
  30 namespace Dali
  31 {
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class Atlas;
  36 }
  37
  38 /**
  39  * @brief An Atlas is a large image containing multiple smaller images.
  40  *
  41  * Buffer image and resource image( by providing the url ) are supported for uploading.
  42  * Images must be uploaded at a specified position, to populate the Atlas.
  43  * The client is responsible for generating the appropriate geometry (UV coordinates) needed to draw images within the Atlas.
  44  *
  45  * @note For gles 2.0, matched pixel format is demanded to ensure the correct atlasing.
  46  *       The only exception supported is uploading image of RGB888 to atlas of RGBA8888 format which is converted manually before pushing to GPU.
  47  *
  48  * For context recovery after loss:
  49  * By default, the atlas will re-upload the resource images automatically,
  50  * while the buffer images are left to the client to upload again by connecting to the Stage::ContextRegainedSignal().
  51  * If resource and buffer images are mixed and they overlap inside the atlas, the recovered contents may be incorrect.
  52  * In these case, switch off the context recovery by calling SetContextRecovery( false ),
  53  * and upload both buffer images and resource image to the atlas in order to restore the atlas.
  54  */
  55 class DALI_IMPORT_API Atlas : public Image
  56 {
  57 public:
  58
  59   typedef uint32_t SizeType;
  60
  61 public:
  62
  63   /**
  64    * @brief Create a new Atlas.
  65    *
  66    * @pre width & height are greater than zero.
  67    * The maximum size of the atlas is limited by GL_MAX_TEXTURE_SIZE.
  68    * @param [in] width          The atlas width in pixels.
  69    * @param [in] height         The atlas height in pixels.
  70    * @param [in] pixelFormat    The pixel format (rgba 32 bit by default).
  71    * @param [in] recoverContext Whether re-uploading the resource images automatically when regaining the context( true by default )
  72    * @return A handle to a new Atlas.
  73    */
  74   static Atlas New( SizeType width,
  75                     SizeType height,
  76                     Pixel::Format pixelFormat = Pixel::RGBA8888,
  77                     bool recoverContext = true );
  78
  79   /**
  80    * @brief Create an empty handle.
  81    *
  82    * Calling member functions of an empty handle is not allowed.
  83    */
  84   Atlas();
  85
  86   /**
  87    * @brief Clear the Atlas with the given color
  88    *
  89    * @note The Atlas does not clear itself automatically during construction.
  90    * Application should call this clear function to avoid getting garbage pixels in the atlas.
  91    * By calling Clear, all the current uploaded image information will be lost.
  92    * @param [in] color The color used to clear the Atlas.
  93    */
  94   void Clear( const Vector4& color  );
  95
  96   /**
  97    * @brief Upload a buffer image to the atlas.
  98    *
  99    * @pre The pixel format of this buffer image must match the Atlas format.
 100    * @param [in] bufferImage The buffer image to upload.
 101    * @param [in] xOffset Specifies an offset in the x direction within the atlas.
 102    * @param [in] yOffset Specifies an offset in the y direction within the atlas.
 103    * @return True if the image has compatible pixel format and fits within the atlas at the specified offset.
 104    */
 105   bool Upload( BufferImage bufferImage,
 106                SizeType xOffset,
 107                SizeType yOffset );
 108
 109   /**
 110    * @brief Upload a resource image to atlas
 111    *
 112    * @param [in] url The URL of the resource image file to use
 113    * @param [in] xOffset Specifies an offset in the x direction within the atlas.
 114    * @param [in] yOffset Specifies an offset in the y direction within the atlas.
 115    * @return True if the image has compatible pixel format and fits within the atlas at the specified offset.
 116    */
 117   bool Upload( const std::string& url,
 118                SizeType xOffset,
 119                SizeType yOffset );
 120
 121   /**
 122    * @brief Upload a pixel buffer to atlas
 123    *
 124    * @param [in] pixelData      The pixel data.
 125    * @param [in] xOffset        Specifies an offset in the x direction within the atlas.
 126    * @param [in] yOffset        Specifies an offset in the y direction within the atlas.
 127    */
 128   bool Upload( PixelData pixelData,
 129                SizeType xOffset,
 130                SizeType yOffset );
 131   /**
 132    * @brief Downcast an Object handle to Atlas.
 133    *
 134    * If handle points to a Atlas the downcast produces valid
 135    * handle. If not the returned handle is left uninitialized.
 136    *
 137    * @param[in] handle to An object
 138    * @return handle to a Atlas or an empty handle
 139    */
 140   static Atlas DownCast( BaseHandle handle );
 141
 142   /**
 143    * @brief Destructor
 144    *
 145    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 146    */
 147   ~Atlas();
 148
 149   /**
 150    * @brief This copy constructor is required for (smart) pointer semantics.
 151    *
 152    * @param [in] handle A reference to the copied handle
 153    */
 154   Atlas( const Atlas& handle );
 155
 156   /**
 157    * @brief This assignment operator is required for (smart) pointer semantics.
 158    *
 159    * @param [in] rhs  A reference to the copied handle
 160    * @return A reference to this
 161    */
 162   Atlas& operator=( const Atlas& rhs);
 163
 164 public: // Not intended for application developers
 165
 166   explicit DALI_INTERNAL Atlas( Internal::Atlas* );
 167 };
 168
 169 } // namespace Dali
 170
 171 #endif // __DALI_ATLAS_H__