
                         AV3D - Programmer's Guide
                         -------------------------

                 Adam Majer <adamm@galacticasoftware.com>

                       ver. 0.01 -- August 15, 2001


-------------------------------------------------------------------------------


-------------------------------------------------------------------------------


Contents
--------

     1.        Introduction

     2.        Quick start - IMPORTANT
     2.1.      Software Requirements

     3.        Reference
     3.1.      OpenGL Interface
     3.2.      Sound and Music Interface
     3.3.      Input Classes
     3.4.      Miscelenous


-------------------------------------------------------------------------------


1. Introduction
---------------

     To make the story short, Audio/Video 3D Programming Library
     (henceforth AV3D) is really a wrapper library that provides OS
     independent interface to OpenGL, audio and usr input devices.  The
     main goal of this library is to provide a stable and flexible base
     platform for all non-conventional GUI applications that require very
     low overhead on the part of the wrapper.  In other words, this library
     is meant for rapid game development.

     AV3D is designed to be a scalable game platform...  If you are looking
     to code a word processor, this is probably the wrong library for you.


-------------------------------------------------------------------------------


2. Quick start - IMPORTANT
--------------------------

     Important facts and guidelines in the following table will enable you
     to effectively use the reference that follows.

        * _bool AV3D_InitProc()_ -- This should be the entry point into
          your program.  It is called once at the beginning of the program.
          Allocate all structures for your program, etc, etc....  Return
          value of _false_ means successful intialization and the program
          will continue.

        * _bool AV3D_MainLoop()_ -- Draw one frame here.  Don't forget to
          flip pages!  If return value is _true_ the loop will exit and
          program terminates.

        * _bool AV3D_EndProc()_ -- Called when program is about to
          terminate execution.  Return value of _false_ indicates success
          but right now it is ignored.

        * _Always use dynamic allocations when building instances of
          classes._ This is because the library uses the main entry point
          into the program to initialize any global variables particular to
          the OS.

        * You need to define the either __X11__ or __WINDOWS -- currently
          the 2 supported structures..  X Window System was tested under
          Linux OS.

     That's about it...  For an example see _Common/_All_Demo.cpp_ To
     complile just run make in the main AV3D directory and executable
     together with library will be in _Bin_ directory.


2.1. Software Requirements
--------------------------

     This library was designed with scalability in mind but at this time it
     was only tested with the following 2 OS-s.

2.1.1. Linux
------------

        * libmikmod2 version >= 3.1.9

        * OpenGL library - example is Mesa3D

        * XFree86 version >= 3.3.6 Tested with the 4.x series and DRI.

        * g++ compiler or compatible

2.1.2. Microsoft Windows
------------------------

        * libmikmod2 version >= 3.1.9 - INCLUDED

        * DirectX version >= 7.0

        * Borland C++ Builder >=5.5 compiler.  Available free at
          www.borland.com

        * OpenGL supported video card - ie.  can you run QuakeIII?  It req.
          OpenGL


-------------------------------------------------------------------------------


3. Reference
------------


3.1. OpenGL Interface
---------------------

     OpenGL internface in AV3D is accomplished with the _AV_Video_ class.
     _AV_Font_ is just a font interface to the screen...

3.1.1. AV_Video
---------------

          class AV_Video
          {
            AV_Video(const char*, int, int, int, bool=false);
            ~AV_Video();
          
            void ClearScreen();
            void FlipPages();
            int  GetHeight();
            int  GetWidth();
            void RestoreVideoMode();
            void SetFont(AV_Font&);
            void SetVideoMode(const char*, int, int, int, bool=false);
          
            void Write(int, int, const char *String, int Length=0);
            void WriteFormatted(int, int, const char *String, int Length=0);
          }

3.1.1.1. AV_Video(const char *Title, int Width, int Height, int Depth, bool
fFullScreen);
----------------------------------------------------------------------------

     _Description_ - Initializes AV_Video and creates the initial windows
     for OpenGL.

     _Parameters_

        * _Title_ - Title of the window that will be created.

        * _Width_ - Width of the viewport.

        * _Height_ - Height of the viewport.

        * _Depth_ - Bits per pixel color depth.  May be used or ignored.

        * _fFullScreen_ - true for Full Screen mode - default is false.

     _Returns_

     NONE

3.1.1.2. ~AV_Video();
---------------------

     _Description_ - Destructor for AV_Video.  Restores video mode and/or
     destructs OpenGL interface.

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.1.3. void ClearScreen();
----------------------------

     _Description_ - Clears current video page.

     _Parameters_ NONE

     _Returns_

     NONE

3.1.1.4. void FlipPages()
-------------------------

     _Description_ - Makes visual page current buffer and current buffer is
     put on the screen.

     _Parameters_ NONE

     _Returns_

     NONE

3.1.1.5. int GetHeight()
------------------------

     _Description_ - Height height of viewport in pixels

     _Parameters_

     NONE

     _Returns_

     Height of the viewport in pixels.

3.1.1.6. int GetWidth()
-----------------------

     _Description_ - Returns the viewport width in pixels.

     _Parameters_

     NONE

     _Returns_

     Viewport width in pixels.

3.1.1.7. void RestoreVideoMode()
--------------------------------

     _Description_ - Kills current OpenGL interface made with the AV_Video

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.1.8. void SetFont(AV_Font &font)
------------------------------------

     _Description_ - Sets current font

     _Parameters_

        * _list_ - Reference to the desired font.

     _Returns_

     NONE

3.1.1.9. void SetVideoMode(const char* Title, int Width, int Height, int
Depth, bool fFullScreen);
----------------------------------------------------------------------------

     _Description_ - Creates a new OpenGL interface killing the prevoius
     one if necessary.

     _Parameters_

     See AV_Video contructor.

     _Returns_

     NONE

3.1.1.10. void Write(int x, int y, const char *String, int Length=0);
---------------------------------------------------------------------

     _Description_ - Writes out a scring at the indicated raster position
     using current font.

     _Parameters_

        * _x, y_ - Raster (x,y) position.  NOTE: It clearly depends on the
          projection matrix.

        * _String_ - String to print.

        * _Length_ - Length to print.  if Length=0 then this fuction will
          call strlen(String) to determine the length of the string.
          Default is 0.

     _Returns_

     NONE

3.1.1.11. void WriteFormatted(int x, int y, const char *String, int
Length);
----------------------------------------------------------------------------

     _Description_ - Writes out a scring at the indicated raster position
     using current font.  It's just like Write except it has some format
     modifiers like "\n" and "\t"

     _Parameters_

     See AV_Video::Write(...)

     _Returns_

     NONE

3.1.2. AV_Font
--------------

          clas AV_Font
          {
            AV_Font(AV_Font&);
            AV_Font(AV_Video&, AV_FontStruct&);
            virtual ~AV_Font();
          }

3.1.2.1. AV_Font(AV_Font &font);
--------------------------------

     _Description_ - Copy contructor

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.2.2. AV_Font(AV_Video &video, AV_FontStructure &font)
---------------------------------------------------------

     _Description_ - Creates the specified font or "closest" match.

     _Parameters_

        * _video_ - AV_Video reference.

        * _font_ - Font structure reference.  It is defined as follows

          	struct AV_FontStruct{
          	    const char *FontFace;
          	    int Size, Width;               // size=height in pixels
          	    bool fItalic, fBold;
          	};

     _Returns_

     NONE

3.1.2.3. virtual ~AV_Font()
---------------------------

     _Description_ - Destructor

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.3. AV_Camera
----------------

          class AV_Camera
          {
            enum Direction{VERTICAL=0x01, HORIZONTAL=0x02, ROLL=0x04};
            AV_Camera();
          
            void Go();
            void RotateAngle1(Direction, double);
            void Translate(double, double, double);
            void TranslateR(double, double, double)
            void ZeroAll();
          };

3.1.3.1. AV_Camera()
--------------------

     _Description_ - Initializes the POV (point of view) camera.  Needs
     OpenGL to work.

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.3.2. void Go()
------------------

     _Description_ - Moves and rotates the world to what the player sees.
     Call this function before drawing the world.

     _Parameters_

     NONE

     _Returns_

     NONE

3.1.3.3. void RotateAngle1(Direction dir, double angle)
-------------------------------------------------------

     _Description_ - Rotates the camera as in a flight simulator not simple
     rotation as in First Person shooter.

     _Parameters_

        * _dir_ - Mask composed of the enum Direction.  eg.
          VERTICAL|HORIZONTAL or ROLL.  This will be the direction of
          rotation specified by _angle_

        * _angle_ - Rotation angle in degrees

     _Returns_

     NONE

3.1.3.4. void Translate(double dx, double dy, double dz)
--------------------------------------------------------

     _Description_ - Translates the camera in absolute coordinates.

     _Parameters_

        * _dx, dy, dz_ - Distance to translate in each of three
          cooridinates.

     _Returns_

     NONE

3.1.3.5. void TranslateR(double dx, double dy, double dz)
---------------------------------------------------------

     _Description_ - Translates the camera in ROTATED coorinate system.

     _Parameters_

     see AV_Camera::Translate

     _Returns_

     NONE

3.1.3.6. void ZeroAll()
-----------------------

     _Description_ - Returns to unrotated coodinate system with vector z
     intro the screen.

     _Parameters_

     NONE

     _Returns_

     NONE


3.2. Sound and Music Interface
------------------------------

     This section uses MikMod library to provide SFX and Module (.MOD,
     .S3M, etc.) playpack.

3.2.1. AV_Sound
---------------

          class AV_Sound
          {
            AV_Sound(AV_Video&, AV_Camera&, int Channels=32);
            ~AV_Sound();
          
            void PlayMusic(const char *);
            int SFX(SAMPLE *Data, int x=0, int y=0, int z=0);
            void Stop(int);
            void StopAll();
          
            SAMPLE* LoadSample(FILE *in);
            int  GetSampleFrequency(SAMPLE *s);
            void ChangeSampleFrequency(SAMPLE *s, int f);
            void FreeSample(SAMPLE *s);
          }

3.2.1.1. AV_Sound(AV_Video &video, AV_Camera &cam, int Channels);
-----------------------------------------------------------------

     _Description_ - Initializes the sound library - contructor

     _Parameters_

        * _video, cam_ - Reference to AV_Video and AV_Camera.

        * _Channels_ - Number of channels to be reserve for playback.

     _Returns_

     NONE

3.2.1.2. ~AV_Sound()
--------------------

     _Description_ - Desctructor

     _Parameters_

     NONE

     _Returns_

     NONE

3.2.1.3. void PlayMusic(const char *file)
-----------------------------------------

     _Description_ - Plays a module file or MP3 file in the background.

     _Parameters_

        * _file_ - Path to the file that is to be played.

     _Returns_

     NONE

3.2.1.4. int SFX(SAMPLE *sample, int x=0, int y=0, int z=0)
-----------------------------------------------------------

     _Description_ - Plays the sample at the current coordinates.

     _Parameters_

        * _sample_ - sample to be played.

        * _x,y,z_ - coordinates of samble playback.  Default is (0,0,0)
          thus center at full volume.

     _Returns_

     Channel of the voice that was enabled.

3.2.1.5. void Stop(int voice)
-----------------------------

     _Description_ - Stops a specific voice

     _Parameters_

        * _voice_ - Voice to stop playing.  Returned by SFX.  If voice=-1
          then music is stopped.

     _Returns_

     NONE

3.2.1.6. void StopAll();
------------------------

     _Description_ - Stops all SFX and music

     _Parameters_

     NONE

     _Returns_

     NONE

3.2.1.7. SAMPLE *LoadSample(FILE *in)
-------------------------------------

     _Description_ - Loads a specific sample.  Currently only WAV samples
     are loaded.

     _Parameters_

        * _in_ - file descriptor of where the sample is.

     _Returns_

     SAMPLE pointer.  Use AV_Sound::FreeSample to free it when it is no
     longer needed.

3.2.1.8. int GetSampleFrequency(SAMPLE *sample)
-----------------------------------------------

     _Description_ - Returns sample frequency in Hz

     _Parameters_

        * _sample_ - Sample to get freq.  from.

     _Returns_

     Sample frequency.

3.2.1.9. void ChangeSampleFrequency(SAMPLE *sample, int freq);
--------------------------------------------------------------

     _Description_ - Changes sample frequency to a new value

     _Parameters_

        * _sample_ - SAMPLE that will have freq.  changed.

        * _freq_ - new frequency of the sample

     _Returns_

     NONE

3.2.1.10. void FreeSample(SAMPLE *sample)
-----------------------------------------

     _Description_ - Frees alloced sample from memory

     _Parameters_

        * _sample_ - sample to free.

     _Returns_

     NONE


3.3. Input Classes
------------------

     Currenly AV_Keyboard, AV_Joystick and AV_Mouse are included here.
     AV_Joystick class requires that the joysticks are enumarated first.
     See AV_Joystick for more details.

     FIXME: Still need to write this - look at Common/_All_Demo.cpp and
     av3d.hpp for examples and information.


3.4. Miscelenous
----------------

     These include exception class that is thrown by AV3D and the Timer
     Class.  Also some global functions and variables are included here.


-------------------------------------------------------------------------------


     AV3D - Programmer's Guide

     Adam Majer <adamm@galacticasoftware.com>

     ver. 0.01 -- August 15, 2001

