1 #ifndef DALI_INTERNAL_IMAGE_ATTRIBUTES_H
2 #define DALI_INTERNAL_IMAGE_ATTRIBUTES_H
5 * Copyright (c) 2021 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/image-operations.h>
26 #include <dali/public-api/images/pixel.h>
27 #include <dali/public-api/math/rect.h>
28 #include <dali/public-api/math/vector2.h>
35 * @brief Describes Image properties like dimensions and pixel format and
36 * operations to be applied to images during the load process.
38 * ImageAttributes is used to define a set of properties of an image and a
39 * sequence of operations to be applied when loading it.
41 * The overall order of operations which can be applied is:
42 * 1. Determine the desired dimensions for the final bitmap.
43 * 2. Scale the image to fit the desired dimensions.
45 * The default for each stage is to do nothing.
46 * To enable a calculation of desired final image dimensions and fitting to it, SetSize() must be called.
48 * 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.
49 * The fitting to destination dimensions controlled by the ScalingMode may choose to fit to a larger area with an equivalent aspect ratio.
50 * 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.
51 * This is transparent to an application as the upscaling can happen during rendering.
53 * To enable scaling of images on load, desired dimensions must be set using SetSize().
54 * 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.
55 * The desired dimensions 2-tuple 'd' is determined as follows for loaded image dimensions 'l' and 's', the dimensions tuple set with SetSize():
56 * * `d = s, if s.x != 0 & s.y != 0, else:`
57 * * `d = [s.x, s.x * (l.y / l.x)], if s.x != 0 & s.y = 0, else:`
58 * * `d = [s.y * (l.x / l.y), s.y], if s.x = 0 & s.y != 0, else:`
59 * * `d = l, otherwise.`
61 * Use cases for scaling images on load include:
62 * 1. Full-screen image display: Limit loaded image resolution to device resolution using ShrinkToFit mode.
63 * 2. Thumbnail gallery grid: Limit loaded image resolution to screen tile using ScaleToFill mode.
64 * 3. Image columns: Limit loaded image resolution to column width using FitWidth mode.
65 * 4. Image rows: Limit loaded image resolution to row height using FitHeight mode.
67 * @note The aspect ratio of image contents is preserved by all scaling modes, so for example squares in input images stay square after loading.
73 * @brief Scaling options, used when resizing images on load to fit desired dimensions.
75 * A scaling mode controls the region of a loaded image to be mapped to the
76 * desired image rectangle specified using ImageAttributes.SetSize().
77 * All scaling modes preserve the aspect ratio of the image contents.
79 typedef Dali::FittingMode::Type ScalingMode;
82 * @brief Filtering options, used when resizing images on load to sample original pixels.
84 * A FilterMode controls how pixels in the raw image on-disk are sampled and
85 * combined to generate each pixel of the destination loaded image.
87 * @note NoFilter and Box modes do not guarantee that the loaded pixel array
88 * exactly matches the rectangle specified by the desired dimensions and
89 * ScalingMode, but all other filter modes do if the desired dimensions are
90 * `<=` the raw dimensions of the image file.
92 using FilterMode = Dali::SamplingMode::Type;
94 static const ImageAttributes DEFAULT_ATTRIBUTES; ///< Default attributes have no size
97 * @brief Default constructor, initializes to default values.
102 * @brief This copy constructor is required for correctly copying internal implementation.
104 * @param [in] rhs A reference to the copied handle
106 ImageAttributes(const ImageAttributes& rhs);
109 * @brief This assignment operator is required for correctly handling the internal implementation.
111 * @param [in] rhs A reference to the copied handle
112 * @return a reference to this object
114 ImageAttributes& operator=(const ImageAttributes& rhs);
117 * @brief Default destructor.
122 * @brief Create an initialised image attributes object.
124 * @return A handle to a newly allocated object
126 static ImageAttributes New();
129 * @brief Set the size properties.
131 * By default width and height are set to zero which means the image loaded has the original size.
132 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
133 * the one that is set and the aspect ratio of the image.
135 * @param [in] width desired width.
136 * @param [in] height desired height
138 void SetSize(uint32_t width, uint32_t height);
141 * @brief Set the image dimension properties.
143 * By default, width and height are set to zero which means the image loaded has the original size.
144 * If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from
145 * the one that is set and the aspect ratio of the image.
147 * @param [in] size desired size.
149 void SetSize(const Size& size);
152 * @brief Set the scale field of the image attributes.
154 * By default, ShrinkToFit is set.
155 * @param [in] scalingMode The desired scaling mode
157 void SetScalingMode(ScalingMode scalingMode);
160 * @brief Setter for the FilterMode.
161 * By default, Box is set.
162 * @param [in] filterMode The desired filter mode.
164 void SetFilterMode(FilterMode filterMode);
167 * @brief Set whether the image will be rotated/flipped back into portrait orientation.
169 * This will only be necessary if metadata indicates that the
170 * image has a different viewing orientation.
172 * This metadata, optionally present in formats that use exif for example,
173 * can encode the physical orientation of the camera which took the picture,
174 * establishing which directions in the image correspond to real-world "up"
176 * By default the metadata is ignored, but if this function is called with
177 * the value "true", the pixels of an image are reordered at load time to reflect
178 * the orientation in the metadata.
180 * @param [in] enabled If true, the image orientation metadata will be used to
181 * transform the pixels of the image as laid-out in memory.
183 void SetOrientationCorrection(bool enabled);
186 * @brief Change all members in one operation.
187 * @param[in] dimensions width and height
188 * @param[in] scaling Scaling mode for resizing loads.
189 * @param[in] sampling Sampling mode.
190 * @param[in] orientation Orientation correction toggle.
192 void Reset(ImageDimensions dimensions = ImageDimensions(0, 0), ScalingMode scaling = ScalingMode(), FilterMode sampling = FilterMode(), bool orientationCorrection = true);
195 * @brief Return the width currently represented by the attribute.
199 unsigned int GetWidth() const;
202 * @brief Return the height currently represented by the attribute.
206 unsigned int GetHeight() const;
209 * @brief Return the size currently represented by the attribute.
213 Size GetSize() const;
216 * @brief Return the scale currently represented by the attribute.
220 ScalingMode GetScalingMode() const;
223 * @brief Getter for the FilterMode
225 * @return The FilterMode previously set, or the default value if none has
228 FilterMode GetFilterMode() const;
231 * @brief Whether to correct for physical orientation of an image.
233 * @return Whether image pixels should be transformed according to the
234 * orientation metadata, if any.
236 bool GetOrientationCorrection() const;
239 * @brief Less then comparison operator.
241 * @param [in] a parameter tested
242 * @param [in] b parameter tested
243 * @return true if a is less than b
245 friend bool operator<(const ImageAttributes& a, const ImageAttributes& b);
248 * @brief Equal to comparison operator.
250 * @param [in] a parameter tested for equality
251 * @param [in] b parameter tested for equality
252 * @return true if a is equal to b
254 friend bool operator==(const ImageAttributes& a, const ImageAttributes& b);
257 * @brief Not equal to comparison operator.
259 * @param [in] a parameter tested for equality
260 * @param [in] b parameter tested for equality
261 * @return true if a is not equal to b
263 friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
266 struct ImageAttributesImpl;
267 ImageAttributesImpl* impl; ///< Implementation pointer
271 * @brief Less then comparison operator.
273 * @param [in] a parameter tested
274 * @param [in] b parameter tested
275 * @return true if a is less than b
277 bool operator<(const ImageAttributes& a, const ImageAttributes& b);
280 * @brief Equal to comparison operator.
282 * @param [in] a parameter tested for equality
283 * @param [in] b parameter tested for equality
284 * @return true if a is equal to b
286 bool operator==(const ImageAttributes& a, const ImageAttributes& b);
289 * @brief Not equal to comparison operator.
291 * @param [in] a parameter tested for equality
292 * @param [in] b parameter tested for equality
293 * @return true if a is not equal to b
295 bool operator!=(const ImageAttributes& a, const ImageAttributes& b);
297 } // namespace Internal
300 #endif // DALI_INTERNAL_IMAGE_ATTRIBUTES_H