Raster image with pixel format, planes, and metadata. More...

#include <image.h>

Public Types
using	Ptr = SharedPtr< Image >
	Shared pointer type for Image.

using	List = promeki::List< Image >
	List of Image values.

using	PtrList = promeki::List< Ptr >
	List of shared Image pointers.

Public Member Functions
	Image ()=default
	Constructs an invalid (empty) image.

	Image (const ImageDesc &desc, const MemSpace &ms=MemSpace::Default)
	Constructs an image from an image descriptor.

	Image (const Size2Du32 &s, int pixfmt, const MemSpace &ms=MemSpace::Default)
	Constructs an image from a size and pixel format ID.

	Image (size_t w, size_t h, int pixfmt, const MemSpace &ms=MemSpace::Default)
	Constructs an image from width, height, and pixel format ID.

bool	isValid () const
	Returns true if the image has a valid descriptor and allocated planes.

const ImageDesc &	desc () const
	Returns the image descriptor.

int	pixelFormatID () const
	Returns the pixel format identifier.

const PixelFormat *	pixelFormat () const
	Returns a pointer to the PixelFormat object.

const Size2Du32 &	size () const
	Returns the image dimensions.

size_t	width () const
	Returns the image width in pixels.

size_t	height () const
	Returns the image height in pixels.

const Metadata &	metadata () const
	Returns a const reference to the image metadata.

Metadata &	metadata ()
	Returns a mutable reference to the image metadata.

size_t	lineStride (int plane=0) const
	Returns the line stride in bytes for the given plane.

const Buffer::Ptr &	plane (int index=0) const
	Returns the buffer for the given image plane.

const Buffer::PtrList &	planes () const
	Returns the list of all plane buffers.

void *	data (int index=0) const
	Returns a raw data pointer for the given plane.

Error	fill (char value) const
	Fills all image planes with the given byte value.

bool	isExclusive () const
	Returns true if all plane buffers are exclusively owned.

void	ensureExclusive ()
	Ensures exclusive ownership of all plane buffers.

bool	isCompressed () const
	Returns true if this image uses a compressed pixel format.

size_t	compressedSize () const
	Returns the compressed data size in bytes.

PaintEngine	createPaintEngine () const
	Creates a paint engine for drawing on this image.

Image	convert (PixelFormat::ID pixelFormat, const Metadata &metadata) const
	Converts this image to a different pixel format.

Static Public Member Functions
static Image	fromCompressedData (const void *data, size_t size, size_t width, size_t height, int pixfmt, const Metadata &metadata=Metadata())
	Creates a compressed image from pre-encoded data.

Detailed Description

Raster image with pixel format, planes, and metadata.

Holds image pixel data organized into one or more memory planes according to the image's pixel format. Provides convenience accessors for dimensions, pixel format, and metadata, as well as pixel format conversion and paint engine creation. When shared ownership is needed, use Image::Ptr.

Compressed images: Image also represents compressed (encoded) image data such as JPEG. A compressed image uses a compressed pixel format (e.g. PixelFormat::JPEG_RGB8) and stores the encoded bitstream in its single plane buffer. Use isCompressed() to test whether an image is compressed, compressedSize() to get the encoded byte count, and data() to access the raw encoded bytes. The preferred way to create a compressed image is the fromCompressedData() factory.

Example — creating a compressed image: // After compressing with libjpeg or another codec:

Image jpeg = Image::fromCompressedData(jpegBytes, jpegSize,

1920, 1080,

PixelFormat::JPEG_RGB8,

srcImage.metadata());

assert(jpeg.isCompressed());

assert(jpeg.compressedSize() == jpegSize);

Image
Raster image with pixel format, planes, and metadata.
Definition image.h:48

Image::List
promeki::List< Image > List
List of Image values.
Definition image.h:55

Image::fromCompressedData
static Image fromCompressedData(const void *data, size_t size, size_t width, size_t height, int pixfmt, const Metadata &metadata=Metadata())
Creates a compressed image from pre-encoded data.

PixelFormat::JPEG_RGB8
@ JPEG_RGB8
JPEG-compressed 8-bit RGB.
Definition pixelformat.h:54

Constructor & Destructor Documentation

◆ Image() [1/3]

Image::Image	(	const ImageDesc &	desc,
		const MemSpace &	ms = `MemSpace::Default`
	)

Constructs an image from an image descriptor.

Parameters

desc	Image descriptor specifying size, pixel format, and metadata.
ms	Memory space to allocate plane buffers from.

◆ Image() [2/3]

Image::Image	(	const Size2Du32 &	s,
		int	pixfmt,
		const MemSpace &	ms = `MemSpace::Default`
	)

inline

Constructs an image from a size and pixel format ID.

Parameters

s	Image dimensions.
pixfmt	Pixel format identifier.
ms	Memory space to allocate from.

◆ Image() [3/3]

Image::Image	(	size_t	w,
		size_t	h,
		int	pixfmt,
		const MemSpace &	ms = `MemSpace::Default`
	)

inline

Constructs an image from width, height, and pixel format ID.

Parameters

w	Image width in pixels.
h	Image height in pixels.
pixfmt	Pixel format identifier.
ms	Memory space to allocate from.

Member Function Documentation

◆ compressedSize()

size_t Image::compressedSize ( ) const

inline

Returns the compressed data size in bytes.

For compressed images, the encoded bitstream lives in the first plane buffer. This method returns that buffer's logical size, which is the actual encoded byte count. Use data() to obtain a pointer to the encoded bytes.

Returns 0 for uncompressed images or if no planes are allocated.

Returns: The compressed data size, or 0.

◆ convert()

Image Image::convert	(	PixelFormat::ID	pixelFormat,
		const Metadata &	metadata
	)		const

Converts this image to a different pixel format.

Parameters

pixelFormat	The target pixel format ID.
metadata	Metadata to attach to the converted image.

Returns: A new Image in the target pixel format.

◆ createPaintEngine()

PaintEngine Image::createPaintEngine ( ) const

inline

Creates a paint engine for drawing on this image.

Returns: A PaintEngine configured for this image's pixel format.

◆ data()

void * Image::data ( int index = 0 ) const

inline

Returns a raw data pointer for the given plane.

Parameters

index The plane index (defaults to 0).

Returns: A void pointer to the plane's pixel data.

◆ desc()

const ImageDesc & Image::desc ( ) const

inline

Returns the image descriptor.

Returns: A const reference to the ImageDesc.

◆ ensureExclusive()

void Image::ensureExclusive ( )

inline

Ensures exclusive ownership of all plane buffers.

For each plane Buffer::Ptr, calls modify() to trigger a copy-on-write detach if the reference count is greater than 1. In a linear pipeline where only one consumer holds a reference, this is a no-op. In fan-out scenarios where multiple consumers share the same buffers, this creates private copies so that the caller can safely mutate the pixel data.

◆ fill()

Error Image::fill ( char value ) const

inline

Fills all image planes with the given byte value.

Parameters

value The byte value to fill with.

Returns: Error::Ok on success, or an error if no planes exist or a fill fails.

◆ fromCompressedData()

static Image Image::fromCompressedData	(	const void *	data,
		size_t	size,
		size_t	width,
		size_t	height,
		int	pixfmt,
		const Metadata &	metadata = `Metadata()`
	)

static

Creates a compressed image from pre-encoded data.

This is the preferred way to construct a compressed Image. It allocates a plane buffer sized to hold the encoded data, copies the bytes in, sets the buffer's logical size to size, and attaches the supplied metadata. The resulting Image reports isCompressed() == true and compressedSize() == size.

The width and height describe the original uncompressed dimensions — they are stored in the ImageDesc so that downstream consumers know the frame size without decoding.

Parameters

data	Pointer to the compressed data.
size	Size of the compressed data in bytes.
width	Original image width in pixels.
height	Original image height in pixels.
pixfmt	Compressed pixel format ID (e.g. PixelFormat::JPEG_RGB8).
metadata	Optional metadata to attach (e.g. timecode).

Returns: A valid compressed Image, or an invalid Image on failure.

◆ height()

size_t Image::height ( ) const

inline

Returns the image height in pixels.

Returns: The height.

◆ isCompressed()

bool Image::isCompressed ( ) const

inline

Returns true if this image uses a compressed pixel format.

Returns: true if the pixel format is compressed (e.g. JPEG).

◆ isExclusive()

bool Image::isExclusive ( ) const

inline

Returns true if all plane buffers are exclusively owned.

A plane is exclusive when its Buffer::Ptr has a reference count of 1 (or is null). This is useful for determining whether it is safe to mutate the pixel data in place without affecting other consumers that may share the same buffers.

Returns: true if every plane buffer has referenceCount() <= 1.

◆ isValid()

bool Image::isValid ( ) const

inline

Returns true if the image has a valid descriptor and allocated planes.

Returns: true if the image descriptor is valid.

◆ lineStride()

size_t Image::lineStride ( int plane = 0 ) const

inline

Returns the line stride in bytes for the given plane.

Parameters

plane The plane index (defaults to 0).

Returns: The number of bytes per scanline.

◆ metadata() [1/2]

Metadata & Image::metadata ( )

inline

Returns a mutable reference to the image metadata.

Returns: The metadata.

◆ metadata() [2/2]

const Metadata & Image::metadata ( ) const

inline

Returns a const reference to the image metadata.

Returns: The metadata.

◆ pixelFormat()

const PixelFormat * Image::pixelFormat ( ) const

inline

Returns a pointer to the PixelFormat object.

Returns: The PixelFormat pointer, or nullptr if unknown.

◆ pixelFormatID()

int Image::pixelFormatID ( ) const

inline

Returns the pixel format identifier.

Returns: The pixel format ID integer.

◆ plane()

const Buffer::Ptr & Image::plane ( int index = 0 ) const

inline

Returns the buffer for the given image plane.

Parameters

index The plane index (defaults to 0).

Returns: A const reference to the Buffer shared pointer.

◆ planes()

const Buffer::PtrList & Image::planes ( ) const

inline

Returns the list of all plane buffers.

Returns: A const reference to the Buffer::PtrList.

◆ size()

const Size2Du32 & Image::size ( ) const

inline

Returns the image dimensions.

Returns: A const reference to the Size2Du32.

◆ width()

size_t Image::width ( ) const

inline

Returns the image width in pixels.

Returns: The width.

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

include/promeki/proav/image.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Image() [1/3]

◆ Image() [2/3]

◆ Image() [3/3]

Member Function Documentation

◆ compressedSize()

◆ convert()

◆ createPaintEngine()

◆ data()

◆ desc()

◆ ensureExclusive()

◆ fill()

◆ fromCompressedData()

◆ height()

◆ isCompressed()

◆ isExclusive()

◆ isValid()

◆ lineStride()

◆ metadata() [1/2]

◆ metadata() [2/2]

◆ pixelFormat()

◆ pixelFormatID()

◆ plane()

◆ planes()

◆ size()

◆ width()