=encoding UTF-8

=head1 NAME

TCOD::Color - A representation of a color

=head1 SYNOPSIS

    use TCOD;

    my $red   = TCOD::RED;
    my $blue  = TCOD::BLUE;
    my $green = TCOD::GREEN;

    my $new = TCOD::WHITE - ( $red + $blue );

    say "It's green!" if $new == $green;
    # OUTPUT: It's green!

=head1 DESCRIPTION

This represents a TCOD color.

=head1 METHODS

=head2 new

    $color = TCOD::Color->new( $r, $g, $b );

Construct a new TCOD::Color object. Takes the red, green and blue
components as positional parameters, as iintegers between 0 and 255.

=head2 r

    $red = $color->r;

The red component of this color, as an integer between 0 and 255.

=head2 g

    $green = $color->g;

The green component of this color, as an integer between 0 and 255.

=head2 b

    $blue = $color->b;

The blue component of this color, as an integer between 0 and 255.

=head2 lerp

    $new_color = $start_color->lerp( $end_color, $factor );

Return a new color interpolated between a start and end color. The value
in C<$factor>, which must be a number between 0 and 1, determines how
close to either endpoint the new color will be: if the factor is 0 it will
be equal to the start color, if it's 1 it will be equal to the end color.

=head2 get_hue

    $hue = $color->get_hue;

The hue of this color, in degrees between 0 and 360. Note that if the hue
is equal to 360 it will be returned as 0.

=head2 set_hue

    $color->set_hue( $hue );

Set the hue of this color. Input is a number between 0 and 360.
Note that setting the hue of a color to 360 is the same as setting it
to 0.

=head2 get_saturation

    $saturation = $color->get_saturation;

The saturation of this color, as a number between 0 and 1.

=head2 set_saturation

    $color->set_saturation( $saturation );

Set the saturation of this color. Input is a number between 0 and 1.

=head2 get_value

    $value = $color->get_value;

The value of this color, as a number between 0 and 1.

=head2 set_value

    $color->set_value( $value );

Set the value of this color. Input is a number between 0 and 1.

=head2 shift_hue

    $color->shift_hue( $shift );

Shifts the hue of this color by the number of degrees provided.

=head2 scale_HSV

    $color->shift_hue( $saturation_factor, $value_factor );

Modifies the saturation and value of this color by multiplying them with
the factors provided.

=head2 get_HSV

    my ( $h, $s, $v ) = $color->get_HSV;

Returns a list with the hue, saturation, and value of this color.
The values are the same as those obtained from the individual getters
described above.

=head2 set_HSV

    $color->set_HSV( $h, $s, $v );

Sets the hue, saturation, and value of this color to the values provided.
The values should be the same as those used for the setters described above.

=head2 equals

    $bool = $color->equals( $other );

Returns true if both colors are equivalent.

=head2 add

    $new_color = $color->add( $other );

Returns a new color, the result of adding the red, green, and blue
components of the second color to the respective ones of the first.

=head2 subtract

    $new_color = $color->subtract( $other );

Returns a new color, the result of subtracting the red, green, and blue
components of the second color from the respective ones of the first.

=head2 multiply

    $new_color = $color->multiply( $other );

Returns a new color, the result of multipliying the red, green, and blue
components of the second color with the respective ones of the first.

=head2 multiply_scalar

    $new_color = $color->multiply_scalar( $value );

Returns a new color, the result of multipliying each of the red, green,
and blue components of the first color with the scalar value provided.

=head1 FUNCTIONS

=head2 gen_map

    @colors = TCOD::Color::gen_map( %map_spec );

Generate a color map according to a spec. The spec should hold a list
of pairs, with the first element of each pair being a color in the map,
and the second element being the position of that color in the resulting
map.

Returns a list of colors generated by interpolating between the
positions specified in the spec.

For example, calling this function like

    TCOD::Color::gen_map(
        TCOD::BLACK ,=> 0,
        TCOD::GREY  ,=> 7,
        TCOD::WHITE ,=> 9,
    );

would result in the following list of colors being generated:

    #000000 # TCOD::BLACK at position 0
    #121212
    #242424
    #363636
    #484848
    #5a5a5a
    #6c6c6c
    #7f7f7f # TCOD::GREY at position 7
    #bfbfbf
    #ffffff # TCOD::WHITE at position 9

No effort is made internally to sort the pairs of the spec, so the user
should make sure they are in the desired order.

Using a non-zero position in the first pair is acceptable. In this case,
the positions before this in the generated list will be undefined.

=head1 COLOR ARITHMETIC

Some color arithmetic operations are supported using overloaded operators.
The following table shows which ones are, and what methods they call:

    Operation            Method
    ------------------------------------
    $color == $color      equals
    $color +  $color      add
    $color -  $color      subtract
    $color *  $color      multiply
    $color *  $scalar     multiply_scalar

All of these operations result in the creation of a new color object, leaving
the original ones untouched.

=head1 SEE ALSO

=over

=item L<TCOD>

=item L<TCOD::Console>

=back

=head1 COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.
