Basic Embedding

[Richard Kain]

I mentioned posting an example of what I came up with, and I do like to deliver. For any Python-heads out there, here you go...

Code:

import tilengine as tln
import pygame as pgm

#Time to handle the basic start-up code for the Tilengine
tEngine = tln.Engine.create(640, 480, 1, 0, 1)
tBack = tln.Bitmap.fromfile("beach.png") #I'm taking the beach image from the color-cycling example here, you can replace this with any other graphic image you have on hand.
tEngine.set_background_bitmap(tBack) #We're assuming your image is in the same folder, check the standard example projects if you require more advanced resource loading.

#We've got the basics of the Tilengine running, now it's time to fire up our basic PyGame
pgm.init()
pgm.display.set_caption("Tilengine Embed Trial")
pyScreen = pgm.display.set_mode((640, 480), pgm.RESIZABLE) #This fires up PyGame's basic rendering, and returns to us a PyGame Surface to work with. We're using the Resizable flag to test window resizing.

pyTargetRender = pgm.Surface((640, 480), 0, 32) #We have a reference to the screen, but now we want a placeholder Surface that we can use as a target for the Tilengine rendering
pyTargetRender.fill((98, 98, 98, 255)) #We'll fill the target area with a darker grey tone, just so it will stand out from the default background.

tEngine.set_render_target(pyTargetRender._pixels_address, 2560) #This is where the magic happens. We are taking our Tilengine object, and pointing its rendering to the placeholder Surface we created
#We're using the built-in _pixel_address reference in PyGame to retrieve a memory-address for the pixel-buffer of the placeholder Surface. That's what Tilengine needs to focus its rendering on the Surface.
#The number we're providing is for the scanline renderer. We get this number by taking the bit-depth of the Surface, dividing it by 8, and then multiplying it by the width of the target Surface.
#In this case we are getting 4 x 640, which is why we are using 2560. The bit-depth of our Surface is 32, which divided by 8 gives us 4. Keeping your target render width static will help.
#I'm planning on doing any scaling in PyGame, and not worrying about changing the Tilengine render resolution, so it should be fine.

gameRunning = True
while gameRunning:
   for pEvent in pgm.event.get():
       if pEvent.type == pgm.QUIT:
           gameRunning = False
   
   pyScreen.fill((0, 0, 0, 255)) #We'll fill the screen with standard black, which is a good start for frame refreshing
   tEngine.update_frame() #This is the standard function we use to update the Tilengine rendering, it will handle updating the current frame. Any frame-based game logic changes should happen before this.
   pyScreen.blit(pyTargetRender, (0, 0)) #And this is where we draw our placeholder framebuffer to the PyGame screen. Easy enough.
   pgm.display.flip() #A standard function to insure screen refreshing. This manually forces the display to update based on our defined changes.

#That pretty much covers it. A very basic application where we essentially embed Tilengine into a PyGame project. This replaces the stanard windowing within Tilengine with the PyGame windowing system.
#From this point forward, the majority of rendering will be handled by Tilengine. But we will still have access to standard PyGame rendering, as well as all of the other PyGame libraries.
#This includes PyGame input, as well as PyGame audio. You still get the rendering speed and tile-map support of Tilengine, but now you can also leverage the additional features of PyGame.

Please note, I haven't tested this out on a Raspberry Pi yet, only on a Windows machine. It worked just fine on that Windows machine, just note that I haven't given this a thorough wash on multiple platforms. I can't guarantee that it will work everywhere. That said, it works like a charm on Windows.