Texture Loader (Version 1.4)
(For use with Win32 openGL Applications)

By Chris Leathley (Black)
Originally Based on Jeff Molofee's (Nehe) IPicture Basecode

Introduction

This document describes how the Texture Loader works and how to use it. When I first started on openGL I wanted to make a texture manager which was flexible for the type of applications I was used to (totally out of my control, user controlled stuff, etc..). I based this project from Nehes Ipicture source and expanded it for my requirements. This code is the result of that process and is in constant development to improve it and make it more flexible.

It supports -

You are free to use this code in your application in any way you see fit.

Enjoy and Many Thanks to Nehe for his site..

 


Download

You can download the source here .. TextureLoader.zip

 


Common Data Types

Most commands require the application to hold it's texture information in the following data type. This structure contains the openGL Texture ID as well as any other information about the texture (such as it's width, height and Bit Depth)

typedef struct
{
  GLuint TextureID;   // Texture ID Used To Select A Texture
  eglTexType TexType; // Texture Format
  GLuint Width;       // Image Width
  GLuint Height;      // Image Height
  GLuint Type;        // Image Type (GL_RGB, GL_RGBA)
  GLuint Bpp;         // Image Color Depth In Bits Per Pixel
} glTexture;


Binding The Loaded Texture

When you have loaded all your textures, then you must tell openGL to bind the texture before you can use it (this is standard openGL programming) and nothing specific for the Texture Loader.

To Bind your texture, just pass it the TextureID field from the glTexture Structure..

eg..

glBindTexture(GL_TEXTURE_2D, m_MyWallTexture.TextureID);

 


API

Initialisation

You need to create an instance of the texture loader before it can be used (yeah I know.. teaching you to suck eggs). This can be done 2 ways by either by making a New class at run time

eg..

TextureLoader *pTextureLoader = new TextureLoader();

or by defining the Texture Loader as a data/class variable as in your main Application/Game code header file..

eg..

class MyClass
{
  TextureLoader m_TextureLoader;
}
;

The Texture Loader defaults to Alpha Matching BMP files with colour 0,0,0 (Black), High Quality Textures, Bilinear Filtering and Normal Texture Generation (as apposed to mipmap generation).

 

SetAlphaMatch

SetAlphaMatch(GLboolean fEnabled,
              GLubyte   RedAlphaMatch,

             
GLubyte   GreenAlphaMatch,
             
GLubyte   BlueAlphaMatch)

When Bitmap (BMP) files are loaded, the Texture Loader can look though the image data at create a Alpha Mask based on a specified colour. This allows you to make a single colour Transparent in your image. (such as a sprite). TGA files can contain their own Alpha Mask so that is used instead of generating one based on the Match colour. Because of the dithering the JPG files have (plus the loss compression). Matching a precise colour with JPG is basically impossible so it is best (and faster) to disable Alpha Matching when you know that the file format is JPG.

This command should be given before the texture is loaded.

The Default is for Alpha Matching to be enabled with the Colour being Black (0,0,0).

The Parameters passed into SetAlphaMatch are;

fEnabled If TRUE then alpha matching is performed. If FALSE then it is not.
RedAlphaMatch Defines the Red Component of the Colour to Alpha Match against.
GreenAlphaMatch as above but for the Green Component.
BlueAlphaMatch as above but for the Blue Component

Example:

// Set Alpha Matching to Bright Pink
pTextureLoader->SetAlphaMatch(TRUE, 0, 0xFF, 0xFF);

 

SetHighQualityTextures

SetHighQualityTextures(GLboolean fEnabled)

This flag when set, will automatically scale each image in Half to reduce the Texture memory required in the video card by 4 for each texture. This allow for more textures to be stored on low spec systems. If is best to have an option for this in your applications settings to allow the use to turn it on or off depending on their machine.

This command should be given before the texture is loaded.

The Default is for High Quality Textures to be Enabled.

The Parameters passed into SetHighQualityTextures are;

fEnabled If TRUE then High Quality Textures will be created. If FALSE then each image is reduced in size.

Example:

// Generate Low-Quality Textures
pTextureLoader->SetHighQualityTextures(FALSE);

 

SetMipMapping

SetMipMapping(GLboolean fEnabled)

This flag when set, will create MipMaps instead of normal Textures. Mipmaps serve 2 purposes. They are used in Trilinear filtering to give much nicer detail to the texture aswell as defining multiple Textures for openGL to use depending on the distance of the texture from the view point (this making rendering faster)

Please note that Mip Map Generation is only looked at if the Filter type is set to Bilinear as Trilinear requires MipMaps anyway.

The Default is for MipMapping Disabled.

This command should be given before the texture is loaded.

The Parameters passed into SetMipMapping are;

fEnabled If TRUE then MipMap Textures will be created. If FALSE then the default for the Filter type will be used.

Example:

// Generate MipMapped Textures
pTextureLoader->SetMipMapping(TRUE);

 

SetTextureFilter

SetTextureFilter(eglTexFilterType type)

This allows you to specify the type of filtering to be used when openGL processes the Texture. There are 3 types. No Filtering, Bilinear and Trilinear.

Bilinear and Trilinear Filtering looks a lot nicer but also requires (in the case of Trilinear) more processing time and more video ram on the graphics card.

The Default is Bilinear Filtering.

This command should be given before the texture is loaded.

The Parameters passed into SetTextureFilter are;

eglTexFilterType

Defines the filtering type to use. Valid values are; txNoFilter, txBilinear & txTrilinear.

Example:

// Set Filter to Trilinear
pTextureLoader->SetTextureFilter(txTrilinear);

 

LoadTextureFromDisk

LoadTextureFromDisk(char      *szFileName,
                    glTexture *pglTexture)

Load a Texture (BMP, GIF, JPG or TGA) from either a physical hard disk or an Internet Stream.

This function looks at the extension of the file being loaded to make a decision as to which image decoder to use, so it must be correct and represent the actual format of the file.

If you are loading from disk then the starting directory will be the same directory as which the application was run from.

The Parameters passed into LoadTextureFromDisk are;

szFileName File name (or Internet Address) to load the Image from. As mentioned above. the filename must also include an extension for this command to work.
pglTexture

Pointer to a glTexture structure which will be populated on return with the Texture ID to use for openGL.

Example: (Loading from Disk)

// Load wall.tga from my Data directory
glTexture m_MyWallTexture;
pTextureLoader->LoadTextureFromDisk("Data\\Wall.tga", &m_MyWallTexture);

If your application resides in "C:\Program Files\MyApp" then the image is loaded from "C:\Program Files\MyApp\Data\Wall.tga".

Example: (Loading from a Stream)

// Load the Logo from my website..
glTexture m_MyLogoTexture;
pTextureLoader->LoadTextureFromDisk("http://mywebsite.com/logo.jpg", &m_MyLogoTexture);

of course you must have a internet connection present for the above to work.

 

LoadTextureFromRam

LoadTextureFromRam(unsigned char *pData,
                   int           Length,
                   glTexture     *pglTexture,
                   eglTexType    TexType)

Load a Texture (BMP, GIF, JPG or TGA) from a RAM Location. This is usefull when you have your own file storage system.

This function will create a temporary file in the current directory which is deleted after use.

The Parameters passed into LoadTextureFromRam are;

pData Pointer to a memory location which contains the Raw Binary data of an Image file.
Length The Length of the Raw Binary data.
pglTexture

Pointer to a glTexture structure which will be populated on return with the Texture ID to use for openGL.

eglTexType

Defines the Image format type of the data pointed to by pData. Valid values are; txBmp, txGif, txJpg & txTga. This must be of the correct type for this command to work.

Example:

// Load wall.gif from my ram location
glTexture m_MyWallTexture;
pTextureLoader->LoadTextureFromRam(pMyImageData, imageDataSize, &m_MyWallTexture, txGif);

 

LoadTextureFromResource

LoadTextureFromResource(unsigned int ResourceName,
                        char         *pResourceType,
                        glTexture    *pglTexture,
                        eglTexType   TexType)

Load a Texture (GIF, JPG or TGA) from a Resource (Visual Studio C++ Version 6). This is use full when you which to include images within your EXE and not have external files. Currently BMP files are not supported (due to a bug I'm trying to work around)

This function will create a temporary file in the current directory which is deleted after use.

The Parameters passed into LoadTextureFromResource are;

ResourceName The Resource ID as defined by you in Visual C++. (usually prefixed with IDR_)
pResourceType Pointer to the Name of the Resource Group to load the texture from. When importing 'Custom' resources into a VC Project it must go into a area defined by You. Pass the name of that area in this parameter.
pglTexture

Pointer to a glTexture structure which will be populated on return with the Texture ID to use for openGL.

eglTexType

Defines the Image format type of the data in the resource. Valid values are; txGif, txJpg & txTga.

Example:

// Load my title image from the resources
glTexture m_MyTitleLogoTexture;
pTextureLoader->LoadTextureFromResource(IDR_TITLE_LOGO,
                                        "IMAGES",
                                        &m_MyTitleLogoTexture,
                                        txTga);

 

FreeTexture

FreeTexture(glTexture *pglTexture)

Frees a texture created with LoadTextureFrom.. and releases it from openGL. Should always be done when you application exits.

The Parameters passed into FreeTexture are;

pglTexture

Pointer to a glTexture structure which has the TextureID field populated with a call to one of the LoadTextureFrom.. functions.

Example:

// Free my Wall texture
pTextureLoader->FreeTexture(&m_MyWallTexture);