1 #ifndef __DALI_INTERNAL_IMAGE_ATTRIBUTES_H__
2 #define __DALI_INTERNAL_IMAGE_ATTRIBUTES_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
25 #include <dali/public-api/images/pixel.h>
26 #include <dali/public-api/images/image-operations.h>
27 #include <dali/public-api/math/rect.h>
28 #include <dali/public-api/math/vector2.h>
36 * @brief Describes Image properties like dimensions and pixel format and
37 * operations to be applied to images during the load process.
39 * ImageAttributes is used to define a set of properties of an image and a
40 * sequence of operations to be applied when loading it.
42 * The overall order of operations which can be applied is:
43 * 1. Determine the desired dimensions for the final bitmap.
44 * 2. Scale the image to fit the desired dimensions.
46 * The default for each stage is to do nothing.
47 * To enable a calculation of desired final image dimensions and fitting to it, SetSize() must be called.
49 * The loader does not guarantee to rescale a loaded image to the exact desired dimensions, but it will make a best effort to downscale images.
50 * The fitting to destination dimensions controlled by the ScalingMode may choose to fit to a larger area with an equivalent aspect ratio.
51 * If the requested dimensions are larger than the loaded ones, it will never upscale on load to fill them but will instead fit to smaller dimensions of identical aspect ratio.
52 * This is transparent to an application as the upscaling can happen during rendering.
54 * To enable scaling of images on load, desired dimensions must be set using SetSize().
55 * Only one of the dimensions need be supplied, in which case, the other is calculated based on the aspect ratio of the raw loaded image.
56 * The desired dimensions 2-tuple 'd' is determined as follows for loaded image dimensions 'l' and 's', the dimensions tuple set with SetSize():
57 * * `d = s, if s.x != 0 & s.y != 0, else:`
58 * * `d = [s.x, s.x * (l.y / l.x)], if s.x != 0 & s.y = 0, else:`
59 * * `d = [s.y * (l.x / l.y), s.y], if s.x = 0 & s.y != 0, else:`
60 * * `d = l, otherwise.`
62 * Use cases for scaling images on load include:
63 * 1. Full-screen image display: Limit loaded image resolution to device resolution using ShrinkToFit mode.
64 * 2. Thumbnail gallery grid: Limit loaded image resolution to screen tile using ScaleToFill mode.
65 * 3. Image columns: Limit loaded image resolution to column width using FitWidth mode.
66 * 4. Image rows: Limit loaded image resolution to row height using FitHeight mode.
68 * @note The aspect ratio of image contents is preserved by all scaling modes, so for example squares in input images stay square after loading.
75 * @brief Scaling options, used when resizing images on load to fit desired dimensions.
77 * A scaling mode controls the region of a loaded image to be mapped to the
78 * desired image rectangle specified using ImageAttributes.SetSize().
79 * All scaling modes preserve the aspect ratio of the image contents.
81 typedef Dali::FittingMode::Type ScalingMode;
84 * @brief Filtering options, used when resizing images on load to sample original pixels.
86 * A FilterMode controls how pixels in the raw image on-disk are sampled and
87 * combined to generate each pixel of the destination loaded image.
89 * @note NoFilter and Box modes do not guarantee that the loaded pixel array
90 * exactly matches the rectangle specified by the desired dimensions and
91 * ScalingMode, but all other filter modes do if the desired dimensions are
92 * `<=` the raw dimensions of the image file.
94 typedef Dali::SamplingMode::Type FilterMode;
96 static const ImageAttributes DEFAULT_ATTRIBUTES; ///< Default attributes have no size
99 * @brief Default constructor, initializes to default values.
104 * @brief This copy constructor is required for correctly copying internal implementation.
106 * @param [in] rhs A reference to the copied handle
108 ImageAttributes(const ImageAttributes& rhs);
111 * @brief This assignment operator is required for correctly handling the internal implementation.
113 * @param [in] rhs A reference to the copied handle
114 * @return a reference to this object
116 ImageAttributes& operator=(const ImageAttributes& rhs);
119 * @brief Default destructor.
124 * @brief Create an initialised image attributes object.
126 * @return A handle to a newly allocated object
128 static ImageAttributes New();
131 * @brief Create an initialised image attributes object.
133 * @param [in] width desired width.
134 * @param [in] height desired height
135 * @return A handle to a newly allocated object
137 static ImageAttributes New(unsigned int width, unsigned int height);
140 * @brief Set the size properties.
142 * By default width and height are set to zero which means the image loaded has the original size.
143 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
144 * the one that is set and the aspect ratio of the image.
146 * @param [in] width desired width.
147 * @param [in] height desired height
149 void SetSize(unsigned int width, unsigned int height);
152 * @brief Set the image dimension properties.
154 * By default, width and height are set to zero which means the image loaded has the original size.
155 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
156 * the one that is set and the aspect ratio of the image.
158 * @param [in] size desired size.
160 void SetSize( const Size& size );
163 * @brief Set the scale field of the image attributes.
165 * By default, ShrinkToFit is set.
166 * @param [in] scalingMode The desired scaling mode
168 void SetScalingMode( ScalingMode scalingMode );
171 * @brief Setter for the FilterMode.
172 * By default, Box is set.
173 * @param [in] filterMode The desired filter mode.
175 void SetFilterMode( FilterMode filterMode );
178 * @brief Set whether the image will be rotated/flipped back into portrait orientation.
180 * This will only be necessary if metadata indicates that the
181 * image has a different viewing orientation.
183 * This metadata, optionally present in formats that use exif for example,
184 * can encode the physical orientation of the camera which took the picture,
185 * establishing which directions in the image correspond to real-world "up"
187 * By default the metadata is ignored, but if this function is called with
188 * the value "true", the pixels of an image are reordered at load time to reflect
189 * the orientation in the metadata.
191 * @param [in] enabled If true, the image orientation metadata will be used to
192 * transform the pixels of the image as laid-out in memory.
194 void SetOrientationCorrection(bool enabled);
197 * @brief Change all members in one operation.
198 * @param[in] dimensions width and height
199 * @param[in] scaling Scaling mode for resizing loads.
200 * @param[in] sampling Sampling mode.
201 * @param[in] orientation Orientation correction toggle.
203 void Reset( ImageDimensions dimensions = ImageDimensions(0, 0), ScalingMode scaling = ScalingMode(), FilterMode sampling = FilterMode(), bool orientationCorrection = true );
207 * @brief Return the width currently represented by the attribute.
211 unsigned int GetWidth() const;
214 * @brief Return the height currently represented by the attribute.
218 unsigned int GetHeight() const;
221 * @brief Return the size currently represented by the attribute.
225 Size GetSize() const;
228 * @brief Return the scale currently represented by the attribute.
232 ScalingMode GetScalingMode() const;
235 * @brief Getter for the FilterMode
237 * @return The FilterMode previously set, or the default value if none has
240 FilterMode GetFilterMode() const;
243 * @brief Whether to correct for physical orientation of an image.
245 * @return Whether image pixels should be transformed according to the
246 * orientation metadata, if any.
248 bool GetOrientationCorrection() const;
251 * @brief Less then comparison operator.
253 * @param [in] a parameter tested
254 * @param [in] b parameter tested
255 * @return true if a is less than b
257 friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
260 * @brief Equal to comparison operator.
262 * @param [in] a parameter tested for equality
263 * @param [in] b parameter tested for equality
264 * @return true if a is equal to b
266 friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
269 * @brief Not equal to comparison operator.
271 * @param [in] a parameter tested for equality
272 * @param [in] b parameter tested for equality
273 * @return true if a is not equal to b
275 friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
278 struct ImageAttributesImpl;
279 ImageAttributesImpl* impl; ///< Implementation pointer
283 * @brief Less then comparison operator.
285 * @param [in] a parameter tested
286 * @param [in] b parameter tested
287 * @return true if a is less than b
289 bool operator<(const ImageAttributes& a, const ImageAttributes& b);
292 * @brief Equal to comparison operator.
294 * @param [in] a parameter tested for equality
295 * @param [in] b parameter tested for equality
296 * @return true if a is equal to b
298 bool operator==(const ImageAttributes& a, const ImageAttributes& b);
301 * @brief Not equal to comparison operator.
303 * @param [in] a parameter tested for equality
304 * @param [in] b parameter tested for equality
305 * @return true if a is not equal to b
307 bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
309 } // namespace Internal
312 #endif // __DALI_INTERNAL_IMAGE_ATTRIBUTES_H__