1 #ifndef DALI_TOOLKIT_IMAGE_ATLAS_H
2 #define DALI_TOOLKIT_IMAGE_ATLAS_H
4 * Copyright (c) 2016 Samsung Electronics Co., Ltd.
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
23 #include <dali/public-api/object/base-handle.h>
24 #include <dali/public-api/images/image-operations.h>
25 #include <dali/public-api/images/pixel.h>
26 #include <dali/public-api/images/pixel-data.h>
27 #include <dali/public-api/rendering/texture.h>
30 #include <dali-toolkit/devel-api/image-loader/atlas-upload-observer.h>
37 namespace Internal DALI_INTERNAL
43 * @brief An ImageAtlas is a large texture containing multiple smaller images.
45 * Only images with url provided or pixel data are supported for uploading.
46 * The images are loaded by a worker thread to avoid blocking the main event thread.
48 class DALI_IMPORT_API ImageAtlas : public BaseHandle
52 typedef uint32_t SizeType;
57 * @brief Create a new ImageAtlas.
59 * @param [in] width The atlas width in pixels.
60 * @param [in] height The atlas height in pixels.
61 * @param [in] pixelFormat The pixel format (rgba 32 bit by default).
62 * @return A handle to a new ImageAtlas.
64 static ImageAtlas New( SizeType width, SizeType height,
65 Pixel::Format pixelFormat = Pixel::RGBA8888 );
68 * @brief Create an empty handle.
70 * Calling member functions of an empty handle is not allowed.
80 * @brief This copy constructor is required for (smart) pointer semantics.
82 * @param [in] handle A reference to the copied handle
84 ImageAtlas( const ImageAtlas& handle );
87 * @brief This assignment operator is required for (smart) pointer semantics.
89 * @param [in] handle A reference to the copied handle
90 * @return A reference to this
92 ImageAtlas& operator=( const ImageAtlas& handle );
95 * @brief Get the atlas image.
97 * This atlas texture is still valid after destroying the ImageAtlas object.
99 * @return The atlas texture
104 * @brief Query what percentage of space is been occupied in the atlas.
106 * @return The occupancy rate of the atlas.
108 float GetOccupancyRate() const;
111 * @brief Set the broken image which is used to replace the image if loading fails.
113 * @param[in] brokenImageUrl The url of the broken image.
115 void SetBrokenImage( const std::string& brokenImageUrl );
118 * @brief Upload a resource image to the atlas.
120 * @note To make the atlasing efficient, a valid size should be provided.
121 * If size is not provided, then the image file will be opened to read the actual size for loading.
122 * Do not set a size that is bigger than the actual image size, as the up-scaling is not available,
123 * the content of the area not covered by actual image is undefined, it will not be cleared.
125 * SamplingMode::BOX_THEN_LINEAR is used to sampling pixels from the input image while fitting it to desired size.
127 * @param [out] textureRect The texture area of the resource image in the atlas.
128 * @param [in] url The URL of the resource image file to use.
129 * @param [in] size The width and height to fit the loaded image to.
130 * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
131 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
132 * @return True if there is enough space to fit this image in,false otherwise.
134 bool Upload( Vector4& textureRect,
135 const std::string& url,
136 ImageDimensions size = ImageDimensions(),
137 FittingMode::Type fittingMode = FittingMode::DEFAULT,
138 bool orientationCorrection = true );
141 * @brief Upload a resource image to the atlas.
143 * @note To make the atlasing efficient, a valid size should be provided.
144 * If size is not provided, then the image file will be opened to read the actual size for loading.
145 * Do not set a size that is bigger than the actual image size, as the up-scaling is not available,
146 * the content of the area not covered by actual image is undefined, it will not be cleared.
148 * SamplingMode::BOX_THEN_LINEAR is used to sampling pixels from the input image while fitting it to desired size.
150 * @param [out] textureRect The texture area of the resource image in the atlas.
151 * @param [in] url The URL of the resource image file to use.
152 * @param [in] size The width and height to fit the loaded image to.
153 * @param [in] fittingMode The method used to fit the shape of the image before loading to the shape defined by the size parameter.
154 * @param [in] orientationCorrection Reorient the image to respect any orientation metadata in its header.
155 * @param[in] atlasUploadObserver The observer to observe the upload state inside the ImageAtlas.
156 * @return True if there is enough space to fit this image in,false otherwise.
157 * @note The valid callback function here is required to have the signature of void( void ).
159 bool Upload( Vector4& textureRect,
160 const std::string& url,
161 ImageDimensions size,
162 FittingMode::Type fittingMode,
163 bool orientationCorrection,
164 AtlasUploadObserver* atlasUploadObserver );
167 * @brief Upload a pixel buffer to atlas
169 * @param [out] textureRect The texture area of the resource image in the atlas.
170 * @param [in] pixelData The pixel data.
172 bool Upload( Vector4& textureRect, PixelData pixelData );
175 * @brief Remove the image at the given rectangle.
177 * The rectangular area is marked unoccupied, so new image can be added to this area.
179 * @param [in] textureRect The texture area to be removed.
181 void Remove( const Vector4& textureRect );
183 public: // Not intended for developer use
185 explicit DALI_INTERNAL ImageAtlas( Internal::ImageAtlas* impl );
188 } // namespace Toolkit
192 #endif // DALI_TOOLKIT_IMAGE_ATLAS_H