thinBASIC TBGL Website

by Petr Schreiber 

Introduction to TBGL

Welcome adventurer! I can see you can't wait to start with thinBASIC TBGL programming in honest way - from total basics...

This lesson covers the really important and basic things about TBGL, and if you'll be attentive enough, you'll manage to create your first triangle today!

So watch carefully, here we go!

TBGL principles

TBGL is module for easy 3D graphics creation using thinBASIC interpreter. To provide balance between syntax clarity and enough raw performance, I decided to build TBGL on top of OpenGL.

From this you can see your sripts will run best with some 3D card, as OpenGL is hardware accelerated API. If your target PC does not have hardware support of it, you will be able to use all TBGL functionalities, but at desperate speed.

TBGL is build on relatively old version of OpenGL. This assures you will be able to run scripts without graphical quality impact on almost any 3D card. I can recommend nVidia GeForce 2 MX 400 or ATi Radeon 7000 accelerators as lowest reasonable hardware in terms of capabilities and speed.

But using this module you will get more than "just" OpenGL, you will have access to some useful stuff, not present in classical OpenGL.

You must not care about allocating and deleting of textures and display lists, loading and handling of models and other things.

Hmm, I think this is enough said about mega-hyper-super TBGL, I can see in your eyes you are hungry for some code! So here it is -

First TBGL application

To not make things last longer than necessary, here is something which I could call "minimal" TBGL app:


' TBGL Script Skeleton 



hWnd = TBGL_CREATEWINDOWEX("My Demo - press ESC to quit", _

640, 480, 32, _

Looks simple? Yes, it is! But to not miss something important, I will explain some lines of this code.

The first line ( not counting the green comments ) defines, that we will use module - TBGL.

TBGL in this sample does few important things:

  • tbgl_CreateWindowEx - serves to create TBGL window, this function must be called as first of all TBGL arsenal
    It returns handle of TBGL window - this is unique identifier

  • tbgl_ShowWindow - simply forces the window to be visible

  • tbgl_DestroyWindow - is only legal way to kill TBGL window. It performs the automatic clean up of garbage created during execution of script.

But now comes the most important part - application main loop.

Main loop

WHILE TBGL_IsWindow(hWnd) / WEND cycle is essential for our "message pump" and checking of window activity.

Inside this loop we can see tbgl_ClearFrame and tbgl_DrawFrame.

tbgl_ClearFrame prepares your 3D card for drawing, it resets the screen, cleans all information about depth...
You can pass some drawing commands after this command.

When you are finished, you must call tbgl_DrawFrame to flush all tbgl rendering commands, and make them produce some output on screen.

If you try to run the sample code above from thinAir, you will see just black screen. End the application using ESCAPE key.

Why was the screen black? This is default filling color when not specified otherwise. Do you want other color? Try to put following line right after tbgl_ClearFrame:
Now run the script!

triangle with RGB colored vertices on green background
You should see this

The background is green now. If you want to make it colored differently, just use another RGB code of color.

Now, as you are master of background painting, I must tell you one tip: If you want the back color to be same during all code execution, you don't have to specify it for each frame.
Just put it before the main loop, on line up from WHILE. This will save you some performance, if nothing else.

How is that possible? TBGL / OpenGL works as "state automat". Until you change some setting, it remains the same. This is the reason why one call is enough for constant background color.

First triangle

I think you are ready for our first triangle, just change the main loop code to this:
WHILE TBGL_IsWindow(hWnd) 

    TBGL_CAMERA 0, 0, 5, 0, 0, 0
      TBGL_COLOR 255, 0, 0
      TBGL_VERTEX -2, -1, 0

      TBGL_COLOR 0, 255, 0
      TBGL_VERTEX  2, -1, 0

      TBGL_COLOR 0, 0, 255
      TBGL_VERTEX  0, 1, 0



Lot of new stuff, huh? Don't worry, I will explain it immediately.


First important thing is to setup camera, the way you look on 3D world.

3D space is generally expresed by 3 coordinates: x, y and z.
In TBGL, x is "left-right" direction, y is "up-down" and z is depth.

My idea is to look on our triangle form z = 5 to origin of coordinates:
TBGL_CAMERA 0, 0, 5, 0, 0, 0
As you can see, in camera statement there are 6 numbers - first 3 are x,y,z you are looking from ( 0, 0, 5 )and second set of 3 numbers is location you look at ( 0, 0, 0 ).

After specification of camera you can draw any geometry. The most basic drawing is using triangles.
To create triangles, you must specify 3 points ( surprise! ).

Polygon definition

You must tell TBGL you want to create some geometry using tbgl_BeginPoly and tbgl_EndPoly.

Between these two statements you just specify the points of triangle using tbgl_Vertex. To make color for each vertex different I used tbgl_Color, which works on same principle as the background color setup.

So our triangle is set from points (-2, -1, 0 ), which is lower left corner, ( 2, -1, 0 ) - lower right corner and ( 0, 1, 0) which is last, upper vertex.

What about creating two triangles? We will let the current and add one new. To do this, you don't need to call separate tbgl_BeginPoly,tbgl_EndPoly again, just add other three vertices to the lines between them.

To make it more exciting ( presuming there is something exciting on triangles ), the second triangle will be behind the first. To do this, we will copy code of current triangle and just change its z coordinate from 0 to -1.


      ' First    
      TBGL_COLOR 255, 0, 0
      TBGL_VERTEX -2, -1, 0

      TBGL_COLOR 0, 255, 0
      TBGL_VERTEX  2, -1, 0

      TBGL_COLOR 0, 0, 255
      TBGL_VERTEX  0, 1, 0

      ' Second      
      TBGL_COLOR 255, 0, 0
      TBGL_VERTEX -2, -1, -1

      TBGL_COLOR 0, 255, 0
      TBGL_VERTEX  2, -1, -1

      TBGL_COLOR 0, 0, 255
      TBGL_VERTEX  0, 1, -1

two triangles
Look from 5,5,5 to origin

Oh no! When you run it, you can't see the second triangle! What shall we do? Change camera position, to look better at the scene, try this:
    TBGL_CAMERA 5, 5, 5, 0, 0, 0
Now it is all right, second triangle is behind the first.

And our first lesson is over! I hope you was able to understand all the stuff, because you will need it in following, little bit more complicated ( well, not so ) tutorials.

If there were some problems, please contact me on mail or make a post on forum, and I believe we will solve it.