cugl::PixelMap Class Reference

#include <cugl.h>

List of all members.

Public Member Functions

 PixelMap ()
 PixelMap (char *bmpFileName)
 PixelMap (GLint x, GLint y, GLsizei w, GLsizei h)
 ~PixelMap ()
void read (char *bmpFileName)
void read (GLint x, GLint y, GLsizei w, GLsizei h)
void write (char *bmpFileName)
bool badSize ()
void rescale ()
void draw ()
void setTexture (GLuint name)
void setMipmaps (GLuint name)
void select (const PixelMap &src, int xp, int yp, int width, int height)
unsigned long getRows () const
unsigned long getColumns () const
unsigned long getSize () const
char * getName () const
bool ready () const

Private Member Functions

 PixelMap (const PixelMap &pm)
bool allocate (unsigned long newSize)

Private Attributes

unsigned long numRows
unsigned long numCols
unsigned long size
char * fileName
unsigned char * pixels

Friends

bool compatible (const PixelMap &m1, const PixelMap &m2)
void mix (const PixelMap &m1, const PixelMap &m2, PixelMap &res, double prop)
std::ostream & operator<< (std::ostream &os, PixelMap &pm)


Detailed Description

An instance is an RGB pixel array. An instance of PixelMap holds an array that OpenGL can use as a texture or to display directly.

This class is implemented so that it does not depend on Windows. In principle, it should even work with Linux and other operating systems, although this has not been tested thoroughly.

If you want to use a BMP image as a texture, the width and height must be powers of two. Thus a 256 x 512 BMP image is acceptable but a 640 x 400 image is not. This restriction does not apply to images that are displayed as bitmaps.

Since an instance of PixelMap contains pointers, there are memory management issues. The destructor deletes pixel and other data associated with a pixel map. The copy constructor is declared privately and not implemented: this prevents instances being passed by value, although they may be passed by reference. Since there is a default constructor, you can construct arrays of PixelMap's or pointers to PixelMap.

Definition at line 1814 of file cugl.h.


Constructor & Destructor Documentation

cugl::PixelMap::PixelMap (  ) 

Construct an empty pixel map.

cugl::PixelMap::PixelMap ( char *  bmpFileName  ) 

Read a pixel map from a file.

Parameters:
bmpFileName is a path to a BMP file.

cugl::PixelMap::PixelMap ( GLint  x,
GLint  y,
GLsizei  w,
GLsizei  h 
)

Construct a pixel map from a region of the pixel buffer.

Parameters:
x is the X coordinate of the lower left corner of the region.
y is the Y coordinate of the lower left corner of the region.
w is the width of the region in pixels.
h is the height of the region in pixels.
Note:
See also PixelMap::read(x, y, w, h).

cugl::PixelMap::~PixelMap (  ) 

Delete a pixel map.

cugl::PixelMap::PixelMap ( const PixelMap pm  )  [private]

The copy constructor is private and unimplemented. This prevents pixel maps from being copied by mistake.


Member Function Documentation

void cugl::PixelMap::read ( char *  bmpFileName  ) 

Read a BMP file and convert it to a pixel map. Previous data associated with this object will be deleted. The BMP file must satisfy several criteria if it is to be converted successfully. Conversion failure is indicated by the following CUGL errors.

OpenGL cannot use a bitmap as a texture if its dimensions are not powers of 2. To check whether the bitmap has acceptable dimensions, call PixelMap::badSize(). To convert the bitmap dimensions to acceptable values, call PixelMap::rescale().
Parameters:
bmpFileName is the name of the file to be read, with the extension '.bmp'.

void cugl::PixelMap::read ( GLint  x,
GLint  y,
GLsizei  w,
GLsizei  h 
)

Read a pixel map from a region of the framebuffer. This function is similar to the constructor with the same parameters, but allocates new memory only if necessary.

Parameters:
x is the X coordinate of the lower left corner of the region.
y is the Y coordinate of the lower left corner of the region.
w is the width of the region in pixels.
h is the height of the region in pixels.
Note:
See also the constructor PixelMap(x, y, w, h).

void cugl::PixelMap::write ( char *  bmpFileName  ) 

Write a pixel map to an output stream as a BMP file.

Parameters:
bmpFileName is the name of the file to be written, with the extension '.bmp'.

bool cugl::PixelMap::badSize (  ) 

Check the dimensions of the bit map. If the dimensions are not powers of 2, return true. If the dimensions of the bitmap are not powers of 2, OpenGL cannot use it as a texture. You should call PixelMap::rescale() to resize the bit map.

void cugl::PixelMap::rescale (  ) 

Rescale a bit map whose dimensions are not powers of 2. The new image will be distorted; the amount of distortion depends on how much the dimensions have to be altered. Use PixelMap::badSize() to determine whether the dimensions are powers of 2.

void cugl::PixelMap::draw (  ) 

Draw the pixel map at the current raster position. Error NO_PIX_MAP if there is no pixel map avaialble.

void cugl::PixelMap::setTexture ( GLuint  name  ) 

Set texture parameters for the pixel map.

Parameters:
name is an OpenGL index for the texture parameters provided by the caller.
Note:
This function sets GL_TEXTURE_MAG_FILTER and GL_TEXTURE_MIN_FILTER to GL_NEAREST. Call glTexParameter() to change these settings.

When this function returns, OpenGL has copied the pixel map into its own memory space. It is therefore safe to delete the PixelMap instance after calling setTexture().

void cugl::PixelMap::setMipmaps ( GLuint  name  ) 

Set texture parameters for the pixel mipmaps. Construct a family of mipmaps for texturing.

Parameters:
name is an OpenGL index for the texture parameters provided by the caller.
Note:
This function sets GL_TEXTURE_MIN_FILTER to GL_LINEAR_MIPMAP_NEAREST. Call glTexParameter() to change this setting.

When this function returns, OpenGL has copied the pixel map into its own memory space. It is therefore safe to delete the PixelMap instance after calling setMipmaps().

Call this function once only for each texture you need in your program. Use glBindTexture to select textures in the display function.

void cugl::PixelMap::select ( const PixelMap src,
int  xp,
int  yp,
int  width,
int  height 
)

Select a region from a pixel map.

Parameters:
src is the pixel map from which the data is extracted.
xp defines the left side of the selected region.
yp defines the right side of the selected region.
width is the width of the selected region.
height is the height of the selected region.

unsigned long cugl::PixelMap::getRows (  )  const [inline]

Return number of rows in pixel map.

Definition at line 1960 of file cugl.h.

References numRows.

unsigned long cugl::PixelMap::getColumns (  )  const [inline]

Return number of columns in pixel map.

Definition at line 1968 of file cugl.h.

References numCols.

unsigned long cugl::PixelMap::getSize (  )  const [inline]

Return bytes of memory used by pixel map.

Definition at line 1976 of file cugl.h.

References size.

char* cugl::PixelMap::getName (  )  const [inline]

Return name of BMP file.

Definition at line 1984 of file cugl.h.

References fileName.

bool cugl::PixelMap::ready (  )  const [inline]

Return true if a pixel map has been read successfully.

Definition at line 1992 of file cugl.h.

References pixels.

bool cugl::PixelMap::allocate ( unsigned long  newSize  )  [private]

Allocate memory for a new pixel map if necessary.


Friends And Related Function Documentation

bool compatible ( const PixelMap m1,
const PixelMap m2 
) [friend]

Check that two pixel maps are compatible for combining.

void mix ( const PixelMap m1,
const PixelMap m2,
PixelMap res,
double  prop 
) [friend]

Combine two pixel maps.

Parameters:
m1 is the first map to be combined.
m2 is the second map to be combined.
res is the resulting pixel map. The caller is responsible for constructing this map; it is not constructed by the function.
prop is the mixing proportion: 0 gives m1, 0.5 gives half of each, and 1 gives m2.

std::ostream& operator<< ( std::ostream &  os,
PixelMap pm 
) [friend]

Write a description of the pixel map to the output stream.


Member Data Documentation

unsigned long cugl::PixelMap::numRows [private]

Number of rows in the pixel map.

Definition at line 2014 of file cugl.h.

Referenced by getRows().

unsigned long cugl::PixelMap::numCols [private]

Number of columns in the pixel map.

Definition at line 2017 of file cugl.h.

Referenced by getColumns().

unsigned long cugl::PixelMap::size [private]

Size, in bytes, of the pixel map.

Definition at line 2020 of file cugl.h.

Referenced by getSize().

char* cugl::PixelMap::fileName [private]

Name of the file used to store the pixel map.

Definition at line 2023 of file cugl.h.

Referenced by getName().

unsigned char* cugl::PixelMap::pixels [private]

Pointer to the pixels of the map.

Definition at line 2026 of file cugl.h.

Referenced by ready().


The documentation for this class was generated from the following file:
Generated on Wed Sep 12 14:31:42 2007 for CUGL by  doxygen 1.5.2