Visualization Library

A lightweight C++ OpenGL middleware for 2D/3D graphics
[Home] [Tutorials] [All Classes] [Grouped Classes]

vl::Image Class Reference

Implements a generic 1d, 2d, 3d and cubemap image that can have mipmaps. More...

#include <Image.hpp>

Inheritance diagram for vl::Image:

vl::Object

List of all members.

Public Member Functions

 Image ()
 Image (const String &path)
 Image (int x, int y, int z, int bytealign, EImageFormat format, EImageType type)
 Note that the image is not allocated.
virtual const char * className ()
 Returns the name of the class.
virtual ~Image ()
Imageoperator= (const Image &other)
bool isCubemap () const
bool isValid () const
 Returns true if the image has valid width/height/depth, pitch and byte alignment, type/format combination.
EImageDimension dimension () const
void allocate ()
void allocate1D (int x, EImageFormat format, EImageType type)
void allocate2D (int x, int y, int bytealign, EImageFormat format, EImageType type)
void allocate3D (int x, int y, int z, int bytealign, EImageFormat format, EImageType type)
void allocateCubemap (int x, int y, int bytealign, EImageFormat format, EImageType type)
void reset (int x, int y, int z, int bytealign, EImageFormat format, EImageType type, bool is_cubemap)
void clear ()
int byteAlignment () const
 Returns the byte-alignment of the row of the image.
void setByteAlignment (int bytealign)
 Modifies the byte-alignment of the rows of the image, thus changing its pitch.
int bitsPerPixel () const
int requiredMemory () const
 Returns the number of bytes requested to store the image.
String print () const
String printType () const
String printFormat () const
void setWidth (int x)
void setHeight (int y)
void setDepth (int z)
void setFormat (EImageFormat format)
void setType (EImageType type)
KeyValuestags () const
void setTags (KeyValues *tags)
void setImageBuffer (GLBufferObject *gpu_buffer)
 Sets a GLBufferObject to be used as the Image's pixels storage in local and GPU memory.
GLBufferObjectimageBuffer ()
 The GLBufferObject used as the Image's pixels storage in local and GPU memory.
const GLBufferObjectimageBuffer () const
 The GLBufferObject used as the Image's pixels storage in local and GPU memory.
const unsigned char * pixels () const
unsigned char * pixels ()
bool empty ()
unsigned char * pixelsZSlice (int slice)
 Returns the pixels of the specified Z slice of a 3D image.
unsigned char * pixelsXP ()
unsigned char * pixelsXN ()
unsigned char * pixelsYP ()
unsigned char * pixelsYN ()
unsigned char * pixelsZP ()
unsigned char * pixelsZN ()
void setMipmaps (const std::vector< ref< Image > > &mipmaps)
const std::vector< ref< Image > > & mipmaps () const
void clearMipmaps ()
int width () const
int height () const
int depth () const
int pitch () const
EImageFormat format () const
EImageType type () const
int alphaBits () const
 Useful to know if the image format supports alpha or not.
void readPixels (int x, int y, int width, int height, EReadDrawBuffer read_buffer, bool store_in_pixel_buffer_object)
 Reads a rectangular pixel area from the specified read buffer and stores it in an Image.
void flipVertically ()
ref< ImageconvertType (EImageType new_type) const
 Converts the type() of an image.
ref< ImageconvertFormat (EImageFormat new_format) const
 Converts the format() of an image.
bool equalize ()
 Equalizes the image. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.
bool contrast (float black, float white)
 Adjusts the contrast of an image. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.
bool contrastHounsfieldAuto ()
 Adjusts the contrast of an image using the window-center/window-with method used for CT images. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.
bool contrastHounsfield (float center, float width, float intercept, float range)
 Adjusts the contrast of an image using the window-center/window-with method used for CT images. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.
fvec4 sampleLinear (double x)
 Performs a sampling on a 1d image using linear filtering.
fvec4 sampleLinear (double x, double y)
 Performs a sampling on a 2d image using bilinear filtering.
fvec4 sampleLinear (double x, double y, double z)
 Performs a sampling on a 3d image using trilinear filtering.
fvec4 sample (int x, int y=0, int z=0)
 Returns the color associated to the specified pixel.
ref< ImagesubImage (int xstart, int ystart, int width, int height)
 Creates a new image containing the specified rectangular pixel area taken from the source image.
void copySubImage (Image *img_src, RectI src, ivec2 dst)
 Copies the rectangular area specified by src of img_src into an Image at position dst.
void substituteColorRGB_RGBA (unsigned int before, unsigned int after)
 Substitutes the color 'before' with the new color 'after'.
void substituteColorRGB_RGB (unsigned int before, unsigned int after)
 Substitutes the color 'before' with the new color 'after'.
void substituteColorGreenKey (unsigned int col0, unsigned int col1)

Static Public Member Functions

static int bitsPerPixel (EImageType type, EImageFormat format)
 Returns the number of bits used to represents one pixel.
static int requiredMemory (int x, int y, int z, int bytealign, EImageFormat format, EImageType type, bool is_cubemap)
static int requiredMemory1D (int x, EImageFormat format, EImageType type)
static int requiredMemory2D (int x, int y, int bytealign, EImageFormat format, EImageType type)
static int requiredMemory3D (int x, int y, int z, int bytealign, EImageFormat format, EImageType type)
static int requiredMemoryCubemap (int x, int y, int bytealign, EImageFormat format, EImageType type)
static int isCompressedFormat (EImageFormat fmt)
static ref< ImagecreateCubemap (const Image *xp, const Image *xn, const Image *yp, const Image *yn, const Image *zp, const Image *zn)
static ref< ImagemakeNonUniformColorSpectrum (int width, const std::vector< fvec4 > &colors, const std::vector< float > &col_pos)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeNonUniformColorSpectrum (size_t width, size_t col_count, const fvec4 *colors, const float *col_pos)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeColorSpectrum (size_t width, const std::vector< fvec4 > &colors)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeColorSpectrum (size_t width, const fvec4 &c0, const fvec4 &c1)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeColorSpectrum (size_t width, const fvec4 &c0, const fvec4 &c1, const fvec4 &c2)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeColorSpectrum (size_t width, const fvec4 &c0, const fvec4 &c1, const fvec4 &c2, const fvec4 &c3)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.
static ref< ImagemakeColorSpectrum (size_t width, const fvec4 &c0, const fvec4 &c1, const fvec4 &c2, const fvec4 &c3, const fvec4 &c4)
 Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

Protected Member Functions

void updatePitch ()

Protected Attributes

ref< GLBufferObjectmPixels
ref< KeyValuesmTags
std::vector< ref< Image > > mMipmaps
int mWidth
int mHeight
int mDepth
int mPitch
int mByteAlign
EImageFormat mFormat
EImageType mType
bool mIsCubemap


Detailed Description

Implements a generic 1d, 2d, 3d and cubemap image that can have mipmaps.

Image also supports the GL_EXT_pixel_buffer_object extension, see readPixels() and gpuBuffer().

Remarks:
The copy operator performs a deep copy of all the pixel data and thus is to be considered an expensive operation.

Constructor & Destructor Documentation

Image::Image (  ) 

Image::Image ( const String path  ) 

Image::Image ( int  x,
int  y,
int  z,
int  bytealign,
EImageFormat  format,
EImageType  type 
)

Note that the image is not allocated.

Image::~Image (  )  [virtual]


Member Function Documentation

virtual const char* vl::Image::className (  )  [inline, virtual]

Returns the name of the class.

Reimplemented from vl::Object.

Image & Image::operator= ( const Image other  ) 

bool vl::Image::isCubemap (  )  const [inline]

bool Image::isValid (  )  const

Returns true if the image has valid width/height/depth, pitch and byte alignment, type/format combination.

Remarks:
In order to be valid an image must be at least 1x0x0 (1D image) or 1x1x0 (2D or cubemap image) or 1x1x1 (3D image). Sizes like Nx0xM, 0xNxM, 0xNx0, 0x0xN, 0x0x0 are not valid.
Invalid type/format combinations are for example:
  • OGL_RGB / IT_UNSIGNED_SHORT_4_4_4_4: since here the format has 3 components while the type has 4.
  • IF_COMPRESSED_RGB_S3TC_DXT1_EXT / IT_BYTE: since compressed formats require IT_COMPRESSED_TYPE.

EImageDimension Image::dimension (  )  const

void Image::allocate (  ) 

void Image::allocate1D ( int  x,
EImageFormat  format,
EImageType  type 
)

void Image::allocate2D ( int  x,
int  y,
int  bytealign,
EImageFormat  format,
EImageType  type 
)

void Image::allocate3D ( int  x,
int  y,
int  z,
int  bytealign,
EImageFormat  format,
EImageType  type 
)

void Image::allocateCubemap ( int  x,
int  y,
int  bytealign,
EImageFormat  format,
EImageType  type 
)

void Image::reset ( int  x,
int  y,
int  z,
int  bytealign,
EImageFormat  format,
EImageType  type,
bool  is_cubemap 
)

void Image::clear (  ) 

int Image::byteAlignment (  )  const

Returns the byte-alignment of the row of the image.

Possible return values are 1, 2, 4 and 8.

void Image::setByteAlignment ( int  bytealign  ) 

Modifies the byte-alignment of the rows of the image, thus changing its pitch.

Only values like 0, 1, 2, 4 and 8 are allowed. If 0 is passed the byte-alignment takes the value returned by "sizeof(unsigned char*)".

Remarks:
This function must be called before the allocate() function or in any case on a non allocated image otherwise it won't have any effect.

int Image::bitsPerPixel ( EImageType  type,
EImageFormat  format 
) [static]

Returns the number of bits used to represents one pixel.

int vl::Image::bitsPerPixel (  )  const [inline]

int Image::requiredMemory (  )  const

Returns the number of bytes requested to store the image.

Doesn't take into consideration mipmaps.

int Image::requiredMemory ( int  x,
int  y,
int  z,
int  bytealign,
EImageFormat  format,
EImageType  type,
bool  is_cubemap 
) [static]

static int vl::Image::requiredMemory1D ( int  x,
EImageFormat  format,
EImageType  type 
) [inline, static]

static int vl::Image::requiredMemory2D ( int  x,
int  y,
int  bytealign,
EImageFormat  format,
EImageType  type 
) [inline, static]

static int vl::Image::requiredMemory3D ( int  x,
int  y,
int  z,
int  bytealign,
EImageFormat  format,
EImageType  type 
) [inline, static]

static int vl::Image::requiredMemoryCubemap ( int  x,
int  y,
int  bytealign,
EImageFormat  format,
EImageType  type 
) [inline, static]

String Image::print (  )  const

String Image::printType (  )  const

String Image::printFormat (  )  const

void vl::Image::setWidth ( int  x  )  [inline]

void vl::Image::setHeight ( int  y  )  [inline]

void vl::Image::setDepth ( int  z  )  [inline]

void vl::Image::setFormat ( EImageFormat  format  )  [inline]

void vl::Image::setType ( EImageType  type  )  [inline]

KeyValues* vl::Image::tags (  )  const [inline]

void vl::Image::setTags ( KeyValues tags  )  [inline]

void vl::Image::setImageBuffer ( GLBufferObject gpu_buffer  )  [inline]

Sets a GLBufferObject to be used as the Image's pixels storage in local and GPU memory.

You can bind it to a GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER using glBindBuffer() to take advantage of the GL_EXT_pixel_buffer_object extension.

GLBufferObject* vl::Image::imageBuffer (  )  [inline]

The GLBufferObject used as the Image's pixels storage in local and GPU memory.

You can bind it to a GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER using glBindBuffer() to take advantage of the GL_EXT_pixel_buffer_object extension.

const GLBufferObject* vl::Image::imageBuffer (  )  const [inline]

The GLBufferObject used as the Image's pixels storage in local and GPU memory.

You can bind it to a GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER using glBindBuffer() to take advantage of the GL_EXT_pixel_buffer_object extension.

const unsigned char* vl::Image::pixels (  )  const [inline]

unsigned char* vl::Image::pixels (  )  [inline]

bool vl::Image::empty (  )  [inline]

unsigned char * Image::pixelsZSlice ( int  slice  ) 

Returns the pixels of the specified Z slice of a 3D image.

unsigned char * Image::pixelsXP (  ) 

unsigned char * Image::pixelsXN (  ) 

unsigned char * Image::pixelsYP (  ) 

unsigned char * Image::pixelsYN (  ) 

unsigned char * Image::pixelsZP (  ) 

unsigned char * Image::pixelsZN (  ) 

void vl::Image::setMipmaps ( const std::vector< ref< Image > > &  mipmaps  )  [inline]

const std::vector< ref<Image> >& vl::Image::mipmaps (  )  const [inline]

void vl::Image::clearMipmaps (  )  [inline]

int vl::Image::width (  )  const [inline]

int vl::Image::height (  )  const [inline]

int vl::Image::depth (  )  const [inline]

int vl::Image::pitch (  )  const [inline]

EImageFormat vl::Image::format (  )  const [inline]

EImageType vl::Image::type (  )  const [inline]

int Image::alphaBits (  )  const

Useful to know if the image format supports alpha or not.

int Image::isCompressedFormat ( EImageFormat  fmt  )  [static]

void Image::readPixels ( int  x,
int  y,
int  width,
int  height,
EReadDrawBuffer  read_buffer,
bool  store_in_pixel_buffer_object 
)

Reads a rectangular pixel area from the specified read buffer and stores it in an Image.

If 'store_in_pixel_buffer_object' is true the data will be copied in the GPU memory using the GL_EXT_pixel_buffer_object extension, while the local buffer will be deallocated.

Note:
The image returned by this function might seem flipped upside down.

void Image::flipVertically (  ) 

ref< Image > Image::createCubemap ( const Image xp,
const Image xn,
const Image yp,
const Image yn,
const Image zp,
const Image zn 
) [static]

static ref<Image> vl::Image::makeNonUniformColorSpectrum ( int  width,
const std::vector< fvec4 > &  colors,
const std::vector< float > &  col_pos 
) [inline, static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeNonUniformColorSpectrum ( size_t  width,
size_t  col_count,
const fvec4 colors,
const float *  col_pos 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeColorSpectrum ( size_t  width,
const std::vector< fvec4 > &  colors 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeColorSpectrum ( size_t  width,
const fvec4 c0,
const fvec4 c1 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeColorSpectrum ( size_t  width,
const fvec4 c0,
const fvec4 c1,
const fvec4 c2 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeColorSpectrum ( size_t  width,
const fvec4 c0,
const fvec4 c1,
const fvec4 c2,
const fvec4 c3 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > Image::makeColorSpectrum ( size_t  width,
const fvec4 c0,
const fvec4 c1,
const fvec4 c2,
const fvec4 c3,
const fvec4 c4 
) [static]

Creates a 1D Image whose color is interpolated from left to right from the specified spectrum.

ref< Image > vl::Image::convertType ( EImageType  new_type  )  const

Converts the type() of an image.

The source image type and the new type must be one of the following:

  • IT_UNSIGNED_BYTE
  • IT_BYTE
  • IT_UNSIGNED_SHORT
  • IT_SHORT
  • IT_UNSIGNED_INT
  • IT_INT
  • IT_FLOAT

The source image format must be one of the following:

  • IF_RGB
  • IF_RGBA
  • IF_BGR
  • IF_BGRA
  • IF_RED
  • IF_GREEN
  • IF_BLUE
  • IF_ALPHA
  • IF_LUMINANCE
  • IF_LUMINANCE_ALPHA
  • IF_DEPTH_COMPONENT

ref< Image > vl::Image::convertFormat ( EImageFormat  new_format  )  const

Converts the format() of an image.

The source image type must be one of the following:

  • IT_UNSIGNED_BYTE
  • IT_BYTE
  • IT_UNSIGNED_SHORT
  • IT_SHORT
  • IT_UNSIGNED_INT
  • IT_INT
  • IT_FLOAT

The source image format and the new format must be one of the following:

  • IF_RGB
  • IF_RGBA
  • IF_BGR
  • IF_BGRA
  • IF_RED
  • IF_GREEN
  • IF_BLUE
  • IF_ALPHA
  • IF_LUMINANCE
  • IF_LUMINANCE_ALPHA

bool Image::equalize (  ) 

Equalizes the image. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.

This function is mainly useful for images whose type() is IF_LUMINANCE, IF_RED, IF_GREEN, IF_BLUE, IF_ALPHA or IF_DEPTH_COMPONENT.

IF_RGB, IF_RGBA, IF_BGR, IF_BGRA and IF_LUMINANCE_ALPHA types are not optimally handled yet.

bool Image::contrast ( float  black,
float  white 
)

Adjusts the contrast of an image. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.

This function supports only images whose type() is IF_LUMINANCE, IF_RED, IF_GREEN, IF_BLUE, IF_ALPHA or IF_DEPTH_COMPONENT.

The parameters black and white are in normalized units (0=black, 1=white) but are not required to be in the range between 0 and 1.

bool Image::contrastHounsfieldAuto (  ) 

Adjusts the contrast of an image using the window-center/window-with method used for CT images. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.

The center and width parameters are in Hounsfield units.

Calls contrastHounsfield(float center, float width, float intercept, float range) with center, with, range and intercept parameters extracted from the image tags() "WindowCenter", "WindowWidth", "BitsStored" and "RescaleIntercept". This function is equivalent to the code below.

if ( !tags()->has("WindowCenter") || !tags()->has("WindowWidth") || !tags()->has("BitsStored") || !tags()->has("RescaleIntercept"))
  return false;

float center    = tags()->value("WindowCenter").toFloat();
float width     = tags()->value("WindowWidth").toFloat();
float range     = (1<<tags()->value("BitsStored").toInt()) - 1.0f;
float intercept = tags()->value("RescaleIntercept").toFloat();

// Hounsfield units: -1000 = air, +1000 = solid bone
// Transform from Hounsfield units to normalized 0..1 units
center = (center-intercept) / range;
width  = width / range;
return contrast( center-width/2.0f, center+width/2.0f );

bool Image::contrastHounsfield ( float  center,
float  width,
float  intercept,
float  range 
)

Adjusts the contrast of an image using the window-center/window-with method used for CT images. Returns false if the image format() or type() is not supported. This function supports both 3D images and cubemaps.

The center and width parameters are in Hounsfield units.

This function is equivalent to the code below:

// Hounsfield units: -1000 = air, +1000 = solid bone
// Transform from Hounsfield units to normalized 0..1 units
center = (center-intercept) / range;
width  = width / range;
return contrast( center-width/2.0f, center+width/2.0f );

fvec4 Image::sampleLinear ( double  x  ) 

Performs a sampling on a 1d image using linear filtering.

fvec4 Image::sampleLinear ( double  x,
double  y 
)

Performs a sampling on a 2d image using bilinear filtering.

fvec4 Image::sampleLinear ( double  x,
double  y,
double  z 
)

Performs a sampling on a 3d image using trilinear filtering.

fvec4 Image::sample ( int  x,
int  y = 0,
int  z = 0 
)

Returns the color associated to the specified pixel.

The rgb values are mapped to 0..1 for all image types but IT_FLOAT. The value returned for images of type IT_FLOAT is returned exactly as is stored in the image.

The image type() must be one of the following:

  • IT_UNSIGNED_BYTE
  • IT_BYTE
  • IT_UNSIGNED_SHORT
  • IT_SHORT
  • IT_UNSIGNED_INT
  • IT_INT
  • IT_FLOAT

The image format() must be one of the following:

  • IF_RGB
  • IF_RGBA
  • IF_BGR
  • IF_BGRA
  • IF_RED
  • IF_GREEN
  • IF_BLUE
  • IF_ALPHA
  • IF_LUMINANCE
  • IF_LUMINANCE_ALPHA
  • IF_DEPTH_COMPONENT

ref< Image > Image::subImage ( int  xstart,
int  ystart,
int  width,
int  height 
)

Creates a new image containing the specified rectangular pixel area taken from the source image.

The returned image is of the same type() and format() of the original one.

Note:
  • This function supports only 2d images.
  • This function does not support compressed types and formats.

void Image::copySubImage ( Image img_src,
RectI  src,
ivec2  dst 
)

Copies the rectangular area specified by src of img_src into an Image at position dst.

The source and destination image should be of the same type() and format() for maximum performances.

void Image::substituteColorRGB_RGBA ( unsigned int  before,
unsigned int  after 
)

Substitutes the color 'before' with the new color 'after'.

Parameters:
before is an hexadecimal representation of an RGB triplet given in the form 0xRRGGBB.
after is an hexadecimal representation of an RGBA quadruplet given in the form 0xRRGGBBAA. For example 0xFF0000FF is opaque red, 0x00FF0088 is half transparent green. This function can be very useful when you want to modify a specified color of an image or when you want to perform color-key transparency, i.e. when you want to set the transparency of the pixels that have a particular color.
Note:
  • This function can be used only if the image type() is IT_UNSIGNED_BYTE and format() is either IF_RGB or IF_RGBA.
  • If the image format() is set to IF_RGB then the alpha value specified in 'after' is ignored.
  • If you want to be sure to keep the alpha channel intact use the substituteColorRGB_RGB() function instead.

void Image::substituteColorRGB_RGB ( unsigned int  before,
unsigned int  after 
)

Substitutes the color 'before' with the new color 'after'.

Parameters:
before is an hexadecimal representation of an RGB triplet given in the form 0xRRGGBB.
after is an hexadecimal representation of an RGB tripet given in the form 0xRRGGBB. For example 0xFF0000 is opaque red, 0x00FF00 is green. This function can be very useful when you want to modify a specified color of an image but you want to keep the alpha channel intact.
Note:
  • This function can be used only if the image type() is IT_UNSIGNED_BYTE and format() is either IF_RGB or IF_RGBA.
  • If you want to change the alpha channel of the modified pixels use the substituteColorRGB_RGBA() function instead.

void Image::substituteColorGreenKey ( unsigned int  col0,
unsigned int  col1 
)

void Image::updatePitch (  )  [protected]


Member Data Documentation

std::vector< ref<Image> > vl::Image::mMipmaps [protected]

int vl::Image::mWidth [protected]

int vl::Image::mHeight [protected]

int vl::Image::mDepth [protected]

int vl::Image::mPitch [protected]

int vl::Image::mByteAlign [protected]

bool vl::Image::mIsCubemap [protected]


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

Visualization Library v2010.06 Reference Documentation
Copyright 2005-2009 Michele Bosi. All rights reserved.
Updated on Tue Jun 1 00:57:18 2010.
Permission is granted to use this page to write and publish articles regarding Visualization Library.