Graphic...structor(3)

💖 NAME 💖

okay bestie, this is Graphic...structor(3) from the User Contributed Perl Documentation, and the page itself is literally called Graphics::Toolkit::Color::Manual::Constructor — your whole GTC object creation reference. 💅✨

No cap, it's the manual page for how Graphics::Toolkit::Color objects get made. 🫶

---

🌸 SYNOPSIS 🌸

This page has the most detailed description of every single way a GTC object can be created. That means the method new, bestie, but also the color routine, and implicitly the arguments color and to. And yes — those can trigger an error too. 😭

---

✨ OPTIONS ✨

🎀 new 🎀

GTC's whole philosophy is that the API is optimized to be memorable, convenient, and consistent. For that reason there is only one constructor method, and all the necessary complexity lives in the arguments — which are mostly optional and combinable. And there are only 4: color, range, raw and in, which are seldom needed. In most cases it's enough to use color as the only positional argument, which is also the only required argument. 👑

color expects a color definition in one of many acceptable formats. This multitude is one source of perceived complexity, but it's 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's 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. And last not least, there is great convenience in using color names, especially the ones from the default scheme. 🌈

           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( 'RGB',   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(  'rgb(255 0 0)' );         # comma optional
           my $blue = Graphics::Toolkit::Color->new( 'hsv(240, 100%, 100%)' );
           my $blue = Graphics::Toolkit::Color->new( 'hsv(240, 100, 100)' );   # works too

           my $red = Graphics::Toolkit::Color->new(  'rgb: 255, 0, 0' );
           my $blue = Graphics::Toolkit::Color->new( 'HSV: 240, 100, 100' );

           my $color = Graphics::Toolkit::Color->new('#FF0000');
           my $color = Graphics::Toolkit::Color->new('#f00');    # short version

           my $color = Graphics::Toolkit::Color->new('Emerald');
           my $color = Graphics::Toolkit::Color->new('SVG:green');

range expects a range definition that alters the acceptable minimum and maximum values on each color space axis. If you got, for instance, some AppleRGB colors encoded as RGB32 (three 32-bit integers), in order to read them you need to write: 🍓

           my $color = Graphics::Toolkit::Color->new(
                        color => [AppleRGB => [1438, 374, 8285]], range => 2**32-1
           );

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 range. 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: 🔥

           my $color = Graphics::Toolkit::Color->new(
                        color => {r => 0, g => 0, b => 256}, raw => 1
           );

heads up bestie: raw is the switch that decides whether values get clamped or read exactly as written — don't sleep on it. 💀

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 hash can be highly ambiguous. Please note also that the values in AppleRGB space are normal (0..1). 🧚

           my $color = Graphics::Toolkit::Color->new(
                        color => {r => 0, g => 0, b => 1}, in => 'AppleRGB'    # or:
           );
           Graphics::Toolkit::Color->new( color => [0,0,1], in => 'AppleRGB' );

🦋 color 🦋

The regular constructor

           Graphics::Toolkit::Color->new( ...);

is rather bulky and requires much typing and space, which might become inconvenient. In that case you might import the subroutine color, which works exactly like the color argument of the constructor. You cannot use the arguments range and raw here, but you get all the color definition formats the constructor new accepts — including list, which cannot work for the constructor argument color, that has to take scalar values. 💖

           use Graphics::Toolkit::Color qw/color/;
           my $green = color('green');
           my $darkblue = color(20, 20, 250);         # list format
           my $darkblue = color([20, 20, 250]);       # array format

💜 is_in_gamut 💜

The routine is_in_gamut takes color definitions like a constructor, but with raw turned on, and returns just a pseudo bool. ⭐

🌸 arguments 🌸

The argument to works the same way as color, which is used by: distance, mix, analogous and gradient. The only difference is that to accepts also GTC objects. These arguments are also a convenience service preventing unnecessary constructor calls. ✨

---

👑 AUTHOR 👑

Herbert Breunung, <lichtkind@cpan.org> 🫶

🌈 COPYRIGHT 🌈

Copyright 2026 Herbert Breunung.

🎀 LICENSE 🎀

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

---

okay that's the whole page, bestie — footer vibes say perl v5.42.2 and 2026-06-21, so bye and stay iconic 💖🦋✨