Archon::Utilities::Image Struct Reference

A general purpose in-memory bitmap image (rectangular pixel array) with value semantics as well as copy-on-write semantics to improve performance. More...

#include <archon/util/image.H>

Collaboration diagram for Archon::Utilities::Image:

[legend]List of all members.


Public Types
enum	ComponentSpecifier { components_l = 1, components_la = 2, components_rgb = 3, components_rgba = 4 }
Public Member Functions
	operator bool () const
	Returns true unless the image is a null image.
	Image ()
	Create a special null image.
	Image (unsigned width, unsigned height, ComponentSpecifier components=components_rgba, unsigned bitsPerComponent=8, string comment="")
	Create an image with an uninitialized pixel buffer.
unsigned	getWidth () const
unsigned	getHeight () const
unsigned	getBitsPerComponent () const
unsigned	getCharsPerPixel () const
unsigned	getCharsPerRow () const
unsigned	getMaxComponentValue () const
ComponentSpecifier	getComponentSpecifier () const
string	getComment () const
	Fetch the image comment.
void	setComment (string c)
	Set a new image comment.
const char *	getPixelBuffer () const
char *	getPixelBuffer ()
const char *	getPixelPtr (int x, int y) const
char *	getPixelPtr (int x, int y)
void	getPixel (int x, int y, unsigned &l) const
void	setPixel (int x, int y, unsigned l)
void	getPixel (int x, int y, unsigned &l, unsigned &a) const
void	setPixel (int x, int y, unsigned l, unsigned a)
void	getPixel (int x, int y, unsigned &r, unsigned &g, unsigned &b) const
void	setPixel (int x, int y, unsigned r, unsigned g, unsigned b)
void	getPixel (int x, int y, unsigned &r, unsigned &g, unsigned &b, unsigned &a) const
void	setPixel (int x, int y, unsigned r, unsigned g, unsigned b, unsigned a)
void	getPixel (int x, int y, double &l) const
void	setPixel (int x, int y, double l)
void	getPixel (int x, int y, double &l, double &a) const
void	setPixel (int x, int y, double l, double a)
void	getPixel (int x, int y, double &r, double &g, double &b) const
void	setPixel (int x, int y, double r, double g, double b)
void	getPixel (int x, int y, double &r, double &g, double &b, double &a) const
void	setPixel (int x, int y, double r, double g, double b, double a)
void	swap (Image &i)
	Efficient swapping that avoids access to the referenced object, in particular, its reference count.
	Image (Ref< Stream::Reader > r, string sourceName, string formatSpecifier="", Logger l=Logger::get(), const Context c=0) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException)
	Load an image from the specified reader.
	Image (string filePath, string formatSpecifier="", Logger l=Logger::get(), const Context c=0) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException)
	Load an image from the specified file.
void	load (Ref< Stream::Reader > r, string sourceName, string formatSpecifier="", ProgressTracker t=0, Logger l=Logger::get(), const Context *c=0) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException)
	Load an image from the specified reader.
void	load (string filePath, string formatSpecifier="", ProgressTracker t=0, Logger l=Logger::get(), const Context *c=0) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException)
	Load in image from the specified file.
void	save (Ref< Stream::Writer > w, string targetName, string formatSpecifier="", ProgressTracker t=0, Logger l=Logger::get(), const Context *c=0) const throw (UnknownFormatException, IOException, UnexpectedException)
	If an empty format specifier is passed the format is determined by the suffix of the target name.
void	save (string filePath, string formatSpecifier="", ProgressTracker t=0, Logger l=Logger::get(), const Context *c=0) const throw (UnknownFormatException, IOException, UnexpectedException)
	If an empty format specifier is passed the format is determined by the suffix of the file name.
Static Public Attributes
static const string	PNG = "png"
	Specifier for PNG format.
static const string	TIFF = "tiff"
	Specifier for TIFF format.
static const string	PNM = "pnm"
	Specifier for PNM format.
static const string	JPEG = "jpeg"
	Specifier for JPEG format.
static const string	GIF = "gif"
	Specifier for GIF format.
Classes
struct	Context
	Holds the list of known image formats. More...
struct	Format
	This class represents one single image format. More...
struct	ImageException
struct	InvalidFormatException
	The image file contents is corrupt or of a different format than the one selected. More...
struct	ProgressTracker
struct	Rep
struct	UnknownFormatException
	Image format could not be detected. More...

Detailed Description

A general purpose in-memory bitmap image (rectangular pixel array) with value semantics as well as copy-on-write semantics to improve performance.

The class comes with a comprehensive set of manipulation functions and is able to read and write image files in various well-known image file formats such as PNG, JPEG and GIF.

This class offers direct access to the memory buffer holding the pixels. Pixels are stored in row major order starting with the left most pixel of the bottom most row. Pixel coordinates (x,y) should likewise be understood such that (0,0) is at the lower left corner of the image.

Each pixel consists of 1 or more chars. Each new pixel always starts on a char boundary (i.e. pixels are char aligned.)

There are two parameters of the Image that determine just how many chars are used per pixel: The number of components per pixel and the number of bits per component.

A pixel consistst of 1, 2, 3 or 4 components (or channels). The specific interpretation of the components is a function of the number as follows:

   Number of
   components   Interpretation (in given order)
  -----------------------------------------------
   1            L      Luminance
   2            LA     Luminance, alpha
   3            RGB    Red, green, blue
   4            RGBA   Red, green, blue, alpha

Each component (or channel) consists of 1, 2, 4, 8, or 16 bits.

Assuming that chars are 8 bit wide we could have up to 8 chars per pixel. Assuming further the the target system is a little-endian system such as the Intel x86 family, we get the following pixel layouts:

                  Chars per               Address offset
  Configuration   pixel            3        2        1        0
 ------------------------------------------------------------------
  L(1)              1                                     0000000l
  L(2)              1                                     000000ll
  L(4)              1                                     0000llll
  L(8)              1                                     llllllll
  L(16)             2                            LLLLLLLL llllllll

  LA(1)             1                                     000000al
  LA(2)             1                                     0000aall
  LA(4)             1                                     aaaallll
  LA(8)             2                            aaaaaaaa llllllll
  LA(16)            4          AAAAAAAA aaaaaaaa LLLLLLLL llllllll

  RGB(1)            1                                     00000bgr
  RGB(2)            1                                     00bbggrr
  RGB(4)            2                            0000bbbb ggggrrrr
  RGB(8)            3                   bbbbbbbb gggggggg rrrrrrrr
  RGB(16)           6      ... GGGGGGGG gggggggg RRRRRRRR rrrrrrrr

  RGBA(1)           1                                     0000abgr
  RGBA(2)           1                                     aabbggrr
  RGBA(4)           2                            aaaabbbb ggggrrrr
  RGBA(8)           4          aaaaaaaa bbbbbbbb gggggggg rrrrrrrr
  RGBA(16)          8      ... GGGGGGGG gggggggg RRRRRRRR rrrrrrrr

Where capital letters indicate MBS (most significant byte.) On a big-endian system such as the PPC family seen in Macs we would for instance get this instead:

                  Chars per               Address offset
  Configuration   pixel            3        2        1        0
 ------------------------------------------------------------------
  LA(16)            4          aaaaaaaa AAAAAAAA llllllll LLLLLLLL

So please note that the exact byte ordering of the pixel buffer used in this class is not entirely fixed. It depends on the endianness of the platform.

Todo:: Revisit all file format I/O for supporting bits-per-char greater than 8.

Todo:: Considder adding a "Pixel operator(x, y)" where Pixel holds a pointer to the pixel byte(s).

Then protect the copy constructor and the copy assignmen operator so the application cannot store the returned object longer than the image. On the Pixel class should be a number of conversion operators and assignment operators.

Todo:: Add fill and clear member functions.

Definition at line 143 of file image.H.

Member Enumeration Documentation

enum Archon::Utilities::Image::ComponentSpecifier

Enumerator:

components_l Luminance (one channel).

components_la Luminance and alpha (two channels).

components_rgb Red, green and blue (three channels).

components_rgba Red, green, blue and alpha (four channels).

Definition at line 156 of file image.H.

Constructor & Destructor Documentation

Archon::Utilities::Image::Image ( ) [inline]

Create a special null image.
A null image has no pixel buffer nor any attributes and thus, it requires a minimum of storage.

Note:
Most operations are illegal on a null image.

Definition at line 171 of file image.H.

Archon::Utilities::Image::Image ( Ref< Stream::Reader > r,

string sourceName,

string formatSpecifier = "",

Logger * l = Logger::get(),

const Context * c = 0

) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException) [inline]

Load an image from the specified reader.
If the format specifier is empty, an attempt to auto-detect the format will be done. First the initial part of the stream is examined against the various format signatures. If this yields no unique result then the suffix of the source name (if any) is used to try to dertermine the format.

Parameters:

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during parsing of the stream contents.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the initial image contents nor from the suffix of the source name.

InvalidFormatException When a fatal error occurs during parsing of the stream contents.

Definition at line 452 of file image.H.

Archon::Utilities::Image::Image ( string filePath,

string formatSpecifier = "",

Logger * l = Logger::get(),

const Context * c = 0

) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException) [inline, explicit]

Load an image from the specified file.
If the format specifier is empty, an attempt to auto-detect the format will be done. First the initial part of the stream is examined against the various format signatures. If this yields no unique result then the suffix of the source name (if any) is used to try to dertermine the format.

Parameters:

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during parsing of the file contents.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the initial image contents nor from the suffix of the file name.

InvalidFormatException When a fatal error occurs during parsing of the file contents.

Definition at line 482 of file image.H.
References Archon::Utilities::Stream::makeFileReader(), and Archon::Utilities::File::nameOf().

Member Function Documentation

string Archon::Utilities::Image::getComment ( ) const [inline]

Fetch the image comment.

Returns:
The comment in UTF-8 encoding.

Definition at line 195 of file image.H.

void Archon::Utilities::Image::load ( string filePath,

string formatSpecifier = "",

ProgressTracker * t = 0,

Logger * l = Logger::get(),

const Context * c = 0

) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException) [inline]

Load in image from the specified file.
The new image contents replaces the old contents.

Parameters:

filePath The path name of a file containg an image in one of the supported formats.

t Pass an instance of ProgressTracker if you need progress indications. This is needed if you want to display a progress bar or if you need to display partially loaded images.

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during parsing of the file contents.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the initial image contents nor from the suffix of the file name.

InvalidFormatException When a fatal error occurs during parsing of the file contents.

Definition at line 553 of file image.H.
References Archon::Utilities::Stream::makeFileReader(), and Archon::Utilities::File::nameOf().

void Archon::Utilities::Image::load ( Ref< Stream::Reader > r,

string sourceName,

string formatSpecifier = "",

ProgressTracker * t = 0,

Logger * l = Logger::get(),

const Context * c = 0

) throw (UnknownFormatException, InvalidFormatException, IOException, UnexpectedException) [inline]

Load an image from the specified reader.
The new image contents replaces the old contents.

Parameters:

r The stream that will provide the image data.

sourceName A nmemonic which will be used to identify the stream in log and exception messages.

t Pass an instance of ProgressTracker if you need progress indications. This is needed if you want to display a progress bar or if you need to display partially loaded images.

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during parsing of the stream contents.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the initial image contents nor from the suffix of the source name.

InvalidFormatException When a fatal error occurs during parsing of the stream contents.

Definition at line 518 of file image.H.

void Archon::Utilities::Image::save ( string filePath,

string formatSpecifier = "",

ProgressTracker * t = 0,

Logger * l = Logger::get(),

const Context * c = 0

) const throw (UnknownFormatException, IOException, UnexpectedException) [inline]

If an empty format specifier is passed the format is determined by the suffix of the file name.

Parameters:

t Pass an instance of ProgressTracker if you need progress indications. This is needed if eg. you want to display a progress bar.

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during serialization of the image.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the suffix of the file name.

Definition at line 609 of file image.H.
References Archon::Utilities::Stream::makeFileWriter(), and Archon::Utilities::File::nameOf().

void Archon::Utilities::Image::save ( Ref< Stream::Writer > w,

string targetName,

string formatSpecifier = "",

ProgressTracker * t = 0,

Logger * l = Logger::get(),

const Context * c = 0

) const throw (UnknownFormatException, IOException, UnexpectedException) [inline]

If an empty format specifier is passed the format is determined by the suffix of the target name.

Parameters:

t Pass an instance of ProgressTracker if you need progress indications. This is needed if eg. you want to display a progress bar.

l Pass 0 to disable logging. Otherwise this logger will be used to report warnings and non-fatal errors during serialization of the image.

c Pass 0 if you want to use the default context.

Exceptions:

UnknownFormatException If an empty formatSpecifier is passed and the format could not be detected from the suffix of the target name.

Definition at line 581 of file image.H.
Referenced by Archon::Raytracer::Engine::render().

void Archon::Utilities::Image::setComment ( string c ) [inline]

Set a new image comment.

Parameters:

c The comment in UTF-8 encoding.

Definition at line 202 of file image.H.
References Archon::Utilities::MutaRef< T >::mutate().
Referenced by Archon::Utilities::FormatLibjpeg::load().

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

archon/util/image.H
archon/util/image.C

Generated on Sun Jul 30 22:57:25 2006 for Archon by

1.4.4

Archon::Utilities::Image Struct Reference

Public Types

Public Member Functions

Static Public Attributes

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation