Describes a pixel packing format and provides format-specific operations. More...

#include <pixelformat.h>

Collaboration diagram for PixelFormat:

[legend]

Classes
struct	CompDesc
	Describes a single component within the pixel format. More...

struct	Data
	Aggregate descriptor holding all metadata for a pixel format. More...

struct	PlaneDesc
	Describes a single image plane. More...

Public Types
enum	ID { Invalid = 0 , RGBA8 , RGB8 , RGB10 , YUV8_422 , YUV10_422 , JPEG_RGBA8 , JPEG_RGB8 , JPEG_YUV8_422 , Invalid = 0 , RGBA8 , RGB8 , RGB10 , YUV8_422 , YUV10_422 }
	The ID of the unique packing format for the pixel. More...

enum	Sampling { SamplingUndefined = 0 , Sampling444 , Sampling422 , Sampling411 , Sampling420 , SamplingUndefined = 0 , Sampling444 , Sampling422 , Sampling411 , Sampling420 }
	Chroma subsampling mode. More...

enum	CompType { CompEmpty = 0 , CompAlpha , CompRed , CompGreen , CompBlue , CompY , CompCb , CompCr , CompEmpty = 0 , CompAlpha , CompRed , CompGreen , CompBlue , CompY , CompCb , CompCr }
	Pixel component type. More...

enum	ID { Invalid = 0 , RGBA8 , RGB8 , RGB10 , YUV8_422 , YUV10_422 , JPEG_RGBA8 , JPEG_RGB8 , JPEG_YUV8_422 , Invalid = 0 , RGBA8 , RGB8 , RGB10 , YUV8_422 , YUV10_422 }
	Unique packing format identifier. More...

enum	Sampling { SamplingUndefined = 0 , Sampling444 , Sampling422 , Sampling411 , Sampling420 , SamplingUndefined = 0 , Sampling444 , Sampling422 , Sampling411 , Sampling420 }
	Chroma subsampling mode. More...

enum	CompType { CompEmpty = 0 , CompAlpha , CompRed , CompGreen , CompBlue , CompY , CompCb , CompCr , CompEmpty = 0 , CompAlpha , CompRed , CompGreen , CompBlue , CompY , CompCb , CompCr }
	Pixel component type. More...

using	Comp = uint16_t
	Component value type.

using	CompList = std::vector< Comp >
	List of component values.

typedef size_t(*	StrideFunc) (const Size2Du32 &size)
	Function that returns the number of bytes per line.

typedef size_t(*	SizeFunc) (const Size2Du32 &size)
	Function that returns the total number of bytes for an image of the given size.

typedef bool(*	FillFunc) (const Image &img, const Comp *comps)
	Function that fills an image with a pixel value from a component array.

typedef Pixel(*	CreatePixelFunc) (const Comp *comps)
	Function that computes a Pixel from component inputs.

typedef uint32_t	FourCC
	FourCC code type.

Public Member Functions
	PixelFormat ()=default
	Default constructor.

virtual	~PixelFormat ()
	Virtual destructor.

bool	isValid () const
	Returns true if this pixel format is valid (not Invalid).

int	id () const
	Returns the unique ID of this pixel format.

String	name () const
	Returns the short name of this pixel format.

String	desc () const
	Returns a human-readable description of this pixel format.

Sampling	sampling () const
	Returns the chroma subsampling mode.

size_t	pixelsPerBlock () const
	Returns the number of pixels in one encoded block.

size_t	bytesPerBlock () const
	Returns the number of bytes in one encoded block.

bool	hasAlpha () const
	Returns true if this format includes an alpha channel.

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

const FourCCList &	fourccList () const
	Returns the list of FourCC codes associated with this format.

size_t	compCount () const
	Returns the number of components in this pixel format.

const CompDesc &	compDesc (size_t index) const
	Returns the component descriptor at the given index.

size_t	planeCount () const
	Returns the number of planes in this pixel format.

const PlaneDesc &	planeDesc (size_t index) const
	Returns the plane descriptor at the given index.

bool	isValidPlane (size_t index) const
	Returns true if the given plane index is valid.

bool	isValidCompCount (size_t ct) const
	Returns true if the given component count is sufficient.

size_t	lineStride (size_t planeIndex, const ImageDesc &desc) const
	Returns the number of bytes per line for a given plane.

size_t	planeSize (size_t planeIndex, const ImageDesc &desc) const
	Returns the total byte size of a given plane.

PaintEngine	createPaintEngine (const Image &img) const
	Creates a PaintEngine that can draw on the given image.

	PixelFormat (ID id=Invalid)
	Constructs a PixelFormat from an ID.

PixelFormat &	operator= (const PixelFormat &o)
	Copy assignment operator.

bool	operator== (const PixelFormat &o) const
	Returns true if both formats have the same ID.

bool	operator!= (const PixelFormat &o) const
	Returns true if the formats have different IDs.

bool	isValid () const
	Returns true if this pixel format is valid (not Invalid).

const Data &	data () const
	Returns a const reference to the underlying Data descriptor.

ID	id () const
	Returns the format ID.

const String &	name () const
	Returns the short format name.

const String &	desc () const
	Returns the human-readable description.

size_t	comps () const
	Returns the number of components in this format.

size_t	planes () const
	Returns the number of planes in this format.

size_t	stride (const Size2Du32 &s, int p=0) const
	Returns the line stride in bytes for the given image size and plane.

size_t	size (const Size2Du32 &s, int p=0) const
	Returns the total byte size for the given image size and plane.

bool	fill (const Image &img, const CompList &comps) const
	Fills an image with the pixel value defined by a component list.

bool	fill (const Image &img, const Comp *comps, size_t compCount) const
	Fills an image with the pixel value defined by a component array.

Pixel	createPixel (const Comp *comps, size_t compCount) const
	Creates a Pixel from a component array.

Static Public Member Functions
static int	registerPixelFormat (PixelFormat *pixelFormat)
	Registers a pixel format in the global registry.

static const PixelFormat *	lookup (int id)
	Looks up a registered pixel format by its ID.

static const String &	formatName (ID id)
	Returns the human-readable name for a given format ID.

Protected Member Functions
virtual size_t	__lineStride (size_t planeIndex, const ImageDesc &desc) const
	Virtual implementation of lineStride().

virtual size_t	__planeSize (size_t planeIndex, const ImageDesc &desc) const
	Virtual implementation of planeSize().

virtual PaintEngine	__createPaintEngine (const Image &image) const
	Virtual implementation of createPaintEngine().

Protected Attributes
int	_id = Invalid
	Unique format identifier.

String	_name
	Short format name.

String	_desc
	Human-readable description.

Sampling	_sampling = SamplingUndefined
	Chroma subsampling mode.

size_t	_pixelsPerBlock = 0
	Pixels per encoded block.

size_t	_bytesPerBlock = 0
	Bytes per encoded block.

bool	_hasAlpha = false
	Whether format has alpha.

bool	_compressed = false
	Whether format is compressed.

FourCCList	_fourccList
	Associated FourCC codes.

List< CompDesc >	_compList
	Component descriptors.

List< PlaneDesc >	_planeList
	Plane descriptors.

Detailed Description

Describes a pixel packing format and provides format-specific operations.

Legacy pixel format descriptor (superseded by the new PixelFormat).

PixelFormat is a polymorphic base class that describes how pixel data is packed in memory. It does not concern itself with color semantics, only with the layout of components, planes, and blocks. Concrete subclasses are registered at static-init time via PROMEKI_REGISTER_PIXELFORMAT and looked up by numeric ID.

Provides an interface for interacting with data in a particular pixel packing format. This class does not concern itself with the concept of color, only with the layout of components within packed data.

Deprecated:: Use the new PixelFormat class in pixelformat.h instead.

Member Typedef Documentation

◆ CreatePixelFunc

typedef Pixel(* PixelFormat::CreatePixelFunc) (const Comp *comps)

Function that computes a Pixel from component inputs.

Parameters

comps Array of component values.

Returns: A Pixel value.

◆ FillFunc

typedef bool(* PixelFormat::FillFunc) (const Image &img, const Comp *comps)

Function that fills an image with a pixel value from a component array.

Parameters

img	The image to fill.
comps	Array of component values (must have at least the required count).

Returns: true on success.

◆ SizeFunc

typedef size_t(* PixelFormat::SizeFunc) (const Size2Du32 &size)

Function that returns the total number of bytes for an image of the given size.

Parameters

size	Image dimensions.

Returns: Total image size in bytes.

◆ StrideFunc

typedef size_t(* PixelFormat::StrideFunc) (const Size2Du32 &size)

Function that returns the number of bytes per line.

Parameters

size	Image dimensions.

Returns: Line stride in bytes.

Member Enumeration Documentation

◆ CompType [1/2]

enum PixelFormat::CompType

Pixel component type.

Enumerator
CompEmpty	Empty or unused component slot.
CompAlpha	Alpha (transparency) component.
CompRed	Red color component.
CompGreen	Green color component.
CompBlue	Blue color component.
CompY	Luma (Y) component.
CompCb	Blue-difference chroma (Cb/U) component.
CompCr	Red-difference chroma (Cr/V) component.
CompEmpty	Empty or unused component slot.
CompAlpha	Alpha (transparency) component.
CompRed	Red color component.
CompGreen	Green color component.
CompBlue	Blue color component.
CompY	Luma (Y) component.
CompCb	Blue-difference chroma (Cb/U) component.
CompCr	Red-difference chroma (Cr/V) component.

◆ CompType [2/2]

enum PixelFormat::CompType

Pixel component type.

Enumerator
CompEmpty	Empty or unused component slot.
CompAlpha	Alpha (transparency) component.
CompRed	Red color component.
CompGreen	Green color component.
CompBlue	Blue color component.
CompY	Luma (Y) component.
CompCb	Blue-difference chroma (Cb/U) component.
CompCr	Red-difference chroma (Cr/V) component.
CompEmpty	Empty or unused component slot.
CompAlpha	Alpha (transparency) component.
CompRed	Red color component.
CompGreen	Green color component.
CompBlue	Blue color component.
CompY	Luma (Y) component.
CompCb	Blue-difference chroma (Cb/U) component.
CompCr	Red-difference chroma (Cr/V) component.

◆ ID [1/2]

enum PixelFormat::ID

The ID of the unique packing format for the pixel.

Enumerator
Invalid	Invalid or uninitialized pixel format.
RGBA8	8-bit RGBA (32 bits per pixel).
RGB8	8-bit RGB (24 bits per pixel).
RGB10	10-bit RGB.
YUV8_422	8-bit YUV with 4:2:2 chroma subsampling.
YUV10_422	10-bit YUV with 4:2:2 chroma subsampling.
JPEG_RGBA8	JPEG-compressed 8-bit RGBA.
JPEG_RGB8	JPEG-compressed 8-bit RGB.
JPEG_YUV8_422	JPEG-compressed 8-bit YUV 4:2:2.
Invalid	Invalid or uninitialized pixel format.
RGBA8	8-bit RGBA (32 bits per pixel).
RGB8	8-bit RGB (24 bits per pixel).
RGB10	10-bit RGB.
YUV8_422	8-bit YUV with 4:2:2 chroma subsampling.
YUV10_422	10-bit YUV with 4:2:2 chroma subsampling.

◆ ID [2/2]

enum PixelFormat::ID

Unique packing format identifier.

Enumerator
Invalid	Invalid or uninitialized pixel format.
RGBA8	8-bit RGBA (32 bits per pixel).
RGB8	8-bit RGB (24 bits per pixel).
RGB10	10-bit RGB.
YUV8_422	8-bit YUV with 4:2:2 chroma subsampling.
YUV10_422	10-bit YUV with 4:2:2 chroma subsampling.
JPEG_RGBA8	JPEG-compressed 8-bit RGBA.
JPEG_RGB8	JPEG-compressed 8-bit RGB.
JPEG_YUV8_422	JPEG-compressed 8-bit YUV 4:2:2.
Invalid	Invalid or uninitialized pixel format.
RGBA8	8-bit RGBA (32 bits per pixel).
RGB8	8-bit RGB (24 bits per pixel).
RGB10	10-bit RGB.
YUV8_422	8-bit YUV with 4:2:2 chroma subsampling.
YUV10_422	10-bit YUV with 4:2:2 chroma subsampling.

◆ Sampling [1/2]

enum PixelFormat::Sampling

Chroma subsampling mode.

Enumerator
SamplingUndefined	Undefined or unknown sampling.
Sampling444	4:4:4 (no chroma subsampling).
Sampling422	4:2:2 (horizontal chroma subsampling by 2).
Sampling411	4:1:1 (horizontal chroma subsampling by 4).
Sampling420	4:2:0 (horizontal and vertical chroma subsampling by 2).
SamplingUndefined	Undefined or unknown sampling.
Sampling444	4:4:4 (no chroma subsampling).
Sampling422	4:2:2 (horizontal chroma subsampling by 2).
Sampling411	4:1:1 (horizontal chroma subsampling by 4).
Sampling420	4:2:0 (horizontal and vertical chroma subsampling by 2).

◆ Sampling [2/2]

enum PixelFormat::Sampling

Chroma subsampling mode.

Enumerator
SamplingUndefined	Undefined or unknown sampling.
Sampling444	4:4:4 (no chroma subsampling).
Sampling422	4:2:2 (horizontal chroma subsampling by 2).
Sampling411	4:1:1 (horizontal chroma subsampling by 4).
Sampling420	4:2:0 (horizontal and vertical chroma subsampling by 2).
SamplingUndefined	Undefined or unknown sampling.
Sampling444	4:4:4 (no chroma subsampling).
Sampling422	4:2:2 (horizontal chroma subsampling by 2).
Sampling411	4:1:1 (horizontal chroma subsampling by 4).
Sampling420	4:2:0 (horizontal and vertical chroma subsampling by 2).

Constructor & Destructor Documentation

◆ PixelFormat()

PixelFormat::PixelFormat ( ID id = Invalid )

inline

Constructs a PixelFormat from an ID.

Parameters

id	The pixel format ID (defaults to Invalid).

Member Function Documentation

◆ __createPaintEngine()

virtual PaintEngine PixelFormat::__createPaintEngine ( const Image & image ) const

protectedvirtual

Virtual implementation of createPaintEngine().

Parameters

image The image to create a paint engine for.

Returns: A PaintEngine configured for this pixel format.

◆ __lineStride()

virtual size_t PixelFormat::__lineStride	(	size_t	planeIndex,
		const ImageDesc &	desc
	)		const

protectedvirtual

Virtual implementation of lineStride().

Parameters

planeIndex	Zero-based plane index.
desc	Image descriptor providing dimensions.

Returns: Line stride in bytes.

◆ __planeSize()

virtual size_t PixelFormat::__planeSize	(	size_t	planeIndex,
		const ImageDesc &	desc
	)		const

protectedvirtual

Virtual implementation of planeSize().

Parameters

planeIndex	Zero-based plane index.
desc	Image descriptor providing dimensions.

Returns: Plane size in bytes.

◆ compDesc()

const CompDesc & PixelFormat::compDesc ( size_t index ) const

inline

Returns the component descriptor at the given index.

Parameters

index Zero-based component index.

Returns: Reference to the CompDesc for that component.

◆ createPaintEngine()

PaintEngine PixelFormat::createPaintEngine ( const Image & img ) const

Creates a PaintEngine that can draw on the given image.

Parameters

img	The image to create a paint engine for.

Returns: A PaintEngine configured for this pixel format.

◆ createPixel()

Pixel PixelFormat::createPixel	(	const Comp *	comps,
		size_t	compCount
	)		const

Creates a Pixel from a component array.

Parameters

comps	Array of component values.
compCount	Number of components in the array.

Returns: A Pixel value.

◆ fill() [1/2]

bool PixelFormat::fill	(	const Image &	img,
		const Comp *	comps,
		size_t	compCount
	)		const

Fills an image with the pixel value defined by a component array.

Parameters

img	The image to fill.
comps	Array of component values.
compCount	Number of components in the array.

Returns: true on success.

◆ fill() [2/2]

bool PixelFormat::fill	(	const Image &	img,
		const CompList &	comps
	)		const

inline

Fills an image with the pixel value defined by a component list.

Parameters

img	The image to fill.
comps	List of component values.

Returns: true on success.

◆ formatName()

static const String & PixelFormat::formatName ( ID id )

static

Returns the human-readable name for a given format ID.

Parameters

id	The pixel format ID.

Returns: Reference to the format name string.

◆ isCompressed()

bool PixelFormat::isCompressed ( ) const

inline

Returns true if this is a compressed pixel format.

Compressed formats (e.g. JPEG_RGB8) store an encoded bitstream rather than scanline-addressable pixel data. Image::isCompressed() is a convenience wrapper around this.

See also: Image::isCompressed(), Image::compressedSize(), Image::fromCompressedData()

◆ isValidCompCount()

bool PixelFormat::isValidCompCount ( size_t ct ) const

inline

Returns true if the given component count is sufficient.

Parameters

ct	Number of components to check against.

Returns: true if ct is at least as large as the format's component count.

◆ isValidPlane()

bool PixelFormat::isValidPlane ( size_t index ) const

inline

Returns true if the given plane index is valid.

Parameters

index Zero-based plane index to check.

Returns: true if the index is within the plane list.

◆ lineStride()

size_t PixelFormat::lineStride	(	size_t	planeIndex,
		const ImageDesc &	desc
	)		const

Returns the number of bytes per line for a given plane.

Parameters

planeIndex	Zero-based plane index.
desc	Image descriptor providing dimensions.

Returns: Line stride in bytes.

◆ lookup()

static const PixelFormat * PixelFormat::lookup ( int id )

static

Looks up a registered pixel format by its ID.

Parameters

id	The format ID to look up.

Returns: Pointer to the PixelFormat, or nullptr if not found.

◆ planeDesc()

const PlaneDesc & PixelFormat::planeDesc ( size_t index ) const

inline

Returns the plane descriptor at the given index.

Parameters

index Zero-based plane index.

Returns: Reference to the PlaneDesc for that plane.

◆ planeSize()

size_t PixelFormat::planeSize	(	size_t	planeIndex,
		const ImageDesc &	desc
	)		const

Returns the total byte size of a given plane.

Parameters

planeIndex	Zero-based plane index.
desc	Image descriptor providing dimensions.

Returns: Plane size in bytes.

◆ registerPixelFormat()

static int PixelFormat::registerPixelFormat ( PixelFormat * pixelFormat )

static

Registers a pixel format in the global registry.

Parameters

pixelFormat Pointer to a heap-allocated PixelFormat subclass.

Returns: The registered format's ID.

◆ size()

size_t PixelFormat::size	(	const Size2Du32 &	s,
		int	p = `0`
	)		const

inline

Returns the total byte size for the given image size and plane.

Parameters

s	Image dimensions.
p	Plane index (defaults to 0).

Returns: Plane size in bytes, or 0 if no size function is set.

◆ stride()

size_t PixelFormat::stride	(	const Size2Du32 &	s,
		int	p = `0`
	)		const

inline

Returns the line stride in bytes for the given image size and plane.

Parameters

s	Image dimensions.
p	Plane index (defaults to 0).

Returns: Line stride in bytes, or 0 if no stride function is set.

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

include/promeki/proav/pixelformat.h
include/promeki/proav/pixelformat_old.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ CreatePixelFunc

◆ FillFunc

◆ SizeFunc

◆ StrideFunc

Member Enumeration Documentation

◆ CompType [1/2]

◆ CompType [2/2]

◆ ID [1/2]

◆ ID [2/2]

◆ Sampling [1/2]

◆ Sampling [2/2]

Constructor & Destructor Documentation

◆ PixelFormat()

Member Function Documentation

◆ __createPaintEngine()

◆ __lineStride()

◆ __planeSize()

◆ compDesc()

◆ createPaintEngine()

◆ createPixel()

◆ fill() [1/2]

◆ fill() [2/2]

◆ formatName()

◆ isCompressed()

◆ isValidCompCount()

◆ isValidPlane()

◆ lineStride()

◆ lookup()

◆ planeDesc()

◆ planeSize()

◆ registerPixelFormat()

◆ size()

◆ stride()