KTech::Output Class Reference

Engine component responsible for outputting rendered images. More...

#include <output.hpp>

Public Member Functions
void	PrintStartupNotice (const std::string &title, const std::string &years, const std::string &author, const std::string &programName) const
	Print a copyright notice.
void	Clear ()
	Clear the image buffer.
void	Draw (const std::vector< Cell > &sourceImage, UPoint resolution, Point position=Point(0, 0), UPoint start=UPoint(0, 0), UPoint end=UPoint(0, 0), uint8_t alpha=std::numeric_limits< uint8_t >::max())
	Draw a Cell-based image .
void	Draw (const std::vector< CellA > &sourceImage, UPoint resolution, Point position=Point(0, 0), UPoint start=UPoint(0, 0), UPoint end=UPoint(0, 0), uint8_t alpha=std::numeric_limits< uint8_t >::max())
	Draw a CellA-based image .
void	Print ()
	Print the internal image buffer.
auto	ShouldRenderThisTick () -> bool
	Check whether things changed and require a new render.
auto	ShouldPrintThisTick () const -> bool
	Check whether the terminal changed and requires a new print.

Static Public Member Functions
static void	Log (const std::string &text, RGB color)
	Print colored log text to the terminal.

Public Attributes
const UPoint	resolution
	The size of the image buffer (viewport).
std::vector< std::string >	outputOnQuit
	Vector of strings to print when the game quits (specifically, in Output::~Output()).

Friends
class	Engine

Detailed Description

Engine component responsible for outputting rendered images.

Member Function Documentation

Clear()

void KTech::Output::Clear

(

)

Clear the image buffer.

Doesn't clear the terminal; that is done by Output::Print() just before printing the new image.

Use this function if you need to draw your image on a blank sheet. For example, if you simply draw a fully-opaque Camera image each frame, you can probably skip this part, because Camera images completely override old image buffer cells. However, if you are drawing a UI image, you will want to first call this function, because UI images don't always completely override old image buffer cells. This is because Camera images are Cell-based, while UI images are CellA-based.

It's recommended to use this function in conjunction with Output::ShouldRenderThisTick().

See also

Output::ShouldRenderThisTick()

Draw() [1/2]

void KTech::Output::Draw	(	const std::vector< Cell > &	sourceImage,
		UPoint	resolution,
		Point	position = Point(0, 0),
		UPoint	start = UPoint(0, 0),
		UPoint	end = UPoint(0, 0),
		uint8_t	alpha = std::numeric_limits<uint8_t>::max() )

Draw a Cell-based image .

This function is used for Camera images. It is supposed to completely override old image buffer cells, unless alpha is not set to max (255).

It's recommended to use this function in conjunction with Output::ShouldRenderThisTick().

Parameters

[in]	sourceImage	Image to draw.
[in]	resolution	Resolution of the given sourceImage.
[in]	position	Where to draw the image on the internal image buffer.
[in]	start	From where to draw sourceImage.
[in]	end	Until where to draw sourceImage.
[in]	alpha	Opacity to draw at.

See also

Output::ShouldRenderThisTick()

Draw() [2/2]

void KTech::Output::Draw	(	const std::vector< CellA > &	sourceImage,
		UPoint	resolution,
		Point	position = Point(0, 0),
		UPoint	start = UPoint(0, 0),
		UPoint	end = UPoint(0, 0),
		uint8_t	alpha = std::numeric_limits<uint8_t>::max() )

Draw a CellA-based image .

This function is used for UI images. It is supposed to draw over old image buffer cells rather than completely override them (like Camera images do). This behavior is desired so a UI image can be drawn like a heads-up display, for example, on top of a fully-opaque Camera image.

It's recommended to use this function in conjunction with Output::ShouldRenderThisTick().

Parameters

[in]	sourceImage	Image to draw.
[in]	resolution	Resolution of the given sourceImage.
[in]	position	Where to draw the image on the internal image buffer.
[in]	start	From where to draw sourceImage.
[in]	end	Until where to draw sourceImage.
[in]	alpha	Opacity to draw at.

See also

Output::ShouldRenderThisTick()

Log()

void KTech::Output::Log ( const std::string & text, RGB color )

static

Print colored log text to the terminal.

Simply std::cout's and std::flash's the given text. It has no unique functionality, and doesn't integrate with the output system.

This function is really only useful when no other printing is being done, because Output::Print() will print over the logged text in the terminal.

Parameters

[in]	text	Text to print.
[in]	color	Color for the outputted text.

Print()

void KTech::Output::Print

(

)

Print the internal image buffer.

Call this function after preparing the image buffer using Output::Clear() and Output::Draw() in whatever way that fits your needs.

It's recommended to use this function in conjunction with Output::ShouldRenderThisTick() and Output::ShouldPrintThisTick().

See also

Output::ShouldRenderThisTick(), Output::ShouldPrintThisTick()

PrintStartupNotice()

void KTech::Output::PrintStartupNotice	(	const std::string &	title,
		const std::string &	years,
		const std::string &	author,
		const std::string &	programName ) const

Print a copyright notice.

The GPLv3 requires your "interactive user interface" (your game) to display "Appropriate Legal Notices", which are defined in the following excerpt:

‍An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

You can use this function (or your own implementation) to just print everything that's needed (appropriate copyright notice, warranty disclaimer, copying, and viewing a copy of the license). This function simplifies this by putting your parameter values into a prepared template. If your warranty status differs from what this function prints, you should of course print this on your own.

If you want to have a "prominent item" in your menu to display Appropriate Legal Notices (whether in addition to or instead of printing at the start of your game), you can use the AboutBox widget to display the text, and Switch to hide and show it. This exact method is practiced in the "widgetstest" game example.

Parameters

[in]	title	Title of your project (name and brief description).
[in]	years	Years where your project was released in.
[in]	author	Your name.
[in]	programName	Your project's name.

Something like this will be printed:

{title}
Copyright (C) {years} {author}
 
{programName} is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
he Free Software Foundation, either version 3 of the License, or
any later version.
 
{programName} is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

ShouldPrintThisTick()

auto KTech::Output::ShouldPrintThisTick ( ) const -> bool

nodiscard

Check whether the terminal changed and requires a new print.

The Output engine component keeps track of the terminal size, because if it changes, the printed image needs to adapt. If that happened, this function returns true, telling you that the image buffer should be printed again.

For best performance, use this function in conjunction with Output::ShouldRenderThisTick(). Here's an example:

if (engine.output.ShouldRenderThisTick())
{
    // Render, draw and print
    ui.Render();
    engine.output.Clear();
    ui.Render();
    engine.output.Print();
}
else if (engine.output.ShouldPrintThisTick())
{
    // Just print
    engine.output.Print();
}

When no-game-loop mode is enabled, this function always returns true.

Returns

Whether you should print again.

See also

Output::ShouldRenderThisTick()

Engine::noGameLoopMode

ShouldRenderThisTick()

auto KTech::Output::ShouldRenderThisTick ( ) -> bool

nodiscard

Check whether things changed and require a new render.

Various callback and virtual functions in KTech are expected to return a bool value (e.g. OnTick() virtual functions, and input callback functions registered at CallbackGroup::RegisterCallback()). They should return true if they changed something in the game's world, that might require the game to render a new frame. They should return false if they certainly did not change anything, meaning the game doesn't have to render a new frame.

The Input, Memory and Time engine components remember whether any virtual or callback function returned true throughout the last tick. If any did, it means something has changed (like the position of an Object or the appearance of a Texture). In that case, this function will return true. This allows to "render on demand", i.e., avoid rendering when certainly nothing has changed.

For best performance, use this function in conjunction with Output::ShouldRenderThisTick() (there is an example at its documentation entry).

When no-game-loop mode is enabled, this function always returns true.

Returns

Whether you should render and draw again.

See also

Output::ShouldPrintThisTick()

Engine::noGameLoopMode

---

The documentation for this class was generated from the following files:

• ktech/engine/output.hpp
• ktech/engine/output.cpp