1 #ifndef DALI_INTERNAL_IMAGE_ATTRIBUTES_H
2 #define DALI_INTERNAL_IMAGE_ATTRIBUTES_H
5 * Copyright (c) 2019 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 Set the size properties.
133 * By default width and height are set to zero which means the image loaded has the original size.
134 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
135 * the one that is set and the aspect ratio of the image.
137 * @param [in] width desired width.
138 * @param [in] height desired height
140 void SetSize( uint32_t width, uint32_t height);
143 * @brief Set the image dimension properties.
145 * By default, width and height are set to zero which means the image loaded has the original size.
146 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
147 * the one that is set and the aspect ratio of the image.
149 * @param [in] size desired size.
151 void SetSize( const Size& size );
154 * @brief Set the scale field of the image attributes.
156 * By default, ShrinkToFit is set.
157 * @param [in] scalingMode The desired scaling mode
159 void SetScalingMode( ScalingMode scalingMode );
162 * @brief Setter for the FilterMode.
163 * By default, Box is set.
164 * @param [in] filterMode The desired filter mode.
166 void SetFilterMode( FilterMode filterMode );
169 * @brief Set whether the image will be rotated/flipped back into portrait orientation.
171 * This will only be necessary if metadata indicates that the
172 * image has a different viewing orientation.
174 * This metadata, optionally present in formats that use exif for example,
175 * can encode the physical orientation of the camera which took the picture,
176 * establishing which directions in the image correspond to real-world "up"
178 * By default the metadata is ignored, but if this function is called with
179 * the value "true", the pixels of an image are reordered at load time to reflect
180 * the orientation in the metadata.
182 * @param [in] enabled If true, the image orientation metadata will be used to
183 * transform the pixels of the image as laid-out in memory.
185 void SetOrientationCorrection(bool enabled);
188 * @brief Change all members in one operation.
189 * @param[in] dimensions width and height
190 * @param[in] scaling Scaling mode for resizing loads.
191 * @param[in] sampling Sampling mode.
192 * @param[in] orientation Orientation correction toggle.
194 void Reset( ImageDimensions dimensions = ImageDimensions(0, 0), ScalingMode scaling = ScalingMode(), FilterMode sampling = FilterMode(), bool orientationCorrection = true );
198 * @brief Return the width currently represented by the attribute.
202 unsigned int GetWidth() const;
205 * @brief Return the height currently represented by the attribute.
209 unsigned int GetHeight() const;
212 * @brief Return the size currently represented by the attribute.
216 Size GetSize() const;
219 * @brief Return the scale currently represented by the attribute.
223 ScalingMode GetScalingMode() const;
226 * @brief Getter for the FilterMode
228 * @return The FilterMode previously set, or the default value if none has
231 FilterMode GetFilterMode() const;
234 * @brief Whether to correct for physical orientation of an image.
236 * @return Whether image pixels should be transformed according to the
237 * orientation metadata, if any.
239 bool GetOrientationCorrection() const;
242 * @brief Less then comparison operator.
244 * @param [in] a parameter tested
245 * @param [in] b parameter tested
246 * @return true if a is less than b
248 friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
251 * @brief Equal to comparison operator.
253 * @param [in] a parameter tested for equality
254 * @param [in] b parameter tested for equality
255 * @return true if a is equal to b
257 friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
260 * @brief Not 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 not equal to b
266 friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
269 struct ImageAttributesImpl;
270 ImageAttributesImpl* impl; ///< Implementation pointer
274 * @brief Less then comparison operator.
276 * @param [in] a parameter tested
277 * @param [in] b parameter tested
278 * @return true if a is less than b
280 bool operator<(const ImageAttributes& a, const ImageAttributes& b);
283 * @brief Equal to comparison operator.
285 * @param [in] a parameter tested for equality
286 * @param [in] b parameter tested for equality
287 * @return true if a is equal to b
289 bool operator==(const ImageAttributes& a, const ImageAttributes& b);
292 * @brief Not 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 not equal to b
298 bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
300 } // namespace Internal
303 #endif // DALI_INTERNAL_IMAGE_ATTRIBUTES_H