Cairo(3pm)

1Cairo(3)              User Contributed Perl Documentation             Cairo(3)
2
3
4

NAME

6       Cairo - Perl interface to the cairo library
7

SYNOPSIS

9         use Cairo;
10
11         my $surface = Cairo::ImageSurface->create ('argb32', 100, 100);
12         my $cr = Cairo::Context->create ($surface);
13
14         $cr->rectangle (10, 10, 40, 40);
15         $cr->set_source_rgb (0, 0, 0);
16         $cr->fill;
17
18         $cr->rectangle (50, 50, 40, 40);
19         $cr->set_source_rgb (1, 1, 1);
20         $cr->fill;
21
22         $cr->show_page;
23
24         $surface->write_to_png ('output.png');
25

ABSTRACT

27       Cairo provides Perl bindings for the vector graphics library cairo.  It
28       supports multiple output targets, including PNG, PDF and SVG.  Cairo
29       produces identical output on all those targets.
30

API DOCUMENTATION

32       Note that this listing still lacks entries for Cairo::Surfaces and some
33       utility methods.
34
35   Drawing
36       Cairo::Context -- The cairo drawing context
37
38       Cairo::Context is the main object used when drawing with Cairo. To draw
39       with Cairo, you create a Cairo::Context, set the target surface, and
40       drawing options for the Cairo::Context, create shapes with methods like
41       "$cr-"move_to> and "$cr->line_to", and then draw shapes with
42       "$cr->stroke" or "$cr->fill".
43
44       Cairo::Context's can be pushed to a stack via "$cr->save". They may
45       then safely be changed, without loosing the current state. Use
46       "$cr->restore" to restore to the saved state.  =over
47
48       $cr = Cairo::Context->create ($surface)
49
50       $surface: Cairo::Surface
51
52       $cr->save
53
54       $cr->restore
55
56       $status = $cr->status
57
58       $surface = $cr->get_target
59
60       $cr->push_group [1.2]
61
62       $cr->push_group_with_content ($content) [1.2]
63
64       $content: Cairo::Content
65
66       $pattern = $cr->pop_group [1.2]
67
68       $cr->pop_group_to_source [1.2]
69
70       $surface = $cr->get_group_target [1.2]
71
72       $cr->set_source_rgb ($red, $green, $blue)
73
74       $red: double
75       $green: double
76       $blue: double
77
78       $cr->set_source_rgba ($red, $green, $blue, $alpha)
79
80       $red: double
81       $green: double
82       $blue: double
83       $alpha: double
84
85       $cr->set_source ($source)
86
87       $source: Cairo::Pattern
88
89       $cr->set_source_surface ($surface, $x, $y)
90
91       $surface: Cairo::Surface
92       $x: double
93       $y: double
94
95       $source = $cr->get_source
96
97       $cr->set_antialias ($antialias)
98
99       $antialias: Cairo::Antialias
100
101       $antialias = $cr->get_antialias
102
103       $cr->set_dash ($offset, ...)
104
105       $offset: double
106       ...: list of doubles
107
108       $cr->set_fill_rule ($fill_rule)
109
110       $fill_rule: Cairo::FillRule
111
112       $fill_rule = $cr->get_fill_rule
113
114       $cr->set_line_cap ($line_cap)
115
116       $line_cap: Cairo::LineCap
117
118       $line_cap = $cr->get_line_cap
119
120       $cr->set_line_join ($line_join)
121
122       $line_join: Cairo::LineJoin
123
124       $line_join = $cr->get_line_join
125
126       $cr->set_line_width ($width)
127
128       $width: double
129
130       $width = $cr->get_line_width
131
132       $cr->set_miter_limit ($limit)
133
134       $limit: double
135
136       ($offset, @dashes) = $cr->get_dash [1.4]
137
138       $limit = $cr->get_miter_limit
139
140       $cr->set_operator ($op)
141
142       $op: Cairo::Operator
143
144       $op = $cr->get_operator
145
146       $cr->set_tolerance ($tolerance)
147
148       $tolerance: double
149
150       $tolerance = $cr->get_tolerance
151
152       $cr->clip
153
154       $cr->clip_preserve
155
156       ($x1, $y1, $x2, $y2) = $cr->clip_extents [1.4]
157
158       @rectangles = $cr->copy_clip_rectangle_list [1.4]
159
160       $cr->reset_clip
161
162       $cr->fill
163
164       $cr->fill_preserve
165
166       ($x1, $y1, $x2, $y2) = $cr->fill_extents
167
168       $bool = $cr->in_fill ($x, $y)
169
170       $x: double
171       $y: double
172
173       $cr->mask ($pattern)
174
175       $pattern: Cairo::Pattern
176
177       $cr->mask_surface ($surface, $surface_x, $surface_y)
178
179       $surface: Cairo::Surface
180       $surface_x: double
181       $surface_y: double
182
183       $cr->paint
184
185       $cr->paint_with_alpha ($alpha)
186
187       $alpha: double
188
189       $cr->stroke
190
191       $cr->stroke_preserve
192
193       ($x1, $y1, $x2, $y2) = $cr->stroke_extents
194
195       $bool = $cr->in_stroke ($x, $y)
196
197       $x: double
198       $y: double
199
200       $cr->copy_page
201
202       $cr->show_page
203
204       Paths -- Creating paths and manipulating path data
205
206         $path = [
207           { type => "move-to", points => [[1, 2]] },
208           { type => "line-to", points => [[3, 4]] },
209           { type => "curve-to", points => [[5, 6], [7, 8], [9, 10]] },
210           ...
211           { type => "close-path", points => [] },
212         ];
213
214       Cairo::Path is a data structure for holding a path. This data structure
215       serves as the return value for "$cr->copy_path_data" and
216       "$cr->copy_path_data_flat" as well the input value for
217       "$cr->append_path".
218
219       Cairo::Path is represented as an array reference that contains path
220       elements, represented by hash references with two keys: type and
221       points.  The value for type can be either of the following:
222
223       "move-to"
224       "line-to"
225       "curve-to"
226       "close-path"
227
228       The value for points is an array reference which contains zero or more
229       points.  Points are represented as array references that contain two
230       doubles: x and y.  The necessary number of points depends on the type
231       of the path element:
232
233       "move-to": 1 point
234       "line_to": 1 point
235       "curve-to": 3 points
236       "close-path": 0 points
237
238       The semantics and ordering of the coordinate values are consistent with
239       "$cr->move_to", "$cr->line_to", "$cr->curve_to", and "$cr->close_path".
240
241       $path = $cr->copy_path
242
243       $path = $cr->copy_path_flat
244
245       $cr->append_path ($path)
246
247       $path: Cairo::Path
248
249       $bool = $cr->has_current_point [1.6]
250
251       ($x, $y) = $cr->get_current_point
252
253       $cr->new_path
254
255       $cr->new_sub_path [1.2]
256
257       $cr->close_path
258
259       ($x1, $y1, $x2, $y2) = $cr->path_extents [1.6]
260
261       $cr->arc ($xc, $yc, $radius, $angle1, $angle2)
262
263       $xc: double
264       $yc: double
265       $radius: double
266       $angle1: double
267       $angle2: double
268
269       $cr->arc_negative ($xc, $yc, $radius, $angle1, $angle2)
270
271       $xc: double
272       $yc: double
273       $radius: double
274       $angle1: double
275       $angle2: double
276
277       $cr->curve_to ($x1, $y1, $x2, $y2, $x3, $y3)
278
279       $x1: double
280       $y1: double
281       $x2: double
282       $y2: double
283       $x3: double
284       $y3: double
285
286       $cr->line_to ($x, $y)
287
288       $x: double
289       $y: double
290
291       $cr->move_to ($x, $y)
292
293       $x: double
294       $y: double
295
296       $cr->rectangle ($x, $y, $width, $height)
297
298       $x: double
299       $y: double
300       $width: double
301       $height: double
302
303       $cr->glyph_path (...)
304
305       ...: list of Cairo::Glyph's
306
307       $cr->text_path ($utf8)
308
309       $utf8: string in utf8 encoding
310
311       $cr->rel_curve_to ($dx1, $dy1, $dx2, $dy2, $dx3, $dy3)
312
313       $dx1: double
314       $dy1: double
315       $dx2: double
316       $dy2: double
317       $dx3: double
318       $dy3: double
319
320       $cr->rel_line_to ($dx, $dy)
321
322       $dx: double
323       $dy: double
324
325       $cr->rel_move_to ($dx, $dy)
326
327       $dx: double
328       $dy: double
329
330       Patterns -- Gradients and filtered sources
331
332       $status = $pattern->status
333
334       $type = $pattern->get_type [1.2]
335
336       $pattern->set_matrix ($matrix)
337
338       $matrix: Cairo::Matrix
339
340       $matrix = $pattern->get_matrix
341
342       $pattern = Cairo::SolidPattern->create_rgb ($red, $green, $blue)
343
344       $red: double
345       $green: double
346       $blue: double
347
348       $pattern = Cairo::SolidPattern->create_rgba ($red, $green, $blue,
349       $alpha)
350
351       $red: double
352       $green: double
353       $blue: double
354       $alpha: double
355
356       ($r, $g, $b, $a) = $pattern->get_rgba [1.4]
357
358       $pattern = Cairo::SurfacePattern->create ($surface)
359
360       $surface: Cairo::Surface
361
362       $pattern->set_extend ($extend)
363
364       $extend: Cairo::Extend
365
366       $extend = $pattern->get_extend
367
368       $pattern->set_filter ($filter)
369
370       $filter: Cairo::Filter
371
372       $filter = $pattern->get_filter
373
374       $surface = $pattern->get_surface [1.4]
375
376       $pattern = Cairo::LinearGradient->create ($x0, $y0, $x1, $y1)
377
378       $x0: double
379       $y0: double
380       $x1: double
381       $y1: double
382
383       ($x0, $y0, $x1, $y1) = $pattern->get_points [1.4]
384
385       $pattern = Cairo::RadialGradient->create ($cx0, $cy0, $radius0, $cx1,
386       $cy1, $radius1)
387
388       $cx0: double
389       $cy0: double
390       $radius0: double
391       $cx1: double
392       $cy1: double
393       $radius1: double
394
395       ($x0, $y0, $r0, $x1, $y1, $r1) = $pattern->get_circles [1.4]
396
397       $pattern->add_color_stop_rgb (double offset, double red, double green,
398       double blue)
399
400       $offset: double
401       $red: double
402       $green: double
403       $blue: double
404
405       $pattern->add_color_stop_rgba (double offset, double red, double green,
406       double blue, double alpha)
407
408       $offset: double
409       $red: double
410       $green: double
411       $blue: double
412       $alpha: double
413
414       @stops = $pattern->get_color_stops [1.4]
415
416       A color stop is represented as an array reference with five elements:
417       offset, red, green, blue, and alpha.
418
419       Transformations -- Manipulating the current transformation matrix
420
421       $cr->translate ($tx, $ty)
422
423       $tx: double
424       $ty: double
425
426       $cr->scale ($sx, $sy)
427
428       $sx: double
429       $sy: double
430
431       $cr->rotate ($angle)
432
433       $angle: double
434
435       $cr->transform ($matrix)
436
437       $matrix: Cairo::Matrix
438
439       $cr->set_matrix ($matrix)
440
441       $matrix: Cairo::Matrix
442
443       $matrix = $cr->get_matrix
444
445       $cr->identity_matrix
446
447       ($x, $y) = $cr->user_to_device ($x, $y)
448
449       $x: double
450       $y: double
451
452       ($dx, $dy) = $cr->user_to_device_distance ($dx, $dy)
453
454       $dx: double
455       $dy: double
456
457       ($x, $y) = $cr->device_to_user ($x, $y)
458
459       $x: double
460       $y: double
461
462       ($dx, $dy) = $cr->device_to_user_distance ($dx, $dy)
463
464       $dx: double
465       $dy: double
466
467       Text -- Rendering text and sets of glyphs
468
469       Glyphs are represented as anonymous hash references with three keys:
470       index, x and y.  Example:
471
472         my @glyphs = ({ index => 1, x => 2, y => 3 },
473                       { index => 2, x => 3, y => 4 },
474                       { index => 3, x => 4, y => 5 });
475
476       $cr->select_font_face ($family, $slant, $weight)
477
478       $family: string
479       $slant: Cairo::FontSlant
480       $weight: Cairo::FontWeight
481
482       $cr->set_font_size ($size)
483
484       $size: double
485
486       $cr->set_font_matrix ($matrix)
487
488       $matrix: Cairo::Matrix
489
490       $matrix = $cr->get_font_matrix
491
492       $cr->set_font_options ($options)
493
494       $options: Cairo::FontOptions
495
496       $options = $cr->get_font_options
497
498       $cr->set_scaled_font ($scaled_font) [1.2]
499
500       $scaled_font: Cairo::ScaledFont
501
502       $scaled_font = $cr->get_scaled_font [1.4]
503
504       $cr->show_text ($utf8)
505
506       $utf8: string
507
508       $cr->show_glyphs (...)
509
510       ...: list of glyphs
511
512       $face = $cr->get_font_face
513
514       $extents = $cr->font_extents
515
516       $cr->set_font_face ($font_face)
517
518       $font_face: Cairo::FontFace
519
520       $cr->set_scaled_font ($scaled_font)
521
522       $scaled_font: Cairo::ScaledFont
523
524       $extents = $cr->text_extents ($utf8)
525
526       $utf8: string
527
528       $extents = $cr->glyph_extents (...)
529
530       ...: list of glyphs
531
532   Fonts
533       Cairo::FontFace -- Base class for fonts
534
535       $status = $font_face->status
536
537       $type = $font_face->get_type [1.2]
538
539       Scaled Fonts -- Caching metrics for a particular font size
540
541       $scaled_font = Cairo::ScaledFont->create ($font_face, $font_matrix,
542       $ctm, $options)
543
544       $font_face: Cairo::FontFace
545       $font_matrix: Cairo::Matrix
546       $ctm: Cairo::Matrix
547       $options: Cairo::FontOptions
548
549       $status = $scaled_font->status
550
551       $extents = $scaled_font->extents
552
553       $extents = $scaled_font->text_extents ($utf8) [1.2]
554
555       $utf8: string
556
557       $extents = $scaled_font->glyph_extents (...)
558
559       ...: list of glyphs
560
561       $font_face = $scaled_font->get_font_face [1.2]
562
563       $options = $scaled_font->get_font_options [1.2]
564
565       $font_matrix = $scaled_font->get_font_matrix [1.2]
566
567       $ctm = $scaled_font->get_ctm [1.2]
568
569       $type = $scaled_font->get_type [1.2]
570
571       Font Options -- How a font should be rendered
572
573       $font_options = Cairo::FontOptions->create
574
575       $status = $font_options->status
576
577       $font_options->merge ($other)
578
579       $other: Cairo::FontOptions
580
581       $hash = $font_options->hash
582
583       $bools = $font_options->equal ($other)
584
585       $other: Cairo::FontOptions
586
587       $font_options->set_antialias ($antialias)
588
589       $antialias: Cairo::AntiAlias
590
591       $antialias = $font_options->get_antialias
592
593       $font_options->set_subpixel_order ($subpixel_order)
594
595       $subpixel_order: Cairo::SubpixelOrder
596
597       $subpixel_order = $font_options->get_subpixel_order
598
599       $font_options->set_hint_style ($hint_style)
600
601       $hint_style: Cairo::HintStyle
602
603       $hint_style = $font_options->get_hint_style
604
605       $font_options->set_hint_metrics ($hint_metrics)
606
607       $hint_metrics: Cairo::HintMetrics
608
609       $hint_metrics = $font_options->get_hint_metrics
610
611       FreeType Fonts -- Font support for FreeType
612
613       If your cairo library supports it, the FreeType integration allows you
614       to load font faces from font files.  You can query for this capability
615       with "Cairo::HAS_FT_FONT".  To actually use this, you'll need the
616       Font::FreeType module.
617
618       my $face = Cairo::FtFontFace->create ($ft_face, $load_flags=0)
619
620       $ft_face: Font::FreeType::Face
621       $load_flags: integer
622
623       This method allows you to create a Cairo::FontFace from a
624       Font::FreeType::Face.  To obtain the latter, you can for example load
625       it from a file:
626
627         my $file = '/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf';
628         my $ft_face = Font::FreeType->new->face ($file);
629         my $face = Cairo::FtFontFace->create ($ft_face);
630
631   Surfaces
632       Cairo::Surface -- Base class for surfaces
633
634       $new = $old->create_similar ($content, $width, $height)
635
636       $content: Cairo::Content
637       $width: integer
638       $height: integer
639
640       $status = $surface->status
641
642       $surface->finish
643
644       $surface->flush
645
646       $font_options = $surface->get_font_options
647
648       $content = $surface->get_content [1.2]
649
650       $surface->mark_dirty
651
652       $surface->mark_dirty_rectangle ($x, $y, $width, $height)
653
654       $x: integer
655       $y: integer
656       $width: integer
657       $height: integer
658
659       $surface->set_device_offset ($x_offset, $y_offset)
660
661       $x_offset: integer
662       $y_offset: integer
663
664       ($x_offset, $y_offset) = $surface->get_device_offset [1.2]
665
666       $surface->set_fallback_resolution ($x_pixels_per_inch,
667       $y_pixels_per_inch) [1.2]
668
669       $x_pixels_per_inch: double
670       $y_pixels_per_inch: double
671
672       $type = $surface->get_type [1.2]
673
674       $status = $surface->copy_page [1.6]
675
676       $status: Cairo::Status
677
678       $status = $surface->show_page [1.6]
679
680       $status: Cairo::Status
681
682       Image Surfaces -- Rendering to memory buffers
683
684       $surface = Cairo::ImageSurface->create ($format, $width, $height)
685
686       $format: Cairo::Format
687       $width: integer
688       $height: integer
689
690       $surface = Cairo::ImageSurface->create_for_data ($data, $format,
691       $width, $height, $stride)
692
693       $data: image data
694       $format: Cairo::Format
695       $width: integer
696       $height: integer
697       $stride: integer
698
699       $data = $surface->get_data [1.2]
700
701       $format = $surface->get_format [1.2]
702
703       $width = $surface->get_width
704
705       $height = $surface->get_height
706
707       $stride = $surface->get_stride [1.2]
708
709       PDF Surfaces -- Rendering PDF documents
710
711       $surface = Cairo::PdfSurface->create ($filename, $width_in_points,
712       $height_in_points) [1.2]
713
714       $filename: string
715       $width_in_points: double
716       $height_in_points: double
717
718       $surface = Cairo::PdfSurface->create_for_stream ($callback,
719       $callback_data, $width_in_points, $height_in_points) [1.2]
720
721       $callback: Cairo::WriteFunc
722       $callback_data: scalar
723       $width_in_points: double
724       $height_in_points: double
725
726       $surface->set_size ($width_in_points, $height_in_points) [1.2]
727
728       $width_in_points: double
729       $height_in_points: double
730
731       PNG Support -- Reading and writing PNG images
732
733       $surface = Cairo::ImageSurface->create_from_png ($filename)
734
735       $filename: string
736
737       Cairo::ReadFunc: $data = sub { my ($callback_data, $length) = @_; }
738
739       $data: binary image data, of length $length
740       $callback_data: scalar, user data
741       $length: integer, bytes to read
742
743       $surface = Cairo::ImageSurface->create_from_png_stream ($callback,
744       $callback_data)
745
746       $callback: Cairo::ReadFunc
747       $callback_data: scalar
748
749       $status = $surface->write_to_png ($filename)
750
751       $filename: string
752
753       Cairo::WriteFunc: sub { my ($callback_data, $data) = @_; }
754
755       $callback_data: scalar, user data
756       $data: binary image data, to be written
757
758       $status = $surface->write_to_png_stream ($callback, $callback_data)
759
760       $callback: Cairo::WriteFunc
761       $callback_data: scalar
762
763       PostScript Surfaces -- Rendering PostScript documents
764
765       $surface = Cairo::PsSurface->create ($filename, $width_in_points,
766       $height_in_points) [1.2]
767
768       $filename: string
769       $width_in_points: double
770       $height_in_points: double
771
772       $surface = Cairo::PsSurface->create_for_stream ($callback,
773       $callback_data, $width_in_points, $height_in_points) [1.2]
774
775       $callback: Cairo::WriteFunc
776       $callback_data: scalar
777       $width_in_points: double
778       $height_in_points: double
779
780       $surface->set_size ($width_in_points, $height_in_points) [1.2]
781
782       $width_in_points: double
783       $height_in_points: double
784
785       $surface->dsc_begin_setup [1.2]
786
787       $surface->dsc_begin_page_setup [1.2]
788
789       $surface->dsc_comment ($comment) [1.2]
790
791       $comment: string
792
793       $surface->restrict_to_level ($level) [1.6]
794
795       $level: Cairo::PsLevel
796
797       @levels = Cairo::PsSurface::get_levels [1.6]
798
799       $string = Cairo::PsSurface::level_to_string ($level) [1.6]
800
801       $level: Cairo::PsLevel
802
803       $surface->set_eps ($eps) [1.6]
804
805       $eps: boolean
806
807       $eps = $surface->get_eps [1.6]
808
809       SVG Surfaces -- Rendering SVG documents
810
811       $surface = Cairo::SvgSurface->create ($filename, $width_in_points,
812       $height_in_points) [1.2]
813
814       $filename: string
815       $width_in_points: double
816       $height_in_points: double
817
818       $surface = Cairo::SvgSurface->create_for_stream ($callback,
819       $callback_data, $width_in_points, $height_in_points) [1.2]
820
821       $callback: Cairo::WriteFunc
822       $callback_data: scalar
823       $width_in_points: double
824       $height_in_points: double
825
826       $surface->restrict_to_version ($version) [1.2]
827
828       $version: Cairo::SvgVersion
829
830       @versions = Cairo::SvgSurface::get_versions [1.2]
831
832       $string = Cairo::SvgSurface::version_to_string ($version) [1.2]
833
834       $version: Cairo::SvgVersion
835
836   Utilities
837       Version Information -- Run-time and compile-time version checks.
838
839       $version = Cairo->version
840
841       $string = Cairo->version_string
842
843       $version_code = Cairo->VERSION
844
845       $version_code = Cairo->VERSION_ENCODE ($major, $minor, $micro)
846
847       $major: integer
848       $minor: integer
849       $micro: integer
850
851       $stride = Cairo::Format::stride_for_width ($format, $width) [1.6]
852
853       $format: Cairo::Format
854       $width: integer
855

AUTHORS

864       Ross McFarland <rwmcfa1 at neces dot com>
865       Torsten Schoenfeld <kaffeetisch at gmx dot de>
866

COPYRIGHT

868       Copyright (C) 2004-2008 by the cairo perl team
869
870
871
872perl v5.12.0                      2008-04-19                          Cairo(3)

NAME

SYNOPSIS

ABSTRACT

API DOCUMENTATION

SEE ALSO

AUTHORS

COPYRIGHT