[dali_1.9.24] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / devel-api / text / text-utils-devel.h
1 #ifndef DALI_TOOLKIT_TEXT_UTILS_DEVEL_H
2 #define DALI_TOOLKIT_TEXT_UTILS_DEVEL_H
3
4 /*
5  * Copyright (c) 2019 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 // EXTERNAL INCLUDES
22 #include <dali/public-api/object/property-array.h>
23 #include <dali-toolkit/public-api/dali-toolkit-common.h>
24 #include <dali/devel-api/adaptor-framework/pixel-buffer.h>
25 #include <dali/devel-api/text-abstraction/text-abstraction-definitions.h>
26
27 namespace Dali
28 {
29
30 namespace Toolkit
31 {
32
33 namespace DevelText
34 {
35
36 /**
37  * @brief Struct with the text and style parameters to be rendered into a pixel buffer.
38  */
39 struct DALI_TOOLKIT_API RendererParameters
40 {
41   RendererParameters()
42   : text{},
43     horizontalAlignment{ "begin" },
44     verticalAlignment{ "top" },
45     fontFamily{},
46     fontWeight{},
47     fontWidth{},
48     fontSlant{},
49     layout{ "singleLine" },
50     circularAlignment{ "begin" },
51     textColor{ Color::WHITE },
52     fontSize{ 0.f },
53     textWidth{ 0u },
54     textHeight{ 0u },
55     radius{ 0u },
56     beginAngle{ 0.f },
57     incrementAngle{ 0.f },
58     ellipsisEnabled{ true },
59     markupEnabled{ false },
60     isTextColorSet{ false },
61     minLineSize{ 0.f }
62   {}
63
64   std::string text;                ///< The text to be rendered encoded in utf8.
65
66   std::string horizontalAlignment; ///< The horizontal alignment: one of {"begin", "center", "end"}.
67   std::string verticalAlignment;   ///< The vertical alignment: one of {"top", "center", "bottom"}.
68
69   std::string fontFamily;          ///< The font's family.
70   std::string fontWeight;          ///< The font's weight: one of {"thin", "ultraLight", "extraLight", "light", "demiLight", "semiLight", "book", "normal", "regular", "medium", "demiBold", "semiBold", "bold", "ultraBold", "extraBold", "black", "heavy", "extraBlack"}.
71   std::string fontWidth;           ///< The font's width: one of {"ultraCondensed", "extraCondensed", "condensed", "semiCondensed", "normal", "semiExpanded", "expanded", "extraExpanded", "ultraExpanded"}.
72   std::string fontSlant;           ///< The font's slant. one of {"normal", "roman", "italic", "oblique"}
73   std::string layout;              ///< The type of layout: one of {"singleLine", "multiLine", "circular"}
74   std::string circularAlignment;   ///< The text alignment within the arc: one of {"begin", "center", "end"}. The @p horizontalAlignment and @p verticalAlignment can be used to align the text within the text area.
75
76   Vector4 textColor;               ///< The default text's color. Default is white.
77
78   float fontSize;           ///< The font's size (in points).
79
80   unsigned int textWidth;          ///< The width in pixels of the boundaries where the text is going to be laid-out.
81   unsigned int textHeight;         ///< The height in pixels of the boundaries where the text is going to be laid-out.
82
83   unsigned int radius;             ///< The radius in pixels of the circular text.
84   float beginAngle;                ///< The begin angle in degrees of the text area on the circle. The top of the circle is 0°, the right side 90°, the bottom 180° and the left 270°.
85   float incrementAngle;            ///< The increment angle in degrees of the text area on the circle. The @p incrementAngle defines a direction. If positive, the text will be laid out clockwise.
86
87   bool ellipsisEnabled:1;          ///< Whether the ellipsis layout option is enabled.
88   bool markupEnabled:1;            ///< Whether the mark-up processor is enabled.
89   bool isTextColorSet:1;           ///< Whether a default color has been set.
90
91   float minLineSize;               ///< The line's minimum size (in points).
92 };
93
94 /**
95  * @brief Struct with info of the embedded items layout.
96  */
97 struct DALI_TOOLKIT_API EmbeddedItemInfo
98 {
99   TextAbstraction::CharacterIndex characterIndex;       ///< Index to the character within the string.
100   TextAbstraction::GlyphIndex glyphIndex;               ///< Index to the glyph
101   Vector2 position;                                     ///< The layout position within the buffer (top, left corner).
102   Size size;                                            ///< The size within the buffer of the embedded item.
103   Size rotatedSize;                                     ///< The rotated size within the buffer of the embedded item.
104   Degree angle;                                         ///< Rotation angle of the pixel buffer in degrees.
105   TextAbstraction::ColorBlendingMode colorBlendingMode; ///< Whether the color of the image is multiplied by the color of the text.
106 };
107
108 /**
109 * @brief Struct with the parameters needed to build a shadow for the given pixel buffer.
110 */
111 struct DALI_TOOLKIT_API ShadowParameters
112 {
113   Devel::PixelBuffer input; ///< The input pixel buffer used to create the shadow.
114   Vector4 textColor;        ///< The color of the text.
115   Vector4 color;            ///< The color of the shadow.
116   Vector2 offset;           ///< The offset of the shadow.
117   bool blendShadow;         ///< Whether to blend the shadow.
118 };
119
120 /**
121  * @brief Renders text into a pixel buffer.
122  *
123  * @note: Can process a mark-up string.
124  * @note: It does the font selection, RTL reordering, shaping and layouting.
125  * @note: The width of the pixel buffer may be different to the given @e textWidth
126  *        due to some padding pixels added.
127  *
128  *  The text is laid-out for the given size @e (textWidth,textHeight).
129  *  If the @e multiLineEnabled option is enabled, the text will wrap in lines.
130  *  If the @e ellipsisEnabled option is enabled, the text will be ellided if
131  *  there is no more space for new lines.
132  *
133  *  It won't be rendered the parts of the text exceeding the boundaries of
134  *  the given width and height.
135  *
136  *  If the given @e textHeight is zero, a big enough pixel buffer will be created
137  *  to render the full text.
138  *
139  *  If the given @e textWidth is zero, the 'natural size' of the text will be
140  *  used to create the pixel buffer to render the full text.
141  *
142  *  If the radius is not zero, the text will be laid-out following a circular path.
143  *  In that case the text is laid-out in a single line.
144  *
145  * If the mark-up string contains embedded items, the @p embeddedItemLayout vector
146  * contains the layout info of each embedded item.
147  *
148  * @param[in] textParameters The text and style options.
149  * @param[out] embeddedItemLayout The layout info of the embedded items.
150  *
151  * @return A pixel buffer with the text rendered on it.
152  */
153 DALI_TOOLKIT_API Devel::PixelBuffer Render( const RendererParameters& textParameters, Vector<EmbeddedItemInfo>& embeddedItemLayout );
154
155 /**
156  * @brief Creates a shadow for the text given in the input pixel buffer.
157  *
158  * The function returns a RGBA8888 pixel buffer with the text and its shadow rendered on it.
159  *
160  * The pixel format of the @e input pixel buffer could be an A8 or an RGBA8888. If it's
161  * an A8 pixel buffer, it uses the given @e textColor to give color to the text. Otherwise
162  * it uses the color of the @e input pixel buffer.
163  *
164  * @param[in] shadowParameters The parameters needed to create the text's shadow.
165  *
166  * @return A pixel buffer with the text and the shadow rendered on it.
167  */
168 DALI_TOOLKIT_API Devel::PixelBuffer CreateShadow(const ShadowParameters& shadowParameters);
169
170 /**
171  * @brief Converts a @p pixelBuffer with pixel format A8 to RGBA8888 using the given @p color.
172  *
173  * @note Does nothing if the @p pixelBuffer is not A8.
174  *
175  * @param[in] pixelBuffer The pixel buffer with pixel format A8
176  * @param[in] color The color used to convert to RGBA8888
177  * @param[in] multiplyByAlpha Whether to multiply the @p color with the alpha value of the @p pixel @p buffer.
178  *
179  * @return The pixel buffer converted to RGBA8888.
180  */
181 DALI_TOOLKIT_API Devel::PixelBuffer ConvertToRgba8888( Devel::PixelBuffer pixelBuffer, const Vector4& color, bool multiplyByAlpha );
182
183 /**
184 * @brief Updates the @p dst pixel buffer with the data from @p src pixel buffer.
185 *
186 * @note Both pixel buffers must have the same pixel format. Does nothing if both pixel format are different.
187 * @note The function does nothing if the @p src pixel buffer doesn't fit into the @p dst pixel buffer.
188 *
189 * The @p src pixel buffer could be blended with the @p dst pixel buffer if @p blend is set to @e true.
190 *
191 * @param[in] src The pixel buffer from where the data is read.
192 * @param[in] dst The pixel buffer where the data is written..
193 * @param[in] x The top left corner's X within the destination pixel buffer.
194 * @param[in] y The top left corner's y within the destination pixel buffer.
195 * @param[in] blend Whether to blend the source pixel buffer with the destination pixel buffer as background.
196 */
197 DALI_TOOLKIT_API void UpdateBuffer( Devel::PixelBuffer src, Devel::PixelBuffer dst, unsigned int x, unsigned int y, bool blend);
198
199 /**
200  * @brief Splits the text in pages of the size given in @p textParameters
201  *
202  * @note The returned indices are indices to utf32 characters. The input text is encoded in utf8.
203  * @return An array with the indices of the last character of each page
204  */
205 DALI_TOOLKIT_API Dali::Property::Array GetLastCharacterIndex( RendererParameters& textParameters );
206
207 } // namespace DevelText
208
209 } // namespace Toolkit
210
211 } // namespace Dali
212
213 #endif // DALI_TOOLKIT_TEXT_UTILS_DEVEL_H