[Tutorial] Turing Graphics Extensions

[rizzix]

Turing Graphics Extenstions {the next sprite alternative}

Ok so, its funny I have all this stuff and it's just hatching on my computer. I've decided to get rid of them. So here's my first documented library: GFX.

GFX is a very robust and reliable, proceduaral based Turing graphics extenstion library. It includes quite a bit of stuff, useful for animation (as in sprites) and useful elementary drawing functions that extend those of Turing's standard functions.

Imports
Before using this library in your code, it is necessary to import GFX into your code likewise:

code:

import GFX in "path/to/GFX.tu",        Globals in "path/to/Globals.tu"

Quick RGB Color functions
I've found it cumbersome to work with the turing color code. I rather prefer to work with the (255,255,255) tuple colour codes. So I deviced these quick RGB colour functions that return the equivalent (temporary) turing colour code for a given RGB colour code.

code:

RGBi  (r, g, b : int) : Color RGBr  (r, g, b : real) : Color

where RGBi takes in integer values r,g,b such that 0 <= r,g,b <= 255
and RGBr takes in real values r,g,b such that 0.0 <= r,g,b <= 1.0

So in essence, use RGBr when you want to input a percent of each component of the respective Red, Blue and Green colors to from your new color.

example:

code:

drawfillbox(10, 10, 100, 100, RGBr(0.5, 0.5, 0.5))

Note that since this function returns a temporary color there is really no point in retaining the color like this:

code:

var myColor : Color := RGBr(0.5, 0.5, 0.5)

since myColor's value could soon change.


Quick RGBA Color functions
These functions work similar to RGBx, just that they include a fourth argument which is the alpha level 'a', such that 0 <= a <= 1.0 This alpha level determines the transparency of the created colour. A value of 1.0 means completely visible, while a value of 0.0 means completely transparent.

code:

RGBAr (r, g, b, a : real) : RGBA RGBAi (r, g, b : int, a : real) : RGBA

Unfortunately these functions dont return a temporary turing Color code, instead they return a temporary RGBA object. Now there's no need to worry here, it is still quite simple to generate a Turing Color from a RGBA object. To do this you are required to "flatten" the RGBA object into a Turing Color like this:

code:

var c : Color := GFXFlattenRGBA(RGBAr(1.0, 0.0, 0.0, 0.5)) drawfillbox(10, 10, 100, 100, c)

Once again the GFXFlattenRGBA function also returns but only a temporary Color code, so any new call to RGBx or GFXFlattenRGBA will automatically change the temporary color to the new one. The same goes for RGBAx but instead of a Turing Color code, it returns a temporary RGBA object.


Creating non-temporary RGBA objects
Yes! All hope is not lost, this is very much possible. You create a RGBA object by the:GFXCreateRGBAr(r, g, b, a : real) : RGBA function liek this:

code:

var rgba : RGBA := GFXCreateRGBAr (0.1, 0.3, 0.7, 0.8)

And you may flatten this object when ever you whish to actually use it.

NOTE: Since this object is not temporary, you are responsible to dispose it. This is simply done using the GFXDisposeRGBA procedure, like this:

code:

GFXDisposeRGBA(rgba)

Yep! Thats all there is to it. But now that it is disposed of you cannot flatten it again only untill you re-create and assign the variable rgba a new one.


The RGBA drawdot procedure
So to make life a little simple, I've added in the basic GFXDrawDot procedure, which you may extend upon or add in similar functionality as you wish.

code:

GFXDrawDot(10, 10, RGBAr(0.5, 0.6, 0.7, 1.0))

The above code will draw a pixel at (10,10) with the given RGBA configuration: (0.5, 0.6, 0.7, 1.0)


Update Area Extenstions
Two functions here, i've defined that basically interact with the core Turing View.Update procedure:

code:

GFXRadialRefresh (x, y, radius : int) GFXPolyRefresh (x1, y1, x2, y2 : int)

Hopefully these procedures are pretty self explainatory.


Static drawing Extenstions
This is probably the coolest thing about the GFX library: it is infact, in a way, a very robust framework for animations.

Unlike the other Sprite based libraries, this works a little different. We don't use the same functions those other libraries provide, but instead we work on what I call a snapshot-mechanism. Basically, it works like this: before placing a picture on screen, we first take a snapshot of the area of the screen we are to place the picture. Then we display the picture in that area. When we need to move the picture of that area or simply delete that picture, all we do is restore back the already taken snapshot. If we were moving the picture, we simply repeat the procedure but this time taking the snapshot of the new area.


The library declares and defines the follwing functions and procedures for this snapshot mechanism:

code:

GFXTakeSnapshot (x1, y1, x2, y2 : int) : GFXSnapshot

which takes and returns a rectangular snapshot of an area of the screen defined by the corners (x1,y1) to (x2,y2)

code:

GFXRestoreSnapshot (snpshot : GFXSnapshot)

this procedure restores the GFXSnapshot, "snpshot"

code:

GFXDisposeSnapshot (snpshot : GFXSnapshot)

this procedure disposes a taken snapshot, freeing the memory it occupies

code:

GFXDrawStaticPic (pic : Picture, x, y : int) : GFXSnaphshot

this procedure draw a picture created by Pic.New at location (x,y) and returns the snaphot of that area of the screen before the picture was drawn in that location

code:

GFXDrawStaticOval (x, y, r1, r2 : int, clr : Color) : GFXSnapshot

works like Turing's default drawfilloval procedure but takes and retuns a snaphot of the screen before the image is drawn

code:

GFXDrawStaticBox  (x1, y1, x2, y2, clr : int) : GFXSnapshot

works similar to GFXDrawStaticOval, except that it uses the drawfillbox function internally

A typical animation code would look similar to the following snippet:

code:

loop     snp := GFXDrawStaticPic (pic1, x1, y1) % <-- will refresh screen     GFXRestoreSnapshot(snp)                % <-- will _not_ refresh screen     GFXDisposeSnapshot(snp)     x1 += steps_in_x_direction     y1 += steps_in_y_direction end loop snp := GFXDrawStaticPic (pic1, x1, y1)

Note that the three steps listed below are always present (and in that order) in all your animation snippets:

code:

snp := GFXDrawStaticPic (pic1, x1, y1) GFXRestoreSnapshot(snp) GFXDisposeSnapshot(snp)

For the sake of convenience, the following procedures are provided:

code:

GFXDrawRefreshPic (pic : Picture, x, y : int)

this procedure takes a snapshot, draws the pic, restores the snapshot and disposes it, just as seen in the example above

code:

GFXDrawRefreshOval (x, y, r1, r2 : int, clr : Color)

similar to GFXDrawRefreshPic, but drawfilloval's intead

code:

GFXDrawRefreshBox (x1, y1, x2, y2 : int, clr : Color)

similar to GFXDrawRefreshPic, but drawfillbox's intead

So, the above example would be simplified to:

code:

loop     GFXDrawRefreshPic (pic1, x1, y1)     x1 += steps_in_x_direction     y1 += steps_in_y_direction end loop snp := GFXDrawStaticPic (pic1, x1, y1)

Wow, this is one long tutorial,, well.. there other stuff in the GFX library, but thats for Global time slicing, i.e a time based method of synchronizing various processes.. this is perticularly useful when you have multiple processes that draw on the screen at the same time. But.. i'm not going to explain it here,, maybe sometime later..

[Cervantes]

Looks promising, rizzix. I'd like to try it out, but the files aren't where they should be. I found the GFX module at http://www.compsci.ca/bbs/files/gfx.tu, but I couldn't find the globals.tu.

[rizzix]

ok.. fixed