Merge "(FrameCallback) Use uint32_t instead of unsigned int" into devel/master
[platform/core/uifw/dali-core.git] / 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 uint32_t POSITIVE_X = 0u; ///< CubeMap image for +x @SINCE_1_1.43
59   const uint32_t NEGATIVE_X = 1u; ///< CubeMap image for -x @SINCE_1_1.43
60   const uint32_t POSITIVE_Y = 2u; ///< CubeMap image for +y @SINCE_1_1.43
61   const uint32_t NEGATIVE_Y = 3u; ///< CubeMap image for -y @SINCE_1_1.43
62   const uint32_t POSITIVE_Z = 4u; ///< CubeMap image for +z @SINCE_1_1.43
63   const uint32_t 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, uint32_t width, uint32_t 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                uint32_t layer, uint32_t mipmap,
165                uint32_t xOffset, uint32_t yOffset,
166                uint32_t width, uint32_t 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   uint32_t 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   uint32_t 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