home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl5 / Cairo.pm next >
Encoding:
Perl POD Document  |  2008-04-19  |  22.8 KB  |  1,500 lines

  1. #
  2. # Copyright (c) 2004-2008 by the cairo perl team (see the file README)
  3. #
  4. # Licensed under the LGPL, see LICENSE file for more information.
  5. #
  6. # $Header: /cvs/cairo/cairo-perl/Cairo.pm,v 1.40 2008-04-19 16:38:51 tsch Exp $
  7. #
  8.  
  9. package Cairo;
  10.  
  11. use strict;
  12. use warnings;
  13. use DynaLoader;
  14.  
  15. our @ISA = qw/DynaLoader/;
  16.  
  17. our $VERSION = '1.060';
  18.  
  19. sub dl_load_flags { $^O eq 'darwin' ? 0x00 : 0x01 }
  20.  
  21. Cairo->bootstrap ($VERSION);
  22.  
  23. # --------------------------------------------------------------------------- #
  24.  
  25. package Cairo;
  26.  
  27. 1;
  28.  
  29. __END__
  30.  
  31. =head1 NAME
  32.  
  33. Cairo - Perl interface to the cairo library
  34.  
  35. =head1 SYNOPSIS
  36.  
  37.   use Cairo;
  38.  
  39.   my $surface = Cairo::ImageSurface->create ('argb32', 100, 100);
  40.   my $cr = Cairo::Context->create ($surface);
  41.  
  42.   $cr->rectangle (10, 10, 40, 40);
  43.   $cr->set_source_rgb (0, 0, 0);
  44.   $cr->fill;
  45.  
  46.   $cr->rectangle (50, 50, 40, 40);
  47.   $cr->set_source_rgb (1, 1, 1);
  48.   $cr->fill;
  49.  
  50.   $cr->show_page;
  51.  
  52.   $surface->write_to_png ('output.png');
  53.  
  54. =head1 ABSTRACT
  55.  
  56. Cairo provides Perl bindings for the vector graphics library cairo.  It
  57. supports multiple output targets, including PNG, PDF and SVG.  Cairo produces
  58. identical output on all those targets.
  59.  
  60. =head1 API DOCUMENTATION
  61.  
  62. Note that this listing still lacks entries for I<Cairo::Surface>s and some
  63. utility methods.
  64.  
  65. =head2 Drawing
  66.  
  67. =head3 Cairo::Context -- The cairo drawing context
  68.  
  69. I<Cairo::Context> is the main object used when drawing with Cairo. To draw with
  70. Cairo, you create a I<Cairo::Context>, set the target surface, and drawing
  71. options for the I<Cairo::Context>, create shapes with methods like
  72. C<$cr->move_to> and C<$cr-E<gt>line_to>, and then draw shapes with
  73. C<$cr-E<gt>stroke> or C<$cr-E<gt>fill>.
  74.  
  75. I<Cairo::Context>'s can be pushed to a stack via C<$cr-E<gt>save>. They may
  76. then safely be changed, without loosing the current state. Use
  77. C<$cr-E<gt>restore> to restore to the saved state.
  78. =over
  79.  
  80. =head4 $cr = Cairo::Context->create ($surface)
  81.  
  82. =over
  83.  
  84. =item $surface: I<Cairo::Surface>
  85.  
  86. =back
  87.  
  88. =head4 $cr-E<gt>save
  89.  
  90. =head4 $cr->restore
  91.  
  92. =head4 $status = $cr->status
  93.  
  94. =head4 $surface = $cr->get_target
  95.  
  96. =head4 $cr->push_group [1.2]
  97.  
  98. =head4 $cr->push_group_with_content ($content) [1.2]
  99.  
  100. =over
  101.  
  102. =item $content: I<Cairo::Content>
  103.  
  104. =back
  105.  
  106. =head4 $pattern = $cr->pop_group [1.2]
  107.  
  108. =head4 $cr->pop_group_to_source [1.2]
  109.  
  110. =head4 $surface = $cr->get_group_target [1.2]
  111.  
  112. =head4 $cr->set_source_rgb ($red, $green, $blue)
  113.  
  114. =over
  115.  
  116. =item $red: double
  117.  
  118. =item $green: double
  119.  
  120. =item $blue: double
  121.  
  122. =back
  123.  
  124. =head4 $cr->set_source_rgba ($red, $green, $blue, $alpha)
  125.  
  126. =over
  127.  
  128. =item $red: double
  129.  
  130. =item $green: double
  131.  
  132. =item $blue: double
  133.  
  134. =item $alpha: double
  135.  
  136. =back
  137.  
  138. =head4 $cr->set_source ($source)
  139.  
  140. =over
  141.  
  142. =item $source: I<Cairo::Pattern>
  143.  
  144. =back
  145.  
  146. =head4 $cr->set_source_surface ($surface, $x, $y)
  147.  
  148. =over
  149.  
  150. =item $surface: I<Cairo::Surface>
  151.  
  152. =item $x: double
  153.  
  154. =item $y: double
  155.  
  156. =back
  157.  
  158. =head4 $source = $cr->get_source
  159.  
  160. =head4 $cr->set_antialias ($antialias)
  161.  
  162. =over
  163.  
  164. =item $antialias: I<Cairo::Antialias>
  165.  
  166. =back
  167.  
  168. =head4 $antialias = $cr->get_antialias
  169.  
  170. =head4 $cr->set_dash ($offset, ...)
  171.  
  172. =over
  173.  
  174. =item $offset: double
  175.  
  176. =item ...: list of doubles
  177.  
  178. =back
  179.  
  180. =head4 $cr->set_fill_rule ($fill_rule)
  181.  
  182. =over
  183.  
  184. =item $fill_rule: I<Cairo::FillRule>
  185.  
  186. =back
  187.  
  188. =head4 $fill_rule = $cr->get_fill_rule
  189.  
  190. =head4 $cr->set_line_cap ($line_cap)
  191.  
  192. =over
  193.  
  194. =item $line_cap: I<Cairo::LineCap>
  195.  
  196. =back
  197.  
  198. =head4 $line_cap = $cr->get_line_cap
  199.  
  200. =head4 $cr->set_line_join ($line_join)
  201.  
  202. =over
  203.  
  204. =item $line_join: I<Cairo::LineJoin>
  205.  
  206. =back
  207.  
  208. =head4 $line_join = $cr->get_line_join
  209.  
  210. =head4 $cr->set_line_width ($width)
  211.  
  212. =over
  213.  
  214. =item $width: double
  215.  
  216. =back
  217.  
  218. =head4 $width = $cr->get_line_width
  219.  
  220. =head4 $cr->set_miter_limit ($limit)
  221.  
  222. =over
  223.  
  224. =item $limit: double
  225.  
  226. =back
  227.  
  228. =head4 ($offset, @dashes) = $cr->get_dash [1.4]
  229.  
  230. =head4 $limit = $cr->get_miter_limit
  231.  
  232. =head4 $cr->set_operator ($op)
  233.  
  234. =over
  235.  
  236. =item $op: I<Cairo::Operator>
  237.  
  238. =back
  239.  
  240. =head4 $op = $cr->get_operator
  241.  
  242. =head4 $cr->set_tolerance ($tolerance)
  243.  
  244. =over
  245.  
  246. =item $tolerance: double
  247.  
  248. =back
  249.  
  250. =head4 $tolerance = $cr->get_tolerance
  251.  
  252. =head4 $cr->clip
  253.  
  254. =head4 $cr->clip_preserve
  255.  
  256. =head4 ($x1, $y1, $x2, $y2) = $cr->clip_extents [1.4]
  257.  
  258. =head4 @rectangles = $cr->copy_clip_rectangle_list [1.4]
  259.  
  260. =head4 $cr->reset_clip
  261.  
  262. =head4 $cr->fill
  263.  
  264. =head4 $cr->fill_preserve
  265.  
  266. =head4 ($x1, $y1, $x2, $y2) = $cr->fill_extents
  267.  
  268. =head4 $bool = $cr->in_fill ($x, $y)
  269.  
  270. =over
  271.  
  272. =item $x: double
  273.  
  274. =item $y: double
  275.  
  276. =back
  277.  
  278. =head4 $cr->mask ($pattern)
  279.  
  280. =over
  281.  
  282. =item $pattern: I<Cairo::Pattern>
  283.  
  284. =back
  285.  
  286. =head4 $cr->mask_surface ($surface, $surface_x, $surface_y)
  287.  
  288. =over
  289.  
  290. =item $surface: I<Cairo::Surface>
  291.  
  292. =item $surface_x: double
  293.  
  294. =item $surface_y: double
  295.  
  296. =back
  297.  
  298. =head4 $cr->paint
  299.  
  300. =head4 $cr->paint_with_alpha ($alpha)
  301.  
  302. =over
  303.  
  304. =item $alpha: double
  305.  
  306. =back
  307.  
  308. =head4 $cr->stroke
  309.  
  310. =head4 $cr->stroke_preserve
  311.  
  312. =head4 ($x1, $y1, $x2, $y2) = $cr->stroke_extents
  313.  
  314. =head4 $bool = $cr->in_stroke ($x, $y)
  315.  
  316. =over
  317.  
  318. =item $x: double
  319.  
  320. =item $y: double
  321.  
  322. =back
  323.  
  324. =head4 $cr->copy_page
  325.  
  326. =head4 $cr->show_page
  327.  
  328. =cut
  329.  
  330. # --------------------------------------------------------------------------- #
  331.  
  332. =head3 Paths -- Creating paths and manipulating path data
  333.  
  334.   $path = [
  335.     { type => "move-to", points => [[1, 2]] },
  336.     { type => "line-to", points => [[3, 4]] },
  337.     { type => "curve-to", points => [[5, 6], [7, 8], [9, 10]] },
  338.     ...
  339.     { type => "close-path", points => [] },
  340.   ];
  341.  
  342. I<Cairo::Path> is a data structure for holding a path. This data structure
  343. serves as the return value for C<$cr-E<gt>copy_path_data> and
  344. C<$cr-E<gt>copy_path_data_flat> as well the input value for
  345. C<$cr-E<gt>append_path>.
  346.  
  347. I<Cairo::Path> is represented as an array reference that contains path
  348. elements, represented by hash references with two keys: I<type> and I<points>.
  349. The value for I<type> can be either of the following:
  350.  
  351. =over
  352.  
  353. =item C<move-to>
  354.  
  355. =item C<line-to>
  356.  
  357. =item C<curve-to>
  358.  
  359. =item C<close-path>
  360.  
  361. =back
  362.  
  363. The value for I<points> is an array reference which contains zero or more
  364. points.  Points are represented as array references that contain two doubles:
  365. I<x> and I<y>.  The necessary number of points depends on the I<type> of the
  366. path element:
  367.  
  368. =over
  369.  
  370. =item C<move-to>: 1 point
  371.  
  372. =item C<line_to>: 1 point
  373.  
  374. =item C<curve-to>: 3 points
  375.  
  376. =item C<close-path>: 0 points
  377.  
  378. =back
  379.  
  380. The semantics and ordering of the coordinate values are consistent with
  381. C<$cr-E<gt>move_to>, C<$cr-E<gt>line_to>, C<$cr-E<gt>curve_to>, and
  382. C<$cr-E<gt>close_path>.
  383.  
  384. =head4 $path = $cr->copy_path
  385.  
  386. =head4 $path = $cr->copy_path_flat
  387.  
  388. =head4 $cr->append_path ($path)
  389.  
  390. =over
  391.  
  392. =item $path: I<Cairo::Path>
  393.  
  394. =back
  395.  
  396. =head4 $bool = $cr->has_current_point [1.6]
  397.  
  398. =head4 ($x, $y) = $cr->get_current_point
  399.  
  400. =head4 $cr->new_path
  401.  
  402. =head4 $cr->new_sub_path [1.2]
  403.  
  404. =head4 $cr->close_path
  405.  
  406. =head4 ($x1, $y1, $x2, $y2) = $cr->path_extents [1.6]
  407.  
  408. =head4 $cr->arc ($xc, $yc, $radius, $angle1, $angle2)
  409.  
  410. =over
  411.  
  412. =item $xc: double
  413.  
  414. =item $yc: double
  415.  
  416. =item $radius: double
  417.  
  418. =item $angle1: double
  419.  
  420. =item $angle2: double
  421.  
  422. =back
  423.  
  424. =head4 $cr->arc_negative ($xc, $yc, $radius, $angle1, $angle2)
  425.  
  426. =over
  427.  
  428. =item $xc: double
  429.  
  430. =item $yc: double
  431.  
  432. =item $radius: double
  433.  
  434. =item $angle1: double
  435.  
  436. =item $angle2: double
  437.  
  438. =back
  439.  
  440. =head4 $cr->curve_to ($x1, $y1, $x2, $y2, $x3, $y3)
  441.  
  442. =over
  443.  
  444. =item $x1: double
  445.  
  446. =item $y1: double
  447.  
  448. =item $x2: double
  449.  
  450. =item $y2: double
  451.  
  452. =item $x3: double
  453.  
  454. =item $y3: double
  455.  
  456. =back
  457.  
  458. =head4 $cr->line_to ($x, $y)
  459.  
  460. =over
  461.  
  462. =item $x: double
  463.  
  464. =item $y: double
  465.  
  466. =back
  467.  
  468. =head4 $cr->move_to ($x, $y)
  469.  
  470. =over
  471.  
  472. =item $x: double
  473.  
  474. =item $y: double
  475.  
  476. =back
  477.  
  478. =head4 $cr->rectangle ($x, $y, $width, $height)
  479.  
  480. =over
  481.  
  482. =item $x: double
  483.  
  484. =item $y: double
  485.  
  486. =item $width: double
  487.  
  488. =item $height: double
  489.  
  490. =back
  491.  
  492. =head4 $cr->glyph_path (...)
  493.  
  494. =over
  495.  
  496. =item ...: list of I<Cairo::Glyph>'s
  497.  
  498. =back
  499.  
  500. =head4 $cr->text_path ($utf8)
  501.  
  502. =over
  503.  
  504. =item $utf8: string in utf8 encoding
  505.  
  506. =back
  507.  
  508. =head4 $cr->rel_curve_to ($dx1, $dy1, $dx2, $dy2, $dx3, $dy3)
  509.  
  510. =over
  511.  
  512. =item $dx1: double
  513.  
  514. =item $dy1: double
  515.  
  516. =item $dx2: double
  517.  
  518. =item $dy2: double
  519.  
  520. =item $dx3: double
  521.  
  522. =item $dy3: double
  523.  
  524. =back
  525.  
  526. =head4 $cr->rel_line_to ($dx, $dy)
  527.  
  528. =over
  529.  
  530. =item $dx: double
  531.  
  532. =item $dy: double
  533.  
  534. =back
  535.  
  536. =head4 $cr->rel_move_to ($dx, $dy)
  537.  
  538. =over
  539.  
  540. =item $dx: double
  541.  
  542. =item $dy: double
  543.  
  544. =back
  545.  
  546. =cut
  547.  
  548. # --------------------------------------------------------------------------- #
  549.  
  550. =head3 Patterns -- Gradients and filtered sources
  551.  
  552. =head4 $status = $pattern->status
  553.  
  554. =head4 $type = $pattern->get_type [1.2]
  555.  
  556. =head4 $pattern->set_matrix ($matrix)
  557.  
  558. =over
  559.  
  560. =item $matrix: I<Cairo::Matrix>
  561.  
  562. =back
  563.  
  564. =head4 $matrix = $pattern->get_matrix
  565.  
  566. =head4 $pattern = Cairo::SolidPattern->create_rgb ($red, $green, $blue)
  567.  
  568. =over
  569.  
  570. =item $red: double
  571.  
  572. =item $green: double
  573.  
  574. =item $blue: double
  575.  
  576. =back
  577.  
  578. =head4 $pattern = Cairo::SolidPattern->create_rgba ($red, $green, $blue, $alpha)
  579.  
  580. =over
  581.  
  582. =item $red: double
  583.  
  584. =item $green: double
  585.  
  586. =item $blue: double
  587.  
  588. =item $alpha: double
  589.  
  590. =back
  591.  
  592. =head4 ($r, $g, $b, $a) = $pattern->get_rgba [1.4]
  593.  
  594. =head4 $pattern = Cairo::SurfacePattern->create ($surface)
  595.  
  596. =over
  597.  
  598. =item $surface: I<Cairo::Surface>
  599.  
  600. =back
  601.  
  602. =head4 $pattern->set_extend ($extend)
  603.  
  604. =over
  605.  
  606. =item $extend: I<Cairo::Extend>
  607.  
  608. =back
  609.  
  610. =head4 $extend = $pattern->get_extend
  611.  
  612. =head4 $pattern->set_filter ($filter)
  613.  
  614. =over
  615.  
  616. =item $filter: I<Cairo::Filter>
  617.  
  618. =back
  619.  
  620. =head4 $filter = $pattern->get_filter
  621.  
  622. =head4 $surface = $pattern->get_surface [1.4]
  623.  
  624. =head4 $pattern = Cairo::LinearGradient->create ($x0, $y0, $x1, $y1)
  625.  
  626. =over
  627.  
  628. =item $x0: double
  629.  
  630. =item $y0: double
  631.  
  632. =item $x1: double
  633.  
  634. =item $y1: double
  635.  
  636. =back
  637.  
  638. =head4 ($x0, $y0, $x1, $y1) = $pattern->get_points [1.4]
  639.  
  640. =head4 $pattern = Cairo::RadialGradient->create ($cx0, $cy0, $radius0, $cx1, $cy1, $radius1)
  641.  
  642. =over
  643.  
  644. =item $cx0: double
  645.  
  646. =item $cy0: double
  647.  
  648. =item $radius0: double
  649.  
  650. =item $cx1: double
  651.  
  652. =item $cy1: double
  653.  
  654. =item $radius1: double
  655.  
  656. =back
  657.  
  658. =head4 ($x0, $y0, $r0, $x1, $y1, $r1) = $pattern->get_circles [1.4]
  659.  
  660. =head4 $pattern->add_color_stop_rgb (double offset, double red, double green, double blue)
  661.  
  662. =over
  663.  
  664. =item $offset: double
  665.  
  666. =item $red: double
  667.  
  668. =item $green: double
  669.  
  670. =item $blue: double
  671.  
  672. =back
  673.  
  674. =head4 $pattern->add_color_stop_rgba (double offset, double red, double green, double blue, double alpha)
  675.  
  676. =over
  677.  
  678. =item $offset: double
  679.  
  680. =item $red: double
  681.  
  682. =item $green: double
  683.  
  684. =item $blue: double
  685.  
  686. =item $alpha: double
  687.  
  688. =back
  689.  
  690. =head4 @stops = $pattern->get_color_stops [1.4]
  691.  
  692. A color stop is represented as an array reference with five elements: offset,
  693. red, green, blue, and alpha.
  694.  
  695. =cut
  696.  
  697. # --------------------------------------------------------------------------- #
  698.  
  699. =head3 Transformations -- Manipulating the current transformation matrix
  700.  
  701. =head4 $cr->translate ($tx, $ty)
  702.  
  703. =over
  704.  
  705. =item $tx: double
  706.  
  707. =item $ty: double
  708.  
  709. =back
  710.  
  711. =head4 $cr->scale ($sx, $sy)
  712.  
  713. =over
  714.  
  715. =item $sx: double
  716.  
  717. =item $sy: double
  718.  
  719. =back
  720.  
  721. =head4 $cr->rotate ($angle)
  722.  
  723. =over
  724.  
  725. =item $angle: double
  726.  
  727. =back
  728.  
  729. =head4 $cr->transform ($matrix)
  730.  
  731. =over
  732.  
  733. =item $matrix: I<Cairo::Matrix>
  734.  
  735. =back
  736.  
  737. =head4 $cr->set_matrix ($matrix)
  738.  
  739. =over
  740.  
  741. =item $matrix: I<Cairo::Matrix>
  742.  
  743. =back
  744.  
  745. =head4 $matrix = $cr->get_matrix
  746.  
  747. =head4 $cr->identity_matrix
  748.  
  749. =head4 ($x, $y) = $cr->user_to_device ($x, $y)
  750.  
  751. =over
  752.  
  753. =item $x: double
  754.  
  755. =item $y: double
  756.  
  757. =back
  758.  
  759. =head4 ($dx, $dy) = $cr->user_to_device_distance ($dx, $dy)
  760.  
  761. =over
  762.  
  763. =item $dx: double
  764.  
  765. =item $dy: double
  766.  
  767. =back
  768.  
  769. =head4 ($x, $y) = $cr->device_to_user ($x, $y)
  770.  
  771. =over
  772.  
  773. =item $x: double
  774.  
  775. =item $y: double
  776.  
  777. =back
  778.  
  779. =head4 ($dx, $dy) = $cr->device_to_user_distance ($dx, $dy)
  780.  
  781. =over
  782.  
  783. =item $dx: double
  784.  
  785. =item $dy: double
  786.  
  787. =back
  788.  
  789. =cut
  790.  
  791. # --------------------------------------------------------------------------- #
  792.  
  793. =head3 Text -- Rendering text and sets of glyphs
  794.  
  795. Glyphs are represented as anonymous hash references with three keys: I<index>,
  796. I<x> and I<y>.  Example:
  797.  
  798.   my @glyphs = ({ index => 1, x => 2, y => 3 },
  799.                 { index => 2, x => 3, y => 4 },
  800.                 { index => 3, x => 4, y => 5 });
  801.  
  802. =head4 $cr->select_font_face ($family, $slant, $weight)
  803.  
  804. =over
  805.  
  806. =item $family: string
  807.  
  808. =item $slant: I<Cairo::FontSlant>
  809.  
  810. =item $weight: I<Cairo::FontWeight>
  811.  
  812. =back
  813.  
  814. =head4 $cr->set_font_size ($size)
  815.  
  816. =over
  817.  
  818. =item $size: double
  819.  
  820. =back
  821.  
  822. =head4 $cr->set_font_matrix ($matrix)
  823.  
  824. =over
  825.  
  826. =item $matrix: I<Cairo::Matrix>
  827.  
  828. =back
  829.  
  830. =head4 $matrix = $cr->get_font_matrix
  831.  
  832. =head4 $cr->set_font_options ($options)
  833.  
  834. =over
  835.  
  836. =item $options: I<Cairo::FontOptions>
  837.  
  838. =back
  839.  
  840. =head4 $options = $cr->get_font_options
  841.  
  842. =head4 $cr->set_scaled_font ($scaled_font) [1.2]
  843.  
  844. =over
  845.  
  846. =item $scaled_font: I<Cairo::ScaledFont>
  847.  
  848. =back
  849.  
  850. =head4 $scaled_font = $cr->get_scaled_font [1.4]
  851.  
  852. =head4 $cr->show_text ($utf8)
  853.  
  854. =over
  855.  
  856. =item $utf8: string
  857.  
  858. =back
  859.  
  860. =head4 $cr->show_glyphs (...)
  861.  
  862. =over
  863.  
  864. =item ...: list of glyphs
  865.  
  866. =back
  867.  
  868. =head4 $face = $cr->get_font_face
  869.  
  870. =head4 $extents = $cr->font_extents
  871.  
  872. =head4 $cr->set_font_face ($font_face)
  873.  
  874. =over
  875.  
  876. =item $font_face: I<Cairo::FontFace>
  877.  
  878. =back
  879.  
  880. =head4 $cr->set_scaled_font ($scaled_font)
  881.  
  882. =over
  883.  
  884. =item $scaled_font: I<Cairo::ScaledFont>
  885.  
  886. =back
  887.  
  888. =head4 $extents = $cr->text_extents ($utf8)
  889.  
  890. =over
  891.  
  892. =item $utf8: string
  893.  
  894. =back
  895.  
  896. =head4 $extents = $cr->glyph_extents (...)
  897.  
  898. =over
  899.  
  900. =item ...: list of glyphs
  901.  
  902. =back
  903.  
  904. =cut
  905.  
  906. # --------------------------------------------------------------------------- #
  907.  
  908. =head2 Fonts
  909.  
  910. =head3 Cairo::FontFace -- Base class for fonts
  911.  
  912. =head4 $status = $font_face->status
  913.  
  914. =head4 $type = $font_face->get_type [1.2]
  915.  
  916. =cut
  917.  
  918. # --------------------------------------------------------------------------- #
  919.  
  920. =head3 Scaled Fonts -- Caching metrics for a particular font size
  921.  
  922. =head4 $scaled_font = Cairo::ScaledFont->create ($font_face, $font_matrix, $ctm, $options)
  923.  
  924. =over
  925.  
  926. =item $font_face: I<Cairo::FontFace>
  927.  
  928. =item $font_matrix: I<Cairo::Matrix>
  929.  
  930. =item $ctm: I<Cairo::Matrix>
  931.  
  932. =item $options: I<Cairo::FontOptions>
  933.  
  934. =back
  935.  
  936. =head4 $status = $scaled_font->status
  937.  
  938. =head4 $extents = $scaled_font->extents
  939.  
  940. =head4 $extents = $scaled_font->text_extents ($utf8) [1.2]
  941.  
  942. =over
  943.  
  944. =item $utf8: string
  945.  
  946. =back
  947.  
  948. =head4 $extents = $scaled_font->glyph_extents (...)
  949.  
  950. =over
  951.  
  952. =item ...: list of glyphs
  953.  
  954. =back
  955.  
  956. =head4 $font_face = $scaled_font->get_font_face [1.2]
  957.  
  958. =head4 $options = $scaled_font->get_font_options [1.2]
  959.  
  960. =head4 $font_matrix = $scaled_font->get_font_matrix [1.2]
  961.  
  962. =head4 $ctm = $scaled_font->get_ctm [1.2]
  963.  
  964. =head4 $type = $scaled_font->get_type [1.2]
  965.  
  966. =cut
  967.  
  968. # --------------------------------------------------------------------------- #
  969.  
  970. =head3 Font Options -- How a font should be rendered
  971.  
  972. =head4 $font_options = Cairo::FontOptions->create
  973.  
  974. =head4 $status = $font_options->status
  975.  
  976. =head4 $font_options->merge ($other)
  977.  
  978. =over
  979.  
  980. =item $other: I<Cairo::FontOptions>
  981.  
  982. =back
  983.  
  984. =head4 $hash = $font_options->hash
  985.  
  986. =head4 $bools = $font_options->equal ($other)
  987.  
  988. =over
  989.  
  990. =item $other: I<Cairo::FontOptions>
  991.  
  992. =back
  993.  
  994. =head4 $font_options->set_antialias ($antialias)
  995.  
  996. =over
  997.  
  998. =item $antialias: I<Cairo::AntiAlias>
  999.  
  1000. =back
  1001.  
  1002. =head4 $antialias = $font_options->get_antialias
  1003.  
  1004. =head4 $font_options->set_subpixel_order ($subpixel_order)
  1005.  
  1006. =over
  1007.  
  1008. =item $subpixel_order: I<Cairo::SubpixelOrder>
  1009.  
  1010. =back
  1011.  
  1012. =head4 $subpixel_order = $font_options->get_subpixel_order
  1013.  
  1014. =head4 $font_options->set_hint_style ($hint_style)
  1015.  
  1016. =over
  1017.  
  1018. =item $hint_style: I<Cairo::HintStyle>
  1019.  
  1020. =back
  1021.  
  1022. =head4 $hint_style = $font_options->get_hint_style
  1023.  
  1024. =head4 $font_options->set_hint_metrics ($hint_metrics)
  1025.  
  1026. =over
  1027.  
  1028. =item $hint_metrics: I<Cairo::HintMetrics>
  1029.  
  1030. =back
  1031.  
  1032. =head4 $hint_metrics = $font_options->get_hint_metrics
  1033.  
  1034. =cut
  1035.  
  1036. # --------------------------------------------------------------------------- #
  1037.  
  1038. =head3 FreeType Fonts -- Font support for FreeType
  1039.  
  1040. If your cairo library supports it, the FreeType integration allows you to load
  1041. font faces from font files.  You can query for this capability with
  1042. C<Cairo::HAS_FT_FONT>.  To actually use this, you'll need the L<Font::FreeType>
  1043. module.
  1044.  
  1045. =head4 my $face = Cairo::FtFontFace->create ($ft_face, $load_flags=0)
  1046.  
  1047. =over
  1048.  
  1049. =item $ft_face: I<Font::FreeType::Face>
  1050.  
  1051. =item $load_flags: integer
  1052.  
  1053. =back
  1054.  
  1055. This method allows you to create a I<Cairo::FontFace> from a
  1056. I<Font::FreeType::Face>.  To obtain the latter, you can for example load it
  1057. from a file:
  1058.  
  1059.   my $file = '/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf';
  1060.   my $ft_face = Font::FreeType->new->face ($file);
  1061.   my $face = Cairo::FtFontFace->create ($ft_face);
  1062.  
  1063. =cut
  1064.  
  1065. # --------------------------------------------------------------------------- #
  1066.  
  1067. =head2 Surfaces
  1068.  
  1069. =head3 I<Cairo::Surface> -- Base class for surfaces
  1070.  
  1071. =head4 $new = $old->create_similar ($content, $width, $height)
  1072.  
  1073. =over
  1074.  
  1075. =item $content: I<Cairo::Content>
  1076.  
  1077. =item $width: integer
  1078.  
  1079. =item $height: integer
  1080.  
  1081. =back
  1082.  
  1083. =head4 $status = $surface->status
  1084.  
  1085. =head4 $surface->finish
  1086.  
  1087. =head4 $surface->flush
  1088.  
  1089. =head4 $font_options = $surface->get_font_options
  1090.  
  1091. =head4 $content = $surface->get_content [1.2]
  1092.  
  1093. =head4 $surface->mark_dirty
  1094.  
  1095. =head4 $surface->mark_dirty_rectangle ($x, $y, $width, $height)
  1096.  
  1097. =over
  1098.  
  1099. =item $x: integer
  1100.  
  1101. =item $y: integer
  1102.  
  1103. =item $width: integer
  1104.  
  1105. =item $height: integer
  1106.  
  1107. =back
  1108.  
  1109. =head4 $surface->set_device_offset ($x_offset, $y_offset)
  1110.  
  1111. =over
  1112.  
  1113. =item $x_offset: integer
  1114.  
  1115. =item $y_offset: integer
  1116.  
  1117. =back
  1118.  
  1119. =head4 ($x_offset, $y_offset) = $surface->get_device_offset [1.2]
  1120.  
  1121. =head4 $surface->set_fallback_resolution ($x_pixels_per_inch, $y_pixels_per_inch) [1.2]
  1122.  
  1123. =over
  1124.  
  1125. =item $x_pixels_per_inch: double
  1126.  
  1127. =item $y_pixels_per_inch: double
  1128.  
  1129. =back
  1130.  
  1131. =head4 $type = $surface->get_type [1.2]
  1132.  
  1133. =head4 $status = $surface->copy_page [1.6]
  1134.  
  1135. =over
  1136.  
  1137. =item $status: I<Cairo::Status>
  1138.  
  1139. =back
  1140.  
  1141. =head4 $status = $surface->show_page [1.6]
  1142.  
  1143. =over
  1144.  
  1145. =item $status: I<Cairo::Status>
  1146.  
  1147. =back
  1148.  
  1149. =cut
  1150.  
  1151. # --------------------------------------------------------------------------- #
  1152.  
  1153. =head3 Image Surfaces -- Rendering to memory buffers
  1154.  
  1155. =head4 $surface = Cairo::ImageSurface->create ($format, $width, $height)
  1156.  
  1157. =over
  1158.  
  1159. =item $format: I<Cairo::Format>
  1160.  
  1161. =item $width: integer
  1162.  
  1163. =item $height: integer
  1164.  
  1165. =back
  1166.  
  1167. =head4 $surface = Cairo::ImageSurface->create_for_data ($data, $format, $width, $height, $stride)
  1168.  
  1169. =over
  1170.  
  1171. =item $data: image data
  1172.  
  1173. =item $format: I<Cairo::Format>
  1174.  
  1175. =item $width: integer
  1176.  
  1177. =item $height: integer
  1178.  
  1179. =item $stride: integer
  1180.  
  1181. =back
  1182.  
  1183. =head4 $data = $surface->get_data [1.2]
  1184.  
  1185. =head4 $format = $surface->get_format [1.2]
  1186.  
  1187. =head4 $width = $surface->get_width
  1188.  
  1189. =head4 $height = $surface->get_height
  1190.  
  1191. =head4 $stride = $surface->get_stride [1.2]
  1192.  
  1193. =cut
  1194.  
  1195. # --------------------------------------------------------------------------- #
  1196.  
  1197. =head3 PDF Surfaces -- Rendering PDF documents
  1198.  
  1199. =head4 $surface = Cairo::PdfSurface->create ($filename, $width_in_points, $height_in_points) [1.2]
  1200.  
  1201. =over
  1202.  
  1203. =item $filename: string
  1204.  
  1205. =item $width_in_points: double
  1206.  
  1207. =item $height_in_points: double
  1208.  
  1209. =back
  1210.  
  1211. =head4 $surface = Cairo::PdfSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]
  1212.  
  1213. =over
  1214.  
  1215. =item $callback: L<Cairo::WriteFunc>
  1216.  
  1217. =item $callback_data: scalar
  1218.  
  1219. =item $width_in_points: double
  1220.  
  1221. =item $height_in_points: double
  1222.  
  1223. =back
  1224.  
  1225. =head4 $surface->set_size ($width_in_points, $height_in_points) [1.2]
  1226.  
  1227. =over
  1228.  
  1229. =item $width_in_points: double
  1230.  
  1231. =item $height_in_points: double
  1232.  
  1233. =back
  1234.  
  1235. =cut
  1236.  
  1237. # --------------------------------------------------------------------------- #
  1238.  
  1239. =head3 PNG Support -- Reading and writing PNG images
  1240.  
  1241. =head4 $surface = Cairo::ImageSurface->create_from_png ($filename)
  1242.  
  1243. =over
  1244.  
  1245. =item $filename: string
  1246.  
  1247. =back
  1248.  
  1249. =head4 Cairo::ReadFunc: $data = sub { my ($callback_data, $length) = @_; }
  1250.  
  1251. =over
  1252.  
  1253. =item $data: binary image data, of length $length
  1254.  
  1255. =item $callback_data: scalar, user data
  1256.  
  1257. =item $length: integer, bytes to read
  1258.  
  1259. =back
  1260.  
  1261. =head4 $surface = Cairo::ImageSurface->create_from_png_stream ($callback, $callback_data)
  1262.  
  1263. =over
  1264.  
  1265. =item $callback: L<Cairo::ReadFunc>
  1266.  
  1267. =item $callback_data: scalar
  1268.  
  1269. =back
  1270.  
  1271. =head4 $status = $surface->write_to_png ($filename)
  1272.  
  1273. =over
  1274.  
  1275. =item $filename: string
  1276.  
  1277. =back
  1278.  
  1279. =head4 Cairo::WriteFunc: sub { my ($callback_data, $data) = @_; }
  1280.  
  1281. =over
  1282.  
  1283. =item $callback_data: scalar, user data
  1284.  
  1285. =item $data: binary image data, to be written
  1286.  
  1287. =back
  1288.  
  1289. =head4 $status = $surface->write_to_png_stream ($callback, $callback_data)
  1290.  
  1291. =over
  1292.  
  1293. =item $callback: L<Cairo::WriteFunc>
  1294.  
  1295. =item $callback_data: scalar
  1296.  
  1297. =back
  1298.  
  1299. =cut
  1300.  
  1301. # --------------------------------------------------------------------------- #
  1302.  
  1303. =head3 PostScript Surfaces -- Rendering PostScript documents
  1304.  
  1305. =head4 $surface = Cairo::PsSurface->create ($filename, $width_in_points, $height_in_points) [1.2]
  1306.  
  1307. =over
  1308.  
  1309. =item $filename: string
  1310.  
  1311. =item $width_in_points: double
  1312.  
  1313. =item $height_in_points: double
  1314.  
  1315. =back
  1316.  
  1317. =head4 $surface = Cairo::PsSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]
  1318.  
  1319. =over
  1320.  
  1321. =item $callback: L<Cairo::WriteFunc>
  1322.  
  1323. =item $callback_data: scalar
  1324.  
  1325. =item $width_in_points: double
  1326.  
  1327. =item $height_in_points: double
  1328.  
  1329. =back
  1330.  
  1331. =head4 $surface->set_size ($width_in_points, $height_in_points) [1.2]
  1332.  
  1333. =over
  1334.  
  1335. =item $width_in_points: double
  1336.  
  1337. =item $height_in_points: double
  1338.  
  1339. =back
  1340.  
  1341. =head4 $surface->dsc_begin_setup [1.2]
  1342.  
  1343. =head4 $surface->dsc_begin_page_setup [1.2]
  1344.  
  1345. =head4 $surface->dsc_comment ($comment) [1.2]
  1346.  
  1347. =over
  1348.  
  1349. =item $comment: string
  1350.  
  1351. =back
  1352.  
  1353. =head4 $surface->restrict_to_level ($level) [1.6]
  1354.  
  1355. =over
  1356.  
  1357. =item $level: I<Cairo::PsLevel>
  1358.  
  1359. =back
  1360.  
  1361. =head4 @levels = Cairo::PsSurface::get_levels [1.6]
  1362.  
  1363. =head4 $string = Cairo::PsSurface::level_to_string ($level) [1.6]
  1364.  
  1365. =over
  1366.  
  1367. =item $level: I<Cairo::PsLevel>
  1368.  
  1369. =back
  1370.  
  1371. =head4 $surface->set_eps ($eps) [1.6]
  1372.  
  1373. =over
  1374.  
  1375. =item $eps: boolean
  1376.  
  1377. =back
  1378.  
  1379. =head4 $eps = $surface->get_eps [1.6]
  1380.  
  1381. =cut
  1382.  
  1383. # --------------------------------------------------------------------------- #
  1384.  
  1385. =head3 SVG Surfaces -- Rendering SVG documents
  1386.  
  1387. =head4 $surface = Cairo::SvgSurface->create ($filename, $width_in_points, $height_in_points) [1.2]
  1388.  
  1389. =over
  1390.  
  1391. =item $filename: string
  1392.  
  1393. =item $width_in_points: double
  1394.  
  1395. =item $height_in_points: double
  1396.  
  1397. =back
  1398.  
  1399. =head4 $surface = Cairo::SvgSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2]
  1400.  
  1401. =over
  1402.  
  1403. =item $callback: L<Cairo::WriteFunc>
  1404.  
  1405. =item $callback_data: scalar
  1406.  
  1407. =item $width_in_points: double
  1408.  
  1409. =item $height_in_points: double
  1410.  
  1411. =back
  1412.  
  1413. =head4 $surface->restrict_to_version ($version) [1.2]
  1414.  
  1415. =over
  1416.  
  1417. =item $version: I<Cairo::SvgVersion>
  1418.  
  1419. =back
  1420.  
  1421. =head4 @versions = Cairo::SvgSurface::get_versions [1.2]
  1422.  
  1423. =head4 $string = Cairo::SvgSurface::version_to_string ($version) [1.2]
  1424.  
  1425. =over
  1426.  
  1427. =item $version: I<Cairo::SvgVersion>
  1428.  
  1429. =back
  1430.  
  1431. =cut
  1432.  
  1433. # --------------------------------------------------------------------------- #
  1434.  
  1435. =head2 Utilities
  1436.  
  1437. =head3 Version Information -- Run-time and compile-time version checks.
  1438.  
  1439. =head4 $version = Cairo->version
  1440.  
  1441. =head4 $string = Cairo->version_string
  1442.  
  1443. =head4 $version_code = Cairo->VERSION
  1444.  
  1445. =head4 $version_code = Cairo->VERSION_ENCODE ($major, $minor, $micro)
  1446.  
  1447. =over
  1448.  
  1449. =item $major: integer
  1450.  
  1451. =item $minor: integer
  1452.  
  1453. =item $micro: integer
  1454.  
  1455. =back
  1456.  
  1457. =head4 $stride = Cairo::Format::stride_for_width ($format, $width) [1.6]
  1458.  
  1459. =over
  1460.  
  1461. =item $format: I<Cairo::Format>
  1462.  
  1463. =item $width: integer
  1464.  
  1465. =back
  1466.  
  1467. =cut
  1468.  
  1469. # --------------------------------------------------------------------------- #
  1470.  
  1471. =head1 SEE ALSO
  1472.  
  1473. =over
  1474.  
  1475. =item http://cairographics.org/documentation
  1476.  
  1477. Lists many available resources including tutorials and examples
  1478.  
  1479. =item http://cairographics.org/manual/
  1480.  
  1481. Contains the reference manual
  1482.  
  1483. =back
  1484.  
  1485. =head1 AUTHORS
  1486.  
  1487. =over
  1488.  
  1489. =item Ross McFarland E<lt>rwmcfa1 at neces dot comE<gt>
  1490.  
  1491. =item Torsten Schoenfeld E<lt>kaffeetisch at gmx dot deE<gt>
  1492.  
  1493. =back
  1494.  
  1495. =head1 COPYRIGHT
  1496.  
  1497. Copyright (C) 2004-2008 by the cairo perl team
  1498.  
  1499. =cut
  1500.