diff options
Diffstat (limited to 'trunk/docs/tmpl/glyphs.sgml')
| -rw-r--r-- | trunk/docs/tmpl/glyphs.sgml | 555 |
1 files changed, 555 insertions, 0 deletions
diff --git a/trunk/docs/tmpl/glyphs.sgml b/trunk/docs/tmpl/glyphs.sgml new file mode 100644 index 00000000..44dff0db --- /dev/null +++ b/trunk/docs/tmpl/glyphs.sgml @@ -0,0 +1,555 @@ +<!-- ##### SECTION Title ##### --> +Glyph Storage + +<!-- ##### SECTION Short_Description ##### --> +Structures for storing information about glyphs + +<!-- ##### SECTION Long_Description ##### --> +<para> +pango_shape() produces a string of glyphs which +can be measured or drawn to the screen. The following +structures are used to store information about +glyphs. +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### MACRO PANGO_SCALE ##### --> +<para> +The %PANGO_SCALE macro represents the scale between dimensions used +for Pango distances and device units. (The definition of device +units is dependent on the output device; it will typically be pixels +for a screen, and points for a printer.) %PANGO_SCALE is currently +1024, but this may be changed in the future. +</para> +<para> +When setting font sizes, device units are always considered to be +points (as in "12 point font"), rather than pixels. +</para> + + + +<!-- ##### MACRO PANGO_PIXELS ##### --> +<para> +Converts a dimension to device units by rounding. +</para> + +@d: a dimension in Pango units. +@Returns: rounded dimension in device units. + + +<!-- ##### MACRO PANGO_PIXELS_FLOOR ##### --> +<para> +Converts a dimension to device units by flooring. +</para> + +@d: a dimension in Pango units. +@Returns: floored dimension in device units. +@Since: 1.14 + + +<!-- ##### MACRO PANGO_PIXELS_CEIL ##### --> +<para> +Converts a dimension to device units by ceiling. +</para> + +@d: a dimension in Pango units. +@Returns: ceiled dimension in device units. +@Since: 1.14 + + +<!-- ##### MACRO PANGO_UNITS_ROUND ##### --> +<para> +Rounds a dimension to whole device units, but does not +convert it to device units. +</para> + +@d: a dimension in Pango units. +@Returns: rounded dimension in Pango units. +@Since: 1.18 + + +<!-- ##### FUNCTION pango_units_to_double ##### --> +<para> + +</para> + +@i: +@Returns: + + +<!-- ##### FUNCTION pango_units_from_double ##### --> +<para> + +</para> + +@d: +@Returns: + + +<!-- ##### STRUCT PangoRectangle ##### --> +<para> +The #PangoRectangle structure represents a rectangle. It is frequently +used to represent the logical or ink extents of a single glyph or section +of text. (See, for instance, pango_font_get_glyph_extents()) +</para> + +@x: X coordinate of the left side of the rectangle. +@y: Y coordinate of the the top side of the rectangle. +@width: width of the rectangle. +@height: height of the rectangle. + +<!-- ##### MACRO PANGO_ASCENT ##### --> +<para> +Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle +representing glyph extents. The ascent is the distance from the +baseline to the highest point of the character. This is positive if the +glyph ascends above the baseline. +</para> + +@rect: a #PangoRectangle + + +<!-- ##### MACRO PANGO_DESCENT ##### --> +<para> +Extracts the <firstterm>descent</firstterm> from a #PangoRectangle +representing glyph extents. The descent is the distance from the +baseline to the lowest point of the character. This is positive if the +glyph descends below the baseline. +</para> + +@rect: a #PangoRectangle + + +<!-- ##### MACRO PANGO_LBEARING ##### --> +<para> +Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle +representing glyph extents. The left bearing is the distance from the +horizontal origin to the farthest left point of the character. +This is positive for characters drawn completely to the right of the +glyph origin. +</para> + +@rect: a #PangoRectangle + + +<!-- ##### MACRO PANGO_RBEARING ##### --> +<para> +Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle +representing glyph extents. The right bearing is the distance from the +horizontal origin to the farthest right point of the character. +This is positive except for characters drawn completely to the left of the +horizontal origin. +</para> + +@rect: a #PangoRectangle + + +<!-- ##### FUNCTION pango_extents_to_pixels ##### --> +<para> + +</para> + +@ink_rect: +@logical_rect: + + +<!-- ##### STRUCT PangoMatrix ##### --> +<para> + +</para> + +@xx: +@xy: +@yx: +@yy: +@x0: +@y0: + +<!-- ##### MACRO PANGO_TYPE_MATRIX ##### --> +<para> + +</para> + + + +<!-- ##### MACRO PANGO_MATRIX_INIT ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION pango_matrix_copy ##### --> +<para> + +</para> + +@matrix: +@Returns: + + +<!-- ##### FUNCTION pango_matrix_free ##### --> +<para> + +</para> + +@matrix: + + +<!-- ##### FUNCTION pango_matrix_translate ##### --> +<para> + +</para> + +@matrix: +@tx: +@ty: + + +<!-- ##### FUNCTION pango_matrix_scale ##### --> +<para> + +</para> + +@matrix: +@scale_x: +@scale_y: + + +<!-- ##### FUNCTION pango_matrix_rotate ##### --> +<para> + +</para> + +@matrix: +@degrees: + + +<!-- ##### FUNCTION pango_matrix_concat ##### --> +<para> + +</para> + +@matrix: +@new_matrix: + + +<!-- ##### FUNCTION pango_matrix_transform_point ##### --> +<para> + +</para> + +@matrix: +@x: +@y: + + +<!-- ##### FUNCTION pango_matrix_transform_distance ##### --> +<para> + +</para> + +@matrix: +@dx: +@dy: + + +<!-- ##### FUNCTION pango_matrix_transform_rectangle ##### --> +<para> + +</para> + +@matrix: +@rect: + + +<!-- ##### FUNCTION pango_matrix_transform_pixel_rectangle ##### --> +<para> + +</para> + +@matrix: +@rect: + + +<!-- ##### FUNCTION pango_matrix_get_font_scale_factor ##### --> +<para> + +</para> + +@matrix: +@Returns: + + +<!-- ##### TYPEDEF PangoGlyph ##### --> +<para> +A #PangoGlyph represents a single glyph in the output form of a string. +</para> + + +<!-- ##### MACRO PANGO_GLYPH_EMPTY ##### --> +<para> +The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a +special meaning, which is a zero-width empty glyph. This is useful for +example in shaper modules, to use as the glyph for various zero-width +Unicode characters (those passing pango_is_zero_width()). +</para> + + + +<!-- ##### MACRO PANGO_GLYPH_UNKNOWN_FLAG ##### --> +<para> +The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to +a #gunichar value of a valid Unicode character, to produce a #PangoGlyph +value, representing an unknown-character glyph for the respective #gunichar. +</para> + + + +<!-- ##### MACRO PANGO_GET_UNKNOWN_GLYPH ##### --> +<para> +Returns a #PangoGlyph value that means no glyph was found for @wc. +The way this unknown glyphs are rendered is backend specific. For example, +a box with the hexadecimal Unicode code-point of the character written in it +is what is done in the most common backends. +</para> + +@wc: a Unicode character + + +<!-- ##### STRUCT PangoGlyphInfo ##### --> +<para> +The #PangoGlyphInfo structure represents a single glyph together with +positioning information and visual attributes. +It contains the following fields. +</para> + +@glyph: the glyph itself. +@geometry: the positional information about the glyph. +@attr: the visual attributes of the glyph. + +<!-- ##### STRUCT PangoGlyphGeometry ##### --> +<para> +The #PangoGlyphGeometry structure contains width and positioning +information for a single glyph. +</para> + +@width: the logical width to use for the the character. +@x_offset: horizontal offset from nominal character position. +@y_offset: vertical offset from nominal character position. + +<!-- ##### TYPEDEF PangoGlyphUnit ##### --> +<para> +The #PangoGlyphUnit type is used to store dimensions within +Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit. +(A device unit might be a pixel for screen display, or +a point on a printer.) %PANGO_SCALE is currently 1024, and +may change in the future (unlikely though), but you should not +depend on its exact value. The PANGO_PIXELS() macro can be used +to convert from glyph units into device units with correct rounding. +</para> + + +<!-- ##### STRUCT PangoGlyphVisAttr ##### --> +<para> +The PangoGlyphVisAttr is used to communicate information between +the shaping phase and the rendering phase. More attributes may be +added in the future. +</para> + +@is_cluster_start: set for the first logical glyph in each cluster. (Clusters + are stored in visual order, within the cluster, glyphs + are always ordered in logical order, since visual + order is meaningless; that is, in Arabic text, accent glyphs + follow the glyphs for the base character.) + +<!-- ##### STRUCT PangoGlyphString ##### --> +<para> +The #PangoGlyphString structure is used to store strings +of glyphs with geometry and visual attribute information. +The storage for the glyph information is owned +by the structure which simplifies memory management. +</para> + +@num_glyphs: the number of glyphs in the string. +@glyphs: an array of #PangoGlyphInfo structures of length <structfield>num_glyphs</structfield>. +@log_clusters: for each glyph, byte index of the starting character for the +cluster. The indices are relative to the start of the text +corresponding to the PangoGlyphString. + +<!-- ##### STRUCT PangoGlyphItem ##### --> +<para> +A #PangoGlyphItem is a pair of a #PangoItem and the glyphs +resulting from shaping the text corresponding to an item. +As an example of the usage of #PangoGlyphItem, the results +of shaping text with #PangoLayout is a list of #PangoLayoutLine, +each of which contains a list of #PangoGlyphItem. +</para> + +@item: a #PangoItem structure that provides information + about a segment of text. +@glyphs: the glyphs obtained by shaping the text + corresponding to @item. + +<!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### --> +<para> +The #GObject type for #PangoGlyphString. +</para> + + + +<!-- ##### FUNCTION pango_glyph_string_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION pango_glyph_string_copy ##### --> +<para> + +</para> + +@string: +@Returns: + + +<!-- ##### FUNCTION pango_glyph_string_set_size ##### --> +<para> + +</para> + +@string: +@new_len: + + +<!-- ##### FUNCTION pango_glyph_string_free ##### --> +<para> + +</para> + +@string: + + +<!-- ##### FUNCTION pango_glyph_string_extents ##### --> +<para> + +</para> + +@glyphs: +@font: +@ink_rect: +@logical_rect: + + +<!-- ##### FUNCTION pango_glyph_string_extents_range ##### --> +<para> + +</para> + +@glyphs: +@start: +@end: +@font: +@ink_rect: +@logical_rect: + + +<!-- ##### FUNCTION pango_glyph_string_get_width ##### --> +<para> + +</para> + +@glyphs: +@Returns: + + +<!-- ##### FUNCTION pango_glyph_string_index_to_x ##### --> +<para> + +</para> + +@glyphs: +@text: +@length: +@analysis: +@index_: +@trailing: +@x_pos: + + +<!-- ##### FUNCTION pango_glyph_string_x_to_index ##### --> +<para> + +</para> + +@glyphs: +@text: +@length: +@analysis: +@x_pos: +@index_: +@trailing: + + +<!-- ##### FUNCTION pango_glyph_string_get_logical_widths ##### --> +<para> + +</para> + +@glyphs: +@text: +@length: +@embedding_level: +@logical_widths: + + +<!-- ##### FUNCTION pango_glyph_item_split ##### --> +<para> + +</para> + +@orig: +@text: +@split_index: +@Returns: + + +<!-- ##### FUNCTION pango_glyph_item_apply_attrs ##### --> +<para> + +</para> + +@glyph_item: +@text: +@list: +@Returns: + + +<!-- ##### FUNCTION pango_glyph_item_letter_space ##### --> +<para> + +</para> + +@glyph_item: +@text: +@log_attrs: +@letter_spacing: + + +<!-- ##### FUNCTION pango_glyph_item_free ##### --> +<para> + +</para> + +@glyph_item: + + |