2.5. Using off-screen consoles
- Creating an offscreen console
- Creating an offscreen console from a .asc or .apf file
- Loading an offscreen console from a .asc file
- Loading an offscreen console from a .apf file
- Saving a console to a .asc file
- Saving a console to a .apf file
- Blitting a console on another one
- Define a blit-transparent color
- Destroying an offscreen console
The offscreen consoles allow you to draw on secondary consoles as you would do with the root console. You can then blit those secondary consoles on the root console. This allows you to use local coordinate space while rendering a portion of the final screen, and easily move components of the screen without modifying the rendering functions.
Creating an offscreen console
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 blit. The C version of this function returns a console handler that you can use in most console drawing functions.
TCODConsole::TCODConsole(int w, int h)
TCOD_console_t TCOD_console_new(int w, int h)
console_new(w,h)
TCODConsole::TCODConsole(int w, int h)
tcod.Console(w,h)
Parameter | Description |
---|---|
w,h | the console size. 0 < w 0 < h |
Example:
// Creating a 40x20 offscreen console, filling it with red and blitting it on the root console at position 5,5
TCODConsole *offscreenConsole = new TCODConsole(40,20);
offscreenConsole->setDefaultBackground(TCODColor::red);
offscreenConsole->clear();
TCODConsole::blit(offscreenConsole,0,0,40,20,TCODConsole::root,5,5,255);
TCOD_console_t offscreen_console = TCOD_console_new(40,20);
TCOD_console_set_default_background(offscreen_console,TCOD_red);
TCOD_console_clear(offscreen_console);
TCOD_console_blit(offscreen_console,0,0,40,20,NULL,5,5,255);
offscreen_console = libtcod.console_new(40,20)
libtcod.console_set_background_color(offscreen_console,libtcod.red)
libtcod.console_clear(offscreen_console)
libtcod.console_blit(offscreen_console,0,0,40,20,0,5,5,255)
-- Creating a 40x20 offscreen console, filling it with red and blitting it on the root console at position 5,5
offscreenConsole = tcod.Console(40,20)
offscreenConsole:setBackgroundColor(tcod.color.red)
offscreenConsole:clear()
tcod.console.blit(offscreenConsole,0,0,40,20,libtcod.TCODConsole_root,5,5,255)
Creating an offscreen console from a .asc or .apf file
You can create an offscreen console from a file created with Ascii Paint with this constructor
TCODConsole::TCODConsole(const char *filename)
TCOD_console_t TCOD_console_from_file(const char *filename)
Parameter | Description |
---|---|
filename | path to the .asc or .apf file created with Ascii Paint |
Example:
// Creating an offscreen console, filling it with data from the .asc file
TCODConsole *offscreenConsole = new TCODConsole("myfile.asc");
TCOD_console_t offscreen_console = TCOD_console_from_file("myfile.apf");
Loading an offscreen console from a .asc file
You can load data from a file created with Ascii Paint with this function. When needed, the console will be resized to fit the file size. The function returns false if it couldn't read the file.
bool TCODConsole::loadAsc(const char *filename)
bool TCOD_console_load_asc(TCOD_console_t con, const char *filename)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler |
filename | path to the .asc file created with Ascii Paint |
Example:
// Creating a 40x20 offscreen console
TCODConsole *offscreenConsole = new TCODConsole(40,20);
// possibly resizing it and filling it with data from the .asc file
offscreenConsole->loadAsc("myfile.asc");
TCOD_console_t offscreen_console = TCOD_console_new(40,20);
TCOD_console_load_asc(offscreen_console,"myfile.asc");
Loading an offscreen console from a .apf file
You can load data from a file created with Ascii Paint with this function. When needed, the console will be resized to fit the file size. The function returns false if it couldn't read the file.
bool TCODConsole::loadApf(const char *filename)
bool TCOD_console_load_apf(TCOD_console_t con, const char *filename)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler |
filename | path to the .apf file created with Ascii Paint |
Example:
// Creating a 40x20 offscreen console
TCODConsole *offscreenConsole = new TCODConsole(40,20);
// possibly resizing it and filling it with data from the .apf file
offscreenConsole->loadApf("myfile.apf");
TCOD_console_t offscreen_console = TCOD_console_new(40,20);
TCOD_console_load_apf(offscreen_console,"myfile.asc");
Saving a console to a .asc file
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 !
bool TCODConsole::saveAsc(const char *filename) const
bool TCOD_console_save_asc(TCOD_console_t con, const char *filename)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
filename | path to the .asc file to be created |
Example:
console->saveAsc("myfile.asc");
TCOD_console_save_asc(console,"myfile.asc");
Saving a console to a .apf file
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 !
bool TCODConsole::saveApf(const char *filename) const
bool TCOD_console_save_apf(TCOD_console_t con, const char *filename)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
filename | path to the .apf file to be created |
Example:
console->saveApf("myfile.apf");
TCOD_console_save_apf(console,"myfile.apf");
Blitting a console on another one
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 the fade parameter.
static void blit(const TCODConsole *src,int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole *dst, int xDst, int yDst, float foregroundAlpha=1.0f, float backgroundAlpha=1.0f)
void TCOD_console_blit(TCOD_console_t src,int xSrc, int ySrc, int wSrc, int hSrc, TCOD_console_t dst, int xDst, int yDst, float foreground_alpha, float background_alpha)
console_blit(src,xSrc,ySrc,xSrc,hSrc,dst,xDst,yDst,foregroundAlpha=1.0,backgroundAlpha=1.0)
static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst)
static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst, float foreground_alpha)
static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst, float foreground_alpha, float background_alpha)
tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst)
tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst, foreground_alpha)
tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst, foreground_alpha, background_alpha)
Parameter | Description |
---|---|
src | The source console that must be blitted on another one. |
xSrc,ySrc,wSrc,hSrc | The rectangular area of the source console that will be blitted. If wSrc and/or hSrc == 0, the source console width/height are used |
dst | The destination console. |
xDst,yDst | Where to blit the upper-left corner of the source area in the destination console. |
foregroundAlpha,backgroundAlpha | Alpha transparency of the blitted console. 0.0 => The source console is completely transparent. This function does nothing. 1.0 => The source console is opaque. Its cells replace the destination cells. 0 < fade < 1.0 => The source console is partially blitted, simulating real transparency. |
Example:
// Cross-fading between two offscreen consoles. We use two offscreen consoles with the same size as the root console. We render a different screen on each offscreen console. When the user hits a key, we do a cross-fading from the first screen to the second screen.
TCODConsole *off1 = new TCODConsole(80,50);
TCODConsole *off2 = new TCODConsole(80,50);
... print screen1 on off1
... print screen2 of off2
// render screen1 in the game window
TCODConsole::blit(off1,0,0,80,50,TCODConsole::root,0,0);
TCODConsole::flush();
// wait or a keypress
TCODConsole::waitForKeypress(true);
// do a cross-fading from off1 to off2
for (int i=1; i <= 255; i++) {
TCODConsole::blit(off1,0,0,80,50,TCODConsole::root,0,0); // renders the first screen (opaque)
TCODConsole::blit(off2,0,0,80,50,TCODConsole::root,0,0,i/255.0,i/255.0); // renders the second screen (transparent)
TCODConsole::flush();
}
TCOD_console_t off1 = TCOD_console_new(80,50);
TCOD_console_t off2 = TCOD_console_new(80,50);
int i;
... print screen1 on off1
... print screen2 of off2
// render screen1 in the game window
TCOD_console_blit(off1,0,0,80,50,NULL,0,0,1.0,1.0);
TCOD_console_flush();
// wait or a keypress
TCOD_console_wait_for_keypress(true);
// do a cross-fading from off1 to off2
for (i=1; i <= 255; i++) {
TCOD_console_blit(off1,0,0,80,50,NULL,0,0,1.0,1.0); // renders the first screen (opaque)
TCOD_console_blit(off2,0,0,80,50,NULL,0,0,i/255.0,i/255.0); // renders the second screen (transparent)
TCOD_console_flush();
}
off1 = libtcod.console_new(80,50)
off2 = libtcod.console_new(80,50)
... print screen1 on off1
... print screen2 of off2
# render screen1 in the game window
libtcod.console_blit(off1,0,0,80,50,0,0,0)
libtcod.console_flush()
# wait or a keypress
libtcod.console_wait_for_keypress(True)
# do a cross-fading from off1 to off2
for i in range(1,256) :
litbcod.console_blit(off1,0,0,80,50,0,0,0) # renders the first screen (opaque)
litbcod.console_blit(off2,0,0,80,50,0,0,0,i/255.0,i/255.0) # renders the second screen (transparent)
litbcod.console_flush()
-- Cross-fading between two offscreen consoles. We use two offscreen consoles with the same size as the root console. We render a different screen on each offscreen console. When the user hits a key, we do a cross-fading from the first screen to the second screen.
off1 = tcod.Console(80,50)
off2 = tcod.Console(80,50)
... print screen1 on off1
... print screen2 of off2
-- render screen1 in the game window
root=libtcod.TCODConsole_root
tcod.console.blit(off1,0,0,80,50,root,0,0)
tcod.console.flush()
-- wait or a keypress
tcod.console.waitForKeypress(true)
-- do a cross-fading from off1 to off2
for i=1,255,1 do
tcod.console.blit(off1,0,0,80,50,root,0,0) -- renders the first screen (opaque)
tcod.console.blit(off2,0,0,80,50,root,0,0,i/255,i/255) -- renders the second screen (transparent)
tcod.console.flush()
end
Define a blit-transparent color
This function defines a transparent background color for an offscreen console. All cells with this background color are ignored by the blit operation. You can use it to blit only some parts of the console.
void TCODConsole::setKeyColor(const TCODColor &col)
void TCOD_console_set_key_color(TCOD_console_t con,TCOD_color_t col)
console_set_key_color(con,col)
void TCODConsole::setKeyColor(TCODColor col)
Console:setKeyColor(col)
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler or NULL for the root console |
col | the transparent background color |
Destroying an offscreen console
Use this function to destroy an offscreen console and release any resources allocated. Don't use it on the root console.
TCODConsole::~TCODConsole()
void TCOD_console_delete(TCOD_console_t con)
console_delete(con)
void TCODConsole::Dispose()
through garbage collector
Parameter | Description |
---|---|
con | in the C and Python versions, the offscreen console handler |
Example:
TCODConsole *off1 = new TCODConsole(80,50);
... use off1
delete off1;
TCOD_console_t off1 = TCOD_console_new(80,50);
... use off1
TCOD_console_delete(off1);
off1 = libtcod.console_new(80,50)
... use off1
libtcod.console_delete(off1)
off1 = tcod.Console(80,50)
... use off1
off1=nil