WARNING: THIS API IS DEPRECATED. DO NOT USE. ONLY MENTIONED FOR BACKWARDS COMPATIBILITY REASONS

DemoGL functions, v1.2 API

In this section, all exported functions of DemoGL will be described briefly. If this is your first time reading this section, read the descriptions, and familiarize yourself with the functionality that's offered. Don't get scared if you miss any functions you expected to find here. That funcionality is probably taken care of by DemoGL, so you can do the real stuff: creating content. The functions are ordered alphabetically. Use the menu at the left to fastaccess functions deeper in the page.

 
  CreateTextureFromBuffer
 
GLuint  CreateTextureFromBuffer(
    int iWidth,
int iHeight,
byte *pBuffer,
const char *sIdentName,
int iBorder,
GLint iWrapS,
GLint iWrapT,
GLint iMinFilter,
GLint iMagFilter,
bool bMipMaps,
GLint iTexUploadHint
  );

Synopsys

Creates a textureobject inside DemoGL with the data provided in *pBuffer.

Parameters

iWidth
The width of the texture in pixels. Must be 2^n + 2 * iBorder for some integer n.
iHeight
The height of the texture in pixels. Must be 2^n + 2 * iBorder for some integer n.
*pBuffer
Pointer to the buffer that contains the texture. Pixels are stored using 4 bytes, and the pixel format is RGBA. No need to supply 16bit textures for 16bit display. That is taken care of by DemoGL using the settings the user selected in the startup dialog and the OpenGL drivercode.
*sIdentName
Pointer to the Identification Name of the texture. DemoGL identifies the textureobjects it creates from textures in files by their filenames. If effect A will load a texture X and effect B will load that same texture X, X is not reloaded from disk but the referencecounter to that textureobject is increased by one. DemoGL determines if a texture is already loaded in core by the filename which is unique for every texture loaded from disk. However textures created from a buffer or from the framebufferdata don't have a filename, so you have to supply a unique name yourself. You can for example pass the string "tex1" and in another effectobject just call LoadTexture and pass "tex1" as the filename. The effect will get a reference back to the texture you created using CreateTextureFrom Buffer.
iBorder
Specifies the size of the textureborder. Must be 0 or 1. Use this if you have to collide several textures to 1 large picture and if you want to avoid bilineair filtering artifacts at the edges. See for details The Opengl Programmers Manual concerning texturing or help on the function glTexImage2D().
iWrapS
Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; OpenGL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Must be GL_CLAMP or GL_REPEAT.
iWrapT
Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See iWrapS. Must be GL_CLAMP or GL_REPEAT.
iMinFilter
This texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions: (without mipmaps:) GL_NEAREST, GL_LINEAR, (with mipmaps:) GL_NEAREST_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR and GL_LINEAR_MIPMAP_LINEAR. NEAREST is refering to the PIXEL that is nearest to the center of the pixel currently textured, LINEAR is refering to a weighted average of the 4 surrounding pixels of the pixel currently being textured (bi-lineair filtering). These can include border texture elements. NEAREST values are faster but LINEAR are smoother. Experiment with the values until you are satisfied with the result. DemoGL uses OpenGL's 1.1 textureobject facility to store these values with the texture when it's uploaded. You can overrule these in your own code when you actually use the texture, but you don't have to set these values explicitly.
iMagFilter
This texture magnification function is used when the textured pixel maps to an area less than or equal to one texture element. Must be GL_NEAREST or GL_LINEAR
bMipMaps
If true, DemoGL will automatically create mipmaps for you when uploading the texture to OpenGL's texturememory. If you set this to false, iMinFilter with MIPMAP values won't work and opengl's default will be used then (GL_NEAREST).
iTexUploadHint
This hint is ment for the situation when the user has selected 16bit textures. In this situation normally DemoGL selects GL_RGBA4 as texturehint towards OpenGL, so you'll get better alphachannel support. If this isn't necessary in your situation, because the texture doesn't use the alphavalues, you can specify an overruling hint for DemoGL to pass on to OpenGL in 16bit. A good hint for nonalpha textures is GL_RGB5_A1. In situations where the user has selected 32bit textures (recommended, since the driver will transform these to 16bit if necessary and will dither, which gives better results) this hint is ignored and GL_RGBA8 is used. If DemoGL should use the default hint whenever it has to for this texture, set iTexUploadHint to DEMOGL_TEXHINT_USEDEFAULT, which is a constant defined in DemoGL_DLL.h.

Returnvalue(s)

GLuint value.
Will be 0 when there was an error, like there is no more space left in the texturesystem, otherwise this is the OpenGL Texturename that you can use when you call glBindTexture(); Store this returnvalue in a membervariable in your derived effectclass so you can upload it, or delete it.

Remarks

DemoGL is build with OpenGL in mind. OpenGL is a 3D rasterization api and therefore doesn't provide you an LFB in which you can fiddle around. To solve this in a way, you can create textures of your buffers which reside in core memory and then use a 2D projection (Ortogonal projection) in OpenGL to display these by using a texturemapped polygon in XY space. Beware though that uploading textures to the card can be slow when you are uploading a lot of textures. So with this function you can overcome the 2D limitations a bit, but it doesn't solve it totally. Remember that the width and height have to be a power of 2, the pixels are 32bit only (RGBA) and the texture must not exceed the maximum texture limits which are 2048x2048 pixels.

See also

DeleteTexture, UploadTexture, UnUploadTexture
 
  CreateTextureFromFBRegion
 
GLuint  CreateTextureFromFBRegion(
    int iX,
int iY,
int iWidth,
int iHeight,
const char *sIdentName,
int iBorder,
GLint iWrapS,
GLint iWrapT,
GLint iMinFilter,
GLint iMagFilter,
GLint iTexUploadHint
  );

Synopsys

Creates a textureobject inside DemoGL from the pixels in the framebuffer occupying the region (iX,iY) - ((iX + iWidth),(iY + iHeight)).

Parameters

iX
The X coordinate of the left lower corner of the region. Remember that (0,0) is left below.
iY
The X coordinate of the left lower corner of the region. Remember that (0,0) is left below.
iWidth
The width of the texture in pixels. Must be 2^n + 2 * iBorder for some integer n.
iHeight
The height of the texture in pixels. Must be 2^n + 2 * iBorder for some integer n.
*sIdentName
Pointer to the Identification Name of the texture. DemoGL identifies the textureobjects it creates from textures in files by their filenames. If effect A will load a texture X and effect B will load that same texture X, X is not reloaded from disk but the referencecounter to that textureobject is increased by one. DemoGL determines if a texture is already loaded in core by the filename which is unique for every texture loaded from disk. However textures created from a buffer or from the framebufferdata don't have a filename, so you have to supply a unique name yourself. You can for example pass the string "tex1" and in another effectobject just call LoadTexture and pass "tex1" as the filename. The effect will get a reference back to the texture you created using CreateTextureFrom Buffer.
iBorder
Specifies the size of the textureborder. Must be 0 or 1. Use this if you have to collide several textures to 1 large picture and you want to avoid bilineair filtering artifacts at the edges. See for details The Opengl Programmers Manual concerning texturing or help on the function glTexImage2D().
iWrapS
Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; OpenGL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Must be GL_CLAMP or GL_REPEAT.
iWrapT
Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See iWrapS. Must be GL_CLAMP or GL_REPEAT.
iMinFilter
This texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions: (without mipmaps:) GL_NEAREST, GL_LINEAR, (with mipmaps:) GL_NEAREST_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR and GL_LINEAR_MIPMAP_LINEAR. NEAREST is refering to the PIXEL that is nearest to the center of the pixel currently textured, LINEAR is refering to a weighted average of the 4 surrounding pixels of the pixel currently being textured (bi-lineair filtering). These can include border texture elements. NEAREST values are faster but LINEAR are smoother. Experiment with the values until you are satisfied with the result. DemoGL uses OpenGL's 1.1 textureobject facility to store these values with the texture when it's uploaded. You can overrule these in your own code when you actually use the texture, but you don't have to.
iMagFilter
This texture magnification function is used when the textured pixel maps to an area less than or equal to one texture element. Must be GL_NEAREST or GL_LINEAR
iTexUploadHint
This hint is ment for the situation when the user has selected 16bit textures. In this situation normally DemoGL selects GL_RGBA4 as texturehint towards OpenGL, so you'll get better alphachannel support. If this isn't necessary in your situation, because the texture doesn't use the alphavalues, you can specify an overruling hint for DemoGL to pass on to OpenGL in 16bit. A good hint for nonalpha textures is GL_RGB5_A1. In situations where the user has selected 32bit textures (recommended, since the driver will transform these to 16bit if necessary and will dither, which gives better results) this hint is ignored and GL_RGBA8 is used. If DemoGL should use the default hint whenever it has to for this texture, set iTexUploadHint to DEMOGL_TEXHINT_USEDEFAULT, which is a constant defined in DemoGL_DLL.h.

Returnvalue(s)

GLuint value.
Will be 0 when there was an error, otherwise this is the OpenGL Texturename that you can use when you call glBindTexture(); Store this returnvalue in a membervariable in your derived effectclass so you can upload it, or delete it.

Remarks

By default, the region is read from the backbuffer. You can change this by calling glReadBuffer() just before you call CreateTextureFromFBRegion. By reading from the backbuffer you can pre-render textures for things like cubic envmapping while you are showing a fancy picture in the front buffer. By switching off bufferswapping you can render in the backbuffer without having these results popping up in the frontbuffer. This function uses glCopyTexImage2D(), which copies the framebuffer data directly to texturememory on the card. This is very fast, although it has the disadvantage that you can't UnUpload the texture and re-upload it later on. If you don't delete it however it will reside on the card until the application ends. Also, because the pixels are NOT read to core memory, the creation of mipmaps is not available. If you want to create mipmaps from data and you don't care about the slow speed of glReadPixels(), read the framebuffer region yourself and use CreateTextureFromBuffer to create the textures. Allthough the texture data isn't residing in core, other effects can refer to this same textureobject and use it as if it were a texture loaded from disk, by using the same sIdentName.

See also

DeleteTexture, UploadTexture, SetbSwapBuffers
 
  DeleteTexture
 
void  DeleteTexture(
    int iTextureName
  );

Synopsys

Deletes a DemoGL textureobject with the number iTextureName from DemoGL and removes it from OpenGL's texturememory.

Parameters

iTextureName
This parameter is the number you received from one of the three texture creation functions CreateTextureFromBuffer, CreateTextureFromFBRegion and LoadTexture. It's called a name because OpenGL uses these numbers as names to refer to OpenGL textureobjects. DemoGL hides this fuzz for you. All you need to know about a texture is it's IdentName/Filename when you create the textureobject at DemoGL and the number you receive from one of the three texture creation functions mentioned above when you want to do an action with the texture, like using it, deleting it or (un)uploading it.

Returnvalue(s)

None.

Remarks

If more than one effectobject loads/creates a texture with the same Identname/filename, and you call this function, not much will happen. The reference counter of the DemoGL textureobject will be decreased and the texture is still usable for other effectobjects. It's removed from memory (OpenGL texturememory and DemoGL in-core texturememory) when there are no more references to the texture by other effectobjects. If a texture is completely deleted from DemoGL and another effect is loading it again, it has to be read from disk again. Allthough the loadroutines are fast, this can cause stuttering for some milliseconds, so plan when to use certain textures and when to delete them.

See also

UnUploadTexture, UploadTexture, CreateTextureFromBuffer, CreateTextureFromFBRegion, LoadTexture
 
  DisableMessageHandler
 
void  DisableMessageHandler(
    const char *sEffectName
  );

Synopsys

Disables the Messagehandler functionality of the effectobject with the name passed with the function. DemoGL will then not call the MessageHandler method of the effectobject when the effect is running on an active layer and there is a message posted to the application window. The MessageHandler is turned OFF by default.

Parameters

*sEffectName
The name of the effectobject which MessageHandler method should be disabled.

Returnvalue(s)

None.

Remarks

Starting with version 1.2, DemoGL effectobjects have a new method, the MessageHandler method. By default this method is never called, or better: it's disabled. If your application enables it using EnableMessageHandler, DemoGL will call the MessageHandler method of this effect when the effect is running on an active (i.e. visible) layer, and there is a message received by the application's window message handler which lives inside DemoGL. Most messages are not that interesting for your effect but it can be used to receive mouse input or keyboard input, which result in messages, send to the application window, and thus also to all enabled MessageHandler methods of visible effects.

See also

EnableMessageHandler
 
  EnableLoadingSplash
 
void  EnableLoadingSplash(
    const char *sSplashScreenTexture,
int iFileType,
float fOpacity
  );

Synopsys

When your application starts, DemoGL displays the console and all kinds of information before the actual application kicks off. It looks ok, but perhaps you want to please the viewer of your application with a splashscreen you supplied.

Parameters

*sSplashScreenTexture
The name of the file, inclusive path, which contains the texturedata. This will be loaded as a normal texture, but DemoGL won't return an ID. The texture is stored in DemoGL's texturebase, so if you load it again using LoadTexture, it won't be loaded from disk.
iFileType
The type of the file loaded. These types are defined in DemoGL_DLL.h. JPGFILE will tell DemoGL to use the jpg loader, TGAFILE to use the tga loader and BMPFILE to use the ..., that's right, bmp loader. Must be TGAFILE, BMPFILE or JPGFILE.
fOpacity
This is the opacity DemoGL should use when blending the texture over the console when the application starts. It's a value between 0.0 (totally transparent) and 1.0 (totally opaque).

Returnvalue(s)

None.

Remarks

The texture is blenden on top of the console at startup. If you set the opacity to a lower amount than 1.0, you still see the console through the texture. When the application is started, and the console is activated, the splashscreen isn't blended on top of the console, but a normal console is shown.

See also

LoadTexture
 
  EnableMessageHandler
 
void  EnableMessageHandler(
    const char *sEffectName
  );

Synopsys

Enables the Messagehandler functionality of the effectobject with the name passed with the function. DemoGL will then call the MessageHandler method of the effectobject when the effect is running on an active layer and there is a message posted to the application window. The MessageHandler is turned OFF by default.

Parameters

*sEffectName
The name of the effectobject which MessageHandler method should be enabled.

Returnvalue(s)

None.

Remarks

Starting with version 1.2, DemoGL effectobjects have a new method, the MessageHandler method. By default this method is never called, or better: it's disabled. If your application enables it using this function, DemoGL will call the MessageHandler method of this effect when the effect is running on an active (i.e. visible) layer, and there is a message received by the application's window message handler which lives inside DemoGL. Most messages are not that interesting for your effect but it can be used to receive mouse input or keyboard input, which result in messages, send to the application window, and thus also to all enabled MessageHandler methods of visible effects.

See also

DisableMessageHandler
 
  EndApp
 
void  EndApp(void)

Synopsys

Calling this function will start the cleanup cycle inside DemoGL to end the application.

Parameters

None.

Returnvalue(s)

None.

Remarks

This routine is normally called after you return from RunApp(). EndApp will take care of the cleanup of every object created inside DemoGL, stopping running music, closing the window, eventually switching back to normal resolution of the desktop etc. Remember that the effects you registered at DemoGL are not cleaned up. This is because the creation of these objects is done in your own main. Do the cleanup of these objects after you've called EndApp.

See also

RunApp
 
  ExecuteCommand
 
void  ExecuteCommand(
    const char *sCommand
  );

Synopsys

Executes a scriptcommand. Only DemoGL Scriptlanguage commands are accepted. The commands take effect immediately.

Parameters

*sCommand
A normal DemoGL script command.

Returnvalue(s)

None.

Remarks

This function can be used to execute commands from code. It can be an addition to the scriptfile already running for your application. In combination with the MessageHandler method of effectobjects, it's possible to do very precise timing besides the global millisecond timing on the global timeline. It's not recommended to use just this in code timing, because you loose the flexibility of a script.

See also
 
  FreeFile
 
void  FreeFile(
    byte *byFile
  );

Synopsys

Frees the memory allocated when LoadFile was used to load a file into memory.

Parameters

*byFile
Pointer to the file in memory, the same pointer received from LoadFile

Returnvalue(s)

None.

Remarks

If a DLL allocates memory and passes a pointer to that memory to the application that is attached to the DLL (and likely caused the allocation of memory), the attached application is not allowed to free the memory pointed by the pointer it received from the DLL. The deallocation should be done by the DLL. Because DemoGL allocates memory when it loads a file into memory and passes a pointer to that memory back to the calling application, it also has to deallocate that memory. This function, FreeFile(), deallocates memory allocated when LoadFile was called. Every LoadFile() call in your application should have an accompanying FreeFile() call.

See also

LoadFile
 
  GetDemoGLVersion
 
void  GetDemoGLVersion(
    float *fVersion,
long *lBuildnr
  );

Synopsys

Returns in the variables, pointed to by the pointers passed, the version of the current used DemoGL library plus the buildnumber.

Parameters

*fVersion
Pointer to a float variable wherein DemoGL will store the version of the library, for example 1.2
*lBuildnr
Pointer to a long variable wherein DemoGL will store the buildnr, for example 100119.

Returnvalue(s)

None.

Remarks

It's sometimes useful to know if the library that is loaded with the application is of a certain version, or not higher than a certain version. This function allowes you to test if the DemoGL library loaded is of a certain version.

See also

No topics related.
 
  GetLengthOfFile
 
long  GetLengthOfFile(
    const char *sFilename
  );

Synopsys

Returns the length in bytes of the file with filename sFilename which is stored in the datafile, or in the data directory. This filename can contain subpaths

Parameters

*sFilename
This is the name, inclusive path, of the file you want the length of in bytes.

Returnvalue(s)

long value.
The length of the file sFilename in bytes.

Remarks

Because DemoGL does all the File I/O for you and returns a buffer with the data to you, you don't know how large these files are and thus how large the buffer is. Use this function in combination with LoadFile. Be aware of the fact that the sSRCDir parameter passed to OverruleDefaults is placed before sFilename.

Example

Suppose sSRCDir is "mydata", you read from a directory and you want to check the length of the file "mydata\textures\part01\rock.bmp". You then pass "textures\part01\rock.bmp" to GetLengthOfFile: (C/C++ backslash escaping included)

long lLength = GetLengthOfFile("textures\\part01\\rock.bmp");

See also

LoadFile, DemoGL File I/O
 
  IsExtensionAvailable
 
bool  IsExtensionAvailable(
    int iExtension
  );

Synopsys

This function checks with DemoGL if the specified OpenGL extension is available with the current hardware.

Parameters

iExtension
Number defined in DemoGL_Extensions.h that represents the extension to check.

Returnvalue(s)

bool value.
true if the extension is available, false otherwise.

Remarks

Because the OpenGL rendercontext is globally defined inside DemoGL and because DemoGL already parses the extensionstring received from the OpenGL driver, you don't have to parse this string for yourself. Use this function to choose between several codepaths in your application if you want to be sure available hardware is used and not available hardware is emulated, like multitexturing is emulated with a 2 or more pass routine, instead of using the ARB_multitexture extension.

See also

The include files DemoGL_Extensions.h and DemoGL_glext.h, both supplied with the SDK.
 
  LoadFile
 
unsigned char *  LoadFile(
    const char *sFilename
  );

Synopsys

Returns a pointer to a buffer wherein the file with filename sFilename which is stored in the datafile, or in the data directory, is loaded. This filename can contain subpaths. The buffer is already unpacked and decrypted.

Parameters

*sFilename
This is the name, inclusive path, of the file you want the length of in bytes.

Returnvalue(s)

unsigned char * pointer.
pointer to a buffer wherein the total file sFilenameis loaded, decrypted and unpacked.
NULL value.
DemoGL couldn't load the file, couldn't unpack the file or couldn't decrypt the file.

Remarks

DemoGL handles all file I/O for you, so it's completely transparant for you where the files come from (datafile or directory), and you are not bothered by the fact files have to be unpacked and/or decrypted. LoadFile handles all that for you. If you don't need the data from the file anymore, be sure to call FreeFile to free the buffer, because otherwise your application leaks memory. If you want to know how big the buffer is in bytes, use GetLengthOfFile. The source where from DemoGL reads the data, depends on the value of iFileSRC, which is overruleable by OverruleDefaults.

See also

GetLengthOfFile, DemoGL File I/O, OverruleDefaults, FreeFile
 
  LoadTexture
 
GLuint  LoadTexture(
    const char *sFilename,
int iFileType,
GLint iWrapS,
GLint iWrapT,
GLint iMinFilter,
GLint iMagFilter,
bool bMipMaps
bool bCreateAlphaFromColor
int iBorder,
GLint iTexUploadHint
  );

Synopsys

Creates a textureobject inside DemoGL from the data loaded from the file sFilename which is stored in the datafile or in the data directory.

Parameters

*sFilename
Pointer to the filename, inclusive path, of the texture. This will then be loaded from the datafile or from the data directory. The source where from DemoGL reads the data, depends on the value of iFileSRC, which is overruleable by OverruleDefaults. DemoGL identifies the textureobjects it creates from textures in files by their filenames. If effect A will load a texture X and effect B will load that same texture X, X is not reloaded from disk but the reference counter to that textureobject is increased by one. DemoGL determines if a texture is already loaded in core by the filename which is unique for every texture loaded from disk.
iFileType
The type of the file loaded. These types are defined in DemoGL_DLL.h. JPGFILE will tell DemoGL to use the jpg loader, TGAFILE to use the tga loader and BMPFILE to use the ..., that's right, bmp loader. Must be TGAFILE, BMPFILE or JPGFILE.
iWrapS
Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; OpenGL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Must be GL_CLAMP or GL_REPEAT. The texture coordinate s is specified with OpenGL calls like glTexCoord2f(s,t);
iWrapT
Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See iWrapS. Must be GL_CLAMP or GL_REPEAT.
iMinFilter
This texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions: (without mipmaps:) GL_NEAREST, GL_LINEAR, (with mipmaps:) GL_NEAREST_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR and GL_LINEAR_MIPMAP_LINEAR. NEAREST is refering to the PIXEL that is nearest to the center of the pixel currently textured, LINEAR is refering to a weighted average of the 4 surrounding pixels of the pixel currently being textured (bi-lineair filtering). These can include border texture elements. NEAREST values are faster but LINEAR are smoother. Experiment with the values until you are satisfied with the result. DemoGL uses OpenGL's 1.1 textureobject facility to store these values with the texture when it's uploaded. You can overrule these in your own code when you actually use the texture, but you don't have to. The texture coordinate t is specified with OpenGL calls like glTexCoord2f(s,t);
iMagFilter
This texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. Must be GL_NEAREST or GL_LINEAR
bMipMaps
If true, DemoGL will automatically create mipmaps for you when uploading the texture to OpenGL's texturememory. If you set this to false, iMinFilter with MIPMAP values won't work and OpenGL's default will be used (GL_NEAREST).
bCreateAlphaFromColor
Unlike TGA, JPG and BMP do not have alphachannel support. If you want to create an alphachannel from the colors in the texture, simply set this parameter to true. The alpha of every pixel is determined using the formula: A = (0.35 * R) + (0.45 * G) + (0.20 * B). This is useful for flares or other textures that have relative alpha depending on their luminosity. This will give you better results if you blend using glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
iBorder
Specifies the size of the textureborder. Must be 0 or 1. Use this if you have to collide several textures to 1 large picture and you want to avoid bilineair filtering artifacts at the edges. See for details The Opengl Programmers Manual concerning texturing or help on the function glTexImage2D(). Note that if you specify a border, the image you load as a texture has to contain this border. Thus if the picture has a width of 256 pixels and you set iBorder to 1, the actual texture will be 254 pixels.
iTexUploadHint
This hint is ment for the situation when the user has selected 16bit textures. In this situation normally DemoGL selects GL_RGBA4 as texturehint towards OpenGL, so you'll get better alphachannel support. If this isn't necessary in your situation, because the texture doesn't use the alphavalues, you can specify an overruling hint for DemoGL to pass on to OpenGL in 16bit. A good hint for nonalpha textures is GL_RGB5_A1. In situations where the user has selected 32bit textures (recommended, since the driver will transform these to 16bit if necessary and will dither, which gives better results) this hint is ignored and GL_RGBA8 is used. If DemoGL should use the default hint whenever it has to for this texture, set iTexUploadHint to DEMOGL_TEXHINT_USEDEFAULT, which is a constant defined in DemoGL_DLL.h.

Returnvalue(s)

GLuint value.
Will be 0 when there was an error, otherwise this is the OpenGL Texturename that you can use when you call glBindTexture(); Store this returnvalue in a membervariable in your derived effectclass so you can upload it, or delete it.

Remarks

Only 32bpp/24bpp images are supported. Also, the width and height of the images have to be a power of 2 plus 2 * the borderwidth, which can be 0 or 1, to be usable within OpenGL. LoadTexture won't fail when the width and/or height is not a power of 2, but OpenGL won't show the texture. JPG files have 24bpp automatically, TGA files can be 8, 16, 24 or 32bpp. TGA files with 24bpp or 32bpp are supported. BMP files can have several options, only 24bpp bmp files are supported, uncompressed. 8bpp BMP files are supported but converted to 32bit. All 24bpp formats are converted to 32bpp by adding an alphabyte. The value of the alphabyte depends on the setting bCreateAlphaFromColor. If this setting is false then the value of the alphabyte is 0xff. If you want partial transparancy in your textures, for example in round windows in a walltexture, use 32bit TGA with an alphachannel.

See also

DeleteTexture, UploadTexture, UnUploadTexture, Technical aspects and limitations, OverruleDefaults, LoadFile, GetLengthOfFile
 
  LogLineToConsole
 
void  LogLineToConsole(
    const char *sLine,
bool bScroll
  );

Synopsys

Logs a line to the DemoGL Console. This console can be displayed at any time when you press '~' or '`' unless you blocked it with the settings in OverruleDefaults.

Parameters

*sLine
This is the textline you want to log to the console.
bScroll
If true the console will scroll up one line before this line is added to the console contents, otherwise it will not scroll up. So if you want to load 100 files for example you can achieve the QuakeII style console logging, while loading files by passing false (the console won't scroll up before printing a line).

Returnvalue(s)

None.

Remarks

This function is ideal while you are in the developing stage of your application. You can log to the console whatever you want, as long as it is a characterstring and the characters have asciivalues between 32 and 127.

See also
 
  OverruleDefaults
 
void  OverruleDefaults(
    bool bVSYNC,
int iFileSRC,
const char *sSRCDir,
const char *sDataFilename,
const char *sScriptFilename,
bool bShowFPS,
bool bNeverShowFPS,
bool bNeverShowConsole,
bool bShowDebugInfo,
bool bNeverShowDebugInfo,
int iMusicSys
  );

Synopsys

Overrules some defaults in DemoGL, so the programmer can select some options in code.

Parameters

bVSYNC
This parameter tells DemoGL to switch on VSYNC (bVSYNC = true) or to switch off VSYNC (bVSYNC=false), when the extension WGL_EXT_swap_control is available. Switching it off can gain some FPS, but can also lead to tearing. Default is false (which means: OFF).
iFileSRC
The parameter that specifies which source to use to read files. Can be SRC_LOADFROMDATAFILE, which specifies that all files will be read from the file specified with sDataFilename, or SRC_LOADFROMDIR, which specifies that all files will be read from the directory specified with sSRCDir. When you specify SRC_LOADFROMDIR, sDataFilename is ignored. If you specify SRC_LOADFROMDATAFILE, sSRCDir is used to specify a sourcedir inside the datafile specified with sDataFilename. Default is SRC_LOADFROMDATAFILE.
*sSRCDir
If iFileSRC = SRC_LOADFROMDIR: the name of the directory where the files used in your application are stored. If iFileSRC = SRC_LOADFROMDATAFILE: the name of the directory inside the datafile where the files used in your application are stored. Default is "", which means an empty string, which means the directory your application's executable is in, if iFileSRC = SRC_LOADFROMDIR, or which means the rootdir in the datafile if iFileSRC = SRC_LOADFROMDATAFILE.
*sDataFilename
The name of the datafile, if iFileSRC = SRC_LOADFROMDATAFILE. It's assumable that you want to name the datafile after the name of your application. By default DemoGL will look for the file demodat.zip in the directory where the application is ran from. This parameter is ignored if iFileSRC = SRC_LOADFROMDIR.
*sScriptFilename
This is the name of the script, inclusive path, that should be executed with the application. This file is placed in the datafile if iFileSRC = SRC_LOADFROMDATAFILE, and placed in the directory sSRCDir if iFileSRC = SRC_LOADFROMDIR. DemoGL will look for demoflow as default script.
bShowFPS
DemoGL supports a Frame Per Second viewing on the screen. You can activate this by pressing F2 in a running DemoGL application. When true FPS display is turned on when the application runs. Default is false (which means: turned OFF).
bNeverShowFPS
Because a user can switch ON FPS display by pressing F2, you probably want to disable this in your release version. By setting this parameter to true the user won't be able to turn ON FPS display. This option also overrules bShowFPS. Default is false (which means: user is able to turn on the FPS counter).
bNeverShowConsole
The DemoGL console is neat, but a user can disrupt the flow of your application if he opens the console and closes it some time later. Due to the design of DemoGL, the timeline events are executed but no effects are called when the console is up. So if you have a non-rendering effect that does some calculations for you, it won't be executed and it therefore can disrupt the execution of objects that are executed at a later time. So if you truely want to disable the console for users, you can by passing true. Default is false (which means: user is able to bring up the console).
bShowDebugInfo
DemoGL supports an overlay that contains extra debug info for the programmer, like the last 4 lines logged on the console and a high resolution timer. You can activate this overlay by pressing F5 in a running DemoGL application. When true DemoGL will display the layer at startup. Default is false (which means: turned OFF)
bNeverShowDebugInfo
The debug info overlay is ofcourse horrifying for your design, and perhaps you don't want users to get it visible during application run, so you can lock the F5 key. Passing true will block users from visualizing the debug overlay layer. Default is false (which means, user is able to turn on the debug overlay layer)
iMusicSys
This parameter tells DemoGL which musicsubsystem to initialize. Possible values: MP3SUBSYSTEM for when you use MP3 files, or MODSUBSYSTEM, when you use XM/S3M/MTM/IT or MOD files. In a future version, when DemoGL has just 1 library for playing all music media, this parameter will be removed. Until then, this parameter will be used which system will be initialized. Using the wrong system for the musicmedia will likely crash the application. Default is MP3SUBSYSTEM.

Returnvalue(s)

None.

Remarks

Use this function before you call RunApp, otherwise the new defaultsettings you provide are not used. VSYNC is default ON by OpenGL design. It can be switched off with this function but if the driversettings in the registry are set otherwise, it might not work. This is especially the case with nVidia drivers. The nVidia drivers for TNT and TNT2 turn VSYNC on, but if a user changes these settings, there is no way to overrule these settings from code.

See also
 
  RegisterEffect
 
void  RegisterEffect(
    CEffect *pEffectObject
const char *sEffectName
  );

Synopsys

Registers an effectobject with DemoGL. It's then usable and referable by the name sEffectName.

Parameters

*pEffectObjeect
This is a pointer to an effectobject that is derived from the baseclass CEffect. To get an effectobject you programmed into the scheduler and to get it up and running you have to register it with DemoGL by using this function.
*sEffectName
This is a unique name for the effectobject you want to register. With this name you can refer to the effect in your script to define timeline events and to control the execution of the effect.

Returnvalue(s)

None.

Remarks

Be sure the effectname is unique throughout your application. This means that no 2 effects may have the same name. If 2 or more effects have the same name, script execution is undefined. The names are case-sensitive.

See also
 
  RunApp
 
void  RunApp(
    HINSTANCE hInstance
const char *sWindowTitle
bool bUseCrypting
unsigned char byKey1
unsigned char byKey2
  );

Synopsys

Starts the application.

Parameters

hInstance
This is the hInstance variable you received from your WinMain function.
*sWindowTitle
This string will appear as windowtitle if the application is started windowed by the user.
bUseCrypting
This boolean variable is used to tell DemoGL to decrypt all files (if bUseCrypting is true) or to not use decrypting.
byKey1
First key for the decrypting algorithm. Is ignored if bUseCrypting is false. Has to be between 1 and 255, 255 included, and obviously the Key1 parameter you used when you crypted the files with Cryde.
byKey2
Second key for the decrypting algorithm. Is ignored if bUseCrypting is false. Has to be between 1 and 255, 255 included, and obviously the Key2 parameter you used when you crypted the files with Cryde.

Returnvalue(s)

None.

Remarks

This function starts the application and won't return until the application is terminated by the user or ended by the script. Therefore, you should have set up and registered everything you want before you call this function.

See also

EndApp, OverruleDefaults SetStartupDialogVars
 
  SetbSwapBuffers
 
void  SetbSwapBuffers(
    bool bYN
  );

Synopsys

Enables/disables the swapping of the front- and backbuffer.

Parameters

bYN
If true, the front- and backbuffer will be swapped at VSYNC or, when you disabled that, when OpenGL thinks it's ready, using the function SwapBuffers(). If false, this swapping is disabled, and you can use the backbuffer for example to render bitmaps you can upload as texture using CreateTextureFromFBRegion. This way, the user won't see your pre-rendering in the backbuffer.

Returnvalue(s)

None.

Remarks

Use this with CreateTextureFromFBRegion. Remember, when you switched off bufferswapping, and you want to have animation again, you have to turn it back on. "Well, DUH!" will gorgle from some mouths, but how obvious it might seem, there probably will be a day you make this mistake too ;)

See also

CreateTextureFromFBRegion
 
  SetStartupDialogVars
 
void  SetStartupDialogVars(
    const char *sDemoName
const char *sCreators
bool bFullScreen
int iResolution
bool bDisplay32bpp
bool bTexture32bpp
bool bSound
  );

Synopsys

Sets the values of the various controls in the startup dialog of a DemoGL powered application. It overrules the bare defaults for the startup dialog, defined inside DemoGL. You set the values of the controls when the dialog opens.

Parameters

*sDemoName
This string will appear in the textbox Title in the opening dialog.
*sCreators
This string will appear in the textbox Released by in the opening dialog.
bFullScreen
This is the value for the Appearance radio button group. If true Full Screen will be selected, if false, Windowed will be selected.
iResolution
This is the parameter that will select one of the supported resolutions in the startup dialog. Can be RES1024x768, RES640x480 or RES800x600. If iResolution is RES1024x768, 1024x768 will be selected. If iResolution is RES800x600, 800x600 will be selected. If iResolution is RES640x480, ... guess what ..., 640x480 will be selected.
bDisplay32bpp
This is the value for the Display Quality radio button group. If true 32bit will be selected. If false, 16bit will be selected.
bTexture32bpp
This is the value for the Texture Quality radio button group. If true 32bit will be selected. If false, 16bit will be selected.
bSound
This is the value for the Sound radio button group. If true Yes will be selected. If false No will be selected.

Returnvalue(s)

None.

Remarks

This function is called before RunApp. It sets the several controls on the startup dialog to the values passed. The startup dialog will show when you call RunApp. Allways use this function, because with this function you can set the Title and the Released by textboxes in the dialog. The dialog will show when you call RunApp.

See also

RunApp
 
  UnUploadTexture
 
void  UnUploadTexture(
    int iTextureName
  );

Synopsys

Deletes a texture with the number iTextureName from OpenGL's texturememory and thus from the 3D card's texturememory.

Parameters

iTextureName
This parameter is the number you received from one of the three texture creation functions CreateTextureFromBuffer, CreateTextureFromFBRegion and LoadTexture. It is called a name because OpenGL uses these numbers as names to refer to OpenGL textureobjects. DemoGL hides this fuzz for you. All you need to know about a texture is its IdentName/Filename when you create the textureobject at DemoGL and the number you receive from one of the three texture creation functions mentioned above, when you want to do an action with the texture, like using it, deleting it or (un)uploading it.

Returnvalue(s)

None.

Remarks

The DemoGL texturemanagement has 2 stages: first the texture is loaded into core memory, and in the second stage the texture is uploaded to the OpenGL texturememory. OpenGL will accept any number of textures and will decide for itself which textures are uploaded dedicatedly to the 3D card's memory. Because this memory is limited to 16MB or 32MB or, if you are lucky, even larger, it might happen that OpenGL has more textures to store on the card than the card can handle. If you don't need a texture at a certain time, you can UNUPLOAD this texture from the OpenGL texturememory. It still resides in core memory and can be re-uploaded, but it's not in the way of textures that are needed at that certain time. You don't have to use this function and let OpenGL take care of the texturemanagement to the card, but you can't control it. Basicly the OpenGL texturemanagement is based on usage of the texture, but for you this might not be efficient.

See also

UploadTexture, CreateTextureFromBuffer, CreateTextureFromFBRegion, LoadTexture, DeleteTexture
 
  UploadTexture
 
void  UploadTexture(
    int iTextureName
  );

Synopsys

Uploads a texture with the number iTextureName to OpenGL's texturememory. It's then usable for texturing primitives.

Parameters

iTextureName
This parameter is the number you received from one of the three texture creation functions CreateTextureFromBuffer, CreateTextureFromFBRegion and LoadTexture. It's called a name because OpenGL uses these numbers as names to refer to OpenGL textureobjects. DemoGL hides this fuzz for you. All you need to know about a texture is it's IdentName/Filename when you create the textureobject at DemoGL and the number you receive from one of the three texture creation functions mentioned above, when you want to do an action with the texture, like using it, deleting it or (un)uploading it.

Returnvalue(s)

None.

Remarks

When the texture is loaded into DemoGL, it has to be uploaded to OpenGL to be usable for texturing. This function creates with OpenGL an OpenGL TextureObject and defines several parameters you have specified with one of the 3 texture creation functions. OpenGL then takes care of the transport to the 3D hardware of the texture. After you've called this function with a certain loaded texture, you can use this texture for texturing primitives. This is not limited to a certain effectobject. The textures are globally defined inside OpenGL when uploaded, and thus when you upload a texture T in effectobject A, you can also use it in effectobject B, until you un-upload the texture or delete it.

See also

UnUploadTexture, CreateTextureFromBuffer, CreateTextureFromFBRegion, LoadTexture, DeleteTexture


Last revisited on 22nd of January 2001
© 1999-2001 Solutions Design