Glide 2x, 3.x Texture Memory Address Calculation
by Execom/ realtechVR
(c) Copyright realtechVR 2000

http://www.realtech.scene.org
Revision 1.1 - March, 29th 2000


=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-
1) WHAT IS GLIDE ?

Glide is a 3D API from 3Dfx Inc. designed for maximize performance of 3Dfx Voodoo
series 3D accelerators.  For more informations, go to http://www.3dfx.com

=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-
2) WHAT IS GLIDEMEM ?

GlideMem is an C++ API for managing texture memory allocation for 3Dfx. Since 3Dfx
API doesn't provide a high level interface for that thing (you can only load texture
to a certain address but can't free it).
I can be rewritten for C easily.

=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-
3) WHAT DOES GLIDEMEM ?

When you are allocating a texture with Glide, you usually use this function :

FX_ENTRY void FX_CALL
grTexDownloadMipMapLevel( GrChipID_t        tmu,
                          FxU32             startAddress,
                          GrLOD_t           thisLod,
                          GrLOD_t           largeLod,
                          GrAspectRatio_t   aspectRatio,
                          GrTextureFormat_t format,
                          FxU32             evenOdd,
                          void              *data );

The problems is to manage correctly the startAddress parameters. Basic implementations,
begin with startAddress = 0 and increment it until there is no more memory.

GlideMem computes efficiently the best startAddress automatically. It works like malloc
and free.

Here is how to use it :

a) Initialize Glide API
b) instancies GlideMem once.
      gldmem = new GlideMem();

c) Computes the startAdress
startAddress = gldmem->alloc( grTextureMemRequired(evenOdd, info), tmu);
where grTextureMemRequired is a Glide API function that returns the memory required
according the envOdd
and info. See grTextureMemRequired in the Glide API for more info. tmu is the Texture
Memory Unit where's you want to store the texture.

d) When you have finish with your texte, you can release it by calling : 
gldMem->free(startAddress, tmu);
With the same startAddress that GlideMem gave you before.

e) repeat c) and d) operations has many time. You can call gldMem->coreleft(tmu) to get
   the amount of memory left. You can also track the oldest texture and release it if
   you are running out of memory. The counterpart (but this 'dynamic' allocating must
   be programmed by yourself).

f) When exiting the program, make a delete gldmem;
g) Release Glide API

That all. With that, you have more control of the texture memory and knows
exactly how many textures are loaded, and the memory usage.

=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=--=-==-=-=-=-
4) API Documentation

The API is quite simple.

PROTOTYPE : GlideMem::GlideMem()
DESCRIPTION : Initialize Glide Memory Manager

PROTOTYPE : GlideMem::~GlideMem()
DESCRIPTION : Release Glide Memory Manager

PROTOTYPE : GrMemOffset GlideMem::alloc(size_t , GrChipID_t )
DESCRIPTION : Allocate a buffer of <size> bytes in the selected texture unit <tmu>.
If not specified, allocate for TMU0

PROTOTYPE : void GlideMem::free(GrMemOffset , GrChipID_t );
DESCRIPTION :Release a memory block from the selected <offset> at the texture unit <tmu>
If not specified, free for TMU0

PROTOTYPE : void GlideMem::garbageCollection(GrChipID_t tmu);
DESCRIPTION :if you are running of memory, you can force a garbage collection (sort of
'defrag' of you memory). However, a garbageCollection is done each time you made a free.

PROTOTYPE : unsigned GlideMem::coreleft(GrChipID_t tmu) const
DESCRIPTION :Return the amount of memory in bytes left in the select TMU

PROTOTYPE : unsigned GlideMem::getNumbersOfBlock(GrChipID_t tmu) const;
DESCRIPTION :Return the numbers of textures allocated in the given TMU. You can track leak
errors by checking if getNumbersOfBlock()==0 before exiting your program.


* END OF DOCUMENTATION *