CPGFImage Class Reference

PGF image class. More...

#include <PGFimage.h>

Public Member Functions
	CPGFImage ()
virtual	~CPGFImage ()
RGBTRIPLE	Background () const
BYTE	BPP () const
BYTE	ChannelDepth () const
UINT32	ChannelHeight (int c=0) const
BYTE	Channels () const
UINT32	ChannelWidth (int c=0) const
void	Close ()
void	Destroy ()
void	GetBitmap (int pitch, UINT8 buff, BYTE bpp, int channelMap[]=NULL, CallbackPtr cb=NULL, void data=NULL) const THROW_
DataT *	GetChannel (int c=0)
const RGBQUAD *	GetColorTable () const
void	GetColorTable (UINT32 iFirstColor, UINT32 nColors, RGBQUAD *prgbColors) const THROW_
UINT32	GetEncodedHeaderLength () const
UINT32	GetEncodedLevelLength (int level) const
const PGFHeader *	GetHeader () const
UINT32	GetMaxValue () const
const UINT8 *	GetUserData (UINT32 &size) const
void	GetYUV (int pitch, DataT buff, BYTE bpp, int channelMap[]=NULL, CallbackPtr cb=NULL, void data=NULL) const THROW_
UINT32	Height (int level=0) const
void	ImportBitmap (int pitch, UINT8 buff, BYTE bpp, int channelMap[]=NULL, CallbackPtr cb=NULL, void data=NULL) THROW_
void	ImportYUV (int pitch, DataT buff, BYTE bpp, int channelMap[]=NULL, CallbackPtr cb=NULL, void data=NULL) THROW_
BYTE	Level () const
BYTE	Levels () const
BYTE	Mode () const
void	Open (CPGFStream *stream) THROW_
BYTE	Quality () const
void	Read (int level=0, CallbackPtr cb=NULL, void *data=NULL) THROW_
UINT32	ReadEncodedData (int level, UINT8 *target, UINT32 targetLen) const THROW_
UINT32	ReadEncodedHeader (UINT8 *target, UINT32 targetLen) const THROW_
void	ReadPreview () THROW_
void	Reconstruct () THROW_
void	ResetStreamPos () THROW_
bool	ROIisSupported () const
void	SetBackground (BYTE red, BYTE green, BYTE blue)
void	SetBackground (const RGBTRIPLE *bg)
void	SetChannel (DataT *channel, int c=0)
void	SetColorTable (UINT32 iFirstColor, UINT32 nColors, const RGBQUAD *prgbColors) THROW_
void	SetHeader (const PGFHeader &header, BYTE flags=0, UINT8 *userData=0, UINT32 userDataLength=0) THROW_
void	SetMaxValue (UINT32 maxValue)
void	SetRefreshCallback (RefreshCB callback, void *arg)
BYTE	UsedBitsPerChannel () const
BYTE	Version () const
UINT32	Width (int level=0) const
void	Write (CPGFStream stream, int levels=0, CallbackPtr cb=NULL, UINT32 nWrittenBytes=NULL, void *data=NULL) THROW_
Static Public Member Functions
static BYTE	ComputeLevels (UINT32 width, UINT32 height)
static bool	ImportIsSupported (BYTE mode)
static UINT32	LevelHeight (UINT32 height, int level)
static UINT32	LevelWidth (UINT32 width, int level)
Protected Attributes
DataT *	m_channel [MaxChannels]
BYTE	m_currentLevel
CDecoder *	m_decoder
bool	m_downsample
PGFHeader	m_header
UINT32	m_height [MaxChannels]
UINT32 *	m_levelLength
PGFPostHeader	m_postHeader
PGFPreHeader	m_preHeader
BYTE	m_quant
UINT32	m_width [MaxChannels]
CWaveletTransform *	m_wtChannel [MaxChannels]

Detailed Description

PGF image class.

Author:: C. Stamm, R. Spuler

Definition at line 36 of file PGFimage.h.

Constructor & Destructor Documentation

CPGFImage::CPGFImage ( )

Standard constructor: It is used to create a PGF instance for opening and reading.

Definition at line 50 of file PGFimage.cpp.

CPGFImage::~CPGFImage ( ) [virtual]

Destructor: Destroy internal data structures.

Definition at line 76 of file PGFimage.cpp.

Member Function Documentation

RGBTRIPLE CPGFImage::Background ( ) const [inline]

Return the background color of an RGB image with transparency channel.

Returns:: Background color in RGB

Definition at line 248 of file PGFimage.h.

BYTE CPGFImage::BPP ( ) const [inline]

Return the number of bits per pixel.

Valid values can be 1, 8, 12, 16, 24, 31, 32, 48, 64.

Returns:: Number of bits per pixel.

Definition at line 389 of file PGFimage.h.

BYTE CPGFImage::ChannelDepth ( ) const [inline]

Return bits per channel.

Returns:: Bits per channel

Definition at line 338 of file PGFimage.h.

UINT32 CPGFImage::ChannelHeight ( int c = 0 ) const [inline]

Return current image height of given channel in pixels.

The returned height depends on the levels read so far and on ROI.

Parameters:

c

A channel index

Returns:: Channel height in pixels

Definition at line 333 of file PGFimage.h.

BYTE CPGFImage::Channels ( ) const [inline]

Return the number of image channels.

An image of type RGB contains 3 image channels (B, G, R).

Returns:: Number of image channels

Definition at line 376 of file PGFimage.h.

UINT32 CPGFImage::ChannelWidth ( int c = 0 ) const [inline]

Return current image width of given channel in pixels.

The returned width depends on the levels read so far and on ROI.

Parameters:

c

A channel index

Returns:: Channel width in pixels

Definition at line 326 of file PGFimage.h.

void CPGFImage::Close ( )

Close PGF image after opening and reading.

Destructor calls this method during destruction.

Definition at line 97 of file PGFimage.cpp.

BYTE CPGFImage::ComputeLevels	(	UINT32	width,
		UINT32	height
	)			`[static]`

Compute and return number of levels.

During PGF::Write the return value of this method is used in case the parameter levels is not a positive value. A PGF image is structered in levels, numbered between 0 and Levels() - 1. Each level can be seen as a single image, containing the same content as all other levels, but in a different size (width, height). The image size at level i is double the size (width, height) of the image at level i+1. The image at level 0 contains the original size.

Parameters:

	width	Original image width
	height	Original image height

Returns:: Number of PGF levels

Definition at line 787 of file PGFimage.cpp.

void CPGFImage::Destroy ( )

Destroy internal data structures.

Destructor calls this method during destruction.

Definition at line 83 of file PGFimage.cpp.

void CPGFImage::GetBitmap	(	int	pitch,
		UINT8 *	buff,
		BYTE	bpp,
		int	channelMap[] = `NULL`,
		CallbackPtr	cb = `NULL`,
		void *	data = `NULL`
	)			const

Get image data in interleaved format: (ordering of RGB data is BGR[A]) Upsampling, YUV to RGB transform and interleaving are done here to reduce the number of passes over the data.

The absolute value of pitch is the number of bytes of an image row of the given image buffer. If pitch is negative, then the image buffer must point to the last row of a bottom-up image (first byte on last row). if pitch is positive, then the image buffer must point to the first row of a top-down image (first byte). The sequence of output channels in the output image buffer does not need to be the same as provided by PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF provides a channel sequence BGR in RGB color mode. If your provided image buffer expects a channel sequence ARGB, then the channelMap looks like { 3, 2, 1 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of PGF channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each copied buffer row. If cb returns true, then it stops proceeding.
	data	Data Pointer to C++ class container to host callback procedure.

Definition at line 1414 of file PGFimage.cpp.

DataT* CPGFImage::GetChannel ( int c = 0 ) [inline]

Return an internal YUV image channel.

Parameters:

c

A channel index

Returns:: An internal YUV image channel

Definition at line 254 of file PGFimage.h.

const RGBQUAD* CPGFImage::GetColorTable ( ) const [inline]

Returns:: Address of color table

Definition at line 267 of file PGFimage.h.

void CPGFImage::GetColorTable	(	UINT32	iFirstColor,
		UINT32	nColors,
		RGBQUAD *	prgbColors
	)			const

Retrieves red, green, blue (RGB) color values from a range of entries in the palette of the DIB section.

It might throw an IOException.

Parameters:

	iFirstColor	The color table index of the first entry to retrieve.
	nColors	The number of color table entries to retrieve.
	prgbColors	A pointer to the array of RGBQUAD structures to retrieve the color table entries.

Definition at line 1006 of file PGFimage.cpp.

UINT32 CPGFImage::GetEncodedHeaderLength ( ) const

Return the length of all encoded headers in bytes.

Returns:: The length of all encoded headers in bytes

Definition at line 504 of file PGFimage.cpp.

UINT32 CPGFImage::GetEncodedLevelLength ( int level ) const [inline]

Return the length of an encoded PGF level in bytes.

Parameters:

level

The image level

Returns:: The length of a PGF level in bytes

Definition at line 295 of file PGFimage.h.

const PGFHeader* CPGFImage::GetHeader ( ) const [inline]

Return the PGF header structure.

Returns:: A PGF header structure

Definition at line 272 of file PGFimage.h.

UINT32 CPGFImage::GetMaxValue ( ) const [inline]

Get maximum intensity value for image modes with more than eight bits per channel.

Don't call this method before the PGF header has been read.

Returns:: The maximum intensity value.

Definition at line 278 of file PGFimage.h.

const UINT8 * CPGFImage::GetUserData ( UINT32 & size ) const

Return user data and size of user data.

Parameters:

size

[out] Size of user data in bytes.

Returns:: A pointer to user data or NULL if there is no user data.

Definition at line 235 of file PGFimage.cpp.

void CPGFImage::GetYUV	(	int	pitch,
		DataT *	buff,
		BYTE	bpp,
		int	channelMap[] = `NULL`,
		CallbackPtr	cb = `NULL`,
		void *	data = `NULL`
	)			const

Get YUV image data in interleaved format: (ordering is YUV[A]) The absolute value of pitch is the number of bytes of an image row of the given image buffer.

If pitch is negative, then the image buffer must point to the last row of a bottom-up image (first byte on last row). if pitch is positive, then the image buffer must point to the first row of a top-down image (first byte). The sequence of output channels in the output image buffer does not need to be the same as provided by PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF provides a channel sequence BGR in RGB color mode. If your provided image buffer expects a channel sequence VUY, then the channelMap looks like { 2, 1, 0 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of PGF channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each copied buffer row. If cb returns true, then it stops proceeding.
	data	Data Pointer to C++ class container to host callback procedure.

If pitch is negative, then the image buffer must point to the last row of a bottom-up image (first byte on last row). if pitch is positive, then the image buffer must point to the first row of a top-down image (first byte). The sequence of output channels in the output image buffer does not need to be the same as provided by PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF provides a channel sequence BGR in RGB color mode. If your provided image buffer expects a channel sequence VUY, then the channelMap looks like { 2, 1, 0 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of PGF channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each copied buffer row. If cb returns true, then it stops proceeding.

Definition at line 2116 of file PGFimage.cpp.

UINT32 CPGFImage::Height ( int level = 0 ) const [inline]

Return image height of channel 0 at given level in pixels.

The returned height is independent of any Read-operations and ROI.

Parameters:

level

A level

Returns:: Image level height in pixels

Definition at line 352 of file PGFimage.h.

void CPGFImage::ImportBitmap	(	int	pitch,
		UINT8 *	buff,
		BYTE	bpp,
		int	channelMap[] = `NULL`,
		CallbackPtr	cb = `NULL`,
		void *	data = `NULL`
	)

Import an image from a specified image buffer.

This method is usually called before Write(...) and after SetHeader(...). The absolute value of pitch is the number of bytes of an image row. If pitch is negative, then buff points to the last row of a bottom-up image (first byte on last row). If pitch is positive, then buff points to the first row of a top-down image (first byte). The sequence of input channels in the input image buffer does not need to be the same as expected from PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF expects in RGB color mode a channel sequence BGR. If your provided image buffer contains a channel sequence ARGB, then the channelMap looks like { 3, 2, 1 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of input channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each imported buffer row. If cb returns true, then it stops proceeding.
	data	Data Pointer to C++ class container to host callback procedure.

Definition at line 714 of file PGFimage.cpp.

bool CPGFImage::ImportIsSupported ( BYTE mode ) [static]

Check for valid import image mode.

Parameters:

mode

Image mode

Returns:: True if an image of given mode can be imported with ImportBitmap(...)

Definition at line 961 of file PGFimage.cpp.

void CPGFImage::ImportYUV	(	int	pitch,
		DataT *	buff,
		BYTE	bpp,
		int	channelMap[] = `NULL`,
		CallbackPtr	cb = `NULL`,
		void *	data = `NULL`
	)

Import a YUV image from a specified image buffer.

The absolute value of pitch is the number of bytes of an image row. If pitch is negative, then buff points to the last row of a bottom-up image (first byte on last row). If pitch is positive, then buff points to the first row of a top-down image (first byte). The sequence of input channels in the input image buffer does not need to be the same as expected from PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF expects in RGB color mode a channel sequence BGR. If your provided image buffer contains a channel sequence VUY, then the channelMap looks like { 2, 1, 0 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of input channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each imported buffer row. If cb returns true, then it stops proceeding.
	data	Data Pointer to C++ class container to host callback procedure.

The absolute value of pitch is the number of bytes of an image row. If pitch is negative, then buff points to the last row of a bottom-up image (first byte on last row). If pitch is positive, then buff points to the first row of a top-down image (first byte). The sequence of input channels in the input image buffer does not need to be the same as expected from PGF. In case of different sequences you have to provide a channelMap of size of expected channels (depending on image mode). For example, PGF expects in RGB color mode a channel sequence BGR. If your provided image buffer contains a channel sequence VUY, then the channelMap looks like { 2, 1, 0 }. It might throw an IOException.

Parameters:

	pitch	The number of bytes of a row of the image buffer.
	buff	An image buffer.
	bpp	The number of bits per pixel used in image buffer.
	channelMap	A integer array containing the mapping of input channel ordering to expected channel ordering.
	cb	A pointer to a callback procedure. The procedure is called after each imported buffer row. If cb returns true, then it stops proceeding.

Definition at line 2229 of file PGFimage.cpp.

BYTE CPGFImage::Level ( ) const [inline]

Return current image level.

Since Read(...) can be used to read each image level separately, it is helpful to know the current level. The current level immediately after Open(...) is Levels().

Returns:: Current image level

Definition at line 359 of file PGFimage.h.

static UINT32 CPGFImage::LevelHeight	(	UINT32	height,
		int	level
	)			`[inline, static]`

Compute and return image height at given level.

Parameters:

	height	Original image height (at level 0)
	level	An image level

Returns:: Image level height in pixels

Definition at line 420 of file PGFimage.h.

BYTE CPGFImage::Levels ( ) const [inline]

Return the number of image levels.

Returns:: Number of image levels

Definition at line 364 of file PGFimage.h.

static UINT32 CPGFImage::LevelWidth	(	UINT32	width,
		int	level
	)			`[inline, static]`

Compute and return image width at given level.

Parameters:

	width	Original image width (at level 0)
	level	An image level

Returns:: Image level width in pixels

Definition at line 413 of file PGFimage.h.

BYTE CPGFImage::Mode ( ) const [inline]

Return the image mode.

An image mode is a predefined constant value (see also PGFtypes.h) compatible with Adobe Photoshop. It represents an image type and format.

Returns:: Image mode

Definition at line 383 of file PGFimage.h.

void CPGFImage::Open ( CPGFStream * stream )

Open a PGF image at current stream position: read pre-header, header, and ckeck image type.

Precondition: The stream has been opened for reading. It might throw an IOException.

Parameters:

stream

A PGF stream

Definition at line 106 of file PGFimage.cpp.

BYTE CPGFImage::Quality ( ) const [inline]

Return the PGF quality.

The quality is inbetween 0 and MaxQuality. PGF quality 0 means lossless quality.

Returns:: PGF quality

Definition at line 370 of file PGFimage.h.

void CPGFImage::Read	(	int	level = `0`,
		CallbackPtr	cb = `NULL`,
		void *	data = `NULL`
	)

Read and decode some levels of a PGF image at current stream position.

A PGF image is structered in levels, numbered between 0 and Levels() - 1. Each level can be seen as a single image, containing the same content as all other levels, but in a different size (width, height). The image size at level i is double the size (width, height) of the image at level i+1. The image at level 0 contains the original size. Precondition: The PGF image has been opened with a call of Open(...). It might throw an IOException.

Parameters:

	level	The image level of the resulting image in the internal image buffer.
	cb	A pointer to a callback procedure. The procedure is called after reading a single level. If cb returns true, then it stops proceeding.
	data	Data Pointer to C++ class container to host callback procedure.

Definition at line 252 of file PGFimage.cpp.

UINT32 CPGFImage::ReadEncodedData	(	int	level,
		UINT8 *	target,
		UINT32	targetLen
	)			const

Reads the data of an encoded PGF level and copies it to a target buffer without decoding.

Precondition: The PGF image has been opened with a call of Open(...). It might throw an IOException.

Parameters:

	level	The image level
	target	The target buffer
	targetLen	The length of the target buffer in bytes

Returns:: The number of bytes copied to the target buffer

Definition at line 550 of file PGFimage.cpp.

UINT32 CPGFImage::ReadEncodedHeader	(	UINT8 *	target,
		UINT32	targetLen
	)			const

Reads the encoded PGF headers and copies it to a target buffer.

Precondition: The PGF image has been opened with a call of Open(...). It might throw an IOException.

Parameters:

	target	The target buffer
	targetLen	The length of the target buffer in bytes

Returns:: The number of bytes copied to the target buffer

Definition at line 516 of file PGFimage.cpp.

void CPGFImage::ReadPreview ( ) [inline]

Read and decode smallest level of a PGF image at current stream position.

For details, please refert to Read(...) Precondition: The PGF image has been opened with a call of Open(...). It might throw an IOException.

Definition at line 86 of file PGFimage.h.

void CPGFImage::Reconstruct ( )

After you've written a PGF image, you can call this method followed by GetBitmap/GetYUV to get a quick reconstruction (coded -> decoded image).

Definition at line 326 of file PGFimage.cpp.

void CPGFImage::ResetStreamPos ( )

Reset stream position to beginning of PGF pre header.

Definition at line 536 of file PGFimage.cpp.

bool CPGFImage::ROIisSupported ( ) const [inline]

Return true if the pgf image supports Region Of Interest (ROI).

Returns:: true if the pgf image supports ROI.

Definition at line 394 of file PGFimage.h.

void CPGFImage::SetBackground	(	BYTE	red,
		BYTE	green,
		BYTE	blue
	)			`[inline]`

Set background of an RGB image with transparency channel.

Parameters:

	red	A red value (0..255)
	green	A green value (0..255)
	blue	A blue value (0..255)

Definition at line 200 of file PGFimage.h.

void CPGFImage::SetBackground ( const RGBTRIPLE * bg )

Set background of an RGB image with transparency channel or reset to default background.

Parameters:

bg

A pointer to a background color or NULL (reset to default background)

Definition at line 580 of file PGFimage.cpp.

void CPGFImage::SetChannel	(	DataT *	channel,
		int	c = `0`
	)			`[inline]`

Set internal PGF image buffer channel.

Parameters:

	channel	A YUV data channel
	c	A channel index

Definition at line 206 of file PGFimage.h.

void CPGFImage::SetColorTable	(	UINT32	iFirstColor,
		UINT32	nColors,
		const RGBQUAD *	prgbColors
	)

Sets the red, green, blue (RGB) color values for a range of entries in the palette (clut).

It might throw an IOException.

Parameters:

	iFirstColor	The color table index of the first entry to set.
	nColors	The number of color table entries to set.
	prgbColors	A pointer to the array of RGBQUAD structures to set the color table entries.

Definition at line 1020 of file PGFimage.cpp.

void CPGFImage::SetHeader	(	const PGFHeader &	header,
		BYTE	flags = `0`,
		UINT8 *	userData = `0`,
		UINT32	userDataLength = `0`
	)

Set PGF header and user data.

Precondition: The PGF image has been closed with Close(...) or never opened with Open(...). It might throw an IOException.

Parameters:

	header	A valid and already filled in PGF header structure
	flags	A combination of additional version flags
	userData	A user-defined memory block
	userDataLength	The size of user-defined memory block in bytes

Definition at line 600 of file PGFimage.cpp.

void CPGFImage::SetMaxValue ( UINT32 maxValue )

Set maximum intensity value for image modes with more than eight bits per channel.

Don't call this method before SetHeader.

Parameters:

maxValue

The maximum intensity value.

Definition at line 663 of file PGFimage.cpp.

void CPGFImage::SetRefreshCallback	(	RefreshCB	callback,
		void *	arg
	)			`[inline]`

Set refresh callback procedure and its parameter.

The refresh callback is called during Read(...) after each level read.

Parameters:

	callback	A refresh callback procedure
	arg	A parameter of the refresh callback procedure

Definition at line 235 of file PGFimage.h.

BYTE CPGFImage::UsedBitsPerChannel ( ) const

Returns number of used bits per input/output image channel.

Precondition: header must be initialized.

Returns:: number of used bits per input/output image channel.

Definition at line 679 of file PGFimage.cpp.

BYTE CPGFImage::Version ( ) const

Returns highest supported version.

Definition at line 691 of file PGFimage.cpp.

UINT32 CPGFImage::Width ( int level = 0 ) const [inline]

Return image width of channel 0 at given level in pixels.

The returned width is independent of any Read-operations and ROI.

Parameters:

level

A level

Returns:: Image level width in pixels

Definition at line 345 of file PGFimage.h.

void CPGFImage::Write	(	CPGFStream *	stream,
		int	levels = `0`,
		CallbackPtr	cb = `NULL`,
		UINT32 *	nWrittenBytes = `NULL`,
		void *	data = `NULL`
	)

Encode and write a PGF image at current stream position.

A PGF image is structered in levels, numbered between 0 and Levels() - 1. Each level can be seen as a single image, containing the same content as all other levels, but in a different size (width, height). The image size at level i is double the size (width, height) of the image at level i+1. The image at level 0 contains the original size. Precondition: the PGF image contains a valid header (see also SetHeader(...)). It might throw an IOException.

Parameters:

	stream	A PGF stream
	levels	The positive number of levels used in layering or 0 meaning a useful number of levels is computed.
	cb	A pointer to a callback procedure. The procedure is called after reading a single level. If cb returns true, then it stops proceeding.
	nWrittenBytes	[in-out] The number of bytes written into stream are added to the input value.
	data	Data Pointer to C++ class container to host callback procedure.