Buffered Image for SmartMS

Here is a small class to facilitate working with off-screen dynamic images in Smart MS: w3BufferedImage.zip (1kb)
It’ll be in the next Smart update, but you can already use it, it was introduced as part of WarTrail, as a way to optimize graphic elements that are complex and don’t change over several frames (text, tiled background, etc.).

You can use it to bundle graphic layer element, for instance in WarTrail the top & bottom areas (with scores & buttons) are in two distinct buffered images, and when you bring up the “menu” for a tower upgrade, that’s another buffered image.

Setup

To use it, you simply create it, and specify its size, f.i. a 200×50 buffer is created with

buffer := TBufferedImage.Create(200, 50);

then you need to setup its OnRedraw event,  which is a procedure that passes the buffered image itself. This is here that you’ll have to (re)draw whatever your buffered image is meant to contain

buffer.OnRedraw :=
   procedure (Sender : TBufferedImage)
   begin
      Sender.Canvas... your code here ...
   end;

Inplace of the anonymous methods, you can also use a standalone procedure or a regular method (and it might be preferable if what you draw isn’t trivial), as they’re all compatible, the compiler takes care of everything that would differentiate a “procedure” from a “procedure of object” or a “reference to procedure” in Delphi.

Usage

When you need to draw the buffered image, you can use one of its Draw() or DrawScaled() methods, basically telling it to redraw itself on another canvas. The available methods are currently:

// top-left anchor
procedure Draw(dest : TW3Canvas; x, y : Float); overload;
procedure Draw(dest : TW3Canvas; x, y : Float; const sourceRect : TRect); overload;

// center anchor
procedure DrawScaled(dest : TW3Canvas; x, y, scale : Float);

The first two are top-left anchored, ie. the x & y are the top-left of where the image will be drawn, and you can optionally specify a sourceRect, so that only part of your buffered image will be drawn (note that for tiled images, the w3SpriteSheet class is preferable, it offers more features like rotations and automatic sourceRect computations)

For DrawScaled, the x & y are the center of where the image will be drawn.

When you need the image invalidated, you just call it’s Invalidate method, then the next Draw call will first invoke OnRedraw. You can also use the Prepare method to have OnRedraw be invoked at a time of your choosing instead.

Last thing, if you need to draw with alpha-transparency (f.i. to fade-in or out), just use the GlobalAlpha property of the target canvas, f.i.:

myCanvas.GlobalAlpha:=0.5;  // 50% opacity
bufferedImage.Draw(myCanvas, 50, 50); // drawn at top, left = 50,50
myCanvas.GlobalAlpha:=1;  // restore 100% opacity

That’s about it! Now you can efficiently make use of custom dynamic elements, such as multi-layered text with shadow, that would otherwise be too complex to redraw from scratch at each frame!