Tutorial 1b : Initialising Glide
 
Introduction

There are several basic things that must happen in the lifetime of a Glide program, and it is our responsibility to make sure they happen in the correct order and that any errors are handled properly.

At the most basic level, before our program can make use of any rendering functions it must:

  • Find an available Voodoo card.
  • Initialise Glide.
  • Select the Voodoo card that we want to use.
  • Create the Glide rendering window.
Before our program terminates, it must:
  • Deactivate the Voodoo card
  • Shut Glide down.
Note: shutting Glide down automatically deactivates the Voodoo card, so the last two steps can be thought of as just one.

Check for an available Voodoo card

When writing our Glide program, it is reasonable to expect that anyone using it will have a Voodoo card. However, there is a possibility that they may not and our program must handle this correctly. We must also consider the possibility that they have more than one Voodoo card.

To detect the presence of one or more Voodoo cards, we pass an empty GrHwConfiguration structure to the Glide function grSstQueryBoards, thus:

  GrHwConfiguration glide_config;
  grSstQueryBoards( &glide_config );
Our program can then examine the GrHwConfiguration structure to find out what, if any, Voodoo cards are available. For the purposes of this example, let's assume that we'll want to use the first available card, meaning that our program should only fail if there are no cards available.

The num_sst element of the GrHwConfiguration structure contains the number of available cards, so our program should fail if it is set to zero. Suitable code to do this would be:

  if ( !glide_config.num_sst )
    return;
Initialise Glide

Once we've established that at least one Voodoo card is available, we initialise Glide using a single command:

  grGlideInit();
Select the Voodoo card that we want to use

The function grSstSelect selects the Voodoo subsystem that we want to use. "Subsystem" is just another term for a Voodoo card. The parameter that we pass to this function determines which card will be used. Because we want to use the first (or only) card, the code would be:

  grSstSelect( 0 );
Create the Glide rendering window

The final step in preparing Glide for drawing operations is to create a window. This is not the same sort of window that you work with in Windows. It is closer to a Windows display context (the part of memory that is used to store the pixels that will be displayed in a window's client area).

We pass seven parameters to the grSstWinOpen function to describe what sort of window we want to use, and we have many options available that let us work with Glide in the way that is most convenient for us.

The first parameter is the handle of an existing window that we may wish to use for Glide rendering. We want to use the Voodoo card as the renderer so we pass a value of zero.

The second and third parameters specify the resolution that we wish to use and the refresh rate for the card. For this example, we'll use GR_RESOLUTION_640x480 and GR_REFRESH_60Hz which are self-explanatory.

The fourth parameter tells Glide how colours will be specified. All colours in Glide have four values - red, green, blue and alpha. However, we can specify them in many different orders. We'll use the GR_COLORFORMAT_ARGB format so Glide will expect 32-bit colour values to be specified in the form 0xaarrggbb, which means that the colours are ordered in the following bits:

  24 - 31 : alpha
  16 - 23 : red
   8 - 15 : green
   0 -  7 : blue
The fifth parameter tells Glide where we want the origin of the screen to be. We have the choice of the top-left or bottom-left. This only affects the orientation of the Y axis. We want the origin to be in the bottom-left of the screen, with the Y axis moving positively up the screen, so we use GR_ORIGIN_LOWER_LEFT. The X axis always moves positively from left to right.

The sixth and seventh parameters specify how many primary and auxiliary rendering buffers our program needs. For primary buffers, we have a choice of either double or triple buffering (the meaning of which which will be explained in a later tutorial). We'll be using double buffering, so we specify a value of 2. The auxiliary buffer is used mainly for depth buffering, which we will not be using yet, so we specify a value of zero.

Note: you can NOT have a single buffered rendering window.

Having decided what sort of window will be best for our program, we call the function as follows:

  grSstWinOpen(
    0,
    GR_RESOLUTION_640x480,
    GR_REFRESH_60Hz,
    GR_COLORFORMAT_ARGB,
    GR_ORIGIN_LOWER_LEFT,
    2,
    0 );
When calling the grSstWinOpen function, our program must handle the possibility that it will fail. To do this, we examine the boolean return value of the function and fail if it is zero. For example:
  if ( !grSstWinOpen() )
    return;
Deactivate the Voodoo card and shut Glide down

Once our program has finished using the Voodoo card, it needs to deactivate the card and shut Glide down, which is done using one function:

  grGlideShutdown();
Working example

Download the tutor_1b example code to see a working example. To compile the program, use the InsertFile menu option to insert it into the project we created in the first part of this tutorial. You then compile it as you would any other program.

Next Tutorial | Main Page
 


This tutorial is ©1998 by Andrew Smith. No part of this tutorial may be reproduced without permission. If you want to reproduce any of this tutorial for non-commercial purposes then I'm not likely to try and stop you, but please ask me first.