<commit_before>=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 $tools = Imlib2.new();
	# Create a new raw image.
	my $rawimage = $tools.create_image(200, 200);
	exit() unless $rawimage;
	
	# Sets the current image Imlib2 will be using with its function calls.
	$rawimage.context_set_image();
	
	# Sets the color with which text, lines and rectangles are drawn when
	# being rendered onto an image.
	$tools.context_set_color(
	    red   => 255,
	    green => 127,
	    blue  => 0,
	    alpha => 255
	);
	
	$tools.image_fill_rectangle(
	    x      => 0,
	    y      => 0,
	    width  => 200,
	    height => 200
	);
	
	$tools.image_set_format("png");
	unlink("images/test_imlib2.png") if "images/test_imlib2.png".IO ~~ :e;
	$tools.save_image("images/test_imlib2.png");
	
	# Frees the image that is set as the current image in Imlib2's context. 
	$tools.free_image();
	
	exit();

=head1 API REFRENCE

The perl6 API follows closely the C implementation.

=head2 Test

test

=head3 Test head3

test...

=head2 C<context_set_cliprect>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.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.

=head2 C<context_set_dither_mask>

Usage:
	
	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither_mask = True;
	$tools.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.

=head2 C<context_get_dither_mask>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither_mask = $tools.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.

=head2 C<context_set_mask_alpha_threshold>

Usage:
	
	use Imlib2;
	my $tools = Imlib2.new();
	my Int $mask_alpha_threshold = 127;
	$tools.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.

=head2 C<context_get_mask_alpha_threshold>

Usage:

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

Returns:

	Int $mask_alpha_threshold - The current mask alpha threshold.

The current mask alpha threshold.

=head2 C<context_set_anti_alias>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $anti_alias = True;
	$tools.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.

=head2 C<context_get_anti_alias>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $anti_alias = $tools.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.

=head2 C<context_set_dither>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither = True;
	$tools.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.

=head2 C<context_get_dither>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither = $tools.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.

=head2 C<context_set_blend>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $blend = true;
	$tools.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.

=head2 C<context_get_blend>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $blend = $tools.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. 

=head2 C<context_set_color_modifier>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $color_modifier = $tools.create_color_modifier();
	$color_modifier.context_set_color_modifier();
	$tools.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.

=head2 C<context_get_color_modifier>

Usage:

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

Returns:

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

Returns the current color modifier being used.

=head2 C<context_set_operation>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_operation(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 OP_COPY. you can also set it to OP_ADD, OP_SUBTRACT
or OP_RESHADE. Use this function to set the rendering operation.

=over 4

=item *

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

=item *

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

=item *

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

=item *

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

=back

=head2 C<context_get_operation>

Usage:

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

Returns:

	OperationMode $operation - The current operation mode.

Returns the current operation mode.

=head2 C<font.context_set_font>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $tools.load_font("comic", 36);
	$corefont.context_set_font();
	$tools.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().

=head2 C<context_get_font>

Usage:

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

Returns:

	mlib2::Font $font - The current font.

Returns the current font.

=head2 C<context_set_direction>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_direction(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
TEXT_TO_RIGHT, TEXT_TO_LEFT, TEXT_TO_DOWN, TEXT_TO_UP or TEXT_TO_ANGLE.
The default is TEXT_TO_RIGHT. If you use TEXT_TO_ANGLE, you will also
have to set the angle with context_set_angle().

=head2 C<context_get_direction>

Usage:

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

Returns:

	TextDirection $text_direction - The current direction of the text.

Returns the current direction to render text in.

=head2 C<context_set_angle>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Rat $angle = -45.0;
	$tools.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().

=head2 C<context_get_angle>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Rat $angle = $tools.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.

=head2 C<context_set_color>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color(
		red   => 127,
		green => 255,
		blue  => 127,
		alpha => 255);

	# Another way to setup the color channels.
	my Str $hexcode = "#ff00ff";
	my Int $alpha = 127;
	$tools.context_set_color($hexcode, $alpha);

Parameters:

	Int red - Red channel of the current color.
	Int green - Green channel of the current color.
	Int blue - Blue channel of the current color.
	Int alpha - Alpha channel of the current color.
	Str $hex_color - The hexadecimal color code ("#FF00FF").

Sets the color with which text, lines and rectangles are drawn when
being rendered onto an image. Values for red, green, blue and alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %color_channels;
	$tools.context_get_color(%color_channels);
	say %color_channels{'red'};
	say %color_channels{'green'};
	say %color_channels{'blue'};
	say %color_channels{'alpha'};
	say %color_channels{'hexcode'};

	# Another way to get the color channels.
	%color_channels = $tools.context_get_color();

Parameters:

	%color_channels - If a hash is passed as argument.
	
Returns:

	%color_channels - Hash with the channels and a hexcode of the
	                  current colors if no argument is passed.

The current color for rendering text, rectangles and lines.

=over 4

=item *

%color_channels{'red'} - Red channel of the current color.

=item *

%color_channels{'green'} - Green channel of the current color.

=item *

%color_channels{'blue'} - Blue channel of the current color.

=item *

%color_channels{'alpha'} - Alpha channel of the current color.

=item *

%color_channels{'hexcode'} - Hexadecimal code of the current color.

=back

=head2 C<context_set_color_hsva>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_hsva(
		hue        => 180.0,
		saturation => 0.50,
		value      => 0.75,
		alpha      => 127);

Parameters:

	Rat hue - Hue channel of the current color.
	Rat saturation - Saturation channel of the current color.
	Rat value - Value channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in HSVA space. Values for hue are between 0 and 360,
values for saturation and value between 0 and 1, and values for alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_hsva>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %hsva_channels;
	$tools.context_get_color_hsva(%hsva_channels);
	say "Hue: " ~ %hsva_channels{'hue'};
	say "Saturation: " ~ %hsva_channels{'saturation'};
	say "Value: " ~ %hsva_channels{'value'};
	say "Alpha: " ~ %hsva_channels{'alpha'};

Parameters:

	%hsva_channels - Hash (passed as argument) with the channels of
	                 the current color.

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

=over 4

=item *

%hsva_channels{'hue'} - Hue channel of the current color.

=item *

%hsva_channels{'saturation'} - Saturation channel of the current color.

=item *

%hsva_channels{'value'} - Value channel of the current color.

=item *

%hsva_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_hlsa>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_hlsa(
		hue        => 180.0,
		lightness  => 0.75,
		saturation => 0.50,
		alpha      => 127);

Parameters:

	Rat hue - Hue channel of the current color.
	Rat lightness - Lightness channel of the current color.
	Rat saturation - Saturation channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in HLSA space. Values for hue are between 0 and 360,
values for lightness and saturation between 0 and 1, and values for
alpha are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_hlsa>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %hlsa_channels;
	$tools.context_get_color_hlsa(%hlsa_channels);
	say "Hue: " ~ %hlsa_channels{'hue'};
	say "Lightness: " ~ %hlsa_channels{'lightness'};
	say "Saturation: " ~ %hlsa_channels{'saturation'};
	say "Alpha: " ~ %hlsa_channels{'alpha'};

Parameters:

	%hlsa_channels - Hash (passed as argument) with the channels of
	                 the current color.

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

=over 4

=item *

%hlsa_channels{'hue'} - Hue channel of the current color.

=item *

%hlsa_channels{'lightness'} - Lightness channel of the current color.

=item *

%hlsa_channels{'saturation'} - Saturation channel of the current color.

=item *

%hlsa_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_cmya>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_cmya(
		cyan    => 25,
		magenta => 125,
		yellow  => 200,
		alpha   => 255);

Parameters:

	Int cyan - Cyan channel of the current color.
	Int magenta - Magenta channel of the current color.
	Int yellow - Yellow channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in CMYA space. Values for cyan, magenta, yellow and alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_cmya>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %cmya_channels;
	$tools.context_get_color_cmya(%cmya_channels);
	say "Cyan: " ~ %cmya_channels{'cyan'};
	say "Magenta: " ~ %cmya_channels{'magenta'};
	say "Yellow: " ~ %cmya_channels{'yellow'};
	say "Alpha: " ~ %cmya_channels{'alpha'};

Parameters:

	%cmya_channels - Hash (passed as argument) with the CMYA channels of
	                 the current color.

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

=over 4

=item *

%cmya_channels{'cyan'} - Cyan channel of the current color.

=item *

%cmya_channels{'magenta'} - Magenta channel of the current color.

=item *

%cmya_channels{'yellow'} - Yellow channel of the current color.

=item *

%cmya_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_range>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $color_range = $tools.create_color_range();
	$color_range.context_set_color_range();
	$tools.free_color_range();

Parameters:

	Imlib2::ColorRange $color_range - Color range.
	
Sets the current color range to use for rendering gradients.

=head2 C<context_get_color_range>

Usage:

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

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

Returns the current color range being used for gradients.

=head2 C<context_set_image>

Usage:

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

Parameters:

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

=head2 C<context_get_image>

Usage:

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

	Imlib2::Image $image - The current image.

Returns the current context image.

=head2 C<set_cache_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $bytes = 2048 * 1024;
	$tools.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.

=head2 C<get_cache_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $bytes = $tools.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.

=head2 C<set_color_usage>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $max = 256;
	$tools.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.

=head2 C<get_color_usage>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $max = $tools.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 C<flush_loaders>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.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 C<load_image>

Usage:

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

	# Another way to load an image.
	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image(
		filename    => $file,
		immediately => False,
		cache       => True);
	$image.context_set_image();
	... some operations ...
	$tools.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.

=head2 C<free_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	... some operations ...
	my Bool $decache = False;
	$tools.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.

=head2 C<image_get_width>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Int $width = $tools.image_get_width();
	say "Width size: $width pixels";
	$tools.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.

=head2 C<image_get_height>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Int $height = $tools.image_get_height();
	say "Height size: $height pixels";
	$tools.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.

=head2 C<image_get_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my %size = $tools.image_get_size();
	say "Width size: " ~ %size{'width'} ~ " pixels";
	say "Height size: " ~ %size{'height'} ~ " pixels";
	$tools.free_image();

Returns:

	%size - Hash with size in pixels of the current image (width, height).

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

=over 4

=item *

%size{'width'} - The width in pixels of the current image.

=item *

%size{'height'} - The height in pixels of the current image.

=back

=head2 C<image_get_filename>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Str $filename = $tools.image_get_filename();
	say "My filename is: $filename";
	$tools.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.

=head2 C<image_set_has_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Bool $has_alpha = True;
	$tools.image_set_has_alpha($has_alpha);
	... some operations ...
	$tools.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.

=head2 C<image_has_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Bool $has_alpha = $tools.image_has_alpha();
	say "Alpha status: $has_alpha";
	... some operations ...
	$tools.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").

=head2 C<image_set_changes_on_disk>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	$tools.image_set_changes_on_disk();
	... some operations ...
	$tools.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.

=head2 C<new_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	... some operations ...
	$tools.free_image();

Returns

	Imlib2::Border $border - Struct to store the values ​​of the border.

Returns a new structure to store the values of the border of the
current context image.

=head2 C<image_set_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	$border.left(2);
	$border.right(2);
	$border.top(4);
	$border.bottom(4);
	$tools.image_set_border($border);
	... some operations ...
	$tools.free_image();

Parameters:

	Imlib2::Border $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.

=over 4

=item *

$border.left(2) - Set the value of the left side to 2.

=item *

$border.right(2) - Set the value of the right side to 2.

=item *

$border.top(4) - Set the value of the top side to 4.

=item *

$border.bottom(4) - Set the value of the bottom side to 4.

=back

=head2 C<image_get_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	$tools.image_get_border($border);
	say "Left: " ~ $border.left;
	say "Right: " ~ $border.right;
	say "Top: " ~ $border.top;
	say "Bottom: " ~ $border.bottom;
	... some operations ...
	$tools.free_image();

Parameters:

	Imlib2::Border $border - The border of the image.

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.

=over 4

=item *

$border.left - Returns the value of the left side.

=item *

$border.right - Returns the value of the right side.

=item *

$border.top - Returns the value of the top side.

=item *

$border.bottom - Returns the value of the bottom side.

=back

=head2 C<image_set_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my Str $format = "png";
	$tools.image_set_format($format);
	... some operations ...
	$tools.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.

=head2 C<image_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my Str $format = $tools.image_format();
	... some operations ...
	$tools.free_image();

Returns:

	Str $format - Current image format.

Returns the current image's format.

=head2 C<image_set_irrelevant_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_format($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant format flag (True or False).

Sets if the format value of the current image 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 C<image_set_irrelevant_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_border($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant border flag (True or False).
	
Sets if the border of the current image is irrelevant for caching
purposes. By default it is. Set irrelevant to True to make it
irrelevant, and False to make it relevant.

=head2 C<image_set_irrelevant_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_alpha($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant alpha flag (True or False).

Sets if the alpha channel status of the current image (i.e. if there is
or is not one) is important for caching purposes. By default it is not.
Set irrelevant to True to make it irrelevant and False to make it
relevant.

=head2 C<create_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Int $width = 100;
	my Int $height = 200;
	my Imlib2::Image $image = $tools.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.

=head2 C<clone_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cloned_image = $tools.clone_image();
	$cloned_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cloned image
	$loaded_image.context_set_image();
	$tools.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.

=head2 C<create_cropped_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cropped_image = $tools.create_cropped_image(
			x      => 0,
			y      => 0,
			width  => 40,
			height => 80);
	$cropped_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cropped image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

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.

Returns:

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

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 failure.

=head2 C<create_cropped_scaled_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cropped_scaled_image = $tools.create_cropped_scaled_image(
			source_x           => 0,
			source_y           => 0,
			source_width       => 100,
			source_height      => 100,
			destination_width  => 50,
			destination_height => 50);
	$cropped_scaled_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cropped scaled image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

Parameters:

	Int x - The top left x coordinate of the source rectangle. 
	Int y - The top left y coordinate of the source rectangle. 
	Int width - The width of the source rectangle. 
	Int height - The height of the source rectangle.
	Int destination_width - The width of the destination image.
	Int destination_height - The height of the destination image.

Returns:

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

Works the same as create_cropped_image() but will scale the new image
to the new destination destination_width and destination_height whilst
cropping.

=head2 C<create_rotated_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Rat $angle = -45.0;
	my Imlib2::Image $rotated_image = $tools.create_rotated_image($angle);
	$rotated_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the rotated image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

Parameters:

	Rat $angle - An angle in degrees (-360 to 360).

Returns:

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

Creates an new copy of the current image, but rotated by angle degrees.
On success it returns a valid image handle, otherwise NULL.

=head2 C<image_flip>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my FlipMode $flip_mode = HORIZONTAL;
	$tools.image_flip($flip_mode);
	... some operations ...
	$tools.free_image();

Parameters:

	FlipMode $flip_mode - The flip mode flag.

Flips/mirrors the current image.

=over 4

=item *

HORIZONTAL - Flips/mirrors the current image horizontally

=item *

VERTICAL - Flips/mirrors the current image vertically.

=item *

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

=head2 C<image_orientate>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my RotationMode $orientation = ROTATE_90_DEGREE;
	$tools.image_orientate($orientation);
	... some operations ...
	$tools.free_image();

Parameters:

	RotationMode $orientation - The rotation mode flag.

Performs 90 degree rotations on the current image.

=over 4

=item *

ROTATE_90_DEGREE - rotates clockwise by 90 degree.

=item *

ROTATE_180_DEGREE - rotates clockwise by 180 degrees.

=item *

ROTATE_270_DEGREE - rotates clockwise by 270 degrees.

=back

=head2 C<save_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	$tools.image_set_format("png");
	... some operations ...
	my Str $filename = "test.png";
	$tools.save_image($filename);
	$tools.free_image();

	# save image with returned error.
	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	$tools.image_set_format("png");
	... some operations ...
	my Str $filename = "test.png";
	my LoadError $error_return;
	$tools.save_image($filename, $error_return);
	say "No error..." if $error_return == LOAD_ERROR_NONE;
	$tools.free_image();

Parameters:

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

Saves the current image in the format specified by the current image's
format settings to the filename $filename.
If the $error_return is passed as argument the $error_return will be
set to an error value if the save fails. 

=head1 AUTHOR

<NAME> - L<<EMAIL>>

=head1 SEE ALSO

Imlib2 Library Documentation L<http://docs.enlightenment.org/api/imlib2/html/>

=head1 LICENSE

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

<commit_msg>Update Imlib2.pod<commit_after>=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 $tools = Imlib2.new();
	# Create a new raw image.
	my $rawimage = $tools.create_image(200, 200);
	exit() unless $rawimage;
	
	# Sets the current image Imlib2 will be using with its function calls.
	$rawimage.context_set_image();
	
	# Sets the color with which text, lines and rectangles are drawn when
	# being rendered onto an image.
	$tools.context_set_color(
	    red   => 255,
	    green => 127,
	    blue  => 0,
	    alpha => 255
	);
	
	$tools.image_fill_rectangle(
	    x      => 0,
	    y      => 0,
	    width  => 200,
	    height => 200
	);
	
	$tools.image_set_format("png");
	unlink("images/test_imlib2.png") if "images/test_imlib2.png".IO ~~ :e;
	$tools.save_image("images/test_imlib2.png");
	
	# Frees the image that is set as the current image in Imlib2's context. 
	$tools.free_image();
	
	exit();

=head1 API REFRENCE

The perl6 API follows closely the C implementation.

=head2 Test

test

=head3 C<Test head3>

test...

=head3 C<Test head3>

test...

=head2 C<context_set_cliprect>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.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.

=head2 C<context_set_dither_mask>

Usage:
	
	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither_mask = True;
	$tools.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.

=head2 C<context_get_dither_mask>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither_mask = $tools.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.

=head2 C<context_set_mask_alpha_threshold>

Usage:
	
	use Imlib2;
	my $tools = Imlib2.new();
	my Int $mask_alpha_threshold = 127;
	$tools.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.

=head2 C<context_get_mask_alpha_threshold>

Usage:

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

Returns:

	Int $mask_alpha_threshold - The current mask alpha threshold.

The current mask alpha threshold.

=head2 C<context_set_anti_alias>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $anti_alias = True;
	$tools.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.

=head2 C<context_get_anti_alias>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $anti_alias = $tools.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.

=head2 C<context_set_dither>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither = True;
	$tools.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.

=head2 C<context_get_dither>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $dither = $tools.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.

=head2 C<context_set_blend>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $blend = true;
	$tools.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.

=head2 C<context_get_blend>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $blend = $tools.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. 

=head2 C<context_set_color_modifier>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $color_modifier = $tools.create_color_modifier();
	$color_modifier.context_set_color_modifier();
	$tools.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.

=head2 C<context_get_color_modifier>

Usage:

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

Returns:

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

Returns the current color modifier being used.

=head2 C<context_set_operation>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_operation(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 OP_COPY. you can also set it to OP_ADD, OP_SUBTRACT
or OP_RESHADE. Use this function to set the rendering operation.

=over 4

=item *

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

=item *

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

=item *

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

=item *

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

=back

=head2 C<context_get_operation>

Usage:

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

Returns:

	OperationMode $operation - The current operation mode.

Returns the current operation mode.

=head2 C<font.context_set_font>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.add_path_to_font_path("/usr/share/fonts/corefonts");
	my $corefont = $tools.load_font("comic", 36);
	$corefont.context_set_font();
	$tools.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().

=head2 C<context_get_font>

Usage:

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

Returns:

	mlib2::Font $font - The current font.

Returns the current font.

=head2 C<context_set_direction>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_direction(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
TEXT_TO_RIGHT, TEXT_TO_LEFT, TEXT_TO_DOWN, TEXT_TO_UP or TEXT_TO_ANGLE.
The default is TEXT_TO_RIGHT. If you use TEXT_TO_ANGLE, you will also
have to set the angle with context_set_angle().

=head2 C<context_get_direction>

Usage:

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

Returns:

	TextDirection $text_direction - The current direction of the text.

Returns the current direction to render text in.

=head2 C<context_set_angle>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Rat $angle = -45.0;
	$tools.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().

=head2 C<context_get_angle>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Rat $angle = $tools.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.

=head2 C<context_set_color>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color(
		red   => 127,
		green => 255,
		blue  => 127,
		alpha => 255);

	# Another way to setup the color channels.
	my Str $hexcode = "#ff00ff";
	my Int $alpha = 127;
	$tools.context_set_color($hexcode, $alpha);

Parameters:

	Int red - Red channel of the current color.
	Int green - Green channel of the current color.
	Int blue - Blue channel of the current color.
	Int alpha - Alpha channel of the current color.
	Str $hex_color - The hexadecimal color code ("#FF00FF").

Sets the color with which text, lines and rectangles are drawn when
being rendered onto an image. Values for red, green, blue and alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %color_channels;
	$tools.context_get_color(%color_channels);
	say %color_channels{'red'};
	say %color_channels{'green'};
	say %color_channels{'blue'};
	say %color_channels{'alpha'};
	say %color_channels{'hexcode'};

	# Another way to get the color channels.
	%color_channels = $tools.context_get_color();

Parameters:

	%color_channels - If a hash is passed as argument.
	
Returns:

	%color_channels - Hash with the channels and a hexcode of the
	                  current colors if no argument is passed.

The current color for rendering text, rectangles and lines.

=over 4

=item *

%color_channels{'red'} - Red channel of the current color.

=item *

%color_channels{'green'} - Green channel of the current color.

=item *

%color_channels{'blue'} - Blue channel of the current color.

=item *

%color_channels{'alpha'} - Alpha channel of the current color.

=item *

%color_channels{'hexcode'} - Hexadecimal code of the current color.

=back

=head2 C<context_set_color_hsva>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_hsva(
		hue        => 180.0,
		saturation => 0.50,
		value      => 0.75,
		alpha      => 127);

Parameters:

	Rat hue - Hue channel of the current color.
	Rat saturation - Saturation channel of the current color.
	Rat value - Value channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in HSVA space. Values for hue are between 0 and 360,
values for saturation and value between 0 and 1, and values for alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_hsva>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %hsva_channels;
	$tools.context_get_color_hsva(%hsva_channels);
	say "Hue: " ~ %hsva_channels{'hue'};
	say "Saturation: " ~ %hsva_channels{'saturation'};
	say "Value: " ~ %hsva_channels{'value'};
	say "Alpha: " ~ %hsva_channels{'alpha'};

Parameters:

	%hsva_channels - Hash (passed as argument) with the channels of
	                 the current color.

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

=over 4

=item *

%hsva_channels{'hue'} - Hue channel of the current color.

=item *

%hsva_channels{'saturation'} - Saturation channel of the current color.

=item *

%hsva_channels{'value'} - Value channel of the current color.

=item *

%hsva_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_hlsa>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_hlsa(
		hue        => 180.0,
		lightness  => 0.75,
		saturation => 0.50,
		alpha      => 127);

Parameters:

	Rat hue - Hue channel of the current color.
	Rat lightness - Lightness channel of the current color.
	Rat saturation - Saturation channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in HLSA space. Values for hue are between 0 and 360,
values for lightness and saturation between 0 and 1, and values for
alpha are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_hlsa>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %hlsa_channels;
	$tools.context_get_color_hlsa(%hlsa_channels);
	say "Hue: " ~ %hlsa_channels{'hue'};
	say "Lightness: " ~ %hlsa_channels{'lightness'};
	say "Saturation: " ~ %hlsa_channels{'saturation'};
	say "Alpha: " ~ %hlsa_channels{'alpha'};

Parameters:

	%hlsa_channels - Hash (passed as argument) with the channels of
	                 the current color.

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

=over 4

=item *

%hlsa_channels{'hue'} - Hue channel of the current color.

=item *

%hlsa_channels{'lightness'} - Lightness channel of the current color.

=item *

%hlsa_channels{'saturation'} - Saturation channel of the current color.

=item *

%hlsa_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_cmya>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.context_set_color_cmya(
		cyan    => 25,
		magenta => 125,
		yellow  => 200,
		alpha   => 255);

Parameters:

	Int cyan - Cyan channel of the current color.
	Int magenta - Magenta channel of the current color.
	Int yellow - Yellow channel of the current color.
	Int alpha - Alpha channel of the current color.

Sets the color in CMYA space. Values for cyan, magenta, yellow and alpha
are between 0 and 255 - any other values have undefined results.

=head2 C<context_get_color_cmya>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my %cmya_channels;
	$tools.context_get_color_cmya(%cmya_channels);
	say "Cyan: " ~ %cmya_channels{'cyan'};
	say "Magenta: " ~ %cmya_channels{'magenta'};
	say "Yellow: " ~ %cmya_channels{'yellow'};
	say "Alpha: " ~ %cmya_channels{'alpha'};

Parameters:

	%cmya_channels - Hash (passed as argument) with the CMYA channels of
	                 the current color.

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

=over 4

=item *

%cmya_channels{'cyan'} - Cyan channel of the current color.

=item *

%cmya_channels{'magenta'} - Magenta channel of the current color.

=item *

%cmya_channels{'yellow'} - Yellow channel of the current color.

=item *

%cmya_channels{'alpha'} - Alpha channel of the current color.

=back

=head2 C<context_set_color_range>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $color_range = $tools.create_color_range();
	$color_range.context_set_color_range();
	$tools.free_color_range();

Parameters:

	Imlib2::ColorRange $color_range - Color range.
	
Sets the current color range to use for rendering gradients.

=head2 C<context_get_color_range>

Usage:

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

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

Returns the current color range being used for gradients.

=head2 C<context_set_image>

Usage:

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

Parameters:

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

=head2 C<context_get_image>

Usage:

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

	Imlib2::Image $image - The current image.

Returns the current context image.

=head2 C<set_cache_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $bytes = 2048 * 1024;
	$tools.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.

=head2 C<get_cache_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $bytes = $tools.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.

=head2 C<set_color_usage>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $max = 256;
	$tools.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.

=head2 C<get_color_usage>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $max = $tools.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 C<flush_loaders>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	$tools.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 C<load_image>

Usage:

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

	# Another way to load an image.
	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image(
		filename    => $file,
		immediately => False,
		cache       => True);
	$image.context_set_image();
	... some operations ...
	$tools.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.

=head2 C<free_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	... some operations ...
	my Bool $decache = False;
	$tools.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.

=head2 C<image_get_width>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Int $width = $tools.image_get_width();
	say "Width size: $width pixels";
	$tools.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.

=head2 C<image_get_height>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Int $height = $tools.image_get_height();
	say "Height size: $height pixels";
	$tools.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.

=head2 C<image_get_size>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my %size = $tools.image_get_size();
	say "Width size: " ~ %size{'width'} ~ " pixels";
	say "Height size: " ~ %size{'height'} ~ " pixels";
	$tools.free_image();

Returns:

	%size - Hash with size in pixels of the current image (width, height).

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

=over 4

=item *

%size{'width'} - The width in pixels of the current image.

=item *

%size{'height'} - The height in pixels of the current image.

=back

=head2 C<image_get_filename>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $file = "pictures/holidays.jpeg";
	my $image = $tools.load_image($file);
	$image.context_set_image();
	my Str $filename = $tools.image_get_filename();
	say "My filename is: $filename";
	$tools.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.

=head2 C<image_set_has_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Bool $has_alpha = True;
	$tools.image_set_has_alpha($has_alpha);
	... some operations ...
	$tools.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.

=head2 C<image_has_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Bool $has_alpha = $tools.image_has_alpha();
	say "Alpha status: $has_alpha";
	... some operations ...
	$tools.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").

=head2 C<image_set_changes_on_disk>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	$tools.image_set_changes_on_disk();
	... some operations ...
	$tools.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.

=head2 C<new_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	... some operations ...
	$tools.free_image();

Returns

	Imlib2::Border $border - Struct to store the values ​​of the border.

Returns a new structure to store the values of the border of the
current context image.

=head2 C<image_set_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	$border.left(2);
	$border.right(2);
	$border.top(4);
	$border.bottom(4);
	$tools.image_set_border($border);
	... some operations ...
	$tools.free_image();

Parameters:

	Imlib2::Border $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.

=over 4

=item *

$border.left(2) - Set the value of the left side to 2.

=item *

$border.right(2) - Set the value of the right side to 2.

=item *

$border.top(4) - Set the value of the top side to 4.

=item *

$border.bottom(4) - Set the value of the bottom side to 4.

=back

=head2 C<image_get_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	my Imlib2::Border $border = $tools.new_border();
	$tools.image_get_border($border);
	say "Left: " ~ $border.left;
	say "Right: " ~ $border.right;
	say "Top: " ~ $border.top;
	say "Bottom: " ~ $border.bottom;
	... some operations ...
	$tools.free_image();

Parameters:

	Imlib2::Border $border - The border of the image.

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.

=over 4

=item *

$border.left - Returns the value of the left side.

=item *

$border.right - Returns the value of the right side.

=item *

$border.top - Returns the value of the top side.

=item *

$border.bottom - Returns the value of the bottom side.

=back

=head2 C<image_set_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my Str $format = "png";
	$tools.image_set_format($format);
	... some operations ...
	$tools.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.

=head2 C<image_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my Str $format = $tools.image_format();
	... some operations ...
	$tools.free_image();

Returns:

	Str $format - Current image format.

Returns the current image's format.

=head2 C<image_set_irrelevant_format>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_format($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant format flag (True or False).

Sets if the format value of the current image 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 C<image_set_irrelevant_border>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_border($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant border flag (True or False).
	
Sets if the border of the current image is irrelevant for caching
purposes. By default it is. Set irrelevant to True to make it
irrelevant, and False to make it relevant.

=head2 C<image_set_irrelevant_alpha>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Bool $irrelevant = True;
	$tools.image_set_irrelevant_alpha($irrelevant);

Parameters:

	Bool $irrelevant - Irrelevant alpha flag (True or False).

Sets if the alpha channel status of the current image (i.e. if there is
or is not one) is important for caching purposes. By default it is not.
Set irrelevant to True to make it irrelevant and False to make it
relevant.

=head2 C<create_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my Int $width = 100;
	my Int $height = 200;
	my Imlib2::Image $image = $tools.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.

=head2 C<clone_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cloned_image = $tools.clone_image();
	$cloned_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cloned image
	$loaded_image.context_set_image();
	$tools.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.

=head2 C<create_cropped_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cropped_image = $tools.create_cropped_image(
			x      => 0,
			y      => 0,
			width  => 40,
			height => 80);
	$cropped_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cropped image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

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.

Returns:

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

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 failure.

=head2 C<create_cropped_scaled_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Imlib2::Image $cropped_scaled_image = $tools.create_cropped_scaled_image(
			source_x           => 0,
			source_y           => 0,
			source_width       => 100,
			source_height      => 100,
			destination_width  => 50,
			destination_height => 50);
	$cropped_scaled_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the cropped scaled image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

Parameters:

	Int x - The top left x coordinate of the source rectangle. 
	Int y - The top left y coordinate of the source rectangle. 
	Int width - The width of the source rectangle. 
	Int height - The height of the source rectangle.
	Int destination_width - The width of the destination image.
	Int destination_height - The height of the destination image.

Returns:

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

Works the same as create_cropped_image() but will scale the new image
to the new destination destination_width and destination_height whilst
cropping.

=head2 C<create_rotated_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $loaded_image = $tools.load_image("pictures/holidays.jpeg");
	$loaded_image.context_set_image();
	my Rat $angle = -45.0;
	my Imlib2::Image $rotated_image = $tools.create_rotated_image($angle);
	$rotated_image.context_set_image();
	... some operations ...
	$tools.free_image(); # frees the rotated image
	$loaded_image.context_set_image();
	$tools.free_image(); # frees the loaded image

Parameters:

	Rat $angle - An angle in degrees (-360 to 360).

Returns:

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

Creates an new copy of the current image, but rotated by angle degrees.
On success it returns a valid image handle, otherwise NULL.

=head2 C<image_flip>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my FlipMode $flip_mode = HORIZONTAL;
	$tools.image_flip($flip_mode);
	... some operations ...
	$tools.free_image();

Parameters:

	FlipMode $flip_mode - The flip mode flag.

Flips/mirrors the current image.

=over 4

=item *

HORIZONTAL - Flips/mirrors the current image horizontally

=item *

VERTICAL - Flips/mirrors the current image vertically.

=item *

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

=head2 C<image_orientate>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.load_image("pictures/holidays.jpeg");
	$image.context_set_image();
	my RotationMode $orientation = ROTATE_90_DEGREE;
	$tools.image_orientate($orientation);
	... some operations ...
	$tools.free_image();

Parameters:

	RotationMode $orientation - The rotation mode flag.

Performs 90 degree rotations on the current image.

=over 4

=item *

ROTATE_90_DEGREE - rotates clockwise by 90 degree.

=item *

ROTATE_180_DEGREE - rotates clockwise by 180 degrees.

=item *

ROTATE_270_DEGREE - rotates clockwise by 270 degrees.

=back

=head2 C<save_image>

Usage:

	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	$tools.image_set_format("png");
	... some operations ...
	my Str $filename = "test.png";
	$tools.save_image($filename);
	$tools.free_image();

	# save image with returned error.
	use Imlib2;
	my $tools = Imlib2.new();
	my $image = $tools.create_image(100, 200);
	$image.context_set_image();
	$tools.image_set_format("png");
	... some operations ...
	my Str $filename = "test.png";
	my LoadError $error_return;
	$tools.save_image($filename, $error_return);
	say "No error..." if $error_return == LOAD_ERROR_NONE;
	$tools.free_image();

Parameters:

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

Saves the current image in the format specified by the current image's
format settings to the filename $filename.
If the $error_return is passed as argument the $error_return will be
set to an error value if the save fails. 

=head1 AUTHOR

<NAME> - L<<EMAIL>>

=head1 SEE ALSO

Imlib2 Library Documentation L<http://docs.enlightenment.org/api/imlib2/html/>

=head1 LICENSE

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


{'fraction_non_alphanumeric': 0.09816435018550307, 'fraction_numerical': 0.015380142865053436, 'mean_word_length': 4.009500693481276, 'pattern_counts': {'":': 0, '<': 141, '<?xml version=': 0, '>': 225, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '176446', 'n_tokens_mistral': 25443, 'n_tokens_neox': 24113, 'n_words': 8739}