### ----------------------------------------------------
### -- Imlib2
### -- Licenses: Artistic-2.0
### -- Authors: Naoum Hankache, Henrique Dias
### -- File: lib/Imlib2.pod
### ----------------------------------------------------
### -- Chunk 1 of 3
=head1 NAME

Imlib2 - Perl 6 interface to the Imlib2 image library.

=head1 DESCRIPTION

Perl6 binding for Imlib2, a featureful and efficient image manipulation
library, which produces high quality, anti-aliased output. You will need
this library installed in order to use Image-Imlib2 (preferably a recent
version).

=head1 SYNOPSIS

	use Imlib2;

	my $im = Imlib2.new();
	# Create a new raw image.
	my $rawimage = $im.create_image(200, 200);
	exit() unless $rawimage;

	# Sets the current image Imlib2 will be using with its function calls.
	$rawimage.context_set();
	
	# Sets the color with which text, lines and rectangles are drawn when
	# being rendered onto an image.
	$im.context_set_color(
		red   => 255,
		green => 127,
		blue  => 0,
		alpha => 255);

	$im.image_draw_rectangle(
		location => (0, 0),
		size     => (200, 200),
		fill     => True);
	
	$im.image_set_format("png");
	unlink("images/test_imlib2.png") if "images/test_imlib2.png".IO ~~ :e;
	$im.save_image("images/test_imlib2.png");

	# Frees the image that is set as the current image in Imlib2's context. 
	$im.free_image();

	exit();

=head1 API REFRENCE

The perl6 API follows closely the C implementation.

=head2 Context setting/getting.

Functions to set/get values/properties to/from the current context image.

=head3 context_set_dither_mask

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $dither_mask = True;
	$im.context_set_cliprect($dither_mask);

Parameters:

	Bool $dither_mask - The dither mask flag (True or False).

Selects if, you are rendering to a mask, or producing pixmap masks from
images, if the mask is to be dithered or not. passing in True for
dither_mask means the mask pixmap will be dithered, False means it will
not be dithered.

=head3 context_get_dither_mask

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $dither_mask = $im.context_get_dither_mask();

Returns:

	Bool $dither_mask - The current dither mask flag (True or False).

Returns the current mode for dithering pixmap masks. True means
dithering is enabled and False means it is not.

=head3 context_set_anti_alias

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $anti_alias = True;
	$im.context_set_anti_alias($anti_alias);

Parameters:

	Bool $anti_alias - The anti alias flag (True or False).

Toggles "anti-aliased" scaling of images. This isn't quite correct since
it's actually super and sub pixel sampling that it turns on and off, but
anti-aliasing is used for having "smooth" edges to lines and shapes and
this means when images are scaled they will keep their smooth appearance.
Passing in True turns this on and False turns it off.

=head3 context_get_anti_alias

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $anti_alias = $im.context_get_anti_alias();

Returns:

	Bool $anti_alias - The current anti alias flag (True or False).

Returns if Imlib2 currently will smoothly scale images. True means it
will and False means it will not.

=head3 context_set_mask_alpha_threshold

Usage:
	
	use Imlib2;
	my $im = Imlib2.new();
	my Int $mask_alpha_threshold = 127;
	$im.context_set_mask_alpha_threshold($mask_alpha_threshold);

Parameters:

	Int $mask_alpha_threshold - The mask alpha threshold (values between 0 and 255).

Selects, if you are rendering to a mask, the alpha threshold above which
mask bits are set. The default mask alpha threshold is 128, meaning that
a mask bit will be set if the pixel alpha is >= 128.

=head3 context_get_mask_alpha_threshold

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Int $mask_alpha_threshold = $im.context_get_mask_alpha_threshold();

Returns:

	Int $mask_alpha_threshold - The current mask alpha threshold.

The current mask alpha threshold.

=head3 context_set_dither

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $dither = True;
	$im.context_set_dither($dither);

Parameters:

	Bool $dither - The dithering flag (True or False).

Sets the dithering flag for rendering to a drawable or when pixmaps are
produced. This affects the color image appearance by enabling dithering.
Dithering slows down rendering but produces considerably better results.
this option has no effect foe rendering in 24 bit and up, but in 16 bit
and lower it will dither, producing smooth gradients and much better
quality images. setting dither to True enables it and False disables it.

=head3 context_get_dither

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $dither = $im.context_get_dither();

Returns:

	Bool $dither - The current dithering flag (True or False). 

Returns if image data is rendered with dithering currently. True means
yes and False means no.

=head3 context_set_blend

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $blend = true;
	$im.context_set_blend($blend);

Parameters:

	Bool $blend - The blending flag (True or False).

When rendering an image to a drawable, Imlib2 is able to blend the
image directly onto the drawable during rendering. Setting this to True
will enable this. If the image has no alpha channel this has no effect.
Setting it to False will disable this.

=head3 context_get_blend

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $blend = $im.context_get_blend();

Returns:

	Bool $blend - The current blending flag (True or False).

Returns if Imlib2 will blend images onto a drawable whilst rendering to
that drawable. True means yes and False means no.

=head3 context_set

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_modifier = $im.create_color_modifier();
	$color_modifier.context_set();
	$im.free_color_modifier();

Parameters:

	Imlib2::ColorModifier $color_modifier - Current color modifier.

Sets the current color modifier used for rendering pixmaps or images to
a drawable or images onto other images. Color modifiers are lookup
tables that map the values in the red, green, blue and alpha channels
to other values in the same channel when rendering, allowing for fades,
color correction etc. to be done whilst rendering. pass in NULL as the
color_modifier to disable the color modifier for rendering.

=head3 context_get_color_modifier

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_modifier = $im.context_get_color_modifier();

Returns:

	Imlib2::ColorModifier $color_modifier - The current color modifier.

Returns the current color modifier being used.

=over 4

=item *

IMLIB_OP_COPY performs basic alpha blending: DST = (SRC * A) + (DST * (1 - A)).

=item *

IMLIB_OP_ADD does DST = DST + (SRC * A).

=item *

IMLIB_OP_SUBTRACT does DST = DST - (SRC * A).

=item *

IMLIB_OP_RESHADE does DST = DST + (((SRC - 0.5) / 2) * A).

=back

=head3 context_set_operation

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.context_set_operation(IMLIB_OP_COPY);

Parameters:

	OperationMode $operation - The current operation mode. 

When Imlib2 draws an image onto another or an image onto a drawable it
is able to do more than just blend the result on using the given alpha
channel of the image. It is also able to do saturating additive,
subtractive and a combination of the both (called reshade) rendering.
The default mode is IMLIB_OP_COPY. you can also set it to IMLIB_OP_ADD,
IMLIB_OP_SUBTRACT or IMLIB_OP_RESHADE. Use this function to set the
rendering operation.

=head3 context_get_operation

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	say "IMLIB_OP_ADD Operation mode" if $im.context_get_operation() == IMLIB_OP_ADD;

Returns:

	OperationMode $operation - The current operation mode.

Returns the current operation mode.

=head3 context_get_font

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $font = $im.context_get_font();

Returns:

	mlib2::Font $font - The current font.

Returns the current font.

=head3 context_set_direction

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.context_set_direction(IMLIB_TEXT_TO_RIGHT);

Parameters:

	TextDirection $text_direction - Text direction.

Sets the direction in which to draw text in terms of simple 90 degree
orientations or an arbitrary angle. The direction can be one of
IMLIB_TEXT_TO_RIGHT, IMLIB_TEXT_TO_LEFT, IMLIB_TEXT_TO_DOWN,
IMLIB_TEXT_TO_UP or IMLIB_TEXT_TO_ANGLE.
The default is IMLIB_TEXT_TO_RIGHT. If you use IMLIB_TEXT_TO_ANGLE,
you will also have to set the angle with context_set_angle().

=head3 context_get_direction

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	say "TEXT_TO RIGHT is the current direction of the text."
		if $im.context_get_direction() == TEXT_TO_RIGHT;

Returns:

	TextDirection $text_direction - The current direction of the text.

Returns the current direction to render text in.

=head3 context_set_angle

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Rat $angle = -45.0;
	$im.context_set_angle($angle);

Parameters:

	Rat $angle - Angle of the text strings.

Sets the angle at which text strings will be drawn if the text direction
has been set to TEXT_TO_ANGLE with context_set_direction().

=head3 context_get_angle

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Rat $angle = $im.context_get_angle();

Returns:

	Rat $angle - The current angle of the text strings.

Returns the current angle used to render text at if the direction is
TEXT_TO_ANGLE.

=head3 context_set_color

Usage:

	use Imlib2;
	my $im = Imlib2.new();

	# Color in RGBA space
	$im.context_set_color(
		red   => 127,
		green => 255,
		blue  => 127,
		alpha => 255);

	# Another way to setup the color channels.
	# This is like html color tags ("#RRGGBBAA").
	# RR - Red, GG - Green, BB - Blue, AA - Alpha.
	my Str $hex_str_color = "#ff00ffff";
	$im.context_set_color($hex_str_color);

	# Without the alpha color channel.
	# The default value of alpha is 255.
	my Str $hex_str_color_html = "#ff00ff";
	$im.context_set_color($hex_str_color_html);

	# You can even set a color in hexadecimal value.
	my Int $hex_num_color = 0xff00ffff;
	$im.context_set_color($hex_num_color);

	# Color in HSVA space
	$im.context_set_color(
		hue        => 180,
		saturation => 50,
		value      => 75,
		alpha      => 127);

	# Color in HLSA space
	$im.context_set_color(
		hue        => 180,
		lightness  => 75,
		saturation => 50,
		alpha      => 127);

	# Color in CMYA space
	$im.context_set_color(
		cyan    => 25,
		magenta => 125,
		yellow  => 200,
		alpha   => 255);

Parameters:

	Color in RGBA space
		Int red - Red channel of the current color (0 .. 255).
		Int green - Green channel of the current color (0 .. 255).
		Int blue - Blue channel of the current color (0 .. 255).
		Int alpha - Alpha channel of the current color (0 .. 255).

		Str $hex_str_color - Hexadecimal string like html color tags
		                     (#RRGGBBAA / #RRGGBB).
		Int $hex_num_color - Hexadecimal number like html color tags
		                     (0xRRGGBBAA).

	Color in HSVA space
		Int hue - Hue channel of the current color (0 .. 360).
		Int saturation - Saturation channel of the current color (0 .. 100).
		Int value - Value channel of the current color (0 .. 100).
		Int alpha - Alpha channel of the current color (0 .. 255).

	Color in HLSA space
		Int hue - Hue channel of the current color (0 .. 360).
		Int lightness - Lightness channel of the current color (0 .. 100).
		Int saturation - Saturation channel of the current color (0 .. 100).
		Int alpha - Alpha channel of the current color (0 .. 255).

	Color in CMYA space
		Int cyan - Cyan channel of the current color (0 .. 255).
		Int magenta - Magenta channel of the current color (0 .. 255).
		Int yellow - Yellow channel of the current color (0 .. 255).
		Int alpha - Alpha channel of the current color (0 .. 255).

Sets the color with which text, lines and rectangles are drawn when
being rendered onto an image. The values ​​depend on the selected color
space.

=head3 context_get_color

Usage:

	use Imlib2;
	my $im = Imlib2.new();

	# Color in RGBA space
	$im.context_get_color(
		red   => my $red = 0,
		green => my $green = 0,
		blue  => my $blue = 0,
		alpha => my $alpha = 0
	);
	say "Red: $red";
	say "Green: $green";
	say "Blue: $blue";
	say "Alpha: $alpha";

	say "Hex: " ~ $im.get_hex_color_code($red, $green, $blue, $alpha);

	# Color in HSVA space
	$im.context_get_color(
		hue        => my $hue = 0,
		saturation => my $saturation = 0,
		value      => my $value = 0,
		alpha      => $alpha = 0);

	# Color in HLSA space
	$im.context_get_color(
		hue        => my $hue = 0,
		lightness  => my $lightness = 0,
		saturation => my $saturation = 0,
		alpha      => $alpha = 0);

	# Color in CMYA space
	$im.context_get_color(
		cyan    => $cyan = 0,
		magenta => $magenta = 0,
		yellow  => $yellow = 0,
		alpha   => $alpha = 0);

Parameters:

	Color in RGBA space
		Int red is rw - Red channel of the current color.
		Int green is rw - Green channel of the current color.
		Int blue is rw - Blue channel of the current color.
		Int alpha is rw - Alpha channel of the current color.

	Color in HSVA space
		Int hue is rw - Hue channel of the current color.
		Int saturation is rw - Saturation channel of the current color.
		Int value is rw - Value channel of the current color.
		Int alpha is rw - Alpha channel of the current color.

	Color in HLSA space
		Int hue is rw - Hue channel of the current color.
		Int ligtness is rw - Ligtness channel of the current color.
		Int saturation is rw - Saturation channel of the current color.
		Int alpha is rw - Alpha channel of the current color.

	Color in CMYA space
		Int cyan is rw - Cyan channel of the current color.
		Int magenta is rw - Magenta channel of the current color.
		Int yellow is rw - Yellow channel of the current color.
		Int alpha is rw - Alpha channel of the current color.

The current color space for rendering text, rectangles and lines.

=head3 context_get_color_range

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $color_range = $im.context_get_color_range();
	
Returns:

	Imlib2::ColorRange $color_range - The current color range.

Returns the current color range being used for gradients.

=head3 context_set

Usage:

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

Parameters:

	Imlib2::Image $image - Current image.
	
Sets the current image Imlib2 will be using with its function calls.

=head3 context_get_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.context_get_image();
	
Returns:

	Imlib2::Image $image - The current image.

Returns the current context image.

=head3 context_set_cliprect

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.context_set_cliprect(
		x      => 0,
		y      => 0,
		width  => 100,
		height => 100);

Parameters:

	Int x - The top left x coordinate of the rectangle. 
	Int y - The top left y coordinate of the rectangle. 
	Int width - The width of the rectangle. 
	Int height - The height of the rectangle. 

Sets the rectangle of the current context.

=head3 context_get_cliprect

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.context_get_cliprect(
		x      => my $x = 0,
		y      => my $y = 0,
		width  => my $width = 0,
		height => my $height = 0);

	say "x: $x";
	say "y: $y";
	say "width: $width";
	say "height: $height";

Parameters:

	Int x is rw - The top left x coordinate of the rectangle. 
	Int y is rw - The top left y coordinate of the rectangle. 
	Int width is rw - The width of the rectangle. 
	Int height is rw - The height of the rectangle. 

The rectangle of the current context.

=head3 set_cache_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $bytes = 2048 * 1024;
	$im.set_cache_size($bytes);

Parameters:

	Int $bytes - Cache size.

Sets the cache size. The size is in bytes. Setting the cache size to 0
effectively flushes the cache and keeps the cache size at 0 until set
to another value. Whenever you set the cache size Imlib2 will flush as
many old images and pixmap from the cache as needed until the current
cache usage is less than or equal to the cache size.

=head3 get_cache_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $bytes = $im.get_cache_size();

Returns:

	Int $bytes - The current size of the image cache in bytes.

Returns the current size of the image cache in bytes. The cache is a
unified cache used for image data AND pixmaps.

=head3 set_color_usage

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $max = 256;
	$im.set_color_usage($max);

Parameters:

	Int $max - Maximum number of colors.

Sets the maximum number of colors you would like Imlib2 to allocate for
you when rendering. The default is 256. This has no effect in depths
greater than 8 bit.

=head3 get_color_usage

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $max = $im.get_color_usage();

Returns:

	Int $max - The current number of colors.

Gets the number of colors Imlib2 currently at a maximum is allowed to
allocate for rendering. The default is 256.

=head2 Loading Functions.

Functions to load existing images.

=head3 load_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	... some operations ...
	$im.free_image();
	
	# load image with returned error.
	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my LoadError $error_return;
	my $image = $im.load_image($file, $error_return);
	if $error_return == IMLIB_LOAD_ERROR_NONE {
		say "No error...";
		$image.context_set();
		... some operations ...
		$im.free_image();
	}

	# Another way to load an image.
	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image(
		filename    => $file,
		immediately => False,
		cache       => True);
	$image.context_set();
	... some operations ...
	$im.free_image();
	
Parameters:

	Str $file - Image file.
	LoadError $error_return - The returned error.

	Str filename - Image file.
	Bool cache - If False loads the image without looking in the cache first.
	Bool immediately - If True loads an image from disk located at the
	                   path specified by file. This forces the image data
	                   to be decoded at load time too, instead of decoding
	                   being deferred until it is needed.

Returns:

	Imlib2::Image $image - An image handle.

Loads an image from disk located at the path specified by file. Please
see the section L<How Image Loading Works|http://docs.enlightenment.org/api/imlib2/html/index.html#loading>
for more detail. Returns an image handle on success or NULL on failure.

=head3 free_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	... some operations ...
	my Bool $decache = False;
	$im.free_image() if $image.context_get_image($decache);

Parameters:

	Bool $decache - If is set to True removes image from the cache.
	
Frees the image that is set as the current image in Imlib2's context.

=head3 flush_loaders

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	$im.flush_loaders();

If you want Imlib2 to forcibly flush any cached loaders it has and
re-load them from disk (this is useful if the program just installed a
new loader and does not want to wait till Imlib2 deems it an optimal
time to rescan the loaders).

=head2 Query/Modify Image Parameters.

Functions to query and modify the image parameters, ie, set and get
information about the image.

=head3 image_get_width

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	my Int $width = $im.image_get_width();
	say "Width size: $width pixels";
	$im.free_image();

Returns:

	Int $width - The width in pixels of the current image.

Returns the width in pixels of the current image in Imlib2's context.

=head3 image_get_height

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	my Int $height = $im.image_get_height();
	say "Height size: $height pixels";
	$im.free_image();

Returns:

	Int $height - The height in pixels of the current image.

Returns the height in pixels of the current image in Imlib2's context.

=head3 image_get_size

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	my ($width, $height) = $im.image_get_size();
	say "Width size: " ~ $width ~ " pixels";
	say "Height size: " ~ $height ~ " pixels";
	$im.free_image();

Returns:

	Int ($width, $height) - List with size in pixels of the current 
	                        image (width, height).

Returns the size in pixels of the current image in Imlib2's context.

=head3 image_get_filename

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $im.load_image($file);
	$image.context_set();
	my Str $filename = $im.image_get_filename();
	say "My filename is: $filename";
	$im.free_image();

Returns:

	Str $filename - The current filename.

Returns the filename for the file that is set as the current context.
The string returned is only valid as long as no operations cause the
filename of the image to change. Saving the file with a different name
would cause this. It is suggested you duplicate the string if you wish
to continue to use the string for later processing.

=head3 image_set_has_alpha

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(100, 200);
	$image.context_set();
	my Bool $has_alpha = True;
	$im.image_set_has_alpha($has_alpha);
	... some operations ...
	$im.free_image();

Parameters:

	Bool $has_alpha - Alpha flag (True or False).

Sets the alpha flag for the current image. Set has_alpha to True to
enable the alpha channel in the current image, or False to disable it.

=head3 image_has_alpha

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.create_image(100, 200);
	$image.context_set();
	my Bool $has_alpha = $im.image_has_alpha();
	say "Alpha status: $has_alpha";
	... some operations ...
	$im.free_image();

Returns:

	Bool $has_alpha - Current alpha channel flag (True or False).

Returns True if the current context image has an alpha channel, or
False if it does not (the alpha data space is still there and
available - just "unused").

=head3 image_set_changes_on_disk

Usage:

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

By default Imlib2 will not check the timestamp of an image on disk and
compare it with the image in its cache - this is to minimize disk
activity when using the cache.

Call this function and it will flag the current context image as being
liable to change on disk and Imlib2 will check the timestamp of the
image file on disk and compare it with the cached image when it next
needs to use this image in the cache.

=head3 image_set_border

Usage:

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

	my $structure = Imlib2::Border.new(
		left   => 10,
		right  => 10,
		top    => 10,
		bottom => 10);
	my $border = $structure.init();

	$im.image_set_border($border);
	... some operations ...
	$im.free_image();

Parameters:

	OpaquePointer $border - The border of the image.

Sets the border of the current context image to the values contained in
the Imlib2::Border structure border points to.

=head3 image_get_border

Usage:

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

	my $structure = Imlib2::Border.new();
	my $border = $structure.init();

	$im.image_get_border($border);
	$structure.get($border);
	say "Left: " ~ $structure.left;
	say "Right: " ~ $structure.right;
	say "Top: " ~ $structure.top;
	say "Bottom: " ~ $structure.bottom;
	... some operations ...
	$im.free_image();

Parameters:

	OpaquePointer $border - The border of the image passed as argument.

Fills the Imlib2::Border structure to which border points to with the
values of the border of the current context image. The border is the
area at the edge of the image that does not scale with the rest of the
image when resized - the borders remain constant in size. This is
useful for scaling bevels at the edge of images differently to the
image center.

=head3 image_set_format

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my Str $format = "png";
	$im.image_set_format($format);
	... some operations ...
	$im.free_image();

Parameters:

	Str $format - Format of the image.

Sets the format of the current image. This is used for when you wish
to save an image in a different format that it was loaded in, or if the
image currently has no file format associated with it.

=head3 image_get_format

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $image = $im.load_image("pictures/holidays.jpeg");
	$image.context_set();
	my Str $format = $im.image_get_format();
	... some operations ...
	$im.free_image();

Returns:

	Str $format - Current image format.

Returns the current image's format.

=head3 image_set_irrelevant

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Bool $irrelevant = True;
	$im.image_set_irrelevant(
		format => True,
		border => False,
		alpha  => True);

Parameters:

	Bool format - Irrelevant format flag (True or False).
	Bool border - Irrelevant border flag (True or False).
	Bool alpha - Irrelevant alpha flag (True or False).

Sets if the format, border or alpha channel status value of the current
image (i.e. if there is or is not one) is irrelevant for caching
purposes - by default it is. pass irrelevant as True to make it
irrelevant and False to make it relevant for caching.

=head2 Rendering Functions.

Functions to blend multiple images.

=head3 blend_image_onto_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $parrot_img = $im.load_image("images/parrot.png");
	exit() unless $parrot_img;
	my $camelia_img = $im.load_image("images/camelia-logo.jpg");
	exit() unless $camelia_img;
	$parrot_img.context_set();

	$im.blend_image_onto_image(
		source       => (
			image    => $camelia_img,
			location => (0, 0),
			size     => (200, 200)
		),
		destination  => (
			location => (10, 10),
			size     => (261, 243)
		),
		merge_alpha  => True);

	$im.free_image(); # frees the parrot image
	$camelia_img.context_set();
	$im.free_image(); # frees the camelia image

Parameters:

	source - The source rectangle.
		image - The source image.
		location - X and Y coordinates of the source image.
		size - Width and height of the source image. 
	destination - The destination rectangle
		location - X and Y Int coordinates of the source image.
		size - Width and height of the destination image.
	merge_alpha - Alpha flag (True or False).

Blends the source rectangle (location => (Int $x, Int $y) and size =>
(Int $width, Int $height)) from source_image onto the current image at
the destination (location => (Int $x, Int $y)) location scaled to the
size (size => (Int $width, Int $height)) destination. If merge_alpha is
set to True it will also modify the destination image alpha channel,
otherwise the destination alpha channel is left untouched.

=head2 Creation Functions.

Functions to create, clone and resize images.

=head3 create_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my Int $width = 100;
	my Int $height = 200;
	my Imlib2::Image $image = $im.create_image($width, $height);

Parameters:

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

Returns:

	Imlib2::Image $image - A new raw image.

Creates a new raw image of size width and height. The contents of this
image at creation time are undefined (they could be garbage memory).
You are free to do whatever you like with this image. It is not cached.
On success an image handle is returned - on failure NULL is returned.

=head3 clone_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $loaded_image = $im.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set();
	my Imlib2::Image $cloned_image = $im.clone_image();
	$cloned_image.context_set();
	... some operations ...
	$im.free_image(); # frees the cloned image
	$loaded_image.context_set();
	$im.free_image(); # frees the loaded image

Returns:

	Imlib2::Image $cloned_image - A valid image, otherwise NULL.

Creates an exact duplicate of the current image and returns a valid
image handle on success, or NULL on failure.

=head3 create_resized_image

Usage:

	use Imlib2;
	my $im = Imlib2.new();
	my $loaded_image = $im.load_image("pictures/holidays.jpeg");

	# Crop and Scale
	$loaded_image.context_set();
	my Imlib2::Image $resized_image = $im.create_resized_image(
		location => (50, 60),
		crop     => (150, 100),
		scale    => (300, 300));
	$resized_image.context_set();
	... some operations ...
	$im.free_image(); # frees the resized image

	# Crop only
	$loaded_image.context_set();
	my Imlib2::Image $cropped_image = $im.create_resized_image(
		location => (10, 20),
		crop     => (180, 120));
	$cropped_image.context_set();
	... some operations ...
	$im.free_image(); # frees the cropped image

	# Scale only
	$loaded_image.context_set();
	my Imlib2::Image $scaled_image = $im.create_resized_image(
		scale    => (180, 120));
	$scaled_image.context_set();
	... some operations ...
	$im.free_image(); # frees the scaled image

	$loaded_image.context_set();
	$im.free_image(); # frees the loaded image

Parameters:

	location - List with the top left Int $x and Int $y coordinates
	           of the source rectangle.
	crop - List with Int $width and Int $height of the source rectangle.
	scale - List with Int $width and Int $height of the destination image.

Returns:

	Imlib2::Image $resized_image - A valid image, otherwise NULL.

If the crop option is set creates a duplicate of a (x, y, width, height)
rectangle in the current image and returns a valid image handle on
success, or NULL on