"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "pango-1.20.5/docs/tmpl/glyphs.sgml" of archive pango-1.20.5.tar.gz:

As a special service "SfR Fresh" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field. 
    1 <!-- ##### SECTION Title ##### -->
    2 Glyph Storage
    3 
    4 <!-- ##### SECTION Short_Description ##### -->
    5 Structures for storing information about glyphs
    6 
    7 <!-- ##### SECTION Long_Description ##### -->
    8 <para>
    9 pango_shape() produces a string of glyphs which
   10 can be measured or drawn to the screen. The following
   11 structures are used to store information about
   12 glyphs.
   13 </para>
   14 
   15 <!-- ##### SECTION See_Also ##### -->
   16 <para>
   17 
   18 </para>
   19 
   20 <!-- ##### SECTION Stability_Level ##### -->
   21 
   22 
   23 <!-- ##### MACRO PANGO_SCALE ##### -->
   24 <para>
   25 The %PANGO_SCALE macro represents the scale between dimensions used
   26 for Pango distances and device units. (The definition of device
   27 units is dependent on the output device; it will typically be pixels
   28 for a screen, and points for a printer.) %PANGO_SCALE is currently
   29 1024, but this may be changed in the future.
   30 </para>
   31 <para>
   32 When setting font sizes, device units are always considered to be
   33 points (as in "12 point font"), rather than pixels.
   34 </para>
   35 
   36 
   37 
   38 <!-- ##### MACRO PANGO_PIXELS ##### -->
   39 <para>
   40 Converts a dimension to device units by rounding.
   41 </para>
   42 
   43 @d: a dimension in Pango units.
   44 @Returns: rounded dimension in device units.
   45 
   46 
   47 <!-- ##### MACRO PANGO_PIXELS_FLOOR ##### -->
   48 <para>
   49 Converts a dimension to device units by flooring.
   50 </para>
   51 
   52 @d: a dimension in Pango units.
   53 @Returns: floored dimension in device units.
   54 @Since: 1.14
   55 
   56 
   57 <!-- ##### MACRO PANGO_PIXELS_CEIL ##### -->
   58 <para>
   59 Converts a dimension to device units by ceiling.
   60 </para>
   61 
   62 @d: a dimension in Pango units.
   63 @Returns: ceiled dimension in device units.
   64 @Since: 1.14
   65 
   66 
   67 <!-- ##### MACRO PANGO_UNITS_ROUND ##### -->
   68 <para>
   69 Rounds a dimension to whole device units, but does not
   70 convert it to device units.
   71 </para>
   72 
   73 @d: a dimension in Pango units.
   74 @Returns: rounded dimension in Pango units.
   75 @Since: 1.18
   76 
   77 
   78 <!-- ##### FUNCTION pango_units_to_double ##### -->
   79 <para>
   80 
   81 </para>
   82 
   83 @i:
   84 @Returns:
   85 
   86 
   87 <!-- ##### FUNCTION pango_units_from_double ##### -->
   88 <para>
   89 
   90 </para>
   91 
   92 @d:
   93 @Returns:
   94 
   95 
   96 <!-- ##### STRUCT PangoRectangle ##### -->
   97 <para>
   98 The #PangoRectangle structure represents a rectangle. It is frequently
   99 used to represent the logical or ink extents of a single glyph or section
  100 of text. (See, for instance, pango_font_get_glyph_extents())
  101 </para>
  102 
  103 @x: X coordinate of the left side of the rectangle.
  104 @y: Y coordinate of the the top side of the rectangle.
  105 @width: width of the rectangle.
  106 @height: height of the rectangle.
  107 
  108 <!-- ##### MACRO PANGO_ASCENT ##### -->
  109 <para>
  110 Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle
  111 representing glyph extents. The ascent is the distance from the
  112 baseline to the highest point of the character. This is positive if the
  113 glyph ascends above the baseline.
  114 </para>
  115 
  116 @rect: a #PangoRectangle
  117 
  118 
  119 <!-- ##### MACRO PANGO_DESCENT ##### -->
  120 <para>
  121 Extracts the <firstterm>descent</firstterm> from a #PangoRectangle
  122 representing glyph extents. The descent is the distance from the
  123 baseline to the lowest point of the character. This is positive if the
  124 glyph descends below the baseline.
  125 </para>
  126 
  127 @rect: a #PangoRectangle
  128 
  129 
  130 <!-- ##### MACRO PANGO_LBEARING ##### -->
  131 <para>
  132 Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle
  133 representing glyph extents. The left bearing is the distance from the
  134 horizontal origin to the farthest left point of the character.
  135 This is positive for characters drawn completely to the right of the
  136 glyph origin.
  137 </para>
  138 
  139 @rect: a #PangoRectangle
  140 
  141 
  142 <!-- ##### MACRO PANGO_RBEARING ##### -->
  143 <para>
  144 Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle
  145 representing glyph extents. The right bearing is the distance from the
  146 horizontal origin to the farthest right point of the character.
  147 This is positive except for characters drawn completely to the left of the
  148 horizontal origin.
  149 </para>
  150 
  151 @rect: a #PangoRectangle
  152 
  153 
  154 <!-- ##### FUNCTION pango_extents_to_pixels ##### -->
  155 <para>
  156 
  157 </para>
  158 
  159 @inclusive:
  160 @nearest:
  161 
  162 
  163 <!-- ##### STRUCT PangoMatrix ##### -->
  164 <para>
  165 
  166 </para>
  167 
  168 @xx:
  169 @xy:
  170 @yx:
  171 @yy:
  172 @x0:
  173 @y0:
  174 
  175 <!-- ##### MACRO PANGO_TYPE_MATRIX ##### -->
  176 <para>
  177 
  178 </para>
  179 
  180 
  181 
  182 <!-- ##### MACRO PANGO_MATRIX_INIT ##### -->
  183 <para>
  184 
  185 </para>
  186 
  187 
  188 
  189 <!-- ##### FUNCTION pango_matrix_copy ##### -->
  190 <para>
  191 
  192 </para>
  193 
  194 @matrix:
  195 @Returns:
  196 
  197 
  198 <!-- ##### FUNCTION pango_matrix_free ##### -->
  199 <para>
  200 
  201 </para>
  202 
  203 @matrix:
  204 
  205 
  206 <!-- ##### FUNCTION pango_matrix_translate ##### -->
  207 <para>
  208 
  209 </para>
  210 
  211 @matrix:
  212 @tx:
  213 @ty:
  214 
  215 
  216 <!-- ##### FUNCTION pango_matrix_scale ##### -->
  217 <para>
  218 
  219 </para>
  220 
  221 @matrix:
  222 @scale_x:
  223 @scale_y:
  224 
  225 
  226 <!-- ##### FUNCTION pango_matrix_rotate ##### -->
  227 <para>
  228 
  229 </para>
  230 
  231 @matrix:
  232 @degrees:
  233 
  234 
  235 <!-- ##### FUNCTION pango_matrix_concat ##### -->
  236 <para>
  237 
  238 </para>
  239 
  240 @matrix:
  241 @new_matrix:
  242 
  243 
  244 <!-- ##### FUNCTION pango_matrix_transform_point ##### -->
  245 <para>
  246 
  247 </para>
  248 
  249 @matrix:
  250 @x:
  251 @y:
  252 
  253 
  254 <!-- ##### FUNCTION pango_matrix_transform_distance ##### -->
  255 <para>
  256 
  257 </para>
  258 
  259 @matrix:
  260 @dx:
  261 @dy:
  262 
  263 
  264 <!-- ##### FUNCTION pango_matrix_transform_rectangle ##### -->
  265 <para>
  266 
  267 </para>
  268 
  269 @matrix:
  270 @rect:
  271 
  272 
  273 <!-- ##### FUNCTION pango_matrix_transform_pixel_rectangle ##### -->
  274 <para>
  275 
  276 </para>
  277 
  278 @matrix:
  279 @rect:
  280 
  281 
  282 <!-- ##### FUNCTION pango_matrix_get_font_scale_factor ##### -->
  283 <para>
  284 
  285 </para>
  286 
  287 @matrix:
  288 @Returns:
  289 
  290 
  291 <!-- ##### TYPEDEF PangoGlyph ##### -->
  292 <para>
  293 A #PangoGlyph represents a single glyph in the output form of a string.
  294 </para>
  295 
  296 
  297 <!-- ##### MACRO PANGO_GLYPH_EMPTY ##### -->
  298 <para>
  299 The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
  300 special meaning, which is a zero-width empty glyph.  This is useful for
  301 example in shaper modules, to use as the glyph for various zero-width
  302 Unicode characters (those passing pango_is_zero_width()).
  303 </para>
  304 
  305 
  306 
  307 <!-- ##### MACRO PANGO_GLYPH_INVALID_INPUT ##### -->
  308 <para>
  309 The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
  310 special meaning of invalid input.  #PangoLayout produces one such glyph
  311 per invalid input UTF-8 byte and such a glyph is rendered as a crossed
  312 box.
  313 
  314 Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG
  315 on.
  316 </para>
  317 
  318 @Since: 1.20
  319 
  320 
  321 <!-- ##### MACRO PANGO_GLYPH_UNKNOWN_FLAG ##### -->
  322 <para>
  323 The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
  324 a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
  325 value, representing an unknown-character glyph for the respective #gunichar.
  326 </para>
  327 
  328 
  329 
  330 <!-- ##### MACRO PANGO_GET_UNKNOWN_GLYPH ##### -->
  331 <para>
  332 Returns a #PangoGlyph value that means no glyph was found for @wc.
  333 The way this unknown glyphs are rendered is backend specific.  For example,
  334 a box with the hexadecimal Unicode code-point of the character written in it
  335 is what is done in the most common backends.
  336 </para>
  337 
  338 @wc: a Unicode character
  339 
  340 
  341 <!-- ##### STRUCT PangoGlyphInfo ##### -->
  342 <para>
  343 The #PangoGlyphInfo structure represents a single glyph together with
  344 positioning information and visual attributes.
  345 It contains the following fields.
  346 </para>
  347 
  348 @glyph: the glyph itself.
  349 @geometry: the positional information about the glyph.
  350 @attr: the visual attributes of the glyph.
  351 
  352 <!-- ##### STRUCT PangoGlyphGeometry ##### -->
  353 <para>
  354 The #PangoGlyphGeometry structure contains width and positioning
  355 information for a single glyph.
  356 </para>
  357 
  358 @width: the logical width to use for the the character.
  359 @x_offset: horizontal offset from nominal character position.
  360 @y_offset: vertical offset from nominal character position.
  361 
  362 <!-- ##### TYPEDEF PangoGlyphUnit ##### -->
  363 <para>
  364 The #PangoGlyphUnit type is used to store dimensions within
  365 Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
  366 (A device unit might be a pixel for screen display, or
  367 a point on a printer.) %PANGO_SCALE is currently 1024, and
  368 may change in the future (unlikely though), but you should not
  369 depend on its exact value. The PANGO_PIXELS() macro can be used
  370 to convert from glyph units into device units with correct rounding.
  371 </para>
  372 
  373 
  374 <!-- ##### STRUCT PangoGlyphVisAttr ##### -->
  375 <para>
  376 The PangoGlyphVisAttr is used to communicate information between
  377 the shaping phase and the rendering phase.  More attributes may be
  378 added in the future.
  379 </para>
  380 
  381 @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
  382 		   are stored in visual order, within the cluster, glyphs
  383 		   are always ordered in logical order, since visual
  384 		   order is meaningless; that is, in Arabic text, accent glyphs
  385 		   follow the glyphs for the base character.)
  386 
  387 <!-- ##### STRUCT PangoGlyphString ##### -->
  388 <para>
  389 The #PangoGlyphString structure is used to store strings
  390 of glyphs with geometry and visual attribute information.
  391 The storage for the glyph information is owned
  392 by the structure which simplifies memory management.
  393 </para>
  394 
  395 @num_glyphs: the number of glyphs in the string.
  396 @glyphs: an array of #PangoGlyphInfo structures of length <structfield>num_glyphs</structfield>.
  397 @log_clusters: for each glyph, byte index of the starting character for the
  398 cluster. The indices are relative to the start of the text
  399 corresponding to the PangoGlyphString.
  400 
  401 <!-- ##### STRUCT PangoGlyphItem ##### -->
  402 <para>
  403 A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
  404 resulting from shaping the text corresponding to an item.
  405 As an example of the usage of #PangoGlyphItem, the results
  406 of shaping text with #PangoLayout is a list of #PangoLayoutLine,
  407 each of which contains a list of #PangoGlyphItem.
  408 </para>
  409 
  410 @item: a #PangoItem structure that provides information
  411        about a segment of text.
  412 @glyphs: the glyphs obtained by shaping the text
  413          corresponding to @item.
  414 
  415 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
  416 <para>
  417 The #GObject type for #PangoGlyphString.
  418 </para>
  419 
  420 
  421 
  422 <!-- ##### FUNCTION pango_glyph_string_new ##### -->
  423 <para>
  424 
  425 </para>
  426 
  427 @Returns:
  428 
  429 
  430 <!-- ##### FUNCTION pango_glyph_string_copy ##### -->
  431 <para>
  432 
  433 </para>
  434 
  435 @string:
  436 @Returns:
  437 
  438 
  439 <!-- ##### FUNCTION pango_glyph_string_set_size ##### -->
  440 <para>
  441 
  442 </para>
  443 
  444 @string:
  445 @new_len:
  446 
  447 
  448 <!-- ##### FUNCTION pango_glyph_string_free ##### -->
  449 <para>
  450 
  451 </para>
  452 
  453 @string:
  454 
  455 
  456 <!-- ##### FUNCTION pango_glyph_string_extents ##### -->
  457 <para>
  458 
  459 </para>
  460 
  461 @glyphs:
  462 @font:
  463 @ink_rect:
  464 @logical_rect:
  465 
  466 
  467 <!-- ##### FUNCTION pango_glyph_string_extents_range ##### -->
  468 <para>
  469 
  470 </para>
  471 
  472 @glyphs:
  473 @start:
  474 @end:
  475 @font:
  476 @ink_rect:
  477 @logical_rect:
  478 
  479 
  480 <!-- ##### FUNCTION pango_glyph_string_get_width ##### -->
  481 <para>
  482 
  483 </para>
  484 
  485 @glyphs:
  486 @Returns:
  487 
  488 
  489 <!-- ##### FUNCTION pango_glyph_string_index_to_x ##### -->
  490 <para>
  491 
  492 </para>
  493 
  494 @glyphs:
  495 @text:
  496 @length:
  497 @analysis:
  498 @index_:
  499 @trailing:
  500 @x_pos:
  501 
  502 
  503 <!-- ##### FUNCTION pango_glyph_string_x_to_index ##### -->
  504 <para>
  505 
  506 </para>
  507 
  508 @glyphs:
  509 @text:
  510 @length:
  511 @analysis:
  512 @x_pos:
  513 @index_:
  514 @trailing:
  515 
  516 
  517 <!-- ##### FUNCTION pango_glyph_string_get_logical_widths ##### -->
  518 <para>
  519 
  520 </para>
  521 
  522 @glyphs:
  523 @text:
  524 @length:
  525 @embedding_level:
  526 @logical_widths:
  527 
  528 
  529 <!-- ##### MACRO PANGO_TYPE_GLYPH_ITEM ##### -->
  530 <para>
  531 The #GObject type for #PangoGlyphItem.
  532 </para>
  533 
  534 @Since: 1.20
  535 
  536 
  537 <!-- ##### FUNCTION pango_glyph_item_split ##### -->
  538 <para>
  539 
  540 </para>
  541 
  542 @orig:
  543 @text:
  544 @split_index:
  545 @Returns:
  546 
  547 
  548 <!-- ##### FUNCTION pango_glyph_item_apply_attrs ##### -->
  549 <para>
  550 
  551 </para>
  552 
  553 @glyph_item:
  554 @text:
  555 @list:
  556 @Returns:
  557 
  558 
  559 <!-- ##### FUNCTION pango_glyph_item_letter_space ##### -->
  560 <para>
  561 
  562 </para>
  563 
  564 @glyph_item:
  565 @text:
  566 @log_attrs:
  567 @letter_spacing:
  568 
  569 
  570 <!-- ##### FUNCTION pango_glyph_item_copy ##### -->
  571 <para>
  572 
  573 </para>
  574 
  575 @orig:
  576 @Returns:
  577 
  578 
  579 <!-- ##### FUNCTION pango_glyph_item_free ##### -->
  580 <para>
  581 
  582 </para>
  583 
  584 @glyph_item:
  585 
  586