diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 8 | ||||
| -rw-r--r-- | docs/pango-docs.sgml | 2 | ||||
| -rw-r--r-- | docs/pango-sections.txt | 22 | ||||
| -rw-r--r-- | docs/pango.types | 3 | ||||
| -rw-r--r-- | docs/rotated-text.png | bin | 0 -> 23044 bytes | |||
| -rw-r--r-- | docs/tmpl/pango-renderer.sgml | 4 | ||||
| -rw-r--r-- | docs/tmpl/pangocairo.sgml | 248 | ||||
| -rw-r--r-- | docs/tmpl/pangofc-fontmap.sgml | 1 | ||||
| -rw-r--r-- | docs/tmpl/text-attributes.sgml | 14 | ||||
| -rw-r--r-- | docs/tmpl/xft-fonts.sgml | 2 |
10 files changed, 296 insertions, 8 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index e04dfaed..6d55e7f3 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -25,6 +25,8 @@ IGNORE_HFILES= \ module-defs.h \ opentype \ modules.h \ + pangocairo-private.h \ + pangocairo-fc.h \ pango-engine-private.h \ pango-impl-utils.h \ pango-glyph-item-private.h \ @@ -55,6 +57,9 @@ INCLUDES = \ GTKDOC_LIBS = \ $(top_builddir)/pango/libpangoxft-1.0.la +if HAVE_CAIRO +GTKDOC_LIBS += $(top_builddir)/pango/libpangocairo-1.0.la +endif # Extra options to supply to gtkdoc-mkdb MKDB_OPTIONS=--sgml-mode --output-format=xml @@ -68,7 +73,8 @@ content_files = \ # Images to copy into HTML directory HTML_IMAGES = \ - layout.gif + layout.gif \ + rotated-text.png # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS= diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml index 21498e6e..aa026ff3 100644 --- a/docs/pango-docs.sgml +++ b/docs/pango-docs.sgml @@ -17,6 +17,7 @@ <!ENTITY pango-Win32-Fonts-and-Rendering SYSTEM "xml/win32-fonts.xml"> <!ENTITY pango-FreeType-Fonts-and-Rendering SYSTEM "xml/freetype-fonts.xml"> <!ENTITY pango-Xft-Fonts-and-Rendering SYSTEM "xml/xft-fonts.xml"> +<!ENTITY pangocairo SYSTEM "xml/pangocairo.xml"> <!ENTITY PangoFcFontMap SYSTEM "xml/pangofc-fontmap.xml"> <!ENTITY PangoFcFont SYSTEM "xml/pangofc-font.xml"> <!ENTITY PangoFcDecoder SYSTEM "xml/pangofc-decoder.xml"> @@ -48,6 +49,7 @@ &pango-Win32-Fonts-and-Rendering; &pango-FreeType-Fonts-and-Rendering; &pango-Xft-Fonts-and-Rendering; + &pangocairo; &pango-X-Fonts-and-Rendering; </chapter> diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt index 11cfe179..1972e9b7 100644 --- a/docs/pango-sections.txt +++ b/docs/pango-sections.txt @@ -769,6 +769,28 @@ pango_xft_renderer_get_type </SECTION> <SECTION> +<TITLE>Cairo Rendering</TITLE> +<FILE>pangocairo</FILE> +PangoCairoFontMap +pango_cairo_font_map_new +pango_cairo_font_map_get_default +pango_cairo_font_map_set_resolution +pango_cairo_font_map_get_resolution +pango_cairo_font_map_create_context +pango_cairo_update_context +pango_cairo_create_layout +pango_cairo_update_layout +pango_cairo_show_glyphs +pango_cairo_show_layout_line +pango_cairo_show_layout +<SUBSECTION Standard> +PANGO_CAIRO_FONT_MAP +PANGO_IS_CAIRO_FONT_MAP +PANGO_TYPE_CAIRO_FONT_MAP +pango_cairo_font_map_get_type +</SECTION> + +<SECTION> <FILE>pangofc-fontmap</FILE> <TITLE>PangoFcFontMap</TITLE> PangoFcFontMap diff --git a/docs/pango.types b/docs/pango.types index 5cda42a7..818e81b8 100644 --- a/docs/pango.types +++ b/docs/pango.types @@ -1,4 +1,5 @@ #include <pango/pango.h> +#include <pango/pangocairo.h> #include <pango/pangofc-font.h> #include <pango/pangofc-fontmap.h> #include <pango/pangoft2.h> @@ -19,5 +20,5 @@ pango_fc_font_map_get_type pango_fc_decoder_get_type pango_ft2_font_map_get_type pango_xft_font_get_type - +pango_cairo_font_map_get_type diff --git a/docs/rotated-text.png b/docs/rotated-text.png Binary files differnew file mode 100644 index 00000000..b29682e8 --- /dev/null +++ b/docs/rotated-text.png diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml index adb8f555..f88a679b 100644 --- a/docs/tmpl/pango-renderer.sgml +++ b/docs/tmpl/pango-renderer.sgml @@ -124,12 +124,14 @@ destinations can be created. @renderer: @part: -@y1: +@y1_: @x11: @x21: @y2: @x12: @x22: +<!-- # Unused Parameters # --> +@y1: <!-- ##### FUNCTION pango_renderer_draw_glyph ##### --> diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml new file mode 100644 index 00000000..723a4a09 --- /dev/null +++ b/docs/tmpl/pangocairo.sgml @@ -0,0 +1,248 @@ +<!-- ##### SECTION Title ##### --> +Cairo Rendering + +<!-- ##### SECTION Short_Description ##### --> +Rendering with the Cairo backend + +<!-- ##### SECTION Long_Description ##### --> +<para> +The <ulink url="http://cairographics.org">Cairo library</ulink> is a +vector graphics library with a powerful rendering model. It has such +features as anti-aliased primitives, alpha-compositing, and +gradients. Multiple backends for Cairo are available, to allow +rendering to images, to PDF files, and to the screen on X and on other +windowing systems. The functions in this section allow using Pango +to render to Cairo surfaces. +</para> +<para> +Using Pango with Cairo is straightforward. A #PangoContext created +with pango_cairo_font_map_create_context() can be used on any +Cairo context (cairo_t), but needs to be updated to match the +current transformation matrix and target surface of the Cairo context +using pango_cairo_update_context(). The convenience functions +pango_cairo_create_layout() and pango_cairo_update_layout() handle +the common case where the program doesn't need to manipulate the +properties of the #PangoContext. +</para> +<para> +When you get the metrics of a layout or of a piece of a layout using +functions such as pango_layout_get_extents(), the reported metrics +are in user-space coordinates. If a piece of text is 10 units long, +and you call cairo_scale (cr, 2.0), it still is more-or-less 10 +units long. However, the results will be affected by hinting +(that is, the process of adjusting the text to look good on the +pixel grid), so you shouldn't assume they are completely independent +of the current transformation matrix. Note that the basic metrics +functions in Pango report results in integer Pango units. To get +to the floating point units used in Cairo divide by %PANGO_SCALE. +</para> +<example id="rotated-example"> +<title>Using Pango with Cairo</title> +<programlisting> +#include <math.h> +#include <pango/pangocairo.h> + +static void +draw_text (cairo_t *cr) +{ +#define RADIUS 150 +#define N_WORDS 10 +#define FONT "Sans Bold 27" + + PangoLayout *layout; + PangoFontDescription *desc; + int i; + + /* Center coordinates on the middle of the region we are drawing + */ + cairo_translate (cr, RADIUS, RADIUS); + + /* Create a PangoLayout, set the font and text */ + layout = pango_cairo_create_layout (cr); + + pango_layout_set_text (layout, "Text", -1); + desc = pango_font_description_from_string (FONT); + pango_layout_set_font_description (layout, desc); + pango_font_description_free (desc); + + /* Draw the layout N_WORDS times in a circle */ + for (i = 0; i < N_WORDS; i++) + { + int width, height; + double angle = (360. * i) / N_WORDS; + double red; + + cairo_save (cr); + + /* Gradient from red at angle == 60 to blue at angle == 300 */ + red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2; + cairo_set_rgb_color (cr, red, 0, 1.0 - red); + + cairo_rotate (cr, angle * G_PI / 180.); + + /* Inform Pango to re-layout the text with the new transformation */ + pango_cairo_update_layout (cr, layout); + + pango_layout_get_size (layout, &width, &height); + cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS); + pango_cairo_show_layout (cr, layout); + + cairo_restore (cr); + } + + /* free the layout object */ + g_object_unref (layout); +} + +int main (int argc, char **argv) +{ + cairo_t *cr; + FILE *f; + + if (argc != 2) + { + g_printerr ("Usage: cairo-example OUTPUT_FILENAME\n"); + return 1; + } + + f = fopen (argv[1], "w"); + if (!f) + { + g_printerr ("Usage: cannot open '%s'\n", argv[1]); + return 1; + } + + cr = cairo_create(); + cairo_set_target_png (cr, f, + CAIRO_FORMAT_ARGB32, + 2 * RADIUS, 2 * RADIUS); + + cairo_set_rgb_color (cr, 1.0, 1.0, 1.0); + cairo_rectangle (cr, 0, 0, 2 * RADIUS, 2 * RADIUS); + cairo_fill (cr); + draw_text (cr); + + cairo_destroy (cr); + fclose (f); + + return 0; +} +</programlisting> +</example> +<figure> + <title>Output of <xref linkend="rotated-example"/></title> + <graphic fileref="rotated-text.png" format="PNG"/> +</figure> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### STRUCT PangoCairoFontMap ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION pango_cairo_font_map_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_get_default ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_set_resolution ##### --> +<para> + +</para> + +@fontmap: +@dpi: +<!-- # Unused Parameters # --> +@dpi_x: +@dpi_y: + + +<!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### --> +<para> + +</para> + +@fontmap: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_create_context ##### --> +<para> + +</para> + +@fontmap: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_update_context ##### --> +<para> + +</para> + +@cr: +@context: + + +<!-- ##### FUNCTION pango_cairo_create_layout ##### --> +<para> + +</para> + +@cr: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_update_layout ##### --> +<para> + +</para> + +@cr: +@layout: + + +<!-- ##### FUNCTION pango_cairo_show_glyphs ##### --> +<para> + +</para> + +@cr: +@font: +@glyphs: + + +<!-- ##### FUNCTION pango_cairo_show_layout_line ##### --> +<para> + +</para> + +@cr: +@line: + + +<!-- ##### FUNCTION pango_cairo_show_layout ##### --> +<para> + +</para> + +@cr: +@layout: + + diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml index db72b732..4f919ca3 100644 --- a/docs/tmpl/pangofc-fontmap.sgml +++ b/docs/tmpl/pangofc-fontmap.sgml @@ -44,6 +44,7 @@ Fontconfig-based backend involves deriving from both @default_substitute: @new_font: +@get_render_key: <!-- ##### FUNCTION pango_fc_font_description_from_pattern ##### --> <para> diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml index ecbf7d9e..7c5fa9da 100644 --- a/docs/tmpl/text-attributes.sgml +++ b/docs/tmpl/text-attributes.sgml @@ -47,6 +47,7 @@ attribute is listed in parentheses after the description. @PANGO_ATTR_LETTER_SPACING: @PANGO_ATTR_UNDERLINE_COLOR: @PANGO_ATTR_STRIKETHROUGH_COLOR: +@PANGO_ATTR_ABSOLUTE_SIZE: <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### --> <para> @@ -151,12 +152,17 @@ impose shape restrictions. <!-- ##### STRUCT PangoAttrSize ##### --> <para> - +The #PangoAttrShape structure is used to represent attributes which +set font size. </para> -@attr: -@size: -@absolute: +@attr: the common portion of the attribute +@size: size of font, in units of 1/PANGO_SCALE of a point (for + PANGO_ATTR_SIZE) or of a device uni (for PANGO_ATTR_ABSOLUTE_SIZE) +@absolute: whether the font size is in device units or points. + This field is only present for compatibility with Pango-1.8.0 + (PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will + be %FALSE for PANGO_ATTR_SIZE and %TRUE for PANGO_ATTR_ABSOLUTE_SIZE. <!-- ##### FUNCTION pango_parse_markup ##### --> <para> diff --git a/docs/tmpl/xft-fonts.sgml b/docs/tmpl/xft-fonts.sgml index 50a6e02a..fc4d6cae 100644 --- a/docs/tmpl/xft-fonts.sgml +++ b/docs/tmpl/xft-fonts.sgml @@ -10,7 +10,7 @@ The Xft library is a library for displaying fonts on the X window system; internally it uses the fontconfig library to locate font files, and the FreeType library to load and render fonts. The Xft backend is the recommended Pango font backend for screen -display with X. +display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.) </para> <para> Using the Xft backend is generally straightforward; |
