#include <Image.h>

Inheritance diagram for PLGraphics::Image:

Public Member Functions
PLGRAPHICS_API	Image ()
	Constructor.
PLGRAPHICS_API	Image (const Image &cSource)
	Copy constructor.
virtual PLGRAPHICS_API	~Image ()
	Destructor.
PLGRAPHICS_API Image &	operator= (const Image &cSource)
	Assignment operator.
PLGRAPHICS_API void	ApplyEffect (const ImageEffect &cEffect)
	Apply image effect.
PLGRAPHICS_API ECheckConsistency	CheckConsistency () const
	Check image for possible problems.
bool	IsMultiPart () const
	Check if this image is a multi-part image (e.g. a CubeMap)
PLCore::uint32	GetNumOfParts () const
	Get number of image parts.
ImagePart *	GetPart (PLCore::uint32 nIndex) const
	Get image part.
ImagePart *	GetPartBySemantics (PLCore::uint32 nSemantics) const
	Get image part by semantics.
const PLCore::Container < ImagePart * > &	GetParts () const
	Get image parts.
PLGRAPHICS_API ImagePart *	CreatePart (PLCore::uint32 nSemantics=ImagePartStatic)
	Create a new image part.
PLGRAPHICS_API bool	DeletePart (ImagePart &cPart)
	Delete image part.
PLGRAPHICS_API ImageBuffer *	GetBuffer (PLCore::uint32 nPart=0, PLCore::uint32 nMipmap=0) const
	Get image buffer.
PLGRAPHICS_API void	CreateTestImage (ETestImage nTestImage=TestImage2DSimple)
	Create a test image.
virtual PLGRAPHICS_API bool	Unload () override
	Unloads the loadable.
virtual PLGRAPHICS_API PLCore::String	GetLoadableTypeName () const override
	Returns the loadable type name.
Static Public Member Functions
static PLGRAPHICS_API Image	CreateImage (EDataFormat nDataFormat, EColorFormat nColorFormat, const PLMath::Vector3i &vSize, ECompression nCompression=CompressionNone)
	Create image.
static PLGRAPHICS_API Image	CreateImageAndCopyData (EDataFormat nDataFormat, EColorFormat nColorFormat, const PLMath::Vector3i &vSize, ECompression nCompression=CompressionNone, const PLCore::uint8 *pnData=nullptr)
	Create image and copy given uncompressed image data.
static PLGRAPHICS_API Image	CreateImageAndTakeoverData (EDataFormat nDataFormat, EColorFormat nColorFormat, const PLMath::Vector3i &vSize, ECompression nCompression=CompressionNone, PLCore::uint8 *pnData=nullptr)
	Create image and takeover given uncompressed image data.
static PLGRAPHICS_API Image	CreateImageAndShareData (EDataFormat nDataFormat, EColorFormat nColorFormat, const PLMath::Vector3i &vSize, ECompression nCompression=CompressionNone, PLCore::uint8 *pnData=nullptr)
	Create image and share given uncompressed image data.

Detailed Description

Image class.

Remarks:

It's possible to copy, takeover and share user provided image data:

Copy: Just duplicates the user provided data but leaves the responsibility of the original provided image data up to the user
Takeover: The user gives the ownership of the provided image data to the image which destroys the data when it's no longer used
Share: The image will use the given user provided data directly but doesn't destroy it because the user keeps the ownership

*    Usage example:
*
*    // Allocate image
*    Image cImage = Image::CreateImage(DataByte, ColorRGB, Vector3i(64, 32, 1));
*    ImageBuffer *pImageBuffer = cImage.GetBuffer();
*
*    // Fill image
*    uint8 *pData = pImageBuffer->GetData();
*    for (int i=0; i<pImageBuffer->GetSize().x*pImageBuffer->GetSize().y; i++, pData++)
*        *pData = static_cast<uint8>(Math::GetRand() % 255);
*

Constructor & Destructor Documentation

PLGRAPHICS_API PLGraphics::Image::Image ( )

Constructor.

PLGRAPHICS_API PLGraphics::Image::Image ( const Image & cSource )

Copy constructor.

Parameters:

[in] cSource Source to copy from

virtual PLGRAPHICS_API PLGraphics::Image::~Image ( ) [virtual]

Destructor.

Member Function Documentation

static PLGRAPHICS_API Image PLGraphics::Image::CreateImage	(	EDataFormat	nDataFormat,
		EColorFormat	nColorFormat,
		const PLMath::Vector3i &	vSize,
		ECompression	nCompression = `CompressionNone`
	)		`[static]`

Create image.

Parameters:

[in]	nDataFormat	Desired data format
[in]	nColorFormat	Desired color format
[in]	vSize	Image size
[in]	nCompression	Compression type

Remarks:

This is only an ease of use method doing nothing more than:

		*    Image cImage;
		*    ImageBuffer *pImageBuffer = cImage.CreatePart()->CreateMipmap();
		*    pImageBuffer->CreateImage(nDataFormat, nColorFormat, vSize, nCompression);
		*

static PLGRAPHICS_API Image PLGraphics::Image::CreateImageAndCopyData	(	EDataFormat	nDataFormat,
		EColorFormat	nColorFormat,
		const PLMath::Vector3i &	vSize,
		ECompression	nCompression = `CompressionNone`,
		const PLCore::uint8 *	pnData = `nullptr`
	)		`[static]`

Create image and copy given uncompressed image data.

Parameters:

[in]	nDataFormat	Desired data format
[in]	nColorFormat	Desired color format
[in]	vSize	Image size
[in]	nCompression	Compression type
[in]	pnData	If not a null pointer, data to copy into the created image, must have enough bytes to fill the whole image!

Remarks:

Usage example: Write down the (internally copied) RGB byte image data given by "pnMyImageData" into a 64x32 tga image:

		*    Image::CreateImageAndCopyData(DataByte, ColorRGB, Vector3i(64, 32, 1), CompressionNone, pnMyImageData).Save("MyImage.tga");
		*

This is only an ease of use method doing nothing more than:

		*    Image cImage;
		*    ImageBuffer *pImageBuffer = cImage.CreatePart()->CreateMipmap();
		*    pImageBuffer->CreateImage(nDataFormat, nColorFormat, vSize, nCompression);
		*    pImageBuffer->CopyData(pnData);
		*

Note:

Lookout! This method is dangerous and must be used with care! Do always ensure that your given image data has enough bytes for this image!

static PLGRAPHICS_API Image PLGraphics::Image::CreateImageAndTakeoverData	(	EDataFormat	nDataFormat,
		EColorFormat	nColorFormat,
		const PLMath::Vector3i &	vSize,
		ECompression	nCompression = `CompressionNone`,
		PLCore::uint8 *	pnData = `nullptr`
	)		`[static]`

Create image and takeover given uncompressed image data.

Parameters:

[in]	nDataFormat	Desired data format
[in]	nColorFormat	Desired color format
[in]	vSize	Image size
[in]	nCompression	Compression type
[in]	pnData	If not a null pointer, pointer to the image data to be taken over by the created image, must have enough bytes to fill the whole image!

Remarks:

Usage example: Write down the RGB byte image data given by "pnMyImageData" into a 64x32 tga image:

		*    Image::CreateImageAndTakeoverData(DataByte, ColorRGB, Vector3i(64, 32, 1), CompressionNone, pnMyImageData).Save("MyImage.tga");
		*

Please note that within the example above, "pnMyImageData" is no longer valid after the shown line because the given data was destroyed by the image instance!

This is only an ease of use method doing nothing more than:

		*    Image cImage;
		*    ImageBuffer *pImageBuffer = cImage.CreatePart()->CreateMipmap();
		*    pImageBuffer->CreateImage(nDataFormat, nColorFormat, vSize, nCompression);
		*    pImageBuffer->TakeoverData(pnData);
		*

Note:

Lookout! This method is dangerous and must be used with care! Do always ensure that your given image data has enough bytes for this image!

static PLGRAPHICS_API Image PLGraphics::Image::CreateImageAndShareData	(	EDataFormat	nDataFormat,
		EColorFormat	nColorFormat,
		const PLMath::Vector3i &	vSize,
		ECompression	nCompression = `CompressionNone`,
		PLCore::uint8 *	pnData = `nullptr`
	)		`[static]`

Create image and share given uncompressed image data.

Parameters:

[in]	nDataFormat	Desired data format
[in]	nColorFormat	Desired color format
[in]	vSize	Image size
[in]	nCompression	Compression type
[in]	pnData	If not a null pointer, pointer to the image data to be shared by the created image, must have enough bytes to fill the whole image!

Remarks:

Usage example: Write down the RGB byte image data given by "pnMyImageData" into a 64x32 tga image:

		*    Image::CreateImageAndShareData(DataByte, ColorRGB, Vector3i(64, 32, 1), CompressionNone, pnMyImageData).Save("MyImage.tga");
		*

The shown example is quite efficient because in here, the image instance is just an image data wrapper to pass and process user provided image data within PixelLight without duplicating the data.

This is only an ease of use method doing nothing more than:

		*    Image cImage;
		*    ImageBuffer *pImageBuffer = cImage.CreatePart()->CreateMipmap();
		*    pImageBuffer->CreateImage(nDataFormat, nColorFormat, vSize, nCompression);
		*    pImageBuffer->ShareData(pnData);
		*

Note:

Please be aware that your provided image data must stay valid during the lifetime of the image instance (and potential image copies!)
While this method is quite efficient, it's also quite error prone, so be really careful when using this method
Lookout! This method is dangerous and must be used with care! Do always ensure that your given image data has enough bytes for this image!

PLGRAPHICS_API Image& PLGraphics::Image::operator= ( const Image & cSource )

Assignment operator.

Parameters:

[in] cSource Source to copy from

Returns:: Reference to this object

PLGRAPHICS_API void PLGraphics::Image::ApplyEffect ( const ImageEffect & cEffect )

Apply image effect.

Parameters:

[in] cEffect Image effect

PLGRAPHICS_API ECheckConsistency PLGraphics::Image::CheckConsistency ( ) const

Check image for possible problems.

Returns:: Error code describing any problem found, 'CheckOk' if everything is fine

bool PLGraphics::Image::IsMultiPart ( ) const [inline]

Check if this image is a multi-part image (e.g. a CubeMap)

Returns:: 'true' if the image contains of more than one image part

PLCore::uint32 PLGraphics::Image::GetNumOfParts ( ) const [inline]

Get number of image parts.

Returns:: Number of image parts

ImagePart * PLGraphics::Image::GetPart ( PLCore::uint32 nIndex ) const [inline]

Get image part.

Parameters:

[in] nIndex Index of image part

Returns:: Image part, or a null pointer if it doesn't exist

ImagePart * PLGraphics::Image::GetPartBySemantics ( PLCore::uint32 nSemantics ) const [inline]

Get image part by semantics.

Parameters:

[in] nSemantics ID of image part

Returns:: Image part, or a null pointer if it doesn't exist

const PLCore::Container< ImagePart * > & PLGraphics::Image::GetParts ( ) const [inline]

Get image parts.

Returns:: List of image parts

PLGRAPHICS_API ImagePart* PLGraphics::Image::CreatePart ( PLCore::uint32 nSemantics = ImagePartStatic )

Create a new image part.

Parameters:

[in] nSemantics ID of image part

Returns:: Image part, or a null pointer on error

Remarks:: Chose a semantics ID that describes the role of the new image part (

See also:: EImagePart). Please note that the semantics IDs has to be unique, so trying to create a new image part with an already used ID will cause an error.

PLGRAPHICS_API bool PLGraphics::Image::DeletePart ( ImagePart & cPart )

Delete image part.

Parameters:

[in] cPart Image part

Returns:: 'true' on success, ('cPart' is now no longer valid!) else 'false'

PLGRAPHICS_API ImageBuffer* PLGraphics::Image::GetBuffer	(	PLCore::uint32	nPart = `0`,
		PLCore::uint32	nMipmap = `0`
	)		const

Get image buffer.

Parameters:

[in]	nPart	Index of image part
[in]	nMipmap	Index of mipmap

Returns:: Pointer to image buffer, a null pointer if the specified image buffer does not exist

Remarks:: If GetBuffer() is called with default parameters, it will return the image buffer of the first subimage and first mipmap. So, for most images that contain of only one image part, it is sufficient to just call GetBuffer() in order to get the image buffer.

PLGRAPHICS_API void PLGraphics::Image::CreateTestImage ( ETestImage nTestImage = TestImage2DSimple )

Create a test image.

Parameters:

[in] nTestImage ID of test image

virtual PLGRAPHICS_API bool PLGraphics::Image::Unload ( ) [override, virtual]

Unloads the loadable.

Returns:: 'true' if all went fine, else 'false'

Reimplemented from PLCore::Loadable.

virtual PLGRAPHICS_API PLCore::String PLGraphics::Image::GetLoadableTypeName ( ) const [override, virtual]

Returns the loadable type name.

Returns:: The loadable type name

Reimplemented from PLCore::Loadable.

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation