GL Studio C++ Runtime API
Image Class Reference

#include <image.h>

Inheritance diagram for Image:
IFontImage

Classes

class  InstanceListEntry
 
class  LoadOptions
 

Public Member Functions

void SetReleaseImageDataEnabled (bool enable)
 
bool IsReleaseImageDataEnabled ()
 
virtual int ErrorFound ()
 
virtual void SetError (char *errorMessage)
 
virtual char * GetError ()
 
virtual void Draw ()
 
virtual void Draw (int x, int y)
 
virtual ImageClone ()
 
virtual unsigned char * ImageData ()
 
virtual float TextureCoordX ()
 
virtual float TextureCoordY ()
 
virtual int TextureWidth ()
 
virtual int TextureHeight ()
 
virtual int Size ()
 
virtual int Width ()
 
virtual int Height ()
 
virtual bool TextureHandleValid ()
 
virtual unsigned int TextureHandle () const
 
virtual int PixelFormat ()
 
virtual void PixelFormat (int format)
 
virtual char * PixelFormatString ()
 
virtual int PixelSize ()
 
virtual unsigned char * GetRasterPosition (int x, int y)
 
virtual void SetPixel (int x, int y, float color[])
 
virtual void SetAsCurrentTexture ()
 
virtual void AllocateTextureBinding ()
 
virtual void DeallocateTextureBinding ()
 
virtual void BindTexture ()
 
 Image (const unsigned char *const data, int width, int height, int pixelFormat)
 
 Image (int width, int height, int pixelSize, bool allowNPOT=false)
 
 Image (const glsInlineImage &image)
 
 Image (int width, int height, int components, int format, unsigned int comprLen, const unsigned char *const data[], unsigned long crcVal=0, int lineLength=320)
 
 Image (int width, int height, int components, int format, const unsigned char *const pix[], unsigned long crcVal=0, int lineLength=320)
 
 Image (const Image &source)
 
 Image ()
 
void DoTexSubImage ()
 Perform the upload process from the CPU to the GPU.
 
void UnloadRgbData ()
 
virtual void DeleteUsage ()
 
virtual void AddUsage ()
 
virtual int NumUsers ()
 
virtual void operator= (Image &im)
 
virtual void ScaleTexture ()
 
virtual unsigned long CrcValue ()
 
virtual int operator== (Image &im)
 
virtual ImageFindDuplicate ()
 
virtual void MipMap (bool set)
 
virtual bool MipMap ()
 
virtual void GlTextureCompression (bool set)
 
virtual bool GlTextureCompression ()
 
virtual void ScaleToPowerOfTwo ()
 
virtual void ReplaceImage (unsigned char *imageData)
 
virtual bool ReplaceImage (unsigned char *imageData, int width, int height, int pixelSize)
 
virtual bool LoadInlineImageData ()
 
virtual bool FreeInlineImageData ()
 
virtual bool DisconnectInlineImage (bool loadImage=true)
 
virtual void AllowImageSharing (bool value)
 
virtual bool AllowImageSharing ()
 
bool IsAllowNPOTTextures () const
 
- Public Member Functions inherited from IFontImage
virtual ~IFontImage ()
 
virtual void BindTexture ()=0
 
virtual void MipMap (bool mipMap)=0
 
virtual int PixelFormat ()=0
 

Static Public Member Functions

static List_cInstanceList ()
 
static disti::MutexInstanceListMutex ()
 
static void EmptyInstanceList ()
 
static bool IsDuplicate (Image *image, int width, int height, int components, unsigned long crcVal, bool glTexCompress)
 
static ImageFindDuplicate (int width, int height, int components, unsigned long crcVal, bool glTexCompress)
 

Static Public Attributes

static bool _globalMipMapEnabled
 

Protected Member Functions

void ConvertLuminanceAlphaToAlpha ()
 
void AddSelfToInstanceList ()
 
virtual void SetTexWidthHeight ()
 
virtual bool AllocatePixelMemory (bool zeroOut=true)
 
virtual bool AllocateMipMapMemory (bool zeroOut=true)
 
virtual void CalculateMipMapImages (bool reCalc=false)
 
virtual void Initialize (int width, int height, int pixelSize)
 
virtual ~Image ()
 

Protected Attributes

unsigned int _textureHandle
 
int _pixelFormat
 
int _pixelSize
 
int _errorFound
 
char * _errorMessage
 
int _width
 
int _height
 
int _texWidth
 
int _texHeight
 
float _texCoord [2]
 
unsigned char * _rgbBuf
 
bool _mipMap
 
unsigned char * _mmBuf [MAX_MIP_MAP_IMAGES]
 
unsigned long _crcValue
 
int _numUsers
 
bool _replaceImageFlag
 
bool _releaseImageData
 
bool _glTextureCompression
 
glsInlineImage_staticInlineImage
 
bool _allowImageSharing
 
bool _allowNPOT
 

Static Protected Attributes

static bool _glTextureCompressionSupported
 

Detailed Description

The Image class. Implements loading 2D image files.

Constructor & Destructor Documentation

◆ Image() [1/7]

Image ( const unsigned char *const  data,
int  width,
int  height,
int  pixelFormat 
)

Create an Image object with the specified image data and image size.

Parameters
dataPointer to the image data
widthWidth of the image
heightHeight of the image
pixelFormatThe format of each pixel, eg. GL_RGBA

◆ Image() [2/7]

Image ( int  width,
int  height,
int  pixelSize,
bool  allowNPOT = false 
)

Create an Image object with the specified image size.

Parameters
widthWidth of the image
heightHeight of the image
pixelSizeThe size in bytes of each pixel
allowNPOTIf the image is allowed to be non-power of two (NPOT)

◆ Image() [3/7]

Image ( const glsInlineImage image)

Create an Image from an inline image (GL Studio 2.2 and later API)

Parameters
imageStructure containing details of inline image

◆ Image() [4/7]

Image ( int  width,
int  height,
int  components,
int  format,
unsigned int  comprLen,
const unsigned char *const  data[],
unsigned long  crcVal = 0,
int  lineLength = 320 
)

Create an Image from a buffer of ZLIB compressed data Image data must already be a power of two!

Parameters
widthWidth of the image
heightHeight of the image
componentsThe size in bytes of each pixel
formatThe OpenGL texture format to use
comprLenThe size of the compressed image
dataThe buffer of compressed data
crcValThe CRC value used to find duplicate textures
lineLengthThe number of bytes in each inline image line

◆ Image() [5/7]

Image ( int  width,
int  height,
int  components,
int  format,
const unsigned char *const  pix[],
unsigned long  crcVal = 0,
int  lineLength = 320 
)

Create an Image from a buffer of uncompressed data Image data must already be a power of two!

Parameters
widthWidth of the image
heightHeight of the image
componentsThe size in bytes of each pixel
formatThe OpenGL texture format to use
pixThe buffer of uncompressed data
crcValThe CRC value used to find duplicate textures
lineLengthThe number of bytes in each inline image line

◆ Image() [6/7]

Image ( const Image source)

Copy constructor

Parameters
sourceThe object to copy from.

◆ Image() [7/7]

Image ( )

Constructor for an Image object.

◆ ~Image()

virtual ~Image ( )
protectedvirtual

Destroy an Image object. Frees the memory for the RGB buffer.

Member Function Documentation

◆ AddSelfToInstanceList()

void AddSelfToInstanceList ( )
protected

Add this image to the Image Sharing Instance List

◆ AddUsage()

virtual void AddUsage ( )
virtual

Lets this object know that another something is using this image

◆ AllocateMipMapMemory()

virtual bool AllocateMipMapMemory ( bool  zeroOut = true)
protectedvirtual

Allocate memory for Mip-Map images.

Parameters
zeroOutWhether or not to clear the memory to zero on allocation.
Returns
Whether or not allocation was successful.

◆ AllocatePixelMemory()

virtual bool AllocatePixelMemory ( bool  zeroOut = true)
protectedvirtual

Allocate and initialize the pixel buffer memory for this image _texWidth, _textHeight and _pixelSize must be initialized prior to calling! _rgbBuf is set to the initialized memory.

Parameters
zeroOutWhether or not to clear the memory to zero on allocation.
Returns
True if allocated. false on failure.

◆ AllocateTextureBinding()

virtual void AllocateTextureBinding ( )
virtual

Create a new texture object using Image object data.

◆ AllowImageSharing() [1/2]

virtual bool AllowImageSharing ( )
virtual
Returns
Whether or not this image can be deleted if a duplicate texture is found.

◆ AllowImageSharing() [2/2]

virtual void AllowImageSharing ( bool  value)
virtual

If AllowImageSharing is true, this Image may be deleted by the texture palette if a duplicate texture is found. This also implies that the Image will not change and may be used in place of another texture with the same CrcValue(). If false this causes Image::CrcValue() to always return 0, disabling duplicate checking. (default: true)

Note
If this Image is already in a TexturePalette, you should call TexturePalette::DisableImageSharing() instead of this method.
Parameters
valueThe new sharing flag to set.

◆ BindTexture()

virtual void BindTexture ( )
virtual

Make this Image object the active texture.

Implements IFontImage.

◆ CalculateMipMapImages()

virtual void CalculateMipMapImages ( bool  reCalc = false)
protectedvirtual

Calculate mip-map images from the main image.

Parameters
reCalcWhether or not to perform the calculation.

◆ Clone()

virtual Image * Clone ( )
virtual
Returns
A new image that is a duplicate of this image or NULL if duplication is not possible.

◆ ConvertLuminanceAlphaToAlpha()

void ConvertLuminanceAlphaToAlpha ( )
protected

Convert Luminance Alpha texture to Alpha texture. Used on OpenGL ES target to speedup texturing for fonts

◆ CrcValue()

virtual unsigned long CrcValue ( )
virtual
Returns
the CRC value for this image. 0 indicates an invalid value or that duplicate checking is disabled for the Image.

◆ DeallocateTextureBinding()

virtual void DeallocateTextureBinding ( )
virtual

Deletes the OpenGL texture object for this Image.

◆ DeleteUsage()

virtual void DeleteUsage ( )
virtual

Will delete the Image object if nobody is using it

◆ DisconnectInlineImage()

virtual bool DisconnectInlineImage ( bool  loadImage = true)
virtual

Removes the association between this Image and it's glsInlineImage data. This will use more memory, but makes the Image independent of the static data. This method will attempt to load the image before disconnecting from the glsInlineImage, if the load fails, ImageData() will return NULL afterwards. After calling this method, the Image will no longer have a glsInlineImage associated with it.

Parameters
loadImageIf true, the _rgbBuf will be loaded from the inline image data before disconnecting If false, the _rgbBuf will be allocated but not initialized.
Returns
true if the Image had a glsInlineImage associated with it
false if the Image did not have a glsInlineImage associated with it.

◆ Draw() [1/2]

virtual void Draw ( )
virtual

Draws the image at the current raster position.

◆ Draw() [2/2]

virtual void Draw ( int  x,
int  y 
)
virtual

Draws the image at the x,y raster position specified.

Parameters
xX position to draw the image
yY position to draw the image

◆ EmptyInstanceList()

static void EmptyInstanceList ( )
static

Empties the InstanceList This is done when loading objects which will be drawn in different OpenGL contexts.

◆ ErrorFound()

virtual int ErrorFound ( )
virtual
Returns
The state of any error found reading image file flag.

◆ FindDuplicate() [1/2]

virtual Image * FindDuplicate ( )
virtual

Tries to find an image that is the same as this image

Returns
A pointer to the first image in the image instance list that matches or NULL if not found

◆ FindDuplicate() [2/2]

static Image * FindDuplicate ( int  width,
int  height,
int  components,
unsigned long  crcVal,
bool  glTexCompress 
)
static

Tries to find an image that is the same as a notional image based on the following criteria

Parameters
widthWidth of notional image
heightHeight of notional image
componentsNumber of components in the notional image
crcVal32 bit CRC of notional image
glTexCompressGlTextureCompresssion setting for the image
Returns
A pointer to the first image in the image instance list that matches or NULL if not found

◆ FreeInlineImageData()

virtual bool FreeInlineImageData ( )
virtual

Frees the local rgb buffer if this image has a glsInlineImage associated with it.

Returns
true if the buffer was freed, false if this Image does not have a glsInlineImage associated with it.

◆ GetError()

virtual char * GetError ( )
virtual
Returns
The error message found during reading image file

◆ GetRasterPosition()

virtual unsigned char * GetRasterPosition ( int  x,
int  y 
)
virtual
Returns
A pointer to the memory location corresponding to the given X,Y position within the image.
Parameters
xThe X raster position.
yThe Y raster position.

◆ GlTextureCompression() [1/2]

virtual bool GlTextureCompression ( )
virtual
Returns
Whether or not Open GL texture compression is enabled

◆ GlTextureCompression() [2/2]

virtual void GlTextureCompression ( bool  set)
virtual

Enable or disable Open GL texture compression for this image

Parameters
setWhether or not Open GL texture compression is enabled

◆ Height()

virtual int Height ( )
virtual
Returns
the height of the image.

◆ ImageData()

virtual unsigned char * ImageData ( )
virtual
Returns
A pointer to the 2D image data

◆ Initialize()

virtual void Initialize ( int  width,
int  height,
int  pixelSize 
)
protectedvirtual

Helper routine used by constructor. Allocates pixel memory and sets the texture width, height and pixel size

Parameters
widthWidth of the image
heightHeight of the image
pixelSizeThe size in bytes of each pixel

◆ InstanceList()

static List_c & InstanceList ( )
static

All images get added to the InstanceList.

Returns
A modifiable refernce to the image list.

◆ InstanceListMutex()

static disti::Mutex & InstanceListMutex ( )
static

Use this Mutex when accessing the InstanceList.

Returns
A mutex for accessing the image list.

◆ IsAllowNPOTTextures()

bool IsAllowNPOTTextures ( ) const

Determine if non-power of two (NPOT) textures are allowed for this image.

Returns
true if non-power of two (NPOT) textures are allowed.

◆ IsDuplicate()

static bool IsDuplicate ( Image image,
int  width,
int  height,
int  components,
unsigned long  crcVal,
bool  glTexCompress 
)
static

Determines if an image #1 is the same a notional image based on the following criteria

Parameters
imageImage #1
widthWidth of notional image
heightHeight of notional image
componentsNumber of components in the notional image
crcVal32 bit CRC of notional image
glTexCompressGlTextureCompresssion setting for the image
Returns
True if they are equal

◆ IsReleaseImageDataEnabled()

bool IsReleaseImageDataEnabled ( )
Returns
Whether or not release of image data is enabled.
See also
SetReleaseImageDataEnabled()
disti::GetReleaseImageDataDefault()
Note
The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry were removed to disambiguate between the per-instance setting and the global setting. Code that was calling Image::IsUnloadImageDataEnabled() to get the default flag for all instances should now call disti::GetReleaseImageDataDefault(). Code that was calling Image::InstanceListEntry::IsUnloadImageDataEnabled() to get the flag for only one instance should call this method.

◆ LoadInlineImageData()

virtual bool LoadInlineImageData ( )
virtual

Allocates the local rgb buffer from the glsInlineImage for this image.

Returns
true if successful, false on failure (e.g. this image doesn't have a glsInlineImage associated with it.)

◆ MipMap() [1/2]

virtual bool MipMap ( )
virtual
Returns
Whether or not mipmaps are enabled

◆ MipMap() [2/2]

virtual void MipMap ( bool  set)
virtual

Enable or disable mipmaps for this image

Parameters
setWhether or not mipmaps are enabled

Implements IFontImage.

◆ NumUsers()

virtual int NumUsers ( )
virtual
Returns
the number of simultanious users of this image

◆ operator=()

virtual void operator= ( Image im)
virtual

Assignment operator

Parameters
imThe object to copy from.

◆ operator==()

virtual int operator== ( Image im)
virtual

Equality operator. Determines if two images are equal

Parameters
imImage to test
Returns
boolean result

◆ PixelFormat() [1/2]

virtual int PixelFormat ( )
virtual

Returns the pixel format for this image

Returns
The internal pixel format for this image

Implements IFontImage.

◆ PixelFormat() [2/2]

virtual void PixelFormat ( int  format)
virtual

Sets the pixel format for this image and also the pixel size as determined from the format. Eg. GL_RGBA has a pixel size of 4.

Parameters
formatThe new internal pixel format for this image

◆ PixelFormatString()

virtual char * PixelFormatString ( )
virtual
Returns
The OpenGL enumerator for the pixel format for this image as a string. Used for inline texture generation

◆ PixelSize()

virtual int PixelSize ( )
virtual
Returns
The size of a pixel in this image in bytes

◆ ReplaceImage() [1/2]

virtual void ReplaceImage ( unsigned char *  imageData)
virtual

Replaces the current image with the specified. The new image must be the same _texWidth, _texHeight, and _pixelSize as the current image.

Parameters
imageDataThe image data to replace with.

◆ ReplaceImage() [2/2]

virtual bool ReplaceImage ( unsigned char *  imageData,
int  width,
int  height,
int  pixelSize 
)
virtual

Replaces the current image with the specified.

Parameters
imageDatabuffer containing the new image data
widthnew Width of the image. Must be a power of two (2^n).
heightnew Height of the image. Must be a power of two (2^n).
pixelSizeThe size in bytes of each pixel
Returns
true if successful, false if the operation is unsupported or there was an error.

◆ ScaleTexture()

virtual void ScaleTexture ( )
virtual

Scale the texture to the nearest power of two

◆ ScaleToPowerOfTwo()

virtual void ScaleToPowerOfTwo ( )
virtual

Scales the image up to the nearest power of two in each dimension

◆ SetAsCurrentTexture()

virtual void SetAsCurrentTexture ( )
virtual

Takes the image and creates a 2D Decal texture map. (Not Implemented)

◆ SetError()

virtual void SetError ( char *  errorMessage)
virtual

Sets the error message.

Parameters
errorMessageString containing error message.

◆ SetPixel()

virtual void SetPixel ( int  x,
int  y,
float  color[] 
)
virtual

Set the value of a secific pixel in the rbg buffer.

Parameters
xX position of the pixel
yY position of the pixel
colorColor of the pixel

◆ SetReleaseImageDataEnabled()

void SetReleaseImageDataEnabled ( bool  enable)

Determines whether this image will release its image data from main memory when it is not needed.

When enabled (true), the the Image will release the main memory copy of the data when it is not needed in order to save memory. This flag is enabled by default and should be disabled in situations such as when the ImageData for this Image cannot be re-created from permanent storage.

Note
The default value is determined by disti::GetReleaseImageDataDefault().
Parameters
enableWhether release of image data is enabled.
See also
IsReleaseImageDataEnabled()
disti::SetReleaseImageDataDefault()
Note
The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry were removed to disambiguate between the per-instance setting and the global setting. Code that was calling Image::SetUnloadImageDataEnabled() to set the default flag for all instances should now call disti::SetReleaseImageDataDefault(). Code that was calling Image::InstanceListEntry::SetUnloadImageDataEnabled() to set the flag for only one instance should call this method.

◆ SetTexWidthHeight()

virtual void SetTexWidthHeight ( )
protectedvirtual

Set the Image _texWidth, _texHeight, _texWidth, _texCoord[0], and _texCoord[1]. Width and height must be set before calling this function.

◆ Size()

virtual int Size ( )
virtual
Returns
the memory size of the image in bytes

◆ TextureCoordX()

virtual float TextureCoordX ( )
virtual
Returns
the X position of the texture coordinate used for the image.

◆ TextureCoordY()

virtual float TextureCoordY ( )
virtual
Returns
the Y position of the texture coordinate used for the image.

◆ TextureHandle()

virtual unsigned int TextureHandle ( ) const
inlinevirtual
Returns
the OpenGL texture handle of this texture instance

◆ TextureHandleValid()

virtual bool TextureHandleValid ( )
virtual
Returns
true if the internal texture handle is valid

◆ TextureHeight()

virtual int TextureHeight ( )
virtual
Returns
the texture height of the image file. This is the power of 2 size greater than or equal the size of the image.

◆ TextureWidth()

virtual int TextureWidth ( )
virtual
Returns
the texture width of the image file. This is the power of 2 size greater than or equal to the size of the image.

◆ UnloadRgbData()

void UnloadRgbData ( )

Unload RGB and mipmap data to save memory

◆ Width()

virtual int Width ( )
virtual
Returns
the width of the image.

Member Data Documentation

◆ _allowImageSharing

bool _allowImageSharing
protected

If false, causes Image::CrcValue() to always return 0, disabling duplicate checking.

◆ _allowNPOT

bool _allowNPOT
protected

If true, this texture is not scaled to power of two.

◆ _crcValue

unsigned long _crcValue
protected

CRC value used to determine if two images are the same

◆ _errorFound

int _errorFound
protected

Error found reading image file flag.

◆ _errorMessage

char* _errorMessage
protected

Error message in string format.

◆ _globalMipMapEnabled

bool _globalMipMapEnabled
static

Determines the default value for _mipMap, and does not do mip mapping if false

◆ _glTextureCompression

bool _glTextureCompression
protected

Indicates if GL Texture compression is enabled for this image

◆ _glTextureCompressionSupported

bool _glTextureCompressionSupported
staticprotected

Indicates if GL Texture compression is supported on the Machine that this program is running on.

◆ _height

int _height
protected

Actual height of image in pixels.

◆ _mipMap

bool _mipMap
protected

True if this image should use mip mapping

◆ _mmBuf

unsigned char* _mmBuf[MAX_MIP_MAP_IMAGES]
protected

Pointers to the smaller versions of _rgbBuf

◆ _numUsers

int _numUsers
protected

Count of number of objects that reference this one

◆ _pixelFormat

int _pixelFormat
protected

Pixel format for the image

◆ _pixelSize

int _pixelSize
protected

Size of a pixel in bytes

◆ _releaseImageData

bool _releaseImageData
protected

true to allow image data for image to be unloaded from main memory else false

◆ _replaceImageFlag

bool _replaceImageFlag
protected

Indicates the images has been changed and needs to be re-bound

◆ _rgbBuf

unsigned char* _rgbBuf
protected

Pointer to the image data for this image.

◆ _staticInlineImage

glsInlineImage* _staticInlineImage
protected

Inline image data for this image, if applicable.

◆ _texCoord

float _texCoord[2]
protected

Texture coordinates of upper right corner of image. This will be (1.0,1.0) for a square power of two image

◆ _texHeight

int _texHeight
protected

Texture height (power of 2) of the image in pixels.

◆ _textureHandle

unsigned int _textureHandle
protected

The texture handle of the image.

◆ _texWidth

int _texWidth
protected

Texture width (power of 2) of the image in pixels.

◆ _width

int _width
protected

Actual width of image in pixels.


The documentation for this class was generated from the following file: