pango-1.0/pango/pango-glyph.h

0001 /* Pango
0002  * pango-glyph.h: Glyph storage
0003  *
0004  * Copyright (C) 2000 Red Hat Software
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Library General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Library General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Library General Public
0017  * License along with this library; if not, write to the
0018  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
0019  * Boston, MA 02111-1307, USA.
0020  */
0021
0022 #ifndef __PANGO_GLYPH_H__
0023 #define __PANGO_GLYPH_H__
0024
0025 #include <pango/pango-types.h>
0026 #include <pango/pango-item.h>
0027 #include <pango/pango-break.h>
0028
0029 G_BEGIN_DECLS
0030
0031 typedef struct _PangoGlyphGeometry PangoGlyphGeometry;
0032 typedef struct _PangoGlyphVisAttr PangoGlyphVisAttr;
0033 typedef struct _PangoGlyphInfo PangoGlyphInfo;
0034 typedef struct _PangoGlyphString PangoGlyphString;
0035
0036 /* 1024ths of a device unit */
0037 /**
0038  * PangoGlyphUnit:
0039  *
0040  * The `PangoGlyphUnit` type is used to store dimensions within
0041  * Pango.
0042  *
0043  * Dimensions are stored in 1/PANGO_SCALE of a device unit.
0044  * (A device unit might be a pixel for screen display, or
0045  * a point on a printer.) PANGO_SCALE is currently 1024, and
0046  * may change in the future (unlikely though), but you should not
0047  * depend on its exact value.
0048  *
0049  * The PANGO_PIXELS() macro can be used to convert from glyph units
0050  * into device units with correct rounding.
0051  */
0052 typedef gint32 PangoGlyphUnit;
0053
0054 /* Positioning information about a glyph
0055  */
0056 /**
0057  * PangoGlyphGeometry:
0058  * @width: the logical width to use for the the character.
0059  * @x_offset: horizontal offset from nominal character position.
0060  * @y_offset: vertical offset from nominal character position.
0061  *
0062  * The `PangoGlyphGeometry` structure contains width and positioning
0063  * information for a single glyph.
0064  *
0065  * Note that @width is not guaranteed to be the same as the glyph
0066  * extents. Kerning and other positioning applied during shaping will
0067  * affect both the @width and the @x_offset for the glyphs in the
0068  * glyph string that results from shaping.
0069  *
0070  * The information in this struct is intended for rendering the glyphs,
0071  * as follows:
0072  *
0073  * 1. Assume the current point is (x, y)
0074  * 2. Render the current glyph at (x + x_offset, y + y_offset),
0075  * 3. Advance the current point to (x + width, y)
0076  * 4. Render the next glyph
0077  */
0078 struct _PangoGlyphGeometry
0079 {
0080   PangoGlyphUnit width;
0081   PangoGlyphUnit x_offset;
0082   PangoGlyphUnit y_offset;
0083 };
0084
0085 /* Visual attributes of a glyph
0086  */
0087 /**
0088  * PangoGlyphVisAttr:
0089  * @is_cluster_start: set for the first logical glyph in each cluster.
0090  * @is_color: set if the the font will render this glyph with color. Since 1.50
0091  *
0092  * A `PangoGlyphVisAttr` structure communicates information between
0093  * the shaping and rendering phases.
0094  *
0095  * Currently, it contains cluster start and color information.
0096  * More attributes may be added in the future.
0097  *
0098  * Clusters are stored in visual order, within the cluster, glyphs
0099  * are always ordered in logical order, since visual order is meaningless;
0100  * that is, in Arabic text, accent glyphs follow the glyphs for the
0101  * base character.
0102  */
0103 struct _PangoGlyphVisAttr
0104 {
0105   guint is_cluster_start : 1;
0106   guint is_color         : 1;
0107 };
0108
0109 /* A single glyph
0110  */
0111 /**
0112  * PangoGlyphInfo:
0113  * @glyph: the glyph itself.
0114  * @geometry: the positional information about the glyph.
0115  * @attr: the visual attributes of the glyph.
0116  *
0117  * A `PangoGlyphInfo` structure represents a single glyph with
0118  * positioning information and visual attributes.
0119  */
0120 struct _PangoGlyphInfo
0121 {
0122   PangoGlyph    glyph;
0123   PangoGlyphGeometry geometry;
0124   PangoGlyphVisAttr  attr;
0125 };
0126
0127 /**
0128  * PangoGlyphString:
0129  * @num_glyphs: number of glyphs in this glyph string
0130  * @glyphs: (array length=num_glyphs): array of glyph information
0131  * @log_clusters: logical cluster info, indexed by the byte index
0132  *   within the text corresponding to the glyph string
0133  *
0134  * A `PangoGlyphString` is used to store strings of glyphs with geometry
0135  * and visual attribute information.
0136  *
0137  * The storage for the glyph information is owned by the structure
0138  * which simplifies memory management.
0139  */
0140 struct _PangoGlyphString {
0141   int num_glyphs;
0142
0143   PangoGlyphInfo *glyphs;
0144   int *log_clusters;
0145
0146   /*< private >*/
0147   int space;
0148 };
0149
0150 #define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
0151
0152 PANGO_AVAILABLE_IN_ALL
0153 GType                   pango_glyph_string_get_type             (void) G_GNUC_CONST;
0154
0155 PANGO_AVAILABLE_IN_ALL
0156 PangoGlyphString *      pango_glyph_string_new                  (void);
0157 PANGO_AVAILABLE_IN_ALL
0158 void                    pango_glyph_string_set_size             (PangoGlyphString    *string,
0159                                                                  int                  new_len);
0160
0161 PANGO_AVAILABLE_IN_ALL
0162 PangoGlyphString *      pango_glyph_string_copy                 (PangoGlyphString    *string);
0163 PANGO_AVAILABLE_IN_ALL
0164 void                    pango_glyph_string_free                 (PangoGlyphString    *string);
0165
0166 PANGO_AVAILABLE_IN_ALL
0167 void                    pango_glyph_string_extents              (PangoGlyphString    *glyphs,
0168                                                                  PangoFont           *font,
0169                                                                  PangoRectangle      *ink_rect,
0170                                                                  PangoRectangle      *logical_rect);
0171 PANGO_AVAILABLE_IN_1_14
0172 int                     pango_glyph_string_get_width            (PangoGlyphString    *glyphs);
0173
0174 PANGO_AVAILABLE_IN_ALL
0175 void                    pango_glyph_string_extents_range        (PangoGlyphString    *glyphs,
0176                                                                  int                  start,
0177                                                                  int                  end,
0178                                                                  PangoFont           *font,
0179                                                                  PangoRectangle      *ink_rect,
0180                                                                  PangoRectangle      *logical_rect);
0181
0182 PANGO_AVAILABLE_IN_ALL
0183 void                    pango_glyph_string_get_logical_widths   (PangoGlyphString    *glyphs,
0184                                                                  const char          *text,
0185                                                                  int                  length,
0186                                                                  int                  embedding_level,
0187                                                                  int                 *logical_widths);
0188
0189 PANGO_AVAILABLE_IN_ALL
0190 void                    pango_glyph_string_index_to_x           (PangoGlyphString    *glyphs,
0191                                                                  const char          *text,
0192                                                                  int                  length,
0193                                                                  PangoAnalysis       *analysis,
0194                                                                  int                  index_,
0195                                                                  gboolean             trailing,
0196                                                                  int                 *x_pos);
0197 PANGO_AVAILABLE_IN_ALL
0198 void                    pango_glyph_string_x_to_index           (PangoGlyphString    *glyphs,
0199                                                                  const char          *text,
0200                                                                  int                  length,
0201                                                                  PangoAnalysis       *analysis,
0202                                                                  int                  x_pos,
0203                                                                  int                 *index_,
0204                                                                  int                 *trailing);
0205
0206 PANGO_AVAILABLE_IN_1_50
0207 void                    pango_glyph_string_index_to_x_full      (PangoGlyphString    *glyphs,
0208                                                                  const char          *text,
0209                                                                  int                  length,
0210                                                                  PangoAnalysis       *analysis,
0211                                                                  PangoLogAttr        *attrs,
0212                                                                  int                  index_,
0213                                                                  gboolean             trailing,
0214                                                                  int                 *x_pos);
0215
0216 /* Shaping */
0217
0218 /**
0219  * PangoShapeFlags:
0220  * @PANGO_SHAPE_NONE: Default value
0221  * @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions and widths to whole device units
0222  *   This option should be set if the target renderer can't do subpixel positioning of glyphs
0223  *
0224  * Flags influencing the shaping process.
0225  *
0226  * `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags].
0227  *
0228  * Since: 1.44
0229  */
0230 typedef enum {
0231   PANGO_SHAPE_NONE            = 0,
0232   PANGO_SHAPE_ROUND_POSITIONS = 1 << 0,
0233 } PangoShapeFlags;
0234
0235 PANGO_AVAILABLE_IN_ALL
0236 void                    pango_shape                             (const char          *text,
0237                                                                  int                  length,
0238                                                                  const PangoAnalysis *analysis,
0239                                                                  PangoGlyphString    *glyphs);
0240
0241 PANGO_AVAILABLE_IN_1_32
0242 void                    pango_shape_full                        (const char          *item_text,
0243                                                                  int                  item_length,
0244                                                                  const char          *paragraph_text,
0245                                                                  int                  paragraph_length,
0246                                                                  const PangoAnalysis *analysis,
0247                                                                  PangoGlyphString    *glyphs);
0248
0249 PANGO_AVAILABLE_IN_1_44
0250 void                    pango_shape_with_flags                  (const char          *item_text,
0251                                                                  int                  item_length,
0252                                                                  const char          *paragraph_text,
0253                                                                  int                  paragraph_length,
0254                                                                  const PangoAnalysis *analysis,
0255                                                                  PangoGlyphString    *glyphs,
0256                                                                  PangoShapeFlags      flags);
0257
0258
0259 PANGO_AVAILABLE_IN_1_50
0260 void                    pango_shape_item                        (PangoItem           *item,
0261                                                                  const char          *paragraph_text,
0262                                                                  int                  paragraph_length,
0263                                                                  PangoLogAttr        *log_attrs,
0264                                                                  PangoGlyphString    *glyphs,
0265                                                                  PangoShapeFlags      flags);
0266
0267
0268 G_END_DECLS
0269
0270 #endif /* __PANGO_GLYPH_H__ */