OpenGL guide

30-Apr-2016
Tom Mulgrew

This documentOpenGL supportBasic4GL OpenGL implementationBasic4GL OpenGL initialisation.Double buffered OpenGL window.Image and texture loadingMultitexturing

This document

This document will not teach you OpenGL.

It is intended to give you the information you need to use OpenGL tutorials and example programs from other sources in Basic4GL.

Legacy OpenGL

Basic4GL uses OpenGL version 1.1.

This is considered a "legacy" OpenGL version, because it uses the old fixed-function pipeline, rather than the modern programmable shader pipeline of more recent OpenGL versions.

You will not be able to use Basic4GL to learn modern OpenGL.

Basic4GL is useful for prototyping (it is much quicker to get started with than modern OpenGL), and learning basic 3D graphics concepts, like coordinate systems, vertices, transformations, perspective projection,...

OpenGL support

Basic4GL supports version OpenGLv1.1, and supports all functions of the Win32 OpenGL implementation, except for:

Basic4GL also supports the following functions from the GL_ARB_multitexture extension:

The following glu funtions are supported:

Basic4GL OpenGL implementation

Basic4GL OpenGL initialisation.

Firstly, Basic4GL creates a window for you and initialises it for OpenGL. Therefore Basic4GL programs skip the initialisation stage and can start executing OpenGL commands straight away.

Example:

glTranslatef(0, 0, -4)
glBegin(GL_TRIANGLES)
  glColor3f(1, 0, 0): glVertex2f( 0, 1)
  glColor3f(0, 1, 0): glVertex2f(-1,-1)
  glColor3f(0, 0, 1): glVertex2f( 1,-1)
glEnd()
SwapBuffers()

Basic4GL sets some OpenGL defaults when your program starts, equivalent to the following code:

' Initialise the view port
glViewport(0, 0, WindowWidth(), WindowHeight())

' Create projection matrix, 60 degree field of view, near clip plane at 1, far clip plane at 1000
glMatrixMode(GL_PROJECTION)
glLoadIdentity()
gluPerspective(60, (1.0*WindowWidth()) / WindowHeight(), 1, 1000)

' Initialise the model view matrix
glMatrixMode(GL_MODELVIEW)
glLoadIdentity()

' Enable depth testing
glEnable(GL_DEPTH_TEST)
glDepthFunc(GL_LEQUAL)

This is simply for convenience and saves typing if you're happy with the default settings. Otherwise you will need to explicity setup your own configuration.

Double buffered OpenGL window.

The OpenGL window is double buffered.

This means it has a back buffer, which is hidden away from the user, and a front buffer which corresponds to the visible image on the screen.

All OpenGL rendering occurs in the back buffer. Once the scene is complete and ready to be displayed it is "swapped" to the front buffer, which displays it on the screen.

In Basic4GL you do this with the SwapBuffers() command.

SwapBuffers

SwapBuffers() will swap the completed scene from the back buffer. This immediately displays the result of the image that has just been rendered.

SwapBuffers() is a crucial part of any Basic4GL OpenGL program. Without it the user won't see anything rendered, because it will all be sitting in the back buffer, which is not displayed.

A simple example:

while true
  glClearColor(rnd()%100/100.0, rnd()%100/100.0, rnd()%100/100.0, rnd()%100/100.0)
  glClear(GL_COLOR_BUFFER_BIT)
  SwapBuffers()
  Sleep(500)
wend

Will repeatedly clear the OpenGL window to a random colour, and display it. The visual result is random flickering colours.
Without the SwapBuffers() call, the above program would not appear to do anything, as nothing ever gets through to the front buffer.

Note

SwapBuffers() will either copy the back buffer to the front buffer, or exchange the buffers. This appears to depend on the hardware, screen mode and OpenGL implementation.

Image and texture loading

Basic4GL uses the Corona open-source image library to load image files, for use in OpenGL textures. Through Corona Basic4GL supports Windows Bitmap files, Jpeg files and a host of other formats.

The Corona library is distributed under the zlib license (See ZLib LibPNG license.txt), and is freely available from http://corona.sourceforge.net/.

LoadTex

The easiest way to get a texture into Basic4GL is to use the LoadTex() functions.
Format:

LoadTex(filename)

Where filename is a string containing the filename of an image to load into an OpenGL texture.

This will allocate an OpenGL texture, load the image into the texture, and return the OpenGL texture handle (a numeric handle known as the "texture name").

The function returns 0, if for any reason it cannot load the image and store it in a texture.

See the Sprite Library Guide for more information on loading textures.

Multitexturing

Basic4GL uses OpenGL v1.1.
Multitexturing is not natively part of the v1.1, but is available through the OpenGL extensions mechanism.

Basic4GL automatically hooks into this extension and makes the associated functions and constants available to Basic4GL programs. (If the extension is not available, calling the functions will simply do nothing.)

ExtensionSupported

The Basic4GL function ExtensionSupported is the easiest way to test whether the current hardware supports multitexturing, as for example:

if not ExtensionSupported("GL_ARB_multitexture") then
Do something else...

(You can also check for other extensions, however this version of Basic4GL only supports GL_ARB_multitexture..)

This is exactly equivalent to calling glGetString(GL_EXTENSIONS) and testing the resulting string for the presence of "GL_ARB_multitexture"

MaxTextureUnits

MaxTextureUnits() will return the number of available texturing units.

dim units
units = MaxTextureUnits()

Note: This is also equivalent to:

dim units
glGetIntegerv(GL_MAX_TEXTURE_UNITS_ARB, units)

glMultitexCoord2f, glMultitexCoord2d and glActiveTexture

These are the actual multitexturing functions that Basic4GL supports.

See the MultitextureDemo example program for an example of multitexturing in action.