/ 
Term-Fabulous-0.01
/ Term::Fabulous::Render::Attr

NAME

Term::Fabulous::Render::Attr - Turn colors into termbox2 truecolor attributes

SYNOPSIS

use Term::Fabulous::Render::Attr qw(color_attr clay_color cell_color_attr blended_bg_attr STYLE_FLAGS);
use Term::Fabulous::Color;

my $fg = color_attr( Term::Fabulous::Color->rgb( 0, 0, 0 ) );               # TB_HI_BLACK
my $bg = color_attr( clay_color( { r => 20, g => 25, b => 35, a => 255 } ) );  # 0x141923
my $cell_fg = cell_color_attr( fg => '#ffcc00' );                             # 0xFFCC00
my $dimmed  = blended_bg_attr( Term::Fabulous::Color->rgba( 0, 0, 0, 128 ), 0xFFFFFF );  # 0x7F7F7F

my %name_of_sgr = map { $_->[1] => $_->[2] } STYLE_FLAGS;                   # 1 => 'bold', ...

DESCRIPTION

Most programs never use this module directly. It is used by the render roles and the canvas widgets. Read it if you write your own cell target or UI class (see Term::Fabulous::Render), or to understand the color values returned by "cell" in Term::Fabulous::Widget::Canvas and "pixel" in Term::Fabulous::Widget::PixelCanvas.

termbox2 describes the colors of a cell with an integer attribute. In truecolor mode, the one Term::Fabulous uses, an attribute holds a 24-bit color 0xRRGGBB in its low bits and flags such as reverse video in its high bits. Two values are special:

TB_DEFAULT (0)

The terminal's default color. This is what a color with alpha 0 ("no color") becomes.

TB_HI_BLACK

Opaque black. termbox2 would read the color 0x000000 as the default color, so black needs this flag of its own.

A color with an alpha from 1 to 254 is translucent. Terminals cannot blend colors themselves, so "blended_bg_attr" and "blended_fg_attr" compute the mix of such a color with the attribute below it. The terminal default color has no RGB value to mix with; see those functions for what happens then.

Truecolor is always available: termbox2 is compiled into the distribution with 64-bit attributes (see Term::Fabulous::Termbox).

FUNCTIONS

Nothing is exported by default. Import the functions you need by name, and "STYLE_FLAGS" likewise.

color_attr

my $attr = color_attr($color);

Takes a Term::Fabulous::Color object and returns its attribute: TB_DEFAULT when its alpha is 0, TB_HI_BLACK for black, and the packed 0xRRGGBB value otherwise. Results are cached (the cache is emptied when it reaches 4096 entries).

clay_color

my $color = clay_color( $command->{renderData}{backgroundColor} );

Takes a color as it appears in Clay render commands, a hash reference with the keys r, g, b and a, and returns the matching Term::Fabulous::Color object. Results are cached, so a frame does not parse colors it has seen before (the cache is emptied when it reaches 4096 entries). Dies unless the argument is a hash reference; invalid channels die in Term::Fabulous::Color.

cell_color_attr

my $attr = cell_color_attr( fg => $color );

Converts the color argument of the canvas drawing methods (see "Colors" in Term::Fabulous::Widget::Canvas) into an attribute:

  • undef returns undef ("no color of its own").

  • A non-negative integer is taken as a packed 0xRRGGBB color as it is; 0 becomes TB_HI_BLACK. Integers above 0xFFFFFF die.

  • A Term::Fabulous::Color object, or anything Term::Fabulous::Color->new accepts ([r, g, b, a], '#rrggbb', 'hsl(...)', ...), goes through "color_attr". A color with alpha 0 returns undef.

The first argument names the color in error messages, for example Term::Fabulous::Render::Attr: fg must be a packed 0xRRGGBB value, got 16777216. Invalid colors die in Term::Fabulous::Color.

blended_bg_attr

my $attr = blended_bg_attr( $color, $under );

The background attribute of a translucent Term::Fabulous::Color painted over the background attribute $under: each channel of the color is mixed with the channel below it by the color's alpha (over * alpha + under * (255 - alpha), divided by 255 and rounded), and black becomes TB_HI_BLACK. When $under is the terminal default color, which cannot be blended, the result is the color drawn opaque ("color_attr"). Style flags in $under are kept. An opaque color returns itself, a color with alpha 0 returns $under. Results are cached like "color_attr".

blended_fg_attr

my $attr = blended_fg_attr( $color, $under );

The same mix for the foreground attribute $under of a glyph that a translucent background is painted over, so that the glyph shows through tinted. A terminal-default foreground cannot be blended and is returned unchanged; style flags such as TB_REVERSE are kept.

CONSTANTS

STYLE_FLAGS

foreach my $style (STYLE_FLAGS) {
	my ( $flag, $sgr, $name ) = @$style;
	...
}

Every style flag of an attribute, as a list of array references [ $flag, $sgr, $name ] in the order of their SGR parameters (they are shared; do not change them): the termbox2 flag of Term::Fabulous::Termbox, the SGR parameter that switches it on in a terminal, and its name:

TB_BOLD          1  bold
TB_DIM           2  dim
TB_ITALIC        3  italic
TB_UNDERLINE     4  underline
TB_BLINK         5  blink
TB_REVERSE       7  reverse
TB_INVISIBLE     8  invisible
TB_STRIKEOUT     9  strikeout
TB_UNDERLINE_2  21  double_underline
TB_OVERLINE     53  overline

The parameters are the ones termbox2 writes for these flags. "row_text" in Term::Fabulous::Render::Target::Grid writes them, and the screenshot tools read them back, from this one table.

SEE ALSO

Term::Fabulous::Color, Term::Fabulous::Render, "COLORS" in Term::Fabulous::Manual::Looks.