.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" 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 .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Graphics::Toolkit::Color::Manual::Constructor 3" .TH Graphics::Toolkit::Color::Manual::Constructor 3 2026-06-21 "perl v5.42.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 Graphics::Toolkit::Color::Manual::Constructor \- GTC object creation reference .SH SYNOPSIS .IX Header "SYNOPSIS" This manual page contains the most detailed description about all the ways a GTC object can be created. This is, as to be expected, the method "new", but also the "color" routine and implicitly the arguments color and to. They too might trigger an error. .SH OPTIONS .IX Header "OPTIONS" .SS new .IX Subsection "new" The GTC philosophy tells that the API is optimized to be memorable and convenient and consistent. For that reason there is only one constructor method and all the necessary complexity is in the arguments, which are mostly optional and combinable. And there are only 4: \f(CW\*(C`color\*(C'\fR, \f(CW\*(C`range\*(C'\fR, \f(CW\*(C`raw\*(C'\fR and \f(CW\*(C`in\*(C'\fR which are seldom needed. In most cases it is enough to use \f(CW\*(C`color\*(C'\fR as the only positional argument, which is also the only required argument. .PP color expects a color definition in one of many acceptable formats. This multitude is one source of perceived complexity, but it is really just an offer to serve convenience. Users can select the preferred format and forget about the rest or use this ability to convert between formats (and spaces at once). Independent of that, there is the complexity of supporting many color spaces, which means there are many color space names and axis names. Again, these are a major source of usefulness one just has to look up the needed ones. Last not least there is great convenience in using color names, especially the ones from the default scheme. .PP .Vb 5 \& my $red = Graphics::Toolkit::Color\->new( r => 255, g => 0, b => 0 ); \& my $red = Graphics::Toolkit::Color\->new({r => 255, g => 0, b => 0}); # works too \& ... \->new( Red => 255, Green => 0, Blue => 0); # also fine \& ... \->new( Hue => 0, Saturation => 100, Lightness => 50 ); # same color \& ... \->new( Hue => 0, whiteness => 0, blackness => 0 ); # still the same \& \& my $red = Graphics::Toolkit::Color\->new( 255, 0, 0 ); \& my $red = Graphics::Toolkit::Color\->new( [255, 0, 0]); # does the same \& my $red = Graphics::Toolkit::Color\->new( \*(AqRGB\*(Aq, 255, 0, 0 ); # named list syntax \& my $red = Graphics::Toolkit::Color\->new( RGB => 255, 0, 0 ); # with fat comma \& my $red = Graphics::Toolkit::Color\->new([ RGB => 255, 0, 0]); # named ARRAY \& my $red = Graphics::Toolkit::Color\->new( RGB => [255, 0, 0]); # separate name and values \& my $red = Graphics::Toolkit::Color\->new([ RGB => [255, 0, 0]]); # even inside an ARRAY \& my $red = Graphics::Toolkit::Color\->new( YUV => .299,\-0.168736, .5);# same color in YUV \& \& my $red = Graphics::Toolkit::Color\->new( \*(Aqrgb(255 0 0)\*(Aq ); # comma optional \& my $blue = Graphics::Toolkit::Color\->new( \*(Aqhsv(240, 100%, 100%)\*(Aq ); \& my $blue = Graphics::Toolkit::Color\->new( \*(Aqhsv(240, 100, 100)\*(Aq ); # works too \& \& my $red = Graphics::Toolkit::Color\->new( \*(Aqrgb: 255, 0, 0\*(Aq ); \& my $blue = Graphics::Toolkit::Color\->new( \*(AqHSV: 240, 100, 100\*(Aq ); \& \& my $color = Graphics::Toolkit::Color\->new(\*(Aq#FF0000\*(Aq); \& my $color = Graphics::Toolkit::Color\->new(\*(Aq#f00\*(Aq); # short version \& \& my $color = Graphics::Toolkit::Color\->new(\*(AqEmerald\*(Aq); \& my $color = Graphics::Toolkit::Color\->new(\*(AqSVG:green\*(Aq); .Ve .PP range expects a range definition, that alters the acceptable minimum and maximum values on each color space axis. If you got for instance some \fIAppleRGB\fR colors encoded as RGB32 (three 32\-bit integers). In order to read them you need to write: .PP .Vb 3 \& my $color = Graphics::Toolkit::Color\->new( \& color => [AppleRGB => [1438, 374, 8285]], range => 2**32\-1 \& ); .Ve .PP raw expects a pseudo boolean that defaults to false (0). If true (1) the color definition will be read as is, but if false (0) the values will be clamped into range. This is either the default range of the color space, the color is defined in or the given \f(CW\*(C`range\*(C'\fR. If you want to read an out of gamut color to maybe convert it later into a wide gamut space, where it is in range you have to use: .PP .Vb 3 \& my $color = Graphics::Toolkit::Color\->new( \& color => {r => 0, g => 0, b => 256}, raw => 1 \& ); .Ve .PP in expects a color space name that serves only for disambiguation, since most color definitions already contain the name of the chosen color space. But formats like in the following example \fIhash\fR can be highly ambiguous. Please note also that the values in \fIAppleRGB\fR space are normal (0..1). .PP .Vb 4 \& my $color = Graphics::Toolkit::Color\->new( \& color => {r => 0, g => 0, b => 1}, in => \*(AqAppleRGB\*(Aq # or: \& ); \& Graphics::Toolkit::Color\->new( color => [0,0,1], in => \*(AqAppleRGB\*(Aq ); .Ve .SS color .IX Subsection "color" The regular constructor .PP .Vb 1 \& Graphics::Toolkit::Color\->new( ...); .Ve .PP is rather bulky and requires much typing and space, which might become inconvenient. In that case you might import the subroutine \f(CW\*(C`color\*(C'\fR, which works exactly like the color argument of the constructor. You cannot use the arguments \f(CW\*(C`range\*(C'\fR and \f(CW\*(C`raw\*(C'\fR here but all the color definition formats the constructor "new" accepts, including \fIlist\fR, which cannot work for the constructor argument \f(CW\*(C`color\*(C'\fR, that has to take scalar values. .PP .Vb 4 \& use Graphics::Toolkit::Color qw/color/; \& my $green = color(\*(Aqgreen\*(Aq); \& my $darkblue = color(20, 20, 250); # list format \& my $darkblue = color([20, 20, 250]); # array format .Ve .SS is_in_gamut .IX Subsection "is_in_gamut" The routine is_in_gamut takes color definitions like a constructor, but with raw turned on and returning just a pseudo bool. .SS arguments .IX Subsection "arguments" The argument to works the same way as color, which is used by: distance, mix, analogous and gradient. The only difference is, \f(CW\*(C`to\*(C'\fR accepts also GTC objects. These arguments are also a convenience service preventing unnecessary constructor calls. .SH AUTHOR .IX Header "AUTHOR" Herbert Breunung, .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2026 Herbert Breunung. .SH LICENSE .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.