summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/meson.build1
-rw-r--r--docs/pango_cairo.md129
-rw-r--r--docs/pangocairo.toml.in3
-rw-r--r--pango/pangocairo-render.c132
4 files changed, 133 insertions, 132 deletions
diff --git a/docs/meson.build b/docs/meson.build
index e5c4e350..14a7a5cd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -88,6 +88,7 @@ endif
if cairo_dep.found()
pangocairo_content_files = [
+ 'pango_cairo.md',
'pango-name.png',
'rotated-text.png',
]
diff --git a/docs/pango_cairo.md b/docs/pango_cairo.md
new file mode 100644
index 00000000..2edd8ba8
--- /dev/null
+++ b/docs/pango_cairo.md
@@ -0,0 +1,129 @@
+---
+Title: Rendering with Cairo
+---
+
+# Rendering with Cairo
+
+The Cairo library 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.
+
+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`.
+
+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`.
+
+## Using Pango with Cairo
+
+```
+#include <math.h>
+#include <pango/pangocairo.h>
+
+#define RADIUS 150
+#define N_WORDS 10
+#define FONT "Sans Bold 27"
+
+static void
+draw_text (cairo_t *cr)
+{
+ 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 == 240 */
+ red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
+ cairo_set_source_rgb (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;
+ char *filename;
+ cairo_status_t status;
+ cairo_surface_t *surface;
+
+ if (argc != 2)
+ {
+ g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
+ return 1;
+ }
+
+ filename = argv[1];
+
+ surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+ 2 * RADIUS, 2 * RADIUS);
+ cr = cairo_create (surface);
+
+ cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
+ cairo_paint (cr);
+ draw_text (cr);
+ cairo_destroy (cr);
+
+ status = cairo_surface_write_to_png (surface, filename);
+ cairo_surface_destroy (surface);
+
+ if (status != CAIRO_STATUS_SUCCESS)
+ {
+ g_printerr ("Could not save png to '%s'\n", filename);
+ return 1;
+ }
+
+ return 0;
+}
+```
+
+Once you build and run the example code above, you should see the
+following result:
+
+![Output of rotated-example](rotated-text.png)
diff --git a/docs/pangocairo.toml.in b/docs/pangocairo.toml.in
index 2e0124e3..656be8d2 100644
--- a/docs/pangocairo.toml.in
+++ b/docs/pangocairo.toml.in
@@ -27,6 +27,9 @@ name = "basic"
base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/"
[extra]
+content_files = [
+ "pango_cairo.md",
+]
content_images = [
"pango-name.png",
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 75a7a0f7..6f017fee 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -19,138 +19,6 @@
* Boston, MA 02111-1307, USA.
*/
-/**
- * SECTION:pangocairo
- * @short_description:Font handling and rendering with Cairo
- * @title:Cairo Fonts and Rendering
- *
- * The Cairo library 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.
- *
- * 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.
- *
- * 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.
- *
- * ## Using Pango with Cairo ## {#rotated-example}
- *
- * |[<!-- language="C" -->
- * #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 == 240
- * red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
- * cairo_set_source_rgb (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;
- * char *filename;
- * cairo_status_t status;
- * cairo_surface_t *surface;
- *
- * if (argc != 2)
- * {
- * g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
- * return 1;
- * }
- *
- * filename = argv[1];
- *
- * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
- * 2 * RADIUS, 2 * RADIUS);
- * cr = cairo_create (surface);
- *
- * cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
- * cairo_paint (cr);
- * draw_text (cr);
- * cairo_destroy (cr);
- *
- * status = cairo_surface_write_to_png (surface, filename);
- * cairo_surface_destroy (surface);
- *
- * if (status != CAIRO_STATUS_SUCCESS)
- * {
- * g_printerr ("Could not save png to '%s'\n", filename);
- * return 1;
- * }
- *
- * return 0;
- * }
- * ]|
- *
- * Once you build and run the example code above, you should see the
- * following result:
- *
- * ![Output of rotated-example](rotated-text.png)
- */
#include "config.h"
#include <math.h>