dali/public-api/rendering/texture.h

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