=pod

=head1 NAME

SDL::Pango - Text rendering engine

=head1 CATEGORY

Pango

=head1 SYNOPSIS

 use SDL;
 use SDL::Color;
 use SDL::Surface;
 use SDL::Overlay;
 use SDL::Rect;
 use SDL::Video;
 use SDL::PixelFormat;
 use SDL::Pango;
 use SDL::Pango::Context;
 
 SDL::Pango::init();
 
 my $context = SDL::Pango::Context->new;
 SDL::Pango::set_default_color($context, 0xA7C344FF, 0);
 SDL::Pango::set_markup($context, 'Hallo <b>W<span foreground="red">o</span><i>r</i><u>l</u>d</b>!', -1);

 SDL::init(SDL_INIT_VIDEO);
 
 my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
 my $bg      = SDL::Video::map_RGB($display->format, 0x12, 0x22, 0x45);
 SDL::Video::fill_rect($display, SDL::Rect->new(0, 0, 640, 480), $bg);

 my $surface = SDL::Pango::create_surface_draw($context);
 SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(0, 0, 640, 480));
 
 SDL::Video::update_rect($display, 0, 0, 0, 0);
 SDL::delay(2000);

=head1 CONSTANTS

The constants are exported by default. You can avoid this by doing:

 use SDL::Pango ();

and access them directly:

 SDL::Pango::SDLPANGO_DIRECTION_NEUTRAL;

or by choosing the export tags below:

Export tag: ':align'

=over 4

=item SDLPANGO_ALIGN_LEFT

Left alignment

=item SDLPANGO_ALIGN_CENTER

Centered

=item SDLPANGO_ALIGN_RIGHT

Right alignment

=back

Export tag: ':direction'

=over 4

=item SDLPANGO_DIRECTION_LTR

Left to right

=item SDLPANGO_DIRECTION_RTL

Right to left

=item SDLPANGO_DIRECTION_WEAK_LTR

Left to right (weak)

=item SDLPANGO_DIRECTION_WEAK_RTL

Right to left (weak)

=item SDLPANGO_DIRECTION_NEUTRAL

Neutral

=back

=head1 METHODS

=head2 init

 SDL::Pango::init();

Initialize the Glib and Pango API. This must be called before using other functions in this library, excepting L<SDL::Pango::was_init|SDL::Pango/"was_init">. 
SDL does not have to be initialized before this call.

Returns: always C<0>. 

=head2 was_init

 my $was_init = SDL::Pango::was_init();

Query the initilization status of the Glib and Pango API. You may, of course, use this before L<SDL::Pango::init|SDL::Pango/"init"> to avoid initilizing twice 
in a row.

Returns: Non-zero when already initialized. Zero when not initialized.
 
=head2 set_default_color

 SDL::Pango::set_default_color($context, $foreground, $background);
 SDL::Pango::set_default_color($context, $r1, $g1, $b1, $a1, $r2, $g2, $b2, $a2);

Sets default foreground and background color when rendering text and markup.

You can call it with either 2 color-parameters (32-bit RRGGBBAA values), or with 4 separate values for foreground and 4 separate values for 
background.

=head2 set_minimum_size

 SDL::Pango::set_minimum_size($context, $width, $height);

Sets the minimum size of the drawing rectangle.

=head2 set_text

 SDL::Pango::set_text($context, $text, $length);
 SDL::Pango::set_text($context, $text, $length, $alignment);

Set plain text to context. Text must be utf-8. C<$length> chars will be rendered, pass C<-1> to render the whole text.

C<$alignment> can be:

=over 4

=item *

SDLPANGO_ALIGN_LEFT (default)

=item *

SDLPANGO_ALIGN_CENTER

=item *

SDLPANGO_ALIGN_RIGHT

=back

=head2 set_markup

 SDL::Pango::set_markup($context, $text, $length);

Set markup text to context. Text must be utf-8. C<$length> chars will be rendered, pass C<-1> to render the whole text.

See L<PangoMarkupFormat|http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html> for a description about the markup format.

=head2 get_layout_width

 my $w = SDL::Pango::get_layout_width($context);

Returns the width of the resulting surface of the given text/markup for this context.

=head2 get_layout_height

 my $h = SDL::Pango::get_layout_height($context);

Returns the height of the resulting surface of the given text/markup for this context.

=head2 set_base_direction

 SDL::Pango::set_base_direction($context, $direction);

Sets the direction of the text to either left-to-right or right-to-left.

See L</CONSTANTS>.

=head2 set_dpi

 SDL::Pango::set_dpi($context, $dpi_x, $dpi_y);

Sets the DPI (dots per inch) for this context. Default is C<96>.

=head2 set_language

 SDL::Pango::set_language($context, $language);

Sets the language name for this context.

See L<ISO639-2|http://www.loc.gov/standards/iso639-2/php/code_list.php>.

Example:

 SDL::Pango::set_language($context, "en");

=head2 draw

 SDL::Pango::draw($context, $display, $x, $y);

Draws the text or markup to an existing surface at position C<$x>/C<$y>.

=head2 set_surface_create_args

 SDL::Pango::set_surface_create_args($context, $flags, $bits, $r_mask, $g_mask, $b_mask, $a_mask);

Sets the argumet that are used when creating a surface via L<SDL::Pango::create_surface_draw|SDL::Pango/"create_surface_draw">.

Example:

 SDL::Pango::set_surface_create_args(
     $context, 
     SDL_SWSURFACE, 
     32, 
     0xFF000000, 
     0x00FF0000, 
     0x0000FF00, 
     0x000000FF
 );

=head2 create_surface_draw

 my $surface = SDL::Pango::create_surface_draw($context);

Creates a new surface and draws the text/markup. You can specify the attributes of the surfaces using L<SDL::Pango::set_surface_create_args|SDL::Pango/"set_surface_create_args">.

=head1 AUTHORS

See L<SDL/AUTHORS>.

=head1 SEE ALSO

L<SDL::Pango::Context>, L<SDL::Video>, L<SDL::Surface>, L<SDL::TTF>

=cut