dali/public-api/rendering/texture.h

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