dali/public-api/rendering/texture.h

   1 #ifndef DALI_TEXTURE_H
   2 #define DALI_TEXTURE_H
   3
   4 /*
   5  * Copyright (c) 2023 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/images/native-image-interface.h>
  23 #include <dali/public-api/images/pixel-data.h>
  24 #include <dali/public-api/images/pixel.h>
  25 #include <dali/public-api/object/base-handle.h>
  26
  27 namespace Dali
  28 {
  29 /**
  30  * @addtogroup dali_core_rendering_effects
  31  * @{
  32  */
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class Texture;
  37 }
  38
  39 namespace TextureType
  40 {
  41 /**
  42  * @brief Enumeration for texture types.
  43  * @SINCE_1_1.43
  44  */
  45 enum Type
  46 {
  47   TEXTURE_2D,  ///< One 2D image                            @SINCE_1_1.43
  48   TEXTURE_CUBE ///< Six 2D images arranged in a cube-shape  @SINCE_1_1.43
  49 };
  50
  51 } // namespace TextureType
  52
  53 namespace CubeMapLayer
  54 {
  55 /**
  56    * @brief Faces of a cube map.
  57    * These constants should be used as the "layer" parameter when uploading a cube-map with Texture::Upload.
  58    * @SINCE_1_1.43
  59    */
  60 const uint32_t POSITIVE_X = 0u; ///< CubeMap image for +x @SINCE_1_1.43
  61 const uint32_t NEGATIVE_X = 1u; ///< CubeMap image for -x @SINCE_1_1.43
  62 const uint32_t POSITIVE_Y = 2u; ///< CubeMap image for +y @SINCE_1_1.43
  63 const uint32_t NEGATIVE_Y = 3u; ///< CubeMap image for -y @SINCE_1_1.43
  64 const uint32_t POSITIVE_Z = 4u; ///< CubeMap image for +z @SINCE_1_1.43
  65 const uint32_t NEGATIVE_Z = 5u; ///< CubeMap image for -z @SINCE_1_1.43
  66
  67 } // namespace CubeMapLayer
  68
  69 /**
  70  * @brief Texture represents a texture object used as input or output by shaders.
  71  * @SINCE_1_1.43
  72  */
  73 class DALI_CORE_API Texture : public BaseHandle
  74 {
  75 public:
  76   /**
  77    * @brief Creates a new Texture object.
  78    *
  79    * @SINCE_1_1.43
  80    * @param[in] type The type of the texture
  81    * @param[in] format The format of the pixel data
  82    * @param[in] width The width of the texture
  83    * @param[in] height The height of the texture
  84    * @return A handle to a newly allocated Texture
  85    */
  86   static Texture New(TextureType::Type type, Pixel::Format format, uint32_t width, uint32_t height);
  87
  88   /**
  89    * @brief Creates a new Texture object with no informations.
  90    * Texture will use Uploaded PixelData size and format.
  91    * Before texture Upload is called, width, height and format return invalid values.
  92    *
  93    * @SINCE_2_2.34
  94    * @param[in] type The type of the texture
  95    * @return A handle to a newly allocated Texture
  96    */
  97   static Texture New(TextureType::Type type);
  98
  99   /**
 100    * @brief Creates a new Texture object from a native image.
 101    *
 102    * @SINCE_1_1.43
 103    * @param[in] nativeImageInterface A native image
 104    * @return A handle to a newly allocated Texture
 105    * @note It is not possible to upload data to textures created from a native image using Upload methods
 106    * although there might be platform specific APIs to upload data to a native image.
 107    */
 108   static Texture New(NativeImageInterface& nativeImageInterface);
 109
 110   /**
 111    * @brief Default constructor, creates an empty handle.
 112    *
 113    * @SINCE_1_1.43
 114    */
 115   Texture();
 116
 117   /**
 118    * @brief Destructor.
 119    *
 120    * @SINCE_1_1.43
 121    */
 122   ~Texture();
 123
 124   /**
 125    * @brief Copy constructor, creates a new handle to the same object.
 126    *
 127    * @SINCE_1_1.43
 128    * @param[in] handle Handle to an object
 129    */
 130   Texture(const Texture& handle);
 131
 132   /**
 133    * @brief Downcasts to a texture.
 134    * If not, the returned handle is left uninitialized.
 135    *
 136    * @SINCE_1_1.43
 137    * @param[in] handle Handle to an object
 138    * @return Texture handle or an uninitialized handle
 139    */
 140   static Texture DownCast(BaseHandle handle);
 141
 142   /**
 143    * @brief Assignment operator, changes this handle to point at the same object.
 144    *
 145    * @SINCE_1_1.43
 146    * @param[in] handle Handle to an object
 147    * @return Reference to the assigned object
 148    */
 149   Texture& operator=(const Texture& handle);
 150
 151   /**
 152    * @brief Move constructor.
 153    *
 154    * @SINCE_1_9.22
 155    * @param[in] rhs A reference to the moved handle
 156    */
 157   Texture(Texture&& rhs) noexcept;
 158
 159   /**
 160    * @brief Move assignment operator.
 161    *
 162    * @SINCE_1_9.22
 163    * @param[in] rhs A reference to the moved handle
 164    * @return A reference to this handle
 165    */
 166   Texture& operator=(Texture&& rhs) noexcept;
 167
 168   /**
 169    * @brief Uploads data to the texture from a PixelData object.
 170    *
 171    * @SINCE_1_1.43
 172    * @param[in] pixelData The pixelData object
 173    * @return True if the PixelData object has compatible pixel format and fits within the texture, false otherwise
 174    */
 175   bool Upload(PixelData pixelData);
 176
 177   /**
 178    * @brief Uploads data to the texture from a PixelData object.
 179    * @note Upload does not upsample or downsample pixel data to fit the specified rectangular area in the texture.
 180    *
 181    * @SINCE_1_1.43
 182    * @param[in] pixelData The pixelData object
 183    * @param[in] layer Specifies the layer of a cube map or array texture (Unused for 2D textures). @see CubeMapLayer
 184    * @param[in] mipmap Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image
 185    * @param[in] xOffset Specifies an horizontal offset of the rectangular area in the texture that will be updated
 186    * @param[in] yOffset Specifies a vertical offset of the rectangular area in the texture that will be updated
 187    * @param[in] width Specifies the width of the rectangular area in the texture that will be updated
 188    * @param[in] height Specifies the height of the rectangular area in the texture that will be updated
 189    * @return True if the PixelData object has compatible pixel format and fits in the rectangle specified, false otherwise
 190    */
 191   bool Upload(PixelData pixelData,
 192               uint32_t  layer,
 193               uint32_t  mipmap,
 194               uint32_t  xOffset,
 195               uint32_t  yOffset,
 196               uint32_t  width,
 197               uint32_t  height);
 198
 199   /**
 200    * @brief Generates mipmaps for the texture.
 201    * This will auto generate all the mipmaps for the texture based on the data in the base level.
 202    *
 203    * @SINCE_1_1.43
 204    */
 205   void GenerateMipmaps();
 206
 207   /**
 208    * @brief Returns the width of the texture.
 209    *
 210    * @SINCE_1_1.43
 211    * @return The width, in pixels, of the texture
 212    */
 213   uint32_t GetWidth() const;
 214
 215   /**
 216    * @brief Returns the height of the texture.
 217    *
 218    * @SINCE_1_1.43
 219    * @return The height, in pixels, of the texture
 220    */
 221   uint32_t GetHeight() const;
 222
 223   /**
 224    * @brief Returns the pixel format of the texture.
 225    *
 226    * @SINCE_2_1.29
 227    * @return The pixel format of the texture
 228    */
 229   Pixel::Format GetPixelFormat() const;
 230
 231 public:
 232   /**
 233    * @brief The constructor.
 234    * @note  Not intended for application developers.
 235    * @SINCE_1_1.43
 236    * @param[in] pointer A pointer to a newly allocated Texture
 237    */
 238   explicit DALI_INTERNAL Texture(Internal::Texture* pointer);
 239 };
 240
 241 /**
 242  * @}
 243  */
 244 } //namespace Dali
 245
 246 #endif // DALI_TEXTURE_H