ezEngine Release 26.3
Loading...
Searching...
No Matches
Public Member Functions | List of all members
ezImage Class Reference

Container for image data with automatic memory management. More...

#include <Image.h>

Inheritance diagram for ezImage:
Inheritance graph
[legend]

Public Member Functions

 EZ_DECLARE_MEM_RELOCATABLE_TYPE ()
 
 ezImage ()
 Constructs an empty image.
 
 ezImage (ezImage &&other)
 Move constructor.
 
void operator= (ezImage &&rhs)
 
void Clear ()
 Constructs an empty image. If the image is attached to an external storage, the attachment is discarded.
 
void ResetAndAlloc (const ezImageHeader &header)
 Allocates storage for an image with the given header.
 
void ResetAndUseExternalStorage (const ezImageHeader &header, ezByteBlobPtr externalData)
 Attaches the image to external storage provided by the user.
 
void ResetAndMove (ezImage &&other)
 Takes ownership of another image's data via move semantics.
 
void ResetAndCopy (const ezImageView &other)
 Copies data from an image view into internal storage.
 
ezResult LoadFrom (ezStringView sFileName)
 Convenience function to load the image from the given file.
 
ezResult Convert (ezImageFormat::Enum targetFormat)
 Convenience function to convert the image to the given format.
 
template<typename T >
ezBlobPtr< T > GetBlobPtr ()
 Returns a view to the entire data contained in this image.
 
ezByteBlobPtr GetByteBlobPtr ()
 
ezImage GetSubImageView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0)
 Returns a view to the given sub-image.
 
ezImage GetPlaneView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 uiPlaneIndex=0)
 Returns a view to a sub-plane.
 
ezImage GetSliceView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0)
 Returns a view to z slice of the image.
 
ezImage GetRowView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0)
 Returns a view to a row of pixels resp. blocks.
 
template<typename T >
T * GetPixelPointer (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 x=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0)
 Returns a pointer to a given pixel or block contained in a sub-image.
 
template<typename T >
ezBlobPtr< const T > GetBlobPtr () const
 Returns a view to the entire data contained in this image.
 
ezConstByteBlobPtr GetByteBlobPtr () const
 
ezImageView GetSubImageView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0) const
 Returns a view to the given sub-image.
 
ezImageView GetPlaneView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to a sub-plane.
 
ezImageView GetSliceView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to z slice of the image.
 
ezImageView GetRowView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to a row of pixels resp. blocks.
 
template<typename T >
const T * GetPixelPointer (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 x=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a pointer to a given pixel or block contained in a sub-image.
 
- Public Member Functions inherited from ezImageView
 ezImageView ()
 Constructs an empty image view.
 
 ezImageView (const ezImageHeader &header, ezConstByteBlobPtr imageData)
 Constructs an image view with the given header and image data.
 
void Clear ()
 Resets to an empty state, releasing the reference to external data.
 
bool IsValid () const
 Returns false if the image view does not reference any data yet.
 
void ResetAndViewExternalStorage (const ezImageHeader &header, ezConstByteBlobPtr imageData)
 Resets the view to reference new external image data.
 
ezResult SaveTo (ezStringView sFileName) const
 Convenience function to save the image to the given file.
 
const ezImageHeader & GetHeader () const
 Returns the header this image was constructed from.
 
template<typename T >
ezBlobPtr< const T > GetBlobPtr () const
 Returns a view to the entire data contained in this image.
 
ezConstByteBlobPtr GetByteBlobPtr () const
 
ezImageView GetSubImageView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0) const
 Returns a view to the given sub-image.
 
ezImageView GetPlaneView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to a sub-plane.
 
ezImageView GetSliceView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to z slice of the image.
 
ezImageView GetRowView (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a view to a row of pixels resp. blocks.
 
template<typename T >
const T * GetPixelPointer (ezUInt32 uiMipLevel=0, ezUInt32 uiFace=0, ezUInt32 uiArrayIndex=0, ezUInt32 x=0, ezUInt32 y=0, ezUInt32 z=0, ezUInt32 uiPlaneIndex=0) const
 Returns a pointer to a given pixel or block contained in a sub-image.
 
void ReinterpretAs (ezImageFormat::Enum format)
 Reinterprets the image with a given format; the format must have the same size in bits per pixel as the current one.
 
ezUInt32 GetDepth (ezUInt32 uiMipLevel=0) const
 Returns the image depth for a given mip level, clamped to 1.
 
ezUInt32 GetHeight (ezUInt32 uiMipLevel=0) const
 Returns the image height for a given mip level, clamped to 1.
 
ezUInt32 GetWidth (ezUInt32 uiMipLevel=0) const
 Returns the image width for a given mip level, clamped to 1.
 
ezUInt32 GetNumArrayIndices () const
 Returns the number of array indices.
 
ezUInt32 GetNumFaces () const
 Returns the number of cubemap faces, or 1 for a non-cubemap.
 
ezUInt32 GetNumMipLevels () const
 Returns the number of mip levels, including the full-size image.
 
ezUInt32 GetPlaneCount () const
 Returns the number of image planes.
 
ezImageFormat::Enum GetImageFormat () const
 Returns the image format.
 
ezUInt32 GetNumBlocksX (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the horizontal direction.
 
ezUInt32 GetNumBlocksY (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the horizontal direction.
 
ezUInt32 GetNumBlocksZ (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the depth direction.
 
ezUInt64 GetDepthPitch (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the offset in bytes between two subsequent depth slices of the given mip level.
 
ezUInt64 GetRowPitch (ezUInt32 uiMipLevel=0, ezUInt32 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 ezImageView
ezUInt64 ComputeLayout ()
 
void ValidateSubImageIndices (ezUInt32 uiMipLevel, ezUInt32 uiFace, ezUInt32 uiArrayIndex, ezUInt32 uiPlaneIndex) const
 
template<typename T >
void ValidateDataTypeAccessor (ezUInt32 uiPlaneIndex) const
 
const ezUInt64 & GetSubImageOffset (ezUInt32 uiMipLevel, ezUInt32 uiFace, ezUInt32 uiArrayIndex, ezUInt32 uiPlaneIndex) const
 
- Protected Member Functions inherited from ezImageHeader
 ezImageHeader ()
 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 ezImageFormat::Enum &format)
 Sets the image format.
 
ezImageFormat::Enum GetImageFormat () const
 Returns the image format.
 
void SetWidth (ezUInt32 uiWidth)
 Sets the image width.
 
ezUInt32 GetWidth (ezUInt32 uiMipLevel=0) const
 Returns the image width for a given mip level, clamped to 1.
 
void SetHeight (ezUInt32 uiHeight)
 Sets the image height.
 
ezUInt32 GetHeight (ezUInt32 uiMipLevel=0) const
 Returns the image height for a given mip level, clamped to 1.
 
void SetDepth (ezUInt32 uiDepth)
 Sets the image depth. The default is 1.
 
ezUInt32 GetDepth (ezUInt32 uiMipLevel=0) const
 Returns the image depth for a given mip level, clamped to 1.
 
void SetNumMipLevels (ezUInt32 uiNumMipLevels)
 Sets the number of mip levels, including the full-size image.
 
ezUInt32 GetNumMipLevels () const
 Returns the number of mip levels, including the full-size image.
 
void SetNumFaces (ezUInt32 uiNumFaces)
 Sets the number of cubemap faces. Use 1 for a non-cubemap.
 
ezUInt32 GetNumFaces () const
 Returns the number of cubemap faces, or 1 for a non-cubemap.
 
void SetNumArrayIndices (ezUInt32 uiNumArrayIndices)
 Sets the number of array indices.
 
ezUInt32 GetNumArrayIndices () const
 Returns the number of array indices.
 
ezUInt32 GetPlaneCount () const
 Returns the number of image planes.
 
ezUInt32 GetNumBlocksX (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the horizontal direction.
 
ezUInt32 GetNumBlocksY (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the horizontal direction.
 
ezUInt32 GetNumBlocksZ (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the number of blocks contained in a given mip level in the depth direction.
 
ezUInt64 GetRowPitch (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the offset in bytes between two subsequent rows of the given mip level.
 
ezUInt64 GetDepthPitch (ezUInt32 uiMipLevel=0, ezUInt32 uiPlaneIndex=0) const
 Returns the offset in bytes between two subsequent depth slices of the given mip level.
 
ezUInt64 ComputeDataSize () const
 Computes the data size required for an image with the header's format and dimensions.
 
ezUInt32 ComputeNumberOfMipMaps () const
 Computes the number of mip maps in the full mip chain.
 
bool operator== (const ezImageHeader &other) const
 
bool operator!= (const ezImageHeader &other) const
 
- Protected Attributes inherited from ezImageView
ezHybridArray< ezUInt64, 16 > m_SubImageOffsets
 
ezBlobPtr< ezUInt8 > m_DataPtr
 
- Protected Attributes inherited from ezImageHeader
ezUInt32 m_uiNumMipLevels
 
ezUInt32 m_uiNumFaces
 
ezUInt32 m_uiNumArrayIndices
 
ezUInt32 m_uiWidth
 
ezUInt32 m_uiHeight
 
ezUInt32 m_uiDepth
 
ezImageFormat::Enum m_Format
 

Detailed Description

Container for image data with automatic memory management.

ezImage extends ezImageView by owning the image data it references. It can use either internal storage or attach to external memory. This class handles allocation, deallocation, and provides convenient methods for loading, saving, and converting images.

Memory management:

  • Internal storage: ezImage allocates and manages its own memory
  • External storage: ezImage references user-provided memory (user manages lifetime)
  • Storage can be switched between internal and external as needed

The sub-images are stored in a predefined order compatible with DDS files: For each array slice: mip level 0, mip level 1, ..., mip level N For cubemaps: +X, -X, +Y, -Y, +Z, -Z faces in that order For texture arrays: array slice 0, array slice 1, ..., array slice N

Common usage patterns:

// Load from file
ezImage image;
image.LoadFrom("texture.png");
// Create with specific format
ezImageHeader header;
header.SetImageFormat(ezImageFormat::R8G8B8A8_UNORM);
header.SetWidth(256); header.SetHeight(256);
ezImage image(header);
// Convert format
image.Convert(ezImageFormat::BC1_UNORM);
ezImageHeader
A class containing image meta data, such as format and dimensions.
Definition ImageHeader.h:15
ezImageHeader::SetImageFormat
void SetImageFormat(const ezImageFormat::Enum &format)
Sets the image format.
Definition ImageHeader.h:33
ezImageHeader::SetHeight
void SetHeight(ezUInt32 uiHeight)
Sets the image height.
Definition ImageHeader.h:49
ezImageHeader::SetWidth
void SetWidth(ezUInt32 uiWidth)
Sets the image width.
Definition ImageHeader.h:39
ezImage
Container for image data with automatic memory management.
Definition Image.h:139
ezImage::LoadFrom
ezResult LoadFrom(ezStringView sFileName)
Convenience function to load the image from the given file.
Definition Image.cpp:260
ezImage::Convert
ezResult Convert(ezImageFormat::Enum targetFormat)
Convenience function to convert the image to the given format.
Definition Image.cpp:290

Member Function Documentation

◆ ResetAndAlloc()

void ezImage::ResetAndAlloc ( const ezImageHeader &  header)

Allocates storage for an image with the given header.

If currently using external storage and it's large enough, that storage will be reused. Otherwise, the image will detach from external storage and allocate internal storage. Any existing data is discarded.

◆ ResetAndCopy()

void ezImage::ResetAndCopy ( const ezImageView &  other)

Copies data from an image view into internal storage.

If currently attached to external storage, the attachment is discarded and internal storage is allocated. The source view's data is copied completely.

◆ ResetAndMove()

void ezImage::ResetAndMove ( ezImage &&  other)

Takes ownership of another image's data via move semantics.

The other image is left in an empty state. If the other image uses external storage, this image will also reference that storage and inherit the lifetime requirements.

◆ ResetAndUseExternalStorage()

void ezImage::ResetAndUseExternalStorage ( const ezImageHeader &  header,
ezByteBlobPtr  externalData 
)

Attaches the image to external storage provided by the user.

The external storage must remain valid for the lifetime of this ezImage. The storage must be large enough to hold the image data described by the header. Use this when you want to avoid memory allocation or work with memory-mapped files.

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