dali/public-api/images/native-image-interface.h

   1 #ifndef DALI_NATIVE_IMAGE_INTERFACE_H
   2 #define DALI_NATIVE_IMAGE_INTERFACE_H
   3
   4 /*
   5  * Copyright (c) 2020 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 <cstddef>
  23 #include <cstdint> // uint32_t
  24 #include <string>
  25
  26 // INTERNAL INCLUDES
  27 #include <dali/public-api/object/any.h>
  28 #include <dali/public-api/object/ref-object.h>
  29
  30 namespace Dali
  31 {
  32 /**
  33  * @addtogroup dali_core_images
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Abstract interface to provide platform-specific support for handling image data.
  39  *
  40  * For example, an implementation could use EGL extensions, etc.
  41  * @SINCE_1_0.0
  42  */
  43 class NativeImageInterface : public Dali::RefObject
  44 {
  45 public:
  46   class Extension; ///< Forward declare future extension interface
  47
  48   /**
  49    * @brief Creates the resource for the NativeImage.
  50    *
  51    * e.g. For the EglImageKHR extension, this corresponds to calling eglCreateImageKHR().
  52    * @SINCE_1_9.23
  53    * @return false If the initialization fails
  54    * @pre The graphics subsystem has been initialized
  55    */
  56   virtual bool CreateResource() = 0;
  57
  58   /**
  59    * @brief Destroys the resource for the NativeImage.
  60    *
  61    * e.g. For the EglImageKHR extension, this corresponds to calling eglDestroyImageKHR().
  62    * @SINCE_1_9.23
  63    * @pre The graphics subsystem has been initialized
  64    */
  65   virtual void DestroyResource() = 0;
  66
  67   /**
  68    * @brief Uses the NativeImage as a texture for rendering.
  69    *
  70    * @SINCE_1_0.0
  71    * @return An error code from the graphics subsystem.
  72    * @pre The graphics subsystem has been initialized
  73    */
  74   virtual uint32_t TargetTexture() = 0;
  75
  76   /**
  77    * @brief Called internally when the texture is bound in the GPU
  78    *
  79    * The correct texture sampler has already been bound before the function gets called.
  80    * @SINCE_1_0.0
  81    * @pre The graphics subsystem has been initialized
  82    */
  83   virtual void PrepareTexture() = 0;
  84
  85   /**
  86    * @brief Returns the width of the NativeImage.
  87    *
  88    * @SINCE_1_0.0
  89    * @return Width
  90    */
  91   virtual uint32_t GetWidth() const = 0;
  92
  93   /**
  94    * @brief Returns the height of the NativeImage.
  95    *
  96    * @SINCE_1_0.0
  97    * @return Height
  98    */
  99   virtual uint32_t GetHeight() const = 0;
 100
 101   /**
 102   * @brief Queries whether blending is required.
 103   * @SINCE_1_0.0
 104   * @return True if blending is required
 105   */
 106   virtual bool RequiresBlending() const = 0;
 107
 108   /**
 109    * @brief Get the texture target for binding native image as texture.
 110    *
 111    * @SINCE_1_9.23
 112    * @return Texture target.
 113    */
 114   virtual int GetTextureTarget() const = 0;
 115
 116   /**
 117    * @brief Apply custom fragment prefix for rendering native image.
 118    *
 119    * @param[in,out] shader shader code that will be applied fragment prefix.
 120    * @return True if the shader is changed.
 121    */
 122   virtual bool ApplyNativeFragmentShader(std::string& shader) = 0;
 123
 124   /**
 125    * @brief Get custom sampler type name for rendering native image.
 126    *
 127    * @SINCE_1_9.23
 128    * @return Custom sampler type name.
 129    */
 130   virtual const char* GetCustomSamplerTypename() const = 0;
 131
 132   /**
 133    * @brief Retrieves the internal native image.
 134    *
 135    * @SINCE_1_9.23
 136    * @return Any object containing the internal native image source
 137    */
 138   virtual Any GetNativeImageHandle() const = 0;
 139
 140   /**
 141    * @brief Determine if the source for the native image has changed characteristics.
 142    *
 143    * @SINCE_1_9.23
 144    * @return true if the source data has modified any characteristics of the
 145    * native image, for example if the size of the buffer has changed.
 146    */
 147   virtual bool SourceChanged() const = 0;
 148
 149   /**
 150    * @brief Retrieves the extension for the interface.
 151    *
 152    * @SINCE_1_0.0
 153    * @return The extension if available, NULL otherwise
 154    */
 155   virtual Extension* GetExtension()
 156   {
 157     return nullptr;
 158   }
 159
 160 protected:
 161   /**
 162    * @brief A reference counted object may only be deleted by calling Unreference().
 163    *
 164    * The implementation should destroy the NativeImage resources.
 165    * @SINCE_1_0.0
 166    */
 167   ~NativeImageInterface() override = default;
 168 };
 169
 170 /**
 171  * @brief Pointer to Dali::NativeImageInterface.
 172  * @SINCE_1_0.0
 173  */
 174 using NativeImageInterfacePtr = Dali::IntrusivePtr<NativeImageInterface>;
 175
 176 /**
 177  * @}
 178  */
 179 } // namespace Dali
 180
 181 #endif // DALI_NATIVE_IMAGE_INTERFACE_H