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-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
  26 namespace Dali
  27 {
  28
  29 namespace Toolkit
  30 {
  31
  32 namespace DevelText
  33 {
  34
  35 /**
  36  * @brief Struct with the text and style parameters to be rendered into a pixel buffer.
  37  */
  38 struct DALI_TOOLKIT_API RendererParameters
  39 {
  40   RendererParameters()
  41   : text{},
  42     horizontalAlignment{ "begin" },
  43     verticalAlignment{ "top" },
  44     fontFamily{},
  45     fontWeight{},
  46     fontWidth{},
  47     fontSlant{},
  48     layout{ "singleLine" },
  49     circularAlignment{ "begin" },
  50     textColor{ Color::WHITE },
  51     fontSize{ 0.f },
  52     textWidth{ 0u },
  53     textHeight{ 0u },
  54     radius{ 0u },
  55     beginAngle{ 0.f },
  56     incrementAngle{ 0.f },
  57     ellipsisEnabled{ true },
  58     markupEnabled{ false },
  59     isTextColorSet{ false }
  60   {}
  61
  62   std::string text;                ///< The text to be rendered encoded in utf8.
  63
  64   std::string horizontalAlignment; ///< The horizontal alignment: one of {"begin", "center", "end"}.
  65   std::string verticalAlignment;   ///< The vertical alignment: one of {"top", "center", "bottom"}.
  66
  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.
  73
  74   Vector4 textColor;               ///< The default text's color. Default is white.
  75
  76   float fontSize;           ///< The font's size (in points).
  77
  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.
  80
  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.
  84
  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.
  88 };
  89
  90 /**
  91  * @brief Struct with info of the embedded items layout.
  92  */
  93 struct DALI_TOOLKIT_API EmbeddedItemInfo
  94 {
  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.
 102 };
 103
 104 /**
 105 * @brief Struct with the parameters needed to build a shadow for the given pixel buffer.
 106 */
 107 struct DALI_TOOLKIT_API ShadowParameters
 108 {
 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.
 114 };
 115
 116 /**
 117  * @brief Renders text into a pixel buffer.
 118  *
 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.
 123  *
 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.
 128  *
 129  *  It won't be rendered the parts of the text exceeding the boundaries of
 130  *  the given width and height.
 131  *
 132  *  If the given @e textHeight is zero, a big enough pixel buffer will be created
 133  *  to render the full text.
 134  *
 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.
 137  *
 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.
 140  *
 141  * If the mark-up string contains embedded items, the @p embeddedItemLayout vector
 142  * contains the layout info of each embedded item.
 143  *
 144  * @param[in] textParameters The text and style options.
 145  * @param[out] embeddedItemLayout The layout info of the embedded items.
 146  *
 147  * @return A pixel buffer with the text rendered on it.
 148  */
 149 DALI_TOOLKIT_API Devel::PixelBuffer Render( const RendererParameters& textParameters, Vector<EmbeddedItemInfo>& embeddedItemLayout );
 150
 151 /**
 152  * @brief Creates a shadow for the text given in the input pixel buffer.
 153  *
 154  * The function returns a RGBA8888 pixel buffer with the text and its shadow rendered on it.
 155  *
 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.
 159  *
 160  * @param[in] shadowParameters The parameters needed to create the text's shadow.
 161  *
 162  * @return A pixel buffer with the text and the shadow rendered on it.
 163  */
 164 DALI_TOOLKIT_API Devel::PixelBuffer CreateShadow(const ShadowParameters& shadowParameters);
 165
 166 /**
 167  * @brief Converts a @p pixelBuffer with pixel format A8 to RGBA8888 using the given @p color.
 168  *
 169  * @note Does nothing if the @p pixelBuffer is not A8.
 170  *
 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.
 174  *
 175  * @return The pixel buffer converted to RGBA8888.
 176  */
 177 DALI_TOOLKIT_API Devel::PixelBuffer ConvertToRgba8888( Devel::PixelBuffer pixelBuffer, const Vector4& color, bool multiplyByAlpha );
 178
 179 /**
 180 * @brief Updates the @p dst pixel buffer with the data from @p src pixel buffer.
 181 *
 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.
 184 *
 185 * The @p src pixel buffer could be blended with the @p dst pixel buffer if @p blend is set to @e true.
 186 *
 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.
 192 */
 193 DALI_TOOLKIT_API void UpdateBuffer( Devel::PixelBuffer src, Devel::PixelBuffer dst, unsigned int x, unsigned int y, bool blend);
 194
 195 } // namespace DevelText
 196
 197 } // namespace Toolkit
 198
 199 } // namespace Dali
 200
 201 #endif // DALI_TOOLKIT_TEXT_UTILS_DEVEL_H