Merge "DALi Version 1.4.22" 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  * @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 Uploads data to the texture from a PixelData object.
146    *
147    * @SINCE_1_1.43
148    * @param[in] pixelData The pixelData object
149    * @return True if the PixelData object has compatible pixel format and fits within the texture, false otherwise
150    */
151   bool Upload( PixelData pixelData );
152
153   /**
154    * @brief Uploads data to the texture from a PixelData object.
155    * @note Upload does not upsample or downsample pixel data to fit the specified rectangular area in the texture.
156    *
157    * @SINCE_1_1.43
158    * @param[in] pixelData The pixelData object
159    * @param[in] layer Specifies the layer of a cube map or array texture (Unused for 2D textures). @see CubeMapLayer
160    * @param[in] mipmap Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image
161    * @param[in] xOffset Specifies an horizontal offset of the rectangular area in the texture that will be updated
162    * @param[in] yOffset Specifies a vertical offset of the rectangular area in the texture that will be updated
163    * @param[in] width Specifies the width of the rectangular area in the texture that will be updated
164    * @param[in] height Specifies the height of the rectangular area in the texture that will be updated
165    * @return True if the PixelData object has compatible pixel format and fits in the rectangle specified, false otherwise
166    */
167   bool Upload( PixelData pixelData,
168                uint32_t layer, uint32_t mipmap,
169                uint32_t xOffset, uint32_t yOffset,
170                uint32_t width, uint32_t height );
171
172   /**
173    * @brief Generates mipmaps for the texture.
174    * This will auto generate all the mipmaps for the texture based on the data in the base level.
175    *
176    * @SINCE_1_1.43
177    */
178   void GenerateMipmaps();
179
180   /**
181    * @brief Returns the width of the texture.
182    *
183    * @SINCE_1_1.43
184    * @return The width, in pixels, of the texture
185    */
186   uint32_t GetWidth() const;
187
188   /**
189    * @brief Returns the height of the texture.
190    *
191    * @SINCE_1_1.43
192    * @return The height, in pixels, of the texture
193    */
194   uint32_t GetHeight() const;
195
196 public:
197
198   /**
199    * @brief The constructor.
200    * @note  Not intended for application developers.
201    * @SINCE_1_1.43
202    * @param[in] pointer A pointer to a newly allocated Texture
203    */
204   explicit DALI_INTERNAL Texture( Internal::Texture* pointer );
205 };
206
207 /**
208  * @}
209  */
210 } //namespace Dali
211
212 #endif // DALI_TEXTURE_H