dali-toolkit/internal/visuals/image/image-visual.h

   1 #ifndef DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
   2 #define DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
   3
   4 /*
   5  * Copyright (c) 2022 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 <memory>
  23
  24 #include <dali/public-api/common/intrusive-ptr.h>
  25 #include <dali/public-api/images/image-operations.h>
  26 #include <dali/public-api/object/weak-handle.h>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali-toolkit/devel-api/image-loader/atlas-upload-observer.h>
  30 #include <dali-toolkit/devel-api/visuals/image-visual-properties-devel.h>
  31 #include <dali-toolkit/internal/texture-manager/texture-upload-observer.h>
  32 #include <dali-toolkit/internal/visuals/visual-base-impl.h>
  33 #include <dali-toolkit/internal/visuals/visual-url.h>
  34 #include <dali-toolkit/public-api/visuals/image-visual-properties.h>
  35
  36 namespace Dali
  37 {
  38 class NativeImage;
  39
  40 namespace Toolkit
  41 {
  42 namespace Internal
  43 {
  44 class ImageVisualShaderFactory;
  45 class ImageVisual;
  46 typedef IntrusivePtr<ImageVisual> ImageVisualPtr;
  47
  48 /**
  49  * The visual which renders an image to a quad geometry
  50  *
  51  * The following properties are optional
  52  *
  53  * | %Property Name        | Type              |
  54  * |-----------------------|-------------------|
  55  * | url                   | STRING            |
  56  * | alphaMaskUrl          | STRING            |
  57  * | fittingMode           | INTEGER OR STRING |
  58  * | samplingMode          | INTEGER OR STRING |
  59  * | desiredWidth          | INTEGER           |
  60  * | desiredHeight         | INTEGER           |
  61  * | synchronousLoading    | BOOLEAN           |
  62  * | pixelArea             | VECTOR4           |
  63  * | wrapModeU             | INTEGER OR STRING |
  64  * | wrapModeV             | INTEGER OR STRING |
  65  * | loadPolicy            | INTEGER OR STRING |
  66  * | releasePolicy         | INTEGER OR STRING |
  67  * | orientationCorrection | BOOLEAN           |
  68  *
  69  * where pixelArea is a rectangular area.
  70  * In its Vector4 value, the first two elements indicate the top-left position of the area,
  71  * and the last two elements are the area width and height respectively.
  72  * If not specified, the default value is [0.0, 0.0, 1.0, 1.0], i.e. the entire area of the image.
  73  *
  74  * where wrapModeU and wrapModeV separately decide how the texture should be sampled when the u and v coordinate exceeds the range of 0.0 to 1.0.
  75  * Its value should be one of the following wrap mode:
  76  *   "DEFAULT"
  77  *   "CLAMP_TO_EDGE"
  78  *   "REPEAT"
  79  *   "MIRRORED_REPEAT"
  80  *
  81  * where imageFittingMode should be one of the following fitting modes:
  82  *   "SHRINK_TO_FIT"
  83  *   "SCALE_TO_FILL"
  84  *   "FIT_WIDTH"
  85  *   "FIT_HEIGHT"
  86  *   "DEFAULT"
  87  *
  88  * where imageSamplingMode should be one of the following sampling modes:
  89  *   "BOX"
  90  *   "NEAREST"
  91  *   "LINEAR"
  92  *   "BOX_THEN_NEAREST"
  93  *   "BOX_THEN_LINEAR"
  94  *   "NO_FILTER"
  95  *   "DONT_CARE"
  96  *   "DEFAULT"
  97  *
  98  * where loadPolicy should be one of the following image loading modes
  99  *   "IMMEDIATE"   // Loads image even if visual not attached to stage yet
 100  *   "ATTACHED"    // Only loads image once visual is attached to stage
 101  *
 102  * where releasePolicy should be one of the following policies for when to cache the image
 103  *   "DETACHED"    //  Release image from cache when visual detached from stage
 104  *   "DESTROYED"   //  Keep image in cache until the visual is destroyed
 105  *   "NEVER"       //  Keep image in cache until application ends.
 106  *
 107  * If the Visual is in a LayerUI it will pixel align the image, using a Layer3D will disable pixel alignment.
 108  * Changing layer behaviour between LayerUI to Layer3D whilst the visual is already staged will not have an effect.
 109  */
 110 class ImageVisual : public Visual::Base, public ConnectionTracker, public AtlasUploadObserver, public TextureUploadObserver
 111 {
 112 public:
 113   /**
 114    * @brief Create a new image visual with a URL.
 115    *
 116    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
 117    *
 118    * @param[in] factoryCache The VisualFactoryCache object
 119    * @param[in] shaderFactory The ImageVisualShaderFactory object
 120    * @param[in] imageUrl The URL of the image resource to use
 121    * @param[in] properties A Property::Map containing settings for this visual
 122    * @param[in] size The width and height to fit the loaded image to.
 123    * @param[in] fittingMode The FittingMode of the resource to load
 124    * @param[in] samplingMode The SamplingMode of the resource to load
 125    * @return A smart-pointer to the newly allocated visual.
 126    */
 127   static ImageVisualPtr New(VisualFactoryCache&       factoryCache,
 128                             ImageVisualShaderFactory& shaderFactory,
 129                             const VisualUrl&          imageUrl,
 130                             const Property::Map&      properties,
 131                             ImageDimensions           size         = ImageDimensions(),
 132                             FittingMode::Type         fittingMode  = FittingMode::DEFAULT,
 133                             Dali::SamplingMode::Type  samplingMode = SamplingMode::BOX_THEN_LINEAR);
 134
 135   /**
 136    * @brief Create a new image visual with a URL.
 137    *
 138    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
 139    *
 140    * @param[in] factoryCache The VisualFactoryCache object
 141    * @param[in] shaderFactory The ImageVisualShaderFactory object
 142    * @param[in] imageUrl The URL of the image resource to use
 143    * @param[in] size The width and height to fit the loaded image to.
 144    * @param[in] fittingMode The FittingMode of the resource to load
 145    * @param[in] samplingMode The SamplingMode of the resource to load
 146    * @return A smart-pointer to the newly allocated visual.
 147    */
 148   static ImageVisualPtr New(VisualFactoryCache&       factoryCache,
 149                             ImageVisualShaderFactory& shaderFactory,
 150                             const VisualUrl&          imageUrl,
 151                             ImageDimensions           size         = ImageDimensions(),
 152                             FittingMode::Type         fittingMode  = FittingMode::DEFAULT,
 153                             Dali::SamplingMode::Type  samplingMode = SamplingMode::BOX_THEN_LINEAR);
 154
 155 public: // from Visual
 156   /**
 157    * @copydoc Visual::Base::GetNaturalSize
 158    */
 159   void GetNaturalSize(Vector2& naturalSize) override;
 160
 161   /**
 162    * @copydoc Visual::Base::CreatePropertyMap
 163    */
 164   void DoCreatePropertyMap(Property::Map& map) const override;
 165
 166   /**
 167    * @copydoc Visual::Base::CreateInstancePropertyMap
 168    */
 169   void DoCreateInstancePropertyMap(Property::Map& map) const override;
 170
 171   /**
 172    * @copydoc Visual::Base::OnDoAction
 173    */
 174   void OnDoAction(const Dali::Property::Index actionId, const Dali::Property::Value& attributes) override;
 175
 176 protected:
 177   /**
 178    * @brief Constructor with a URL.
 179    *
 180    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
 181    *
 182    * @param[in] factoryCache The VisualFactoryCache object
 183    * @param[in] shaderFactory The ImageVisualShaderFactory object
 184    * @param[in] imageUrl The URL of the image resource to use
 185    * @param[in] size The width and height to fit the loaded image to.
 186    * @param[in] fittingMode The FittingMode of the resource to load
 187    * @param[in] samplingMode The SamplingMode of the resource to load
 188    */
 189   ImageVisual(VisualFactoryCache&       factoryCache,
 190               ImageVisualShaderFactory& shaderFactory,
 191               const VisualUrl&          imageUrl,
 192               ImageDimensions           size,
 193               FittingMode::Type         fittingMode,
 194               Dali::SamplingMode::Type  samplingMode);
 195
 196   /**
 197    * @brief A reference counted object may only be deleted by calling Unreference().
 198    */
 199   virtual ~ImageVisual();
 200
 201   /**
 202    * @copydoc Visual::Base::OnInitialize
 203    */
 204   void OnInitialize() override;
 205
 206   /**
 207    * @copydoc Visual::Base::DoSetProperties
 208    */
 209   void DoSetProperties(const Property::Map& propertyMap) override;
 210
 211   /**
 212    * @copydoc Visual::Base::DoSetOnScene
 213    */
 214   void DoSetOnScene(Actor& actor) override;
 215
 216   /**
 217    * @copydoc Visual::Base::DoSetOffScene
 218    */
 219   void DoSetOffScene(Actor& actor) override;
 220
 221   /**
 222    * @copydoc Visual::Base::OnSetTransform
 223    */
 224   void OnSetTransform() override;
 225
 226   /**
 227    * @copydoc Visual::Base::UpdateShader
 228    */
 229   void UpdateShader() override;
 230
 231   /**
 232    * @copydoc Visual::Base::GenerateShader
 233    */
 234   Shader GenerateShader() const override;
 235
 236 public:
 237   /**
 238    * @copydoc AtlasUploadObserver::UploadCompleted
 239    *
 240    * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
 241    * This callback is the place to add the renderer as it would be called once the loading is finished.
 242    */
 243   void UploadCompleted() override;
 244
 245   /**
 246    * @copydoc TextureUploadObserver::LoadCompleted
 247    *
 248    * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
 249    * This callback is the place to add the renderer as it would be called once the loading is finished.
 250    */
 251   void LoadComplete(bool success, TextureInformation textureInformation) override;
 252
 253 private:
 254   /**
 255    * Allocate the mask data when a masking property is defined in the property map
 256    */
 257   void AllocateMaskData();
 258
 259   /**
 260    * @brief Load the texture, will try to atlas unless unable or param set to false.
 261    * @param[in, out] atlasing flag if the image has been put in a atlas (true), passing false will not atlas even if possible.
 262    * @param[out] atlasRect if atlasing is used this the texture area of the image in the atlas.
 263    * @param[out] textures resulting texture set from the image loading.
 264    * @param[in] orientationCorrection flag determines if orientation correction should be performed
 265    * @param[in] forceReload flag determines if the texture should be reloaded from its source or use the cached texture.
 266    */
 267   void LoadTexture(bool& atlasing, Vector4& atlasRect, TextureSet& textures, bool orientationCorrection, TextureManager::ReloadPolicy forceReload);
 268
 269   /**
 270    * @brief Checks if atlasing should be attempted
 271    * @return bool returns true if atlasing can be attempted.
 272    */
 273   bool AttemptAtlasing();
 274
 275   /**
 276    * @brief Initializes the Dali::Renderer from the image url
 277    */
 278   void InitializeRenderer();
 279
 280   /**
 281    * Creates the texture set and adds the texture to it
 282    * @param[out] textureRect The texture area of the texture in the atlas.
 283    * @param[in] url The URL of the image resource to use.
 284    * @param[in] synchronousLoading If true, the resource is loaded synchronously, otherwise asynchronously.
 285    * @param[in] attemptAtlasing If true will attempt atlasing, otherwise create unique texture
 286    * @return the texture set to use
 287    */
 288   TextureSet CreateTextureSet(Vector4& textureRect, bool synchronousLoading, bool attemptAtlasing);
 289
 290   /**
 291    * Set the value to the uTextureRect uniform
 292    * @param[in] textureRect The texture rectangular area.
 293    */
 294   void SetTextureRectUniform(const Vector4& textureRect);
 295
 296   /**
 297    * Remove texture with valid TextureId
 298    */
 299   void RemoveTexture();
 300
 301   /**
 302    * @brief Compute texture size
 303    */
 304   void ComputeTextureSize();
 305
 306   /**
 307    * @brief Compute mask texture ratio
 308    * @return The Mask Texture Ratio
 309    */
 310   Vector2 ComputeMaskTextureRatio();
 311
 312   /**
 313    * Helper method to set individual values by index key.
 314    * @param[in] index The index key of the value
 315    * @param[in] value The value
 316    */
 317   void DoSetProperty(Property::Index index, const Property::Value& value);
 318
 319   /**
 320    * @brief Check whether the mask texture is loaded or not.
 321    * If MaskingType is MASKING_ON_LOADING and mask texture is failed to load, update shader.
 322    */
 323   void CheckMaskTexture();
 324
 325 private:
 326   Vector4                            mPixelArea;
 327   WeakHandle<Actor>                  mPlacementActor;
 328   VisualUrl                          mImageUrl;
 329   TextureManager::MaskingDataPointer mMaskingData;
 330
 331   Dali::ImageDimensions     mDesiredSize;
 332   TextureManager::TextureId mTextureId;
 333   TextureSet                mTextures;
 334   Vector2                   mTextureSize;
 335
 336   ImageVisualShaderFactory& mImageVisualShaderFactory;
 337
 338   Dali::FittingMode::Type                         mFittingMode : 3;
 339   Dali::SamplingMode::Type                        mSamplingMode : 4;
 340   Dali::WrapMode::Type                            mWrapModeU : 3;
 341   Dali::WrapMode::Type                            mWrapModeV : 3;
 342   Dali::Toolkit::ImageVisual::LoadPolicy::Type    mLoadPolicy;
 343   Dali::Toolkit::ImageVisual::ReleasePolicy::Type mReleasePolicy;
 344   Vector4                                         mAtlasRect;
 345   Dali::ImageDimensions                           mAtlasRectSize;
 346   TextureManager::LoadState                       mLoadState;             ///< The texture loading state
 347   bool                                            mAttemptAtlasing;       ///< If true will attempt atlasing, otherwise create unique texture
 348   bool                                            mOrientationCorrection; ///< true if the image will have it's orientation corrected.
 349   bool                                            mNeedYuvToRgb{false};   ///< true if we need to convert yuv to rgb.
 350 };
 351
 352 } // namespace Internal
 353
 354 } // namespace Toolkit
 355
 356 } // namespace Dali
 357
 358 #endif /* DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H */