Short tutorial for the new ConsoleBuffer class

[Jotaf]

If you've been following Jice's blog, you know that there's a new class that lets you speed up your game's FPS significantly.

But how do you use it, and more importantly, is it easy to use? I hope so, and this post is meant to show you just that!


How and why

Python can probably run most of your game's code fast enough. It's the heavy work of updating dozens of thousands of cells, many times per second, that can cause it to choke! This won't be the case with many fine-looking turn-based games, but will happen if your game has real-time animations on a big portion of the screen.

ConsoleBuffer is a native Python class that buffers your cell updates and then sends them to libtcod all at once. It's very easy to use, as you'll see. For the usual tasks of drawing GUI's and rendering text, you'll still use the regular libtcod functions.

If you're using libtcod 1.5.1 - build 2 (the latest), you can just replace your libtcodpy.py file with the one I'm attaching here. It will also be available in later libtcod versions.

I also attached an updated samples script; you can activate fast rendering by pressing 'F'.


The typical rendering code!

Time to see some code!
Here's an example that computes some colors based on a cell's location, and updates that cell's background color.

Code:

for y in xrange(SCREEN_HEIGHT):
    for x in xrange(SCREEN_WIDTH):
        
        #make up a color for this cell...
        r = int(x * 255.0 / SCREEN_WIDTH)
        g = int(y * 255.0 / SCREEN_HEIGHT)
        b = int(255 - r / 2 - g / 2)

        #set this cell's background color on the buffer
        libtcod.console_set_back(con, x, y, libtcod.Color(r, g, b), libtcod.BKGND_SET)

Normally you'd get those colors from your map, FOV and maybe some light information.

But that's tens of thousands of expensive calls to console_set_back. How to make it faster?


With ConsoleBuffer

You can use ConsoleBuffer very easily. Just create a buffer, update the cells with the functions set_back, set_fore or set (more info later), and in the end call blit to send those updates to your favorite console.

Code:

#create a buffer the same size as the screen
buffer = libtcod.ConsoleBuffer(SCREEN_WIDTH, SCREEN_HEIGHT)

for y in xrange(SCREEN_HEIGHT):
    for x in xrange(SCREEN_WIDTH):
        
        #make up a color for this cell...
        r = int(x * 255.0 / SCREEN_WIDTH)
        g = int(y * 255.0 / SCREEN_HEIGHT)
        b = int(255 - r / 2 - g / 2)

        #set this cell's background color on the buffer
        buffer.set_back(x, y, r, g, b)

#draw the buffer's contents to a console
buffer.blit(con)

That's all! A few tips:

• The speed-up is much greater in Python 2.6 than Python 2.7. In fact, for some reason many games will be slower with 2.7, so I recommend you install the earlier version instead.
• Avoid calling libtcod's functions repeatedly in your inner rendering loop, or the advantage will be lost. This isn't hard if you don't mind working with the RGB values and go without libtcod's functions.

The full documentation is right below this post.

Happy rendering, and please direct any comments to me in this or another thread!

[Jotaf]

Documentation for the ConsoleBuffer class

Code:

buffer = ConsoleBuffer(width, height, back_r=0, back_g=0, back_b=0, fore_r=0, fore_g=0, fore_b=0, char=' ')

Creates a ConsoleBuffer with specified size. Optionally, you can set the initial background color (R, G and B), foreground color, and character.

Code:

buffer.clear(back_r=0, back_g=0, back_b=0, fore_r=0, fore_g=0, fore_b=0, char=' ')

Clears the buffer with specified initial background color (R, G and B), foreground color, and character.

Code:

buffer.copy()

Returns an independent copy of the buffer (if you just used "buffer2 = buffer" both would point to the same buffer).

Code:

buffer.set_fore(x, y, r, g, b, char)

Sets the foreground color and character of a cell.

Code:

buffer.set_back(x, y, r, g, b)

Sets the background color of a cell.

Code:

buffer.set(x, y, back_r, back_g, back_b, fore_r, fore_g, fore_b, char)

Sets background color, foreground color and character of a cell, all at the same time.

Code:

buffer.blit(dest, fill_fore=True, fill_back=True)

Copies the results to a regular libtcod console. It must have the same size. If you don't need to copy the cells' foreground or background color, set the 2nd or 3rd argument to False, respectively.

[Jotaf]

Another tip:

For color interpolation, without using libtcod's awesome lerp function (which would slow down your rendering code), you can just use the formula:

Code:

r = int(alpha * r1 + (1-alpha) * r2)

And the same way for the green and blue components. This mixes colors (r1, g1, b1) and (r2, g2, b2) with a transparency of alpha.

[researcho]

  very cool!!!!!!

i certainly use that on m RL, but not yet i fear, since i don't have really problems with slow render... but i think this thing will be very useful when i add some heightmap and blit2X functions, that i want to use for enhance visualization for future versions, so i keep this in mind!

[XLambda]

Awesome, thanks for this! It will go right into my project! 

[researcho]

speaking of colors, that buffer functions did't work with libtcod colors?

if not (and if it won't get implemented) ... how can i get rgb values from libtcod colors? the docs didn't say...

solving that i'll no have any problems with using ConsoleBuffer

[Jotaf]

I'm glad you like it

You can access a color's RGB values easily as color.r, color.g and color.b. For example:

Code:

buffer.set_back(x, y, color.r, color.g, color.b)

So you can keep storing and manipulating your colors as libtcod color objects if you want! For example, each tile in your map can have a libtcod color for the background. You can access their RGB values just fine when using ConsoleBuffer, but try not to apply libtcod's functions to these colors if you want maximum FPS. Just grab their RGB values and manipulate them yourself

[researcho]

 

ok the colours issue is solved... but for some reason it won't work with my custom font, so i get ascii characters like ü, é... instead of my nethack icons.. i don't know why happen that, since i set the custom font for the console and it never change  

[Jotaf]

Hm... can you post a script that recreates it, like printing some of those chars to the screen? (You'd need to post the font here too.) Thanks

[researcho]

i made it and.... works perfect 

it HAS to be my fault on something, i'll dive in my own code, but for now i left Buffer optional with a flag, and let the flag be 0 for now... when i really need Buffer, i'll try again this 

[Jotaf]

Ok, that's great