nglImage Class Reference

#include <nglImage.h>

Inheritance diagram for nglImage:

List of all members.

---

Detailed Description

Generic multi-format image loader/exporter.

A nglImage object is a container for image buffer data (using various pixel formats), and also provides a plugin framework (the nglImageCodec codecs) to import from and export to various file formats. Codecs can load data from a stream, making progressive image loading possible. NGL is compiled with classic codecs (PNG, JPEG, TGA) as a default, but you can choose to load them at run time, add your own codec, and so on.

Public Member Functions
Life cycle
	nglImage (nglIStream *pInput, nglImageCodec *pCodec=NULL)
	nglImage (const nglPath &rPath, nglImageCodec *pCodec=NULL)
	nglImage (nglImageInfo &rInfo, bool Clone=true)
	nglImage (const nglImage &rImage)
virtual	~nglImage ()
Image description (info & data)
bool	GetInfo (nglImageInfo &rInfo) const
nglImageBufferFormat	GetBufferFormat () const
nglImagePixelFormat	GetPixelFormat () const
uint	GetWidth () const
uint	GetHeight () const
uint	GetBitDepth () const
uint	GetPixelSize () const
uint	GetBytesPerLine () const
char *	GetBuffer () const
nglImageCodec *	GetCodec () const
Export (save)
bool	Save (nglOStream *pOutput, nglImageCodec *pCodec)
bool	Save (const nglPath &rPath, nglImageCodec *pCodec)
User callbacks
virtual void	OnInfo (nglImageInfo &rInfo)
virtual void	OnData (float Completion)
virtual bool	OnError ()
Static Public Member Functions
Global codec registry
static bool	AddCodec (nglImageCodecInfo *pCodecInfo)
static bool	DelCodec (nglImageCodecInfo *pCodecInfo)
static nglImageCodec *	CreateCodec (int Index)
static nglImageCodec *	CreateCodec (const nglString &rName)
Protected Member Functions
void	OnCodecInfo (nglImageInfo &rInfo)
void	OnCodecData (float Completion)
bool	OnCodecError ()
virtual const nglChar *	OnError (uint &rError) const
Static Protected Member Functions
static void	Init ()
static void	Exit ()
Protected Attributes
nglImageInfo	mInfo
nglImageCodec *	mpCodec
bool	mOwnCodec
float	mCompletion
Friends
class	nglImageCodec

---

Constructor & Destructor Documentation

nglImage::nglImage (  nglIStream *  pInput, nglImageCodec *  pCodec = NULL )

Create an image from a stream Parameters: pInput  input stream (feeding the codec) pCodec  codec to use, NULL means auto-detection If auto-dection is used (pCodec set to NULL), nglImage will ask registered code to find their signature. If the signature check fails for all known codecs, codecs are asked to see if the stream name matches (actually check common file extensions). If a matching codec is still not present, an error will be set (use GetError()). If pCodec is a valid codec instance, it won't be managed, ie. it won't be destroy along the destruction of the nglImage object. When a matching codec is found, as soon as the header information is parsed, the OnInfo() callback will be invoked with valid data (image size, pixel format, etc). Then, OnData() and OnError() will be called respectively when more data was decoded or an error occured (interrupted stream or codec complaint for instance).

nglImage::nglImage (  const nglPath &  rPath, nglImageCodec *  pCodec = NULL )

Create an image from a file Parameters: rPath  input file pCodec  codec to use, NULL means auto-detection If auto-dection is used (pCodec set to NULL), nglImage will ask registered code to find their signature. If the signature check fails for all known codecs, codecs are asked to see if the stream name matches (actually check common file extensions). If a matching codec is still not present, an error will be set (use GetError()). If pCodec is a valid codec instance, it won't be managed, ie. it won't be destroy along the destruction of the nglImage object. To provide a compatible behaviour with the streaming constructor of nglImage, OnInfo() and OnData() callbacks will be called (once, in this order). OnError() might be invoked as well if an error occurs.

nglImage::nglImage (  nglImageInfo &  rInfo, bool  Clone = true )

Create an image from a user given description Parameters: rInfo  image description Clone  if true, clones the buffer data and manage it. If false, only keep a reference, but do not manage the buffer. Create a nglImage object from a comprehensive description. If Clone is true, nglImage makes a copy of rInfo.mpBuffer image data and owns it (ie. release this data memory when the nglImage object is destroyed). If Clone is false, nglImage only copies the rInfo.mpBuffer reference, and do not manage this memory (ie. it won't be released when the nglImage object is destroyed).

nglImage::nglImage (  const nglImage &  rImage  )

Create an image copy from another image Parameters: rImage  source image The object will hold an exact copy of the source image description and buffer data. The image buffer data is cloned (and thus managed).

virtual nglImage::~nglImage (   )  [virtual]

---

Member Function Documentation

static bool nglImage::AddCodec (  nglImageCodecInfo *  pCodecInfo  )  [static]

static nglImageCodec* nglImage::CreateCodec (  const nglString &  rName  )  [static]

static nglImageCodec* nglImage::CreateCodec (  int  Index  )  [static]

static bool nglImage::DelCodec (  nglImageCodecInfo *  pCodecInfo  )  [static]

static void nglImage::Exit (   )  [static, protected]

uint nglImage::GetBitDepth (   )  const

Pixel bit depth (sum of pixel components bit count). Returns 0 if the info is not available.

char* nglImage::GetBuffer (   )  const

Image buffer data. Returns NULL if the info is not available.

nglImageBufferFormat nglImage::GetBufferFormat (   )  const

Internal buffer format. Returns eImageFormatNone if the info is not available.

uint nglImage::GetBytesPerLine (   )  const

Pixel row allocation size in bytes (>= pixel size * image width). Returns 0 if the info is not available.

nglImageCodec* nglImage::GetCodec (   )  const

Fetch current codec Returns: current codec instance pointer If there is no codec in use (ie. import or export running), returns NULL.

uint nglImage::GetHeight (   )  const

Image height in pixels. Returns 0 if the info is not available.

bool nglImage::GetInfo (  nglImageInfo &  rInfo  )  const

Fetch image description Parameters: rInfo  holds image description data Returns: true if rInfo holds valid data, false otherwise Fill rInfo with the image description data.

nglImagePixelFormat nglImage::GetPixelFormat (   )  const

Internal pixel format. Returns eImagePixelNone if the info is not available.

uint nglImage::GetPixelSize (   )  const

Pixel allocation size in bytes (>= pixel bit depth). Returns 0 if the info is not available.

uint nglImage::GetWidth (   )  const

Image width in pixels. Returns 0 if the info is not available.

static void nglImage::Init (   )  [static, protected]

void nglImage::OnCodecData (  float  Completion  )  [protected]

The codec invoke this method whenever more data has been decoded to image buffer.

bool nglImage::OnCodecError (   )  [protected]

The codec invoke this method when an error occurs while encoding/decoding.

void nglImage::OnCodecInfo (  nglImageInfo &  rInfo  )  [protected]

The codec invoke this method as soon as all the image metadata is available.

virtual void nglImage::OnData (  float  Completion  )  [virtual]

More data decoded Parameters: Completion  completion status, from 0 (nothing) to 1 (full image decoded) This method is called when a part of the source image data is decoded into the buffer.

virtual const nglChar* nglImage::OnError (  uint &  rError  )  const [protected, virtual]

Parameters: rError  error code Returns: error message, or NULL if rError is out of bounds When the user invokes GetErrorStr() on an object, the OnError() callback is called with the given error code and should return the corresponding message. When several classes have different string error tables in the same hierarchy, the latest derivation's OnError() is called : it should then use a parent-first search. Example : const nglChar** ChildErrorTable = {_T("no error"), _T("Bad luck"), NULL}; const nglChar* Child::OnError (uint& rError) const { return FetchError(ChildErrorTable, Parent::OnError(rError), rError); } Implements nglError.

virtual bool nglImage::OnError (   )  [virtual]

Returns: CanContinue Try to continue codec job when true, else abort This method is called whenever an error occurs into the codec. User can elect to continue (more errors can follow) when returning true or abort right now by returning false. FIXME: should retrieve error with GetCodec()->GetError()

virtual void nglImage::OnInfo (  nglImageInfo &  rInfo  )  [virtual]

Image description available Parameters: rInfo  image description This method is called as soon as the image description is available. From this point, image size is known and buffer data is properly allocated.

bool nglImage::Save (  const nglPath &  rPath, nglImageCodec *  pCodec )

bool nglImage::Save (  nglOStream *  pOutput, nglImageCodec *  pCodec )

---

Friends And Related Function Documentation

friend class nglImageCodec [friend]

---

Member Data Documentation

float nglImage::mCompletion [protected]

In between 0.0 and 1.0.

nglImageInfo nglImage::mInfo [protected]

The image info.

bool nglImage::mOwnCodec [protected]

false if the codec is supplied by user

nglImageCodec* nglImage::mpCodec [protected]

The codec currently in use to load or save the image.

---