plImage Class Reference

A class containing image data and associated meta data. More...

#include <Image.h>

Inheritance diagram for plImage:

Public Member Functions
	PL_DECLARE_MEM_RELOCATABLE_TYPE ()
	plImage ()
	Constructs an empty image.
	plImage (plImage &&other)
	Move constructor.
void	operator= (plImage &&rhs)
void	Clear ()
	Constructs an empty image. If the image is attached to an external storage, the attachment is discarded.
void	ResetAndAlloc (const plImageHeader &header)
	Constructs an image with the given header and ensures sufficient storage is allocated.
void	ResetAndUseExternalStorage (const plImageHeader &header, plByteBlobPtr externalData)
	Constructs an image with the given header and attaches to the user-supplied external storage.
void	ResetAndMove (plImage &&other)
	Moves the given data into this object.
void	ResetAndCopy (const plImageView &other)
	Constructs from an image view. Copies the image data to internal storage.
plResult	LoadFrom (plStringView sFileName)
	Convenience function to load the image from the given file.
plResult	Convert (plImageFormat::Enum targetFormat)
	Convenience function to convert the image to the given format.
template<typename T >
plBlobPtr< T >	GetBlobPtr ()
	Returns a view to the entire data contained in this image.
plByteBlobPtr	GetByteBlobPtr ()
plImage	GetSubImageView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0)
	Returns a view to the given sub-image.
plImage	GetPlaneView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 uiPlaneIndex=0)
	Returns a view to a sub-plane.
plImage	GetSliceView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0)
	Returns a view to z slice of the image.
plImage	GetRowView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0)
	Returns a view to a row of pixels resp. blocks.
template<typename T >
T *	GetPixelPointer (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 x=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0)
	Returns a pointer to a given pixel or block contained in a sub-image.
template<typename T >
plBlobPtr< const T >	GetBlobPtr () const
	Returns a view to the entire data contained in this image.
plConstByteBlobPtr	GetByteBlobPtr () const
plImageView	GetSubImageView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0) const
	Returns a view to the given sub-image.
plImageView	GetPlaneView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to a sub-plane.
plImageView	GetSliceView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to z slice of the image.
plImageView	GetRowView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to a row of pixels resp. blocks.
template<typename T >
const T *	GetPixelPointer (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 x=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a pointer to a given pixel or block contained in a sub-image.
Public Member Functions inherited from plImageView
	plImageView ()
	Constructs an empty image view.
	plImageView (const plImageHeader &header, plConstByteBlobPtr imageData)
	Constructs an image view with the given header and image data.
void	Clear ()
	Constructs an empty image view.
bool	IsValid () const
	Returns false if the image view does not reference any data yet.
void	ResetAndViewExternalStorage (const plImageHeader &header, plConstByteBlobPtr imageData)
	Constructs an image view with the given header and image data.
plResult	SaveTo (plStringView sFileName) const
	Convenience function to save the image to the given file.
const plImageHeader &	GetHeader () const
	Returns the header this image was constructed from.
template<typename T >
plBlobPtr< const T >	GetBlobPtr () const
	Returns a view to the entire data contained in this image.
plConstByteBlobPtr	GetByteBlobPtr () const
plImageView	GetSubImageView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0) const
	Returns a view to the given sub-image.
plImageView	GetPlaneView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to a sub-plane.
plImageView	GetSliceView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to z slice of the image.
plImageView	GetRowView (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a view to a row of pixels resp. blocks.
template<typename T >
const T *	GetPixelPointer (plUInt32 uiMipLevel=0, plUInt32 uiFace=0, plUInt32 uiArrayIndex=0, plUInt32 x=0, plUInt32 y=0, plUInt32 z=0, plUInt32 uiPlaneIndex=0) const
	Returns a pointer to a given pixel or block contained in a sub-image.
void	ReinterpretAs (plImageFormat::Enum format)
	Reinterprets the image with a given format; the format must have the same size in bits per pixel as the current one.
plUInt32	GetDepth (plUInt32 uiMipLevel=0) const
	Returns the image depth for a given mip level, clamped to 1.
plUInt32	GetHeight (plUInt32 uiMipLevel=0) const
	Returns the image height for a given mip level, clamped to 1.
plUInt32	GetWidth (plUInt32 uiMipLevel=0) const
	Returns the image width for a given mip level, clamped to 1.
plUInt32	GetNumArrayIndices () const
	Returns the number of array indices.
plUInt32	GetNumFaces () const
	Returns the number of cubemap faces, or 1 for a non-cubemap.
plUInt32	GetNumMipLevels () const
	Returns the number of mip levels, including the full-size image.
plUInt32	GetPlaneCount () const
	Returns the number of image planes.
plImageFormat::Enum	GetImageFormat () const
	Returns the image format.
plUInt32	GetNumBlocksX (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the horizontal direction.
plUInt32	GetNumBlocksY (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the horizontal direction.
plUInt32	GetNumBlocksZ (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the depth direction.
plUInt64	GetDepthPitch (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the offset in bytes between two subsequent depth slices of the given mip level.
plUInt64	GetRowPitch (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the offset in bytes between two subsequent rows of the given mip level.

Additional Inherited Members
Protected Member Functions inherited from plImageView
plUInt64	ComputeLayout ()
void	ValidateSubImageIndices (plUInt32 uiMipLevel, plUInt32 uiFace, plUInt32 uiArrayIndex, plUInt32 uiPlaneIndex) const
template<typename T >
void	ValidateDataTypeAccessor (plUInt32 uiPlaneIndex) const
const plUInt64 &	GetSubImageOffset (plUInt32 uiMipLevel, plUInt32 uiFace, plUInt32 uiArrayIndex, plUInt32 uiPlaneIndex) const
Protected Member Functions inherited from plImageHeader
	plImageHeader ()
	Constructs an image using an unknown format and zero size.
void	Clear ()
	Constructs an image using an unknown format and zero size.
void	SetImageFormat (const plImageFormat::Enum &format)
	Sets the image format.
plImageFormat::Enum	GetImageFormat () const
	Returns the image format.
void	SetWidth (plUInt32 uiWidth)
	Sets the image width.
plUInt32	GetWidth (plUInt32 uiMipLevel=0) const
	Returns the image width for a given mip level, clamped to 1.
void	SetHeight (plUInt32 uiHeight)
	Sets the image height.
plUInt32	GetHeight (plUInt32 uiMipLevel=0) const
	Returns the image height for a given mip level, clamped to 1.
void	SetDepth (plUInt32 uiDepth)
	Sets the image depth. The default is 1.
plUInt32	GetDepth (plUInt32 uiMipLevel=0) const
	Returns the image depth for a given mip level, clamped to 1.
void	SetNumMipLevels (plUInt32 uiNumMipLevels)
	Sets the number of mip levels, including the full-size image.
plUInt32	GetNumMipLevels () const
	Returns the number of mip levels, including the full-size image.
void	SetNumFaces (plUInt32 uiNumFaces)
	Sets the number of cubemap faces. Use 1 for a non-cubemap.
plUInt32	GetNumFaces () const
	Returns the number of cubemap faces, or 1 for a non-cubemap.
void	SetNumArrayIndices (plUInt32 uiNumArrayIndices)
	Sets the number of array indices.
plUInt32	GetNumArrayIndices () const
	Returns the number of array indices.
plUInt32	GetPlaneCount () const
	Returns the number of image planes.
plUInt32	GetNumBlocksX (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the horizontal direction.
plUInt32	GetNumBlocksY (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the horizontal direction.
plUInt32	GetNumBlocksZ (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the number of blocks contained in a given mip level in the depth direction.
plUInt64	GetRowPitch (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the offset in bytes between two subsequent rows of the given mip level.
plUInt64	GetDepthPitch (plUInt32 uiMipLevel=0, plUInt32 uiPlaneIndex=0) const
	Returns the offset in bytes between two subsequent depth slices of the given mip level.
plUInt64	ComputeDataSize () const
	Computes the data size required for an image with the header's format and dimensions.
plUInt32	ComputeNumberOfMipMaps () const
	Computes the number of mip maps in the full mip chain.
bool	operator== (const plImageHeader &other) const
bool	operator!= (const plImageHeader &other) const
Protected Attributes inherited from plImageView
plHybridArray< plUInt64, 16 >	m_SubImageOffsets
plBlobPtr< plUInt8 >	m_DataPtr
Protected Attributes inherited from plImageHeader
plUInt32	m_uiNumMipLevels
plUInt32	m_uiNumFaces
plUInt32	m_uiNumArrayIndices
plUInt32	m_uiWidth
plUInt32	m_uiHeight
plUInt32	m_uiDepth
plImageFormat::Enum	m_Format

Detailed Description

A class containing image data and associated meta data.

This class is a lightweight container for image data and the description required for interpreting the data, such as the image format, its dimensions, number of sub-images (i.e. cubemap faces, mip levels and array sub-images). However, it does not provide any methods for interpreting or modifying of the image data.

The sub-images are stored in a predefined order compatible with the layout of DDS files, that is, it first stores the mip chain for each image, then all faces in a case of a cubemap, then the individual images of an image array.

Member Function Documentation

ResetAndAlloc()

void plImage::ResetAndAlloc

(

const plImageHeader &

header

)

Constructs an image with the given header and ensures sufficient storage is allocated.

Note

If this plImage was previously attached to external storage, this will reuse that storage. However, if the external storage is not sufficiently large, ResetAndAlloc() will detach from it and allocate internal storage.

ResetAndCopy()

void plImage::ResetAndCopy

(

const plImageView &

other

)

Constructs from an image view. Copies the image data to internal storage.

If the image is currently attached to external storage, the attachment is discarded.

ResetAndMove()

void plImage::ResetAndMove

(

plImage &&

other

)

Moves the given data into this object.

If other is attached to an external storage, this object will also be attached to it, so life-time requirements for the external storage are now bound to this instance.

ResetAndUseExternalStorage()

void plImage::ResetAndUseExternalStorage	(	const plImageHeader &	header,
		plByteBlobPtr	externalData )

Constructs an image with the given header and attaches to the user-supplied external storage.

The user is responsible to keep the external storage alive as long as this plImage is alive.

---

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

• Code/Engine/Texture/Image/Image.h
• Code/Engine/Texture/Image/Implementation/Image.cpp
• Code/Engine/Texture/Image/Implementation/Image_inl.h