Image

class Image

An immutable snapshot of pixel data.

Images are created from Surfaces via makeSnapshot() and can be drawn onto any Surface via canvas->drawImage(). This is the mechanism for compositing multiple surfaces together.

Public Types

enum class StorageType : u8

Storage backend for the image data.

Values:

enumerator CpuPixmap: CPU-side pixel buffer.

enumerator GpuTexture: GPU texture handle.

Public Functions

inline u64 backendTextureHandle() const

Get the opaque backend texture handle.

Returns:: Texture handle for GPU-backed images; 0 otherwise.

inline PixelFormat format() const

Get pixel format.

Returns:: The pixel format of this image.

inline u32 glTextureId() const

Get the GL texture ID.

Returns:: OpenGL texture name (truncated from u64 to u32).

inline i32 height() const

Get image height.

Returns:: Height in pixels.

inline const PixmapInfo &info() const

Get full pixmap info.

Returns:: Reference to the PixmapInfo descriptor.

inline bool isCpuBacked() const

Check if image is CPU-backed.

Returns:: True if stored as a CPU pixmap.

inline bool isGpuBacked() const

Check if image is GPU-backed.

Returns:: True if stored as a GPU texture.

inline const void *pixels() const

Get raw pixel pointer (CPU-backed images only).

Returns:: Pointer to pixel data, or nullptr for GPU-backed images.

inline const u32 *pixels32() const

Get pixel data as 32-bit words.

Returns:: Pointer to pixel data cast to u32*.

inline StorageType storageType() const

Get the storage type.

Returns:: StorageType::CpuPixmap or StorageType::GpuTexture.

inline i32 stride() const

Get row stride in bytes.

Returns:: Bytes per row.

inline u64 uniqueId() const

Get a stable unique identity for backend caches.

Returns:: Unique image ID.

inline bool valid() const

Check if the image contains valid data.

Returns:: True if dimensions are positive and backing storage is present.

inline i32 width() const

Get image width.

Returns:: Width in pixels.

Public Static Functions

static std::shared_ptr<Image> MakeFromBackendTexture(u64 textureHandle, i32 width, i32 height, PixelFormat fmt = PixelFormat::RGBA8888, std::shared_ptr<void> lifetimeToken = nullptr)

Create an image from a backend-specific GPU texture handle.

Parameters:

textureHandle – Opaque handle (e.g. GLuint for GL, VkImage for Vulkan).
width – Texture width in pixels.
height – Texture height in pixels.
fmt – Pixel format (default RGBA8888).
lifetimeToken – Optional shared_ptr whose destructor releases the texture.

Returns:

Shared pointer to the new Image.

static std::shared_ptr<Image> MakeFromGLTexture(u32 textureId, i32 width, i32 height, PixelFormat fmt = PixelFormat::RGBA8888, std::shared_ptr<void> lifetimeToken = nullptr)

Convenience: create from a GL texture ID.

Parameters:

textureId – OpenGL texture name.
width – Texture width in pixels.
height – Texture height in pixels.
fmt – Pixel format (default RGBA8888).
lifetimeToken – Optional shared_ptr whose destructor releases the texture.

Returns:

Shared pointer to the new Image.

static std::shared_ptr<Image> MakeFromPixmap(const Pixmap &src)

Create an image by copying pixel data from a Pixmap.

Parameters:: src – Source pixmap to copy from.
Returns:: Shared pointer to the new Image.

static std::shared_ptr<Image> MakeFromPixmapNoCopy(const Pixmap &src)

Create an image wrapping existing pixel data (caller must keep data alive).

Parameters:: src – Source pixmap (data is not copied).
Returns:: Shared pointer to the new Image.