=encoding UTF-8

=head1 NAME

TCOD::Console - Terminal emulator for rendering game screens

=head1 SYNOPSIS

    use TCOD;

    TCOD::Console::init_root( 10, 10, 'Test', 0, TCOD::RENDERER_SDL );

    my $start = TCOD::Console->new( 10, 10 );
    $start->print( 1, 1, 'X' );

    my $end = TCOD::Console->new( 10, 10 );
    $end->print( 8, 8, 'X' );

    for ( 1 .. 255 ) {
        $start->blit( 0, 0, 10, 10, undef, 0, 0, 1,        1        );
        $end->blit(   0, 0, 10, 10, undef, 0, 0, $_ / 255, $_ / 255 );
        TCOD::Console::flush;

        TCOD::Sys::sleep_milli(5);
    }

=head1 DESCRIPTION

This class represents a terminal emulator for rendering text-based games.

=head1 METHODS

=head2 new

    $console = TCOD::Console->new( $width, $height );

You can create as many off-screen consoles as you want by using this function.
You can draw on them as you would do with the root console, but you cannot
flush them to the screen. Else, you can blit them on other consoles, including
the root console. See L<blit|/blit>.

This function returns a TCOD::Console object that can be used as a target in
most console drawing functions.

=head2 from_file

    $console = TCOD::Console->from_file( $path );

You can create an offscreen console from a C<.asc> or C<.apf> file created
with Ascii Paint with this constructor

=head2 save_asc

    $bool = $console->save_asc( $path );

You can save data from a console to Ascii Paint format with this function.
The function returns false if it couldn't write the file. This is the only
ASC function that works also with the root console!

=head2 save_apf

    $bool = $console->save_apf( $path );

You can save data from a console to Ascii Paint format with this function.
The function returns false if it couldn't write the file. This is the only
ASC function that works also with the root console!

=head2 blit

    $console->blit(
        $source_x,
        $source_y,
        $source_width,
        $source_height,
        $target,
        $target_x,
        $target_y,
        $foreground_alpha,
        $background_alpha,
    );

This function allows you to blit a rectangular area of the source console at
a specific position on a destination console. It can also simulate alpha
transparency with foreground and background alpha parameters.

=head2 set_key_color

    $console->set_key_color( $color );

This function defines a transparent background color for this console. All
cells with this background color are ignored when calling L<blit|/blit>.
You can use it to blit only some parts of the console.

=head2 clear

    $console->clear;

Reset all the cells in a console. After calling this method, all cells will
have their foreground and background colors set to the console's current
defaults (see L<set_default_foreground|/set_default_foreground> and friends),
and their ASCII code set to 32 (a blank space).

=head2 get_width

    $width = $console->get_width;

Get the width of the console.

=head2 get_height

    $height = $console->get_height;

Get the height of the console.

=head2 set_background_flag

    $console->set_background_flag( $flag );

Set the background mode for the console. The value of C<$flag> should be a
member of the L<BackgroundFlag|TCOD/BackgroundFlag> enum, determines how the
background color is modified.

=head2 get_background_flag

    $flag = $console->get_background_flag;

Get the console's default background flag. It will be a value from the
L<BackgroundFlag|TCOD/BackgroundFlag> enum.

=head2 set_alignment

    $console->set_alignment( $alignment );

Set the alignment for the console. The value of C<$alignment> should be a
member of the L<Alignment|TCOD/Alignment> enum.

=head2 get_alignment

    $alignment = $console->get_alignment;

Get the console's default alignment flag. It will be a value from the
L<Alignment|TCOD/Alignment> enum.

=head2 set_char_background

    $console->set_char_background( $x, $y, $color, $flag );

Set the background color of a cell, leaving other properties (foreground color
and ASCII code) unchanged. The value of C<$flag>, which should be a member of
the L<BackgroundFlag|TCOD/BackgroundFlag> enum, determines how the background
color is modified.

=head2 get_char_background

    $color = $cosole->get_char_background( $x, $y );

Get the background color of a cell.

=head2 set_char_foreground

    $console->set_char_foreground( $x, $y, $color, $flag );

Set the foreground color of a cell, leaving other properties (background color
and ASCII code) unchanged. The value of C<$flag>, which should be a member of
the L<BackgroundFlag|TCOD/BackgroundFlag> enum, determines how the background
color is modified.

=head2 get_char_foreground

    $color = $cosole->get_char_foreground( $x, $y );

Get the foreground color of a cell.

=head2 set_default_background

    $console->set_default_background( $color );

Change the default background color for a console. This is used by several of
the drawing functions described in this document.

=head2 get_default_background

    $color = $console->get_default_background;

Get the default background color for a console. This is used by several of
the drawing functions described in this document.

=head2 set_default_foreground

    $console->set_default_foreground( $color );

Change the default foreground color for a console. This is used by several of
the drawing functions described in this document.

=head2 get_default_foreground

    $color = $console->get_default_foreground;

Get the default foreground color for a console. This is used by several of
the drawing functions described in this document.

=head2 set_char

    $console->set_char( $x, $y, $char_code );

Set the character at the specified coordinate to the specified character
without changing its colors.

The character is passed as an integer code, like one returned by C<ord>
or one of the values in the L<Char|TCOD/Char> enum.

=head2 get_char

    $char_code = $console->get_char( $x, $y );

Return the character at the specified position in the console.

The character is returned as an integer code, like one returned by C<ord>
or one of the values in the L<Char|TCOD/Char> enum.

=head2 put_char

    $console->put_char( $x, $y, $char_code, $background_flag );

Draw a character on a console using the default colors.

The character is passed as an integer code, like one returned by C<ord>
or one of the values in the L<Char|TCOD/Char> enum.

The value in C<$background_flag> determines the behaviour of the background,
and should be one of the values in the L<BackgroundFlag|TCOD/BackgroundFlag>
enum.

=head2 put_char_ex

    $console->put_char_ex(
        $x,
        $y,
        $char_code,
        $foreground_color,
        $background_color,
    );

Draw a character on a console using the default colors.

The character is passed as an integer code, like one returned by C<ord>
or one of the values in the L<Char|TCOD/Char> enum.

=head2 print

    $console->print(             $x, $y,                        $str );
    $console->print_ex(          $x, $y,         $flag, $align, $str );
    $console->print_rect(        $x, $y, $w, $h,                $str );
    $console->print_rect_ex(     $x, $y, $w, $h, $flag, $align, $str );

    $console->print_utf(         $x, $y,                        $str );
    $console->print_ex_utf(      $x, $y,         $flag, $align, $str );
    $console->print_rect_utf(    $x, $y, $w, $h,                $str );
    $console->print_rect_ex_utf( $x, $y, $w, $h, $flag, $align, $str );

Print a string to the console. The different flavours of this function
allow you to set the position of the text to print ( using the C<$x> and
C<$y> coordinates), the dimensions of a box to print it in when it should
wrap (with C<$w> and C<$h>), the background flag to determine the
behaviour of the background (with C<$flag>, which must be a value in the
L<BackgroundFlag|TCOD/BackgroundFlag> enum), the alignment of the text (with
C<$align>, which must be a value in the L<Alignment|TCOD/Alignment> enum).

In all cases, the final value is a string to print. To print UTF-8 strings,
use L<Encode/decode> and use the functions ending in C<_utf>.

The string can contain the C<%c> sequence to work as a control code
placeholders, which will be replaced with any control codes passed in as
additional arguments to these functions, in a manner similar to the C<printf>
family of functions.

Note that, for now, these Perl bindings allow only two such additional codes.

See L<set_color_control|/set_color_control> for how to define the value of
these codes.

=head2 print_frame

    $console->print_frame( $x, $y, $w, $h, $clear, $flag, $str );

This function calls the L<rect|/rect> function using the supplied parameters,
then draws a rectangle with the console's default foreground color.

The value of C<$str> is printed on the top of the rectangle, using inverted
colors.

=head2 get_height_rect

    $height = $console->get_height_rect(     $x, $y, $w, $h, $string );
    $height = $console->get_height_rect_utf( $x, $y, $w, $h, $string );

Returns the expected height of an autowrapped string without actually printing
the string with one of the L<print_rect> family of functions.

=head2 rect

    $console->rect( $x, $y, $w, $h, $clear, $flag );

Fills a rectngle in the console with the specified position and dimensions.

The background color for every cell inside the rectangle will be adjusted with
the default background color of the console (the value in C<$flag> will
determine what effect this wil have on the cell's color).

If C<$clear> is set to a true value, their ASCII code will be set to 32 (space).

=head2 hline

    $console->hline( $x, $y, $length, $flag );

Draws a horizontal line in the console, using ASCII code 196
(C<TCOD::CHAR_HLINE>), and the console's default background/foreground colors.

=head2 vline

    $console->vline( $x, $y, $length, $flag );

Draws an vertical line in the console, using ASCII code 179
(C<TCOD::CHAR_VLINE>), and the console's default background/foreground colors.

=head1 FUNCTIONS

=head2 init_root

    TCOD::Console::init_root(
        $width,
        $height,
        $title,
        $fullscreen,
        $renderer,
    );

Initialise the global game window.

The width and height parameters specify the dimensions of the screen in
characters. The size of the window in pixels will depend on the font used.
The default font uses characters that are 8x8 pixels. See
L<set_custom_font|/set_custom_font> for how to change this font after
creation.

The title will be displayed on top of the window, except when in fullscreen
mode. See L<set_window_title|/set_window_title> for how to change this after
creation.

The window will be created in fullscreen if the value of C<$fullscreen> is
true. See L<set_fullscreen|/set_fullscreen> and
L<is_fullscreen|/is_fullscreen> for ways to modify this after creation.

The renderer will be one of the elements of the L<Renderer|TCOD/Renderer>
enum. If you select a renderer that is not supported by the player's machine,
the underlying library will scan the lower renderers until it finds a working
one.

On recent video cards, GLSL (enabled with C<TCOD::RENDERER_GLSL>) results in
up to 900% increase of framerates in the true color sample compared to SDL
renderer.

Whatever renderer you use, it can always be overridden by the player through
the C<libtcod.cfg> file.

You can dynamically change the renderer after calling this function with
L<TCOD::Sys::set_renderer|TCOD::Sys/set_renderer>. You can also read the
current renderer with L<TCOD::Sys::get_renderer|TCOD::Sys/get_renderer>. This
might be different from the one you set when calling this function in case
it's not supported on the player's computer.

=head2 set_custom_font

    TCOD::Console::set_custom_font(
        $string,
        $flags,
        $horizontal_chars,
        $vertical_chars,
    );

This function allows you to use a bitmap font (PNG or BMP) with custom
character size or layout.

It should be called before initializing the root console with
L<init_root|/init_root>.

Once this function is called, you can define your own custom mappings using
mapping functions

The value in C<$flags> will be a combination of a layout and a type from the
L<FontFlag|TCOD/FontFlag> enum. The last two parameters determine the number
of characters in the font along both axes. If set to 0, these will be deduced
from the layout flag.

=head2 map_ascii_code_to_font

    TCOD::Console::map_ascii_code_to_font( $code, $x, $y );

Maps a single ASCII code to a character in the current font.

=head2 map_ascii_codes_to_font

    TCOD::Console::map_ascii_codes_to_font(
        $range_start,
        $range_length,
        $x,
        $y,
    );

Maps consecutive ASCII codes to characters in the current font. The
coordinate provided (in characters) corresponds to the first character in
the range.

=head2 map_string_to_font

    TCOD::Console::map_string_to_font( $string, $x, $y );

Maps the ASCII codes in a string to consecutive characters in the current
font. The coordinate provided (in characters) corresponds to the first
character in the range.

=head2 is_fullscreen

    TCOD::Console::is_fullscreen;

Returns true if the current mode is fullscreen.

=head2 set_fullscreen

    TCOD::Console::set_fullscreen( $bool );

Enable or disable fullscreen mode.

=head2 set_window_title

    TCOD::Console::set_window_title( $title );

This function dynamically changes the title of the game window.

=head2 is_window_closed

    $bool = TCOD::Console::is_window_closed;

When you start the program, this returns false. Once a "close window"
event has been sent by the window manager, it will always return true.
You're supposed to cleanly exit the game.

=head2 has_mouse_focus

    $bool = TCOD::Console::has_mouse_focus;

Returns true if the mouse cursor is inside the game window area and the
game window is the active application.

=head2 is_active

    $bool = TCOD::Console::is_active;

Returns false if the game window is not the active window or is iconified.

=head2 credits

    TCOD::Console::credits;

Render a credits screen with the message "Powered by libtcod C<$VERSION>",
with the current libtcod version you are running. This can be shown during
startup by calling after L<init_root|/init_root>.

The credits screen can be skipped by pressing any key.

=head2 credits_render

    $bool = TCOD::Console::credits_render( $x, $y, $alpha );

Render the credits message on top of an existing screen at the specified
coordinates. If C<$alpha> is set to a true value, the credits will be
rendered transparently on the existing screen. For this to work, this
function must be called between your screen rendering code and the console
L<flush|/flush>.

Returns true when the credits screen is finished.

=head2 credits_reset

    TCOD::Console::credits_reset;

When using L<credits_render>, you can restart the credits animation from
the beginning before it's finished by calling this function.

=head2 flush

    TCOD::Console::flush;

Once the root console is initialized, you can use one of the printing
functions to change the background colors, the foreground colors or the
ASCII characters on the console.

Once you've finished rendering the root console, you have to actually
apply the updates to the screen with this function.

=head2 set_fade

    TCOD::Console::set_fade( $fade, $color );

This function defines the fading parameters, allowing you to fade the game
screen to/from a color. Once they are defined, the fading parameters are
valid until changed (with another call to this function). You don't have to
call this function for each rendered frame.

=head2 get_fade

    $fade = TCOD::Console::get_fade;

Get the current fade amount. See L<set_fade|/set_fade> for how this is set.

=head2 get_fading_color

    $color = TCOD::Console::get_fading_color;

Get the current fade color. See L<set_fade|/set_fade> for how this is set.

=head2 set_color_control

    TCOD::Console::set_color_control(
        $code,
        $foreground_color,
        $background_color,
    );

If you want to draw a string using different colors for each word, the basic
solution is to call a string printing function several times, changing the
default colors between each call.

An arguably simpler way to do this is to use "color control codes" in your
string, which allows you to draw a string using different colors in a single
call.

A color control code is associated with a foreground and background color set.
If you insert this code in your string, the next characters will use the
colors associated with the color control code.

There are 5 predefined color control codes:

=over

=item * TCOD::COLCTRL_1

=item * TCOD::COLCTRL_2

=item * TCOD::COLCTRL_3

=item * TCOD::COLCTRL_4

=item * TCOD::COLCTRL_5

=back

This function allows you to associate a control code to a color set.

To go back to the console's default colors, insert in your string the color
stop control code: C<TCOD::COLCTRL_STOP>.

You can also use any color without assigning it to a control code, using the
generic control codes: C<TCOD::COLCTRL_FORE_RGB> and C<TCOD::COLCTRL_BACK_RGB>.

These controls respectively change the foreground and background color used to
print the string characters. In the string, you must insert the red, green,
and blue components of the color as numbers between 1 and 255 immediately
after this code. Note that using 0 in this context is not allowed, because it
represents the end of the string in C/C++.

=head2 check_for_keypress

    # Deprecated
    $key = TCOD::Console::check_for_keypress( $mask );

Return immediately with a L<TCOD::Key> populated with data from a recently
pressed key.

The current recommendation, however, is to use SDL functions directly to check
the keyboard state. Consider that option if available.

=head2 is_key_pressed

    # Deprecated
    $bool = TCOD::Console::is_key_pressed( $keycode );

Given a keycode from the L<Keycode|TCOD/Keycode> enum, this function returns
true if the key is currently pressed.

A better way to check for user input is to use
L<TCOD::Sys::check_for_event|TCOD::Sys/check_for_event>.

The current best recommendation, however, is to use SDL functions directly to
check the keyboard state. Consider that option if available.

=head1 SEE ALSO

=over

=item L<TCOD>

=item L<TCOD::Key>

=item L<TCOD::Color>

=item L<TCOD::Image>

=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.
