.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Color::Float 3pm"
.TH Imager::Color::Float 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::Color::Float \- Rough floating point sample color handling
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  $color = Imager::Color\->new($red, $green, $blue);
\&  $color = Imager::Color\->new($red, $green, $blue, $alpha);
\&  $color = Imager::Color\->new("#C0C0FF"); # html color specification
\&
\&  $color\->set($red, $green, $blue);
\&  $color\->set($red, $green, $blue, $alpha);
\&  $color\->set("#C0C0FF"); # html color specification
\&
\&  ($red, $green, $blue, $alpha) = $color\->rgba();
\&  @hsv = $color\->hsv(); # not implemented but proposed
\&  my $c8 = $color\->as_8bit;
\&
\&  $color\->info();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module handles creating color objects used by Imager.  The idea
is that in the future this module will be able to handle color space
calculations as well.
.PP
A floating point Imager color consists of up to four components, each
in the range 0.0 to 1.0. Unfortunately the meaning of the components
can change depending on the type of image you're dealing with:
.IP \(bu 4
for 3 or 4 channel images the color components are red, green, blue,
alpha.
.IP \(bu 4
for 1 or 2 channel images the color components are gray, alpha, with
the other two components ignored.
.PP
An alpha value of zero is fully transparent, an alpha value of 1.0 is
fully opaque.
.SH METHODS
.IX Header "METHODS"
.IP new 4
.IX Item "new"
This creates a color object to pass to functions that need a color argument.
.IP set 4
.IX Item "set"
This changes an already defined color.  Note that this does not affect any places
where the color has been used previously.
.IP \fBrgba()\fR 4
.IX Item "rgba()"
This returns the red, green, blue and alpha channels of the color the
object contains.
.IP info 4
.IX Item "info"
Calling info merely dumps the relevant color to the log.
.IP red 4
.IX Item "red"
.PD 0
.IP green 4
.IX Item "green"
.IP blue 4
.IX Item "blue"
.IP alpha 4
.IX Item "alpha"
.PD
Returns the respective component as a floating point value typically
from 0 to 1.0.
.IP as_8bit 4
.IX Item "as_8bit"
Returns the color as the roughly equivalent 8\-bit Imager::Color
object.  Samples below zero or above 1.0 are clipped.
.IP as_css_rgb 4
.IX Item "as_css_rgb"
Formats the color as a CSS \fBrgb()\fR style color.  If the color is closely
representable as byte style syntax, eg rgb(255, 128, 128), it will be
returned in that form, otherwise the samples are formatted as
percentages with up to 2 decimal places.
.SS "Setting colors"
.IX Subsection "Setting colors"
The \fBnew()\fR and \fBset()\fR methods can accept the following parameters:
.IP \(bu 4
an Imager::Color::Float object
.IP \(bu 4
an Imager::Color object, the ranges of samples are translated from 0...255 to 0.0...1.0.
.IP \(bu 4
3 values, treated as red, green, blue
.IP \(bu 4
4 values, treated as red, green, blue, alpha
.IP \(bu 4
an 8 character hex color, optionally preceded by \f(CW\*(C`#\*(C'\fR.
.IP \(bu 4
a 6 character hex color, optionally preceded by \f(CW\*(C`#\*(C'\fR.
.IP \(bu 4
a CSS \fBrgb()\fR color, based on CSS Color 4.  The \f(CW\*(C`none\*(C'\fR keyword is not
supported and numbers must be simple decimals without exponents. eg.
.Sp
.Vb 4
\&  rgb(50% 50% 100%)
\&  rgb(0, 0, 255)
\&  rgb(0.5 0.5 1.0 / 0.8)
\&  rgb(50%, 50%, 100%, 80%)
.Ve
.Sp
This accepts some colors not accepted by the CSS \fBrgb()\fR specification,
this may change.
.SH AUTHOR
.IX Header "AUTHOR"
Arnar M. Hrafnkelsson, addi@umich.edu
And a great deal of help from others \- see the \f(CW\*(C`README\*(C'\fR for a complete
list.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBImager\fR\|(3), Imager::Color.
.PP
http://imager.perl.org/