AllegroGL HOWTO
===============

HOWTO file


AllegroGL web site:  http://allegrogl.sourceforge.net/

Table of contents:
1.0 Introduction
  1.1 About the library
  1.2 About OpenGL
  1.3 About this document
2.0 The Basic
  2.1 Using AllegroGL for your Window
  2.2 States and screen update
  2.3 Coordinate Systems
  2.4 Text and fonts
  2.5 The Mouse
3.0 I just want OpenGL! Help!
4.0 Contact information



1.1 About the library
~~~~~~~~~~~~~~~~~~~~~

The library mostly provides functions to allow you to use OpenGL alongside
Allegro -- you use OpenGL for your rendering to the screen, and Allegro
for miscellaneous tasks like gathering input, doing timers, getting
cross-platform portability, loading data, playing samples and drawing your
textures. So this library fills the same hole that things like GLUT do.

AllegroGL works with X Window, Microsoft Windows, DOS (via Mesa) and
Mac OS X.



1.2 About OpenGL
~~~~~~~~~~~~~~~~

OpenGL is a long-standing Graphics API originally developed by SGI, but
now controlled by the people at http://www.opengl.org. It is just an API
and not an actual library; there are various libraries that implement the
OpenGL standard from the likes of Microsoft (supplied with Windows). There
is also a free implementation of the OpenGL standard called Mesa, but this
is unofficial and shouldn't really be called OpenGL. You can get it at
http://www.mesa3d.org. Mesa3D is a cross-platform library and even works
in DOS.

The OpenGL specification has reached version 1.4. As of October 2002 not all
OpenGL drivers are compliant with 1.4 but many of them are compliant with 1.3.
However Microsoft Windows OpenGL implementation is still only version 1.1.

However, it is possible to access the OpenGL 1.3 functionality within Windows
as long as the drivers supports it. You'll need to get the modified GLsdk
(created by SGI and Intel). AllegroGL will automatically detect its presence
and link to it.



1.3 About this document
~~~~~~~~~~~~~~~~~~~~~~~

This document serves as a guide to using AllegroGL from the perspective of
an Allegro user, but it should be useful for anyone getting to know
AllegroGL. It is intended to be read from start to end, as I've used
explanations of how features work to explain other features.

To install AllegroGL please read the readme file.
See the included FAQ before asking any questions to the developpers.

There is also a reference built from comments within the AllegroGL code,
available as a download from the AllegroGL site. This details many
commands and options that I haven't talked about here.



2.0 The Basics
--------------

AllegroGL replaces much of Allegro's rendering code on initialisation with
code that interfaces with OpenGL. Your old commands such as blit() and line()
will still work and this is called AllegroGL Direct Mode. Unfortunately
Direct Mode is incomplete and not very fast, so it is probably a better
idea for you to use your own calls to OpenGL. It is important to remember
that AllegroGL Direct Mode is emulated and the functions you are calling
all end up as OpenGL modes. You should note that the above only applies
to drawing stuff on the screen or on video bitmaps. Memory operations are
still done using regular Allegro, so they work properly.

If you don't already know OpenGL here are some suggested resources:

 - The "OpenGL Programming Guide" aka "The Red Book".
   This is a lengthy book which can be downloaded from
   http://www.opengl.org/ in pdf format.
 - If you need the OpenGL syntax reference, check out the OpenGL.org
   reference: http://www.opengl.org/developers/documentation/specs.html
 - Various specific tutorials are available from http://www.gamedev.net/ .
   This is also another place to try and download the Red Book.
 - NeHe's tutorials are available from http://nehe.gamedev.net/
 - The AllegroGL sourcecode and examples!
 - There's a page full of links at
    http://members.net-tech.com.au/alaneb/assemble.htm
 - There is a set of teaching notes that I don't know the URL of entitled
    "CPEN 461/661, Spring 1997  OpenGL Tutorial"


2.1 Using AllegroGL for your Window
-----------------------------------

 - AllegroGL needs to be initialized like nearly all Allegro addons. You
   use the install_allegro_gl() command. I suggest you do it just after 
   allegro_init().
 - When you set your graphics mode, via set_gfx_mode(), you have to use
   one of the following devices:
    - GFX_OPENGL             - Either a fullscreen or window, depending
                               on platform and configuration.
    - GFX_OPENGL_FULLSCREEN  - Fullscreen driver. Only supports "normal"
                               resolutions, like 640x480.
    - GFX_OPENGL_WINDOWED    - Supports any resolution, such as 543x365

    Virtual screens are not supported. Regular Allegro screen modes are
    still available though, so using GFX_AUTODETECT will behave as if
    AllegroGL wasn't present. Allegro alone does not support an OpenGL
    rendering context, so OpenGL calls will *fail* when in an Allegro
    mode, and can even crash the computer. Only run OpenGL commands when
    in an OpenGL mode.

    If you want your program to be more portable, you should use
    GFX_OPENGL exclusively and let the driver decide whether to use
    fullscreen or a window. You can still give the driver a hint as to
    which one you'd like by using allegro_gl_set(AGL_WINDOWED, TRUE) or
    the likes. See the docs for details.
   
    IMPORTANT NOTE: 
    If you switch out of an OpenGL mode, you will lose the current
    context. This means that all your converted fonts, display lists,
    textures, video bitmaps, and so on, will be LOST. Remember to
    destroy AllegroGL fonts before switching out of OpenGL to avoid
    problems when switching back in.


2.2 States and screen update
----------------------------

Now this is where I'm going to stress how OpenGL and therefore AllegroGL
is/are a state machine. Basically this means you apply various states to
OpenGL/AllegroGL which affect the behaviour of future functions. This is
opposed to how Allegro normally does things as Allegro normally just uses
lots of function arguments instead.

 - OpenGL/AllegroGL have their own page flipping code. You do it
   differently to Allegro. First, before you set the graphics mode,
   you need to set an AllegroGL state
    - allegro_gl_set(AGL_DOUBLEBUFFER, 1);
    - allegro_gl_set(AGL_REQUIRE, AGL_DOUBLEBUFFER);

This shows how to do AllegroGL states. You set a state, then you tell
AllegroGL if it is AGL_REQUIRE (required) or AGL_SUGGEST (suggested)
or AGL_DONTCARE (irrelevant).

  - allegro_gl_flip() will do the page flipping. You don't need to
    bother juggling multiple screens.

IMPORTANT NOTE:
The page flip may be implemented as a double buffer. That's
driver-dependant, and there's no way to control it from your program
unless you interface directly with the drivers. The other important
bit is that the 'screen' BITMAP may not be what you see on the screen.
If you've flipped page, then 'screen' will contain the *previous*
frame, and not the current one. In fact, the OpenGL defines the content
of the 'screen' as *undefined* after a flip, so you are not guaranteed to
have anything meaningful in there. It is recommended that you either clear
the screen, or redraw the screen completely at every frame.

Now how do you select the colour depth? Here's how to suggest an 8-bit colour
depth:

 - allegro_gl_set (AGL_COLOR_DEPTH, 8);
 - allegro_gl_set (AGL_SUGGEST, AGL_COLOR_DEPTH);

set_color_depth() will also work, but like Allegro, it becomes a required
depth, which means that your application may not work on some machines if
you don't support multiple depths. This is where AllegroGL comes in.

If no color depth was specified by either calls to allegro_gl_set() or
set_color_depth(), then AllegroGL will use the Allegro default depth - 8 bpp.

One last graphics mode option: AGL_RENDERMETHOD can be set to 1
for hardware acceleration and 0 for software mode.

Of course, all these graphics options must be set before you switch
graphics modes. Graphic options will have no effect until set_gfx_mode()
is called.

OpenGL states are done with the glEnable and glDisable commands.


2.3 Coordinate Systems
----------------------

Allegro and OpenGL/AllegroGL use different co-ordinate systems. The
AllegroGL Direct Mode commands should work the same as Allegros'.
If you are using Allegro commands, and you are inside an
allegro_gl_set_allegro_mode()/unset_allegro_mode() block, then the commands
will behave like their Allegro counterparts. Otherwise, the behaviour is
undefined.

In Allegro, the Top-left corner of the screen is the origin. The X-axis
goes to the right and the Y-axis goes down. The Screen is the same width
and height as the resolution (eg. 640 x 480).

In OpenGL, the centre of the screen is the origin. The X-axis goes to
the right and the Y-axis goes *up* (not down). The Z-axis starts from the
screen and goes out to you. This isn't important for using Allegro
functions, but it is for OpenGL related functions. Screen coordinates are
evaluated as 'units', where 1.0 unit may be different on each axis
depending on the current modelview or projection matrix. We recommend
you have a look at the Red Book for further details.



2.4 Text and fonts
------------------

AllegroGL handles fonts and text differently than Allegro does.

Allegro fonts need to be converted to AllegroGL fonts using the
 - FONT * allegro_gl_convert_allegro_font(FONT * f, int type, float scale)
   function.

  where type is one of:

   - AGL_FONT_TYPE_DONT_CARE   - font is either of the following...
   - AGL_FONT_TYPE_BITMAP      - font as a bitmap
   - AGL_FONT_TYPE_TEXTURED    - font as a textured quad

  Look up the accompanying documentation for details.

 - Fonts should be destroyed by using:
   void allegro_gl_destroy_font()

To use textured fonts you must:
 - glEnable(GL_TEXTURE_2D);

You can use the allegro_gl_printf function to draw AllegroGL fonts OpenGL 
style. You can NOT use Allegro's textout and textprintf on AllegroGL
converted FONTs. Only regular Allegro FONTs work with the Allegro
function.

System fonts can also be loaded into AllegroGL. This method is depricated
and will eventually be removed.


2.5 The Mouse Cursor
--------------------

Allegro's functions for mouse management (show_mouse, set_mouse_cursor,...) can
be used while an OpenGL mode is set. However two cases should be considered :

1. You are using Allegro's GUI : the cursor is automatically drawn by the
   GUI routines. You can manage your mouse cursor the same way you do with
   Allegro.

2. You are not using Allegro's GUI : you have to use algl_draw_mouse() to
   decide when the mouse cursor have to be drawn. In most cases, the best place
   to call algl_draw_mouse() is just before allegro_gl_flip().


3.0 I just want OpenGL! Help!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 1. Make sure you installed AllegroGL correctly. Refer to the readme.txt
    file for detailed installation instructions

 2. Add this code at the top of your file:
    #include <allegro.h>
    #include <alleggl.h>

 3. Initialize AllegroGL by calling install_allegrogl() after allegro_init()
    but before set_gfx_mode() or other AllegroGL or OpenGL commands.
 
 4. Use set_color_depth() then set_gfx_mode(GFX_OPENGL, ...) to set up a
    screen mode. If you need more control (like z-buffer depth), see the
    documentation on the allegro_gl_set() function.
 
 5. Use various OpenGL, Allegro or AllegroGL commands.

 6. Link with AllegroGL and OpenGL libraries. Note that the link ORDER
    MATTERS.

    Those are:
      For Mingw:
        -lagl -lalleg -luser32 -lgdi32 -lopengl32 -lglu32
      For MSVC:
        agl.lib alleg.lib user32.lib gdi32.lib opengl32.lib glu32.lib
      For Unix and Linux:
        -lagl `allegro-config --libs` -lGL -lGLU
      For DOS (Mesa):
        -lagl -lalleg -lmesagl -lmesaglu
      For Mac OS X:
        -lagl `allegro-config --libs` -framework Carbon -framework OpenGL

 7. Compile your program.
 
 8. Rejoice!



Contact information
~~~~~~~~~~~~~~~~~~~

Web page:     http://allegrogl.sourceforge.net/
Mailing list: allegrogl-general@lists.sourceforge.net