### ----------------------------------------------------
### -- Imlib2
### -- Licenses: Artistic-2.0
### -- Authors: Naoum Hankache, Henrique Dias
### -- File: lib/Imlib2.pod
### ----------------------------------------------------
### -- Chunk 2 of 3
 failure. If scale is set, it will scale the new image
to the new destination destination_width and destination_height whilst
cropping.

=head2 Image Modification.

Functions to modify the images.

=head3 image_flip

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my FlipMode $flip_mode = IMLIB_FLIP_HORIZONTAL;
	$im.image_flip($flip_mode);
	... some operations ...
	$im.free_image();

Parameters:

	FlipMode $flip_mode - The flip mode flag.

Flips/mirrors the current image.

=over 4

=item *

IMLIB_FLIP_HORIZONTAL - Flips/mirrors the current image horizontally

=item *

IMLIB_FLIP_VERTICAL - Flips/mirrors the current image vertically.

=item *

IMLIB_FLIP_DIAGONAL - Flips/mirrors the current image diagonally (good
                      for quick and dirty 90 degree rotations if used
                      before to after a horizontal or vertical flip).

=back

=head3 image_orientate

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my RotationMode $orientation = IMLIB_ROTATE_90_DEGREES;
	$im.image_orientate($orientation);
	... some operations ...
	$im.free_image();

Parameters:

	RotationMode $orientation - The rotation mode flag.

Performs 90 degree rotations on the current image.

=over 4

=item *

IMLIB_ROTATE_90_DEGREES - rotates clockwise by 90 degrees.

=item *

IMLIB_ROTATE_180_DEGREES - rotates clockwise by 180 degrees.

=item *

IMLIB_ROTATE_270_DEGREES - rotates clockwise by 270 degrees.

=back

=head3 image_tile

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my TileMode $flip_mode = IMLIB_TILE_HORIZONTAL;
	$im.image_tile($tile_mode);
	... some operations ...
	$im.free_image();

Parameters:

	TileMode $tile_mode - The tile mode flag.

Modifies an image so it will tile seamlessly if used as a tile (i.e.
drawn multiple times horizontally, vertically or both).

=over 4

=item *

IMLIB_TILE_HORIZONTAL - Drawn multiple times horizontally.

=item *

IMLIB_TILE_VERTICAL - Drawn multiple times vertically.

=item *

IMLIB_TILE_BOTH - Drawn multiple times horizontally and vertically.

=back

=head3 image_blur

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my Int $radius = 12;
	$im.image_blur($radius);
	... some operations ...
	$im.free_image();
	
Parameters:

	Int $radius = The radius (value between 0 and 128).

Blurs the current image. A radius value of 0 has no effect, 1 and above
determine the blur matrix radius that determine how much to blur the
image.

=head3 image_sharpen

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my Int $radius = 20;
	$im.image_sharpen($radius);
	... some operations ...
	$im.free_image();

Parameters:

	Int $radius = The radius (value between 0 and 128).

Sharpens the current image. The radius value affects how much to
sharpen by.

=head2 Fonts and text

Functions to handle the fonts and text that you use in the images.

=head3 load_font

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("t/fonts");
	my Str $font = "comic";
	my Int $size = 36;
	my Imlib2::Font $corefont = $im.load_font($font, $size);
	$corefont.context_set();
	... some operations ...
	$im.free_font();

Parameters:

	Str $font - The font name without ttf extension.
	Int $size - The font size in pixels.

Returns:

	Imlib2::Font $corefont - A valid font, otherwise NULL if no font found.

Loads a truetype font from the first directory in the font path that
contains that font. For example. If there is a font file called blum.ttf
somewhere in the font path you might use "blum" for font name and 20 to
load a 20 pixel sized font of blum. If the font cannot be found NULL is
returned.

=head3 free_font

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my Imlib2::Font $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	... some operations ...
	$im.free_font();

Removes the current font from any fallback chain it's in and frees it.

=head3 context_set

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	$im.free_font();

Parameters:

	Imlib2::Font $font - Current font. 

Sets the current font to use when rendering text. you should load the
font first with load_font().

=head3 text_draw

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Int $x = 10;
	my Int $y = 10;
	my Str $text = "perl6";
	$im.text_draw($x, $y, $text);

	# text_draw but with return metrics.	
	my %returned_metrics;
	$im.text_draw(10, 10, "perl6", %returned_metrics);
	say "The width of the string: " ~ %returned_metrics{'width'};
	say "The height of the string: " ~ %returned_metrics{'height'};
	say "The horizontal offset: " ~ %returned_metrics{'horizontal_advance'};
	say "The vertical offset: " ~ %returned_metrics{'vertical_advance'};

	$im.free_font();
	$im.free_image();

Parameters:

	Int $x - The x coordinate of the top left corner.
	Int $y - The y coordinate of the top left corner.
	Str $text - The text string.
	Hash returned_metrics - Hash with returned metrics of the string drawn.

Draws the string text using the current font on the current image at the
(x, y) location (x, y denoting the top left corner of the font string).
If the hash metrics is passed also returns the width and height of the
string drawn, and horizontal_advance returns the number of pixels you
should advance horizontally to draw another string (useful if you are
drawing a line of text word by word) and vertical_advance does the same
for the vertical direction (i.e. drawing text line by line).

=over 4

=item *

%returned_metrics{'width'} - The width of the string.

=item *

%returned_metrics{'height'} - The height of the string.

=item *

%returned_metrics{'horizontal_advance'} - The horizontal offset.

=item *

%returned_metrics{'vertical_advance'} - The vertical offset.

=back

=head3 get_text_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Str $text = "perl6";
	my ($width, $height) = $im.get_text_size($text);
	say "The width of the string: " ~ $width;
	say "The height of the string: " ~ $height;
	$im.free_font();

Parameters:

	Str $text - The text string.

Returns:

	Int $width - The width of the text.
	Int $height - The height of the text.

Gets the width and height in pixels the text string would use up if
drawn with the current font.

=head3 get_text_advance

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Str $text = "perl6";
	my ($horizontal_advance, $vertical_advance) = $im.get_text_advance($text);
	say "The horizontal offset: " ~ $horizontal_advance;
	say "The vertical offset: " ~ $vertical_advance;
	$im.free_font();

Parameters:

	Str $text - The text string.

Returns:

	Int $horizontal_advance - The horizontal offset.
	Int $vertical_advance - The vertical offset.

Gets the advance horizontally and vertically in pixels the next text
string would need to be placed at for the current font. The advances
are not adjusted for rotation so you will have to translate the advances
(which are calculated as if the text was drawn horizontally from left to
right) depending on the text orientation.

=head3 get_text_inset

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Str $text = "perl6";
	my Int $inset = $im.get_text_inset($text);
	say "The inset value of: " ~ $inset;
	$im.free_font();

Parameters:

	Str $text - The text string.

Returns:

	Int $inset - The inset value of.

Returns the inset of the first character of text in using the current
font and returns that value in pixels.

=head3 get_font_ascent

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Int $ascent = $im.get_font_ascent();
	say "The font's ascent: " ~ $ascent;
	$im.free_font();

Returns:

	Int $ascent - The font's ascent.

Returns the current font's ascent value in pixels.

=head3 get_font_descent

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Int $descent = $im.get_font_descent();
	say "The font's descent: " ~ $descent;
	$im.free_font();

Returns:

	Int $descent - The font's descent.

Returns the current font's descent value in pixels.

=head3 get_maximum_font_ascent

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Int $max_ascent = $im.get_maximum_font_ascent();
	say "The font's maximum ascent: " ~ $max_ascent;
	$im.free_font();

Returns:

	Int $max_ascent - The font's maximum ascent.

Returns the current font's maximum ascent extent.

=head3 get_maximum_font_descent

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	my Int $max_descent = $im.get_maximum_font_descent();
	say "The font's maximum descent: " ~ $max_descent;
	$im.free_font();

Returns:

	Int $max_descent - The font's maximum descent.

Returns the current font's maximum descent extent.

=head3 add_path_to_font_path

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Str $font_path = "/usr/share/fonts/corefonts";
	$im.add_path_to_font_path($font_path);
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	... some operations ...
	$im.free_font();

Parameters:

	Str $font_path - A directory path.

Adds the directory path to the end of the current list of directories
to scan for fonts.

=head3 remove_path_from_font_path

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Str $font_path = "/usr/share/fonts/corefonts";
	$im.add_path_to_font_path($font_path);
	my $corefont = $im.load_font("comic", 36);
	$corefont.context_set();
	... some operations ...
	$im.remove_path_from_font_path($font_path);
	$im.free_font();

Parameters:

	Str $font_path - A directory path.

Removes all directories in the font path that match path.

=head3 list_font_path

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("fonts/localfonts");
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my @list = $im.list_font_path();
	say "Number of paths in the list: " ~ @list.elems;
	say "List of directories:\n" ~ @list.join("\n");

	# Number of paths in the list: 2
	# List of directories:
	# fonts/localfonts
	# /usr/share/fonts/corefonts
	... some operations ...

Returns:

	Array @list - A list of strings paths.

Returns a list of strings that are the directories in the font path.

=head3 list_fonts

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.add_path_to_font_path("/usr/share/fonts/corefonts");
	my @list = $im.list_font();
	say "Number of fonts in the list: " ~ @list.elems;
	say "List of fonts:\n" ~ @list.join("\n");

	# Number of fonts in the list: 30
	# List of fonts:
	# comic
	# andalemo
	# arial
	# arialbd
	# arialbi 
	# ...

	... some operations ...

Returns:

	Array @list - A list of strings fonts.

Returns a list of fonts imlib2 can find in its font path.

=head3 set_font_cache_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Int $bytes = 512 * 1024;
	$im.set_font_cache_size($bytes);
	... some operations ...

Parameters:

	Int $bytes - The font cache size in bytes.

Sets the font cache in bytes. Whenever you set the font cache size
Imlib2 will flush fonts from the cache until the memory used by fonts
is less than or equal to the font cache size. Setting the size to 0
effectively frees all speculatively cached fonts.

=head3 get_font_cache_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Int $bytes = $im.get_font_cache_size();
	... some operations ...

Returns:

	Int $bytes - The font cache size in bytes.

Returns the font cache size in bytes.

=head3 flush_font_cache

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.flush_font_cache();
	... some operations ...

Causes a flush of all speculatively cached fonts from the font cache.

=head2 Color modifiers

Imlib 2 also supports Color Modifier curves. You can pass any operation
through a color modifier table that can correct gamma, brightness and
contrast values of an image - as well as indepednantly being able to
determine the mapping tables of each R, G, B and A channel in an image.

=head3 create_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	# Create highlight color modifier
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	$im.modify_color_modifier(brightness => 25);
	... some operations ...

Returns:

	Imlib2::ColorModifier $cm - Valid handle.

Creates a new empty color modifier and returns a valid handle on
success. NULL is returned on failure.

=head3 free_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	# Create highlight color modifier
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	$im.modify_color_modifier(brightness => 25);
	... some operations ...
	$im.free_color_modifier();

Frees the current color modifier. 

=head3 modify_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	$im.modify_color_modifier(
		gamma      => -50,
		brightness => 25,
		contrast   => 95);
	... some operations ...

Parameters:

	Int gamma - Value of gamma.
	Int brightness - Value of brightness.
	Int contrast - Value of contrast.

Modifies the current color modifier by adjusting the gamma, brightness
and contrast values. The color modifier is modified not set, so calling
this repeatedly has cumulative effects. The values ​​of the parameters are
applied in sequence, i.e., In the example, first the gamma is applied,
then the brightness and finally the contrast. You can change the
sequence and can even repeat the parameters. Example: brightness => 25,
contrast => -26, brightness => 62. The range of values goes from -127 to
127. A gamma of 0 is normal linear, 127 brightens and -127 darkens etc.
Brightness values of 0 do not affect anything. -127 will make things
completely black and 127 will make things all white. Values in-between
vary brightness linearly. Contrast of 0 does nothing. -127 will merge to
gray, 127 will double contrast etc.

=head3 set_color_modifier_tables

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	# Initialize the array tables
	my (@red_table, @green_table, @blue_table, @alpha_table);
	loop (my $i = 0; $i <= 255; $i++) {
		@red_table[255-$i] = $i;
		@green_table[255-$i] = $i;
		@blue_table[255-$i] = $i;
		@alpha_table[$i] = 127;
	}
	$im.set_color_modifier_tables(
		@red_table,
		@green_table,
		@blue_table,
		@alpha_table);
	$im.apply_color_modifier();
	... some operations ...

Parameters:

	@red_table - An array of Int.
	@green_table - An array of Int.
	@blue_table - An array of Int.
	@alpha_table - An array of Int.

Explicitly copies the mapping tables from the table pointers passed into
this function into those of the current color modifier. Internally,
tables are 256 entry arrays of DATA8 which are a mapping of that channel
value to a new channel value. A normal mapping would be linear
(v[0] = 0, v[10] = 10, v[50] = 50, v[200] = 200, v[255] = 255).

=head3 get_color_modifier_tables

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	# Initialize the array tables
	my @red_table = ();
	@red_table[$_] = 0 for 0..255;
	my @alpha_table = my @blue_table = my @green_table = @red_table;
	$im.get_color_modifier_tables(
		@red_table,
		@green_table,
		@blue_table,
		@alpha_table);
	... some operations ...

Parameters:

	@red_table - An array of Int.
	@green_table - An array of Int.
	@blue_table - An array of Int.
	@alpha_table - An array of Int.

Internally, copies the table values from the current color modifier into
the pointers to mapping tables specified. They must have 256 entries and
be DATA8 format.

=head3 reset_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	# Create highlight color modifier
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	$im.reset_color_modifier();
	$im.modify_color_modifier(gamma => 75);
	... some operations ...
	$im.free_color_modifier();

Resets the current color modifier to have linear mapping tables.

=head3 apply_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $cm = $im.create_color_modifier();
	$cm.context_set_color_modifier();
	$im.modify_color_modifier(brightness => 25);
	$im.apply_color_modifier(
		location => (20, 20),
		size     => (200, 200)
	);
	... some operations ...

Parameters:

	location - The top left Int x and Int y coordinates of the rectangle.
	size - List with the Int width and the Int height of the rectangle.

Uses the current color modifier and modifies the current image using the
mapping tables in the current color modifier. If the parameters are
provided only modifies a selected rectangle in the current image,
otherwise applies to the entire image.

=head2 Drawing on images.

Functions for drawing points, lines and rectangles.

=head3 image_draw_pixel

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(200, 200);
	$image.context_set();
	$im.context_set_color("#ff0000");
	my ($x, $y) = (10, 10);
	my $update = False;
	my Imlib2::Updates $updates = $im.image_draw_pixel($x, $y, $update);
	... some operations ...
	$im.free_image();

Parameters:

	Int $x - The x coordinate of the pixel. 
	Int $y - The y coordinate of the pixel.
	Bool $update - True if should returns an updates list object, False
	               if not. This parameter is optional.

Returns:

	Imlib2::Updates $updates - An object to handle the updates list.

Draws a pixel using the current color on the current image at ($x, $y)
coordinates. If the B<update> parameter is set to True it will also
return an update you can use for an updates list, otherwise it returns
NULL.

=head3 image_draw_line

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(200, 200);
	$image.context_set();
	$im.context_set_color("#ff0000");
	my Imlib2::Updates $updates = $im.image_draw_line(
		start => (10, 20),
		end   => (180, 190),
		update => False);
	... some operations ...
	$im.free_image();

Parameters:

	start - List with Int x and Int y coordinates of the first point.
	end - List with Int x and Int y coordinates of the second point.
	Bool update - True if should returns an updates list object, False if not.

Returns:

	Imlib2::Updates $updates - An object to handle the updates list.

Draws a line using the current color on the current image from B<start>
coordinates (x1, y1) to B<end> coordinates (x2, y2). If the B<update> option
is set to True it will also return an update you can use for an updates
list, otherwise it returns NULL.

=head3 image_draw_rectangle

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(200, 200);
	$image.context_set();
	$im.context_set_color("#00ff00");
	$im.image_draw_rectangle(
		location => (10, 10),
		size     => (100, 100),
		fill     => False,
		gradient => False,
		angle    => 0.0,
		hsva     => False);
	... some operations ...
	$im.free_image();

Parameters:

	location - The top left Int x and Int y coordinates of the rectangle.
	size - List with the Int width and the Int height of the rectangle.
	Bool fill - True if the rectangle should be filled, False if outlined.
	Bool gradient - True if the rectangle should be filled with a color
	                gradient, False if normal color.
	Rat angle - Angle of gradient.
	Bool hsva - The hsva option (True or False)

Draws the outline of a rectangle on the current image at the ($x, $y)
coordinates with a size of $width and $height pixels, using the current
color. Draws a filled rectangle on the current image if the fill option
is set to True.
If the fill and gradient option is set to True fills a rectangle of
width $width and height $height at the ($x, $y) location specified in
the current image with a linear gradient of the current color range at
an angle of angle degrees with 0 degrees being vertical from top to
bottom going clockwise from there. If the hsva option is set to True a
linear gradient in HSVA color space of the current color range is used.

=head2 Polygon

Functions to build and handle polygons.

=head3 polygon_new

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	my $polygon = $im.polygon_new();
	... some operations ...
	$polygon.free();
	$im.free_image();

Returns:

	Imlib2::Polygon $polygon - Polygon object.

Returns a new polygon object with no points set.

=head3 free

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	my $polygon = $im.polygon_new();
	... some operations ...
	$polygon.free();
	$im.free_image();

Frees a polygon object.

=head3 add_point

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	my $polygon = $im.polygon_new();
	my Int $x = 1;
	my Int $y = 1;
	$polygon.add_point($x, $y);
	$polygon.add_point($x+3, $y);
	$polygon.add_point($x+3, $y+2);
	$polygon.add_point($x+1, $y+3);
	... some operations ...
	$polygon.free();
	$im.free_image();

Parameters:

	Int $x - The x coordinate.
	Int $y - The y coordinate.

Adds the point (x, y) to the polygon $polygon. The point will be added
to the end of the polygon's internal point list. The points are drawn
in order, from the first to the last.

=head3 contains_point

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	my $polygon = $im.polygon_new();
	my Int $x = 2;
	my Int $y = 4;
	$polygon.add_point($x, $y);
	my Bool $test = $polygon.contains_point($x, $y);
	... some operations ...
	$polygon.free();
	$im.free_image();

Parameters:

	Int $x - The x coordinate.
	Int $y - The y coordinate.

Returns:

	my Bool $test - True if the point ($x, $y) is within the area,
	                otherwise False.

Returns True if the point (x, y) is within the area defined by the
polygon poly. Otherwise returns False.

=head3 get_bounds

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $polygon = $im.polygon_new();
	my @points = (
		 30,  30, # top left corner
		180,  10, # top right corner
		180, 180, # bottom right corner
		 60, 190  # bottom left corner
	);
	for @points -> Int $x, Int $y {
		$polygon.add_point($x, $y);
	}
	my ($px1, $py1, $px2, $py2) = $polygon.get_bounds();
	say "X coordinate of the upper left corner: " ~ $px1;
	say "Y coordinate of the upper left corner: " ~ $py1;
	say "X coordinate of the lower right corner: " ~ $px2;
	say "Y coordinate of the lower right corner: " ~ $py2;
	$polygon.free();

Returns:

	Int $px1 - X coordinate of the upper left corner.
	Int $py1 - Y coordinate of the upper left corner.
	Int $px2 - X coordinate of the lower right corner.
	Int $py2 - Y coordinate of the lower right corner.

Calculates the bounding area of the polygon poly. ($px1, $py1) defines
the upper left corner of the bounding box and ($px2, $py2) defines it's
lower right corner.

=head3 image_draw_polygon

Usage:

	use Imlib2;
	
	my $im = Imlib2.new();
	my $rawimage = $im.create_image(200, 200);
	$rawimage.context_set();
	my $polygon = $im.polygon_new();
	my @points = (
		 30,  30, # top left corner
		180,  10, # top right corner
		180, 180, # bottom right corner
		 60, 190  # bottom left corner
	);
	for @points -> Int $x, Int $y {
		$polygon.add_point($x, $y);
	}
	$im.context_set_color(0x000000ff);
	$im.image_draw_polygon(
		$polygon,
		closed => True,
		fill   => False );
	$polygon.free();
	$im.free_image();

Parameters:

	Imlib2::Polygon $polygon - A polygon.
	Bool fill - True if the polygon should be filled, False if outlined.
	Bool closed - Closed polygon flag (True or False).

Draws the polygon $polygon onto the current context image if fill option
is set to False otherwise fills the area defined by the polygon $polygon
if the fill is set to True. Points which have been added to the polygon
are drawn in sequence, first to last. The final point will be joined
with the first point if closed is True. Fills the area defined by the
polygon $polygon on the current context image with the current context
color.

=head2 Ellipse/Circumference

Functions to handle ellipses and circumferences.

=head3 image_draw_ellipse

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(200, 200);
	$image.context_set();
	$im.context_set_color(0x000000ff);
	my Int $xcenter = 100;
	my Int $ycenter = 100;
	my Int $hamplitude = 50;
	my Int $vamplitude = 50;
	my Bool $fill = False;
	$im.image_draw_ellipse(
		center    => ($xcenter, $ycenter),
		amplitude => ($hamplitude, $vamplitude)
		fill      => $fill);
	... some operations ...
	$im.free_image();
	
Parameters:

	Int $xcenter - The X coordinate of the center of the ellipse.
	Int $ycenter - The Y coordinate of the center of the ellipse.
	Int $hamplitude - The horizontal amplitude of the ellipse.
	Int $vamplitude - The vertical amplitude of the ellipse.
	Bool $fill - True if the ellipse should be filled, False if outlined.

Draws the outline of a ellipse on the current context image using the
current context color. If the $fill option is set to True fills an
ellipse on the current context image. The ellipse is defined as
(x-xcenter)^2/hamplitude^2 + (y-ycenter)^2/vamplitude^2 = 1. This means
that the point (xcenter, ycenter) marks the center of the ellipse,
a defines the horizontal amplitude of the ellipse, and vamplitude
defines the vertical amplitude.

=head3 image_draw_circumference

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(200, 200);
	$image.context_set();
	$im.context_set_color(0x000000ff);
	my Int $xcenter = 100;
	my Int $ycenter = 100;
	my Int $radius = 50;
	my Bool $fill = False;
	$im.image_draw_circumference(
		center => ($xcenter, $ycenter),
		radius => $radius
		fill   => $fill);
	... some operations ...
	$im.free_image();
	
Parameters:

	Int $xcenter - The X coordinate of the center of the circumference.
	Int $ycenter - The Y coordinate of the center of the circumference.
	Int $radius - The radius of the circumference.
	Bool $fill - True if the circumference should be filled, False if outlined.

Draws the outline of a circumference on the current image at the center
(xcenter, ycenter) coordinates with a radius, using the current color.
If the $fill option is set to True fills an circumference on the current
context image.

=head2 Color Ranges

Functions to build color gradients.

=head3 create_color_range

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Imlib2::ColorRange $color_range = $im.create_color_range();
	$color_range.context_set();
	... some operations ...
	$im.free_color_range();

Returns:

	Imlib2::ColorRange $color_range - Valid handle. 

Creates a new empty color range and returns a valid handle to that
color range.
	
Sets the current color range to use for rendering gradients.

=head3 free_color_range

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_range = $im.create_color_range();
	$color_range.context_set();
	... some operations ...
	$im.free_color_range();

Frees the current color range.

=head3 context_set

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_range = $im.create_color_range();
	$color_range.context_set();
	... some operations ...
	$im.free_color_range();

Parameters:

	Imlib2::ColorRange $color_range - Color range.

=head3 add_color_to_color_range

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_range = $im.create_color_range();
	$color_range.context_set();
	my Int $distance_away = 0;
	$im.add_color_to_color_range($distance_away);
	... some operations ...
	$im.free_color_range();

Parameters:

	Int $distance_away - Distance from the previous color.

Adds the current color to the current color range at a $distance_away
distance from the previous color in the range (if it's the first color
in the range this is irrelevant).

=head2 Saving.

Functions to save the current image.

=head3 save_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(100, 200);
	$image.context_set();
	$im.image_set