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