1 #ifndef DALI_TOOLKIT_TEXT_UTILS_DEVEL_H
2 #define DALI_TOOLKIT_TEXT_UTILS_DEVEL_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.
22 #include <dali-toolkit/public-api/dali-toolkit-common.h>
23 #include <dali/devel-api/adaptor-framework/pixel-buffer.h>
24 #include <dali/devel-api/text-abstraction/text-abstraction-definitions.h>
36 * @brief Struct with the text and style parameters to be rendered into a pixel buffer.
38 struct DALI_TOOLKIT_API RendererParameters
42 horizontalAlignment{ "begin" },
43 verticalAlignment{ "top" },
48 layout{ "singleLine" },
49 circularAlignment{ "begin" },
50 textColor{ Color::WHITE },
56 incrementAngle{ 0.f },
57 ellipsisEnabled{ true },
58 markupEnabled{ false },
59 isTextColorSet{ false }
62 std::string text; ///< The text to be rendered encoded in utf8.
64 std::string horizontalAlignment; ///< The horizontal alignment: one of {"begin", "center", "end"}.
65 std::string verticalAlignment; ///< The vertical alignment: one of {"top", "center", "bottom"}.
67 std::string fontFamily; ///< The font's family.
68 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"}.
69 std::string fontWidth; ///< The font's width: one of {"ultraCondensed", "extraCondensed", "condensed", "semiCondensed", "normal", "semiExpanded", "expanded", "extraExpanded", "ultraExpanded"}.
70 std::string fontSlant; ///< The font's slant. one of {"normal", "roman", "italic", "oblique"}
71 std::string layout; ///< The type of layout: one of {"singleLine", "multiLine", "circular"}
72 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.
74 Vector4 textColor; ///< The default text's color. Default is white.
76 float fontSize; ///< The font's size (in points).
78 unsigned int textWidth; ///< The width in pixels of the boundaries where the text is going to be laid-out.
79 unsigned int textHeight; ///< The height in pixels of the boundaries where the text is going to be laid-out.
81 unsigned int radius; ///< The radius in pixels of the circular text.
82 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°.
83 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.
85 bool ellipsisEnabled:1; ///< Whether the ellipsis layout option is enabled.
86 bool markupEnabled:1; ///< Whether the mark-up processor is enabled.
87 bool isTextColorSet:1; ///< Whether a default color has been set.
91 * @brief Struct with info of the embedded items layout.
93 struct DALI_TOOLKIT_API EmbeddedItemInfo
95 TextAbstraction::CharacterIndex characterIndex; ///< Index to the character within the string.
96 TextAbstraction::GlyphIndex glyphIndex; ///< Index to the glyph
97 Vector2 position; ///< The layout position within the buffer (top, left corner).
98 Size size; ///< The size within the buffer of the embedded item.
99 Size rotatedSize; ///< The rotated size within the buffer of the embedded item.
100 Degree angle; ///< Rotation angle of the pixel buffer in degrees.
101 TextAbstraction::ColorBlendingMode colorBlendingMode; ///< Whether the color of the image is multiplied by the color of the text.
105 * @brief Struct with the parameters needed to build a shadow for the given pixel buffer.
107 struct DALI_TOOLKIT_API ShadowParameters
109 Devel::PixelBuffer input; ///< The input pixel buffer used to create the shadow.
110 Vector4 textColor; ///< The color of the text.
111 Vector4 color; ///< The color of the shadow.
112 Vector2 offset; ///< The offset of the shadow.
113 bool blendShadow; ///< Whether to blend the shadow.
117 * @brief Renders text into a pixel buffer.
119 * @note: Can process a mark-up string.
120 * @note: It does the font selection, RTL reordering, shaping and layouting.
121 * @note: The width of the pixel buffer may be different to the given @e textWidth
122 * due to some padding pixels added.
124 * The text is laid-out for the given size @e (textWidth,textHeight).
125 * If the @e multiLineEnabled option is enabled, the text will wrap in lines.
126 * If the @e ellipsisEnabled option is enabled, the text will be ellided if
127 * there is no more space for new lines.
129 * It won't be rendered the parts of the text exceeding the boundaries of
130 * the given width and height.
132 * If the given @e textHeight is zero, a big enough pixel buffer will be created
133 * to render the full text.
135 * If the given @e textWidth is zero, the 'natural size' of the text will be
136 * used to create the pixel buffer to render the full text.
138 * If the radius is not zero, the text will be laid-out following a circular path.
139 * In that case the text is laid-out in a single line.
141 * If the mark-up string contains embedded items, the @p embeddedItemLayout vector
142 * contains the layout info of each embedded item.
144 * @param[in] textParameters The text and style options.
145 * @param[out] embeddedItemLayout The layout info of the embedded items.
147 * @return A pixel buffer with the text rendered on it.
149 DALI_TOOLKIT_API Devel::PixelBuffer Render( const RendererParameters& textParameters, Vector<EmbeddedItemInfo>& embeddedItemLayout );
152 * @brief Creates a shadow for the text given in the input pixel buffer.
154 * The function returns a RGBA8888 pixel buffer with the text and its shadow rendered on it.
156 * The pixel format of the @e input pixel buffer could be an A8 or an RGBA8888. If it's
157 * an A8 pixel buffer, it uses the given @e textColor to give color to the text. Otherwise
158 * it uses the color of the @e input pixel buffer.
160 * @param[in] shadowParameters The parameters needed to create the text's shadow.
162 * @return A pixel buffer with the text and the shadow rendered on it.
164 DALI_TOOLKIT_API Devel::PixelBuffer CreateShadow(const ShadowParameters& shadowParameters);
167 * @brief Converts a @p pixelBuffer with pixel format A8 to RGBA8888 using the given @p color.
169 * @note Does nothing if the @p pixelBuffer is not A8.
171 * @param[in] pixelBuffer The pixel buffer with pixel format A8
172 * @param[in] color The color used to convert to RGBA8888
173 * @param[in] multiplyByAlpha Whether to multiply the @p color with the alpha value of the @p pixel @p buffer.
175 * @return The pixel buffer converted to RGBA8888.
177 DALI_TOOLKIT_API Devel::PixelBuffer ConvertToRgba8888( Devel::PixelBuffer pixelBuffer, const Vector4& color, bool multiplyByAlpha );
180 * @brief Updates the @p dst pixel buffer with the data from @p src pixel buffer.
182 * @note Both pixel buffers must have the same pixel format. Does nothing if both pixel format are different.
183 * @note The function does nothing if the @p src pixel buffer doesn't fit into the @p dst pixel buffer.
185 * The @p src pixel buffer could be blended with the @p dst pixel buffer if @p blend is set to @e true.
187 * @param[in] src The pixel buffer from where the data is read.
188 * @param[in] dst The pixel buffer where the data is written..
189 * @param[in] x The top left corner's X within the destination pixel buffer.
190 * @param[in] y The top left corner's y within the destination pixel buffer.
191 * @param[in] blend Whether to blend the source pixel buffer with the destination pixel buffer as background.
193 DALI_TOOLKIT_API void UpdateBuffer( Devel::PixelBuffer src, Devel::PixelBuffer dst, unsigned int x, unsigned int y, bool blend);
195 } // namespace DevelText
197 } // namespace Toolkit
201 #endif // DALI_TOOLKIT_TEXT_UTILS_DEVEL_H