#include <gfx_image_pixelformat.h>

Inheritance diagram for PixelFormatInterface:

Detailed Description

This class handles image pixel formats. Each pixel format should has it's own implementation. The memory layout of different pixels is free. This class offers functions to convert from and to other pixel formats.

This interface has only const functions and will not change it's pointers. That's why it's possible to compare PixelFormats by comparing the pointers. The PixelFormats registry provides all registered pixel formats.

One exception is the PixelFormatIndexedColor. It allows to set a color table so this breaks the link and the object is no longer comparable by the pointer. In that case use Cast<PixelFormatIndexedColor>(pixelFormat) to check whether it's this type or not.

Public Member Functions
MAXON_METHOD Result< void >	Init (const PixelFormatGroup &group, const Char *shortName)

MAXON_METHOD Block< const ImageChannel >	GetChannels () const

MAXON_METHOD const PixelFormatGroup &	GetPixelFormatGroup () const

MAXON_METHOD Result< Pix * >	CreatePix (Int width, Int height, Int lineAlignment=1) const

template<typename TYPE >
MAXON_FUNCTION Result< TYPE * >	CreatePix (Int width, Int height, Int lineAlignment=1) const

MAXON_METHOD Int	GetChannelCount () const

MAXON_METHOD const ChannelOffsets &	GetChannelOffsets () const

MAXON_METHOD BITS	GetBitsPerPixel () const

MAXON_METHOD Int	GetBytesPerLine (Int width, Int lineAlignment) const

MAXON_METHOD Int	GetPackedPixelCount () const

MAXON_METHOD Bool	HasAlpha () const

MAXON_METHOD Result< Tuple< PixelFormat, Int > >	GetAlphaPixelFormat () const

MAXON_METHOD ColorSpace	GetColorSpace () const

MAXON_METHOD const ColorProfile &	GetDefaultColorProfile () const

MAXON_METHOD Result< CONVERTPIXELFUNC >	GetConvertPixelFunc (const PixelFormat &srcFormatPtr, const ChannelOffsets &srcChannelOffset, const ChannelOffsets &dstChannelOffset, const ColorProfile &srcColorProfile, ColorProfile *dstColorProfile, Bool forceColorProfileConversion, Bool &disableCaching) const

MAXON_METHOD Result< CONVERTPIXELFUNC >	GetConvertPixelFunc (const PixelFormat &srcFormatPtr, const ChannelOffsets &srcChannelOffset, const ChannelOffsets &dstChannelOffset, const ColorProfile &srcColorProfile, ColorProfile *dstColorProfile, Bool forceColorProfileConversion, COLORCONVERSIONFLAGS colorConversionFlags, Bool &disableCaching) const

MAXON_METHOD Result< void >	ConvertPixelFromSlow (const ImageMutableBuffer &dst, Int count, const ImageConstBuffer &src, const ColorProfile &srcColorProfile, ColorProfile *dstColorProfile, CONVERTPIXELFLAGS cflags, GETPIXELFLAGS flags) const

MAXON_METHOD Bool	IsIdenticalPixel (const ImageConstBuffer &a, const ImageConstBuffer &b, Int oneTolerance) const

MAXON_METHOD String	PixToString (const Pix *src) const

MAXON_METHOD Result< CONVERTPIXELFUNC >	GetConvertPixelFromFunc (const PixelFormat &srcFormatPtr, const ChannelOffsets &srcChannelOffset, const ChannelOffsets &dstChannelOffset, Bool fastSize, Bool &disableCaching) const

MAXON_METHOD Result< CONVERTPIXELFUNC >	GetConvertPixelToFunc (const PixelFormat &dstFormatPtr, const ChannelOffsets &dstChannelOffset, const ChannelOffsets &srcChannelOffset, Bool fastSize, Bool &disableCaching) const

MAXON_METHOD const Char *	GetShortName () const

Private Member Functions
	MAXON_INTERFACE (PixelFormatInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.image.interface.pixelformat")

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE	(	PixelFormatInterface	,
		MAXON_REFERENCE_COPY_ON_WRITE	,
		"net.maxon.image.interface.pixelformat"
	)

private

◆ Init()

MAXON_METHOD Result<void> Init	(	const PixelFormatGroup &	group,
		const Char *	shortName
	)

Private.

Parameters

[in]	group	TODO: (Tilo) please document.
[in]	shortName	Short name of the color format for diagnostic outputs.

Returns: OK on success.

◆ GetChannels()

MAXON_METHOD Block<const ImageChannel> GetChannels ( ) const

Returns a description of all the channels of this pixel format.

Returns: Block with the description of all channels.

◆ GetPixelFormatGroup()

MAXON_METHOD const PixelFormatGroup& GetPixelFormatGroup ( ) const

Returns the corresponding PixelFormatGroup.

◆ CreatePix() [1/2]

MAXON_METHOD Result<Pix*> CreatePix	(	Int	width,
		Int	height,
		Int	lineAlignment = `1`
	)		const

Allocates a buffer for a rectangle of pixels of this PixelFormat.

Parameters

[in]	width	Width of the rectangle.
[in]	height	Height of the rectangle.
[in]	lineAlignment	Alignment for each line. E.g. 4 means that each line is aligned to a byte count of 4.

Returns: Pointer to a memory block with the given size. You must free the memory using DeleteMem. You can access the Pixels by (pointer + yPos * GetBytesPerLine(width, lineAlignment) + GetBitsPerPixel().GetOffset(xPos)).

◆ CreatePix() [2/2]

MAXON_FUNCTION Result<TYPE*> CreatePix	(	Int	width,
		Int	height,
		Int	lineAlignment = `1`
	)		const

◆ GetChannelCount()

MAXON_METHOD Int GetChannelCount ( ) const

Returns the number of channels of the pixel format. E.g. RGB8i returns 3 for the 3 channels R, G and B.

◆ GetChannelOffsets()

MAXON_METHOD const ChannelOffsets& GetChannelOffsets ( ) const

Returns the offset in bits of each channel. The block is one element bigger then the channel count. offsets[GetChannelCount()] is identical to GetBitsPerPixel().

◆ GetBitsPerPixel()

MAXON_METHOD BITS GetBitsPerPixel ( ) const

Returns the size in bits of each pixel (the sum of all channels).

◆ GetBytesPerLine()

MAXON_METHOD Int GetBytesPerLine	(	Int	width,
		Int	lineAlignment
	)		const

Returns the number of bytes for a line with the given lineAlignment.

Parameters

[in]	width	Number of Pixels.
[in]	lineAlignment	Value to which a line should be aligned to (e.g. 4 would align the memory to Int32 borders).

Returns: The number of bytes for the requested number of bytes with the given alignment.

◆ GetPackedPixelCount()

MAXON_METHOD Int GetPackedPixelCount ( ) const

Returns the number of pixels that are packed together within this image format. This means that it's not possible to access chunks with smaller pixel counts than this value. e.g. yuv encoding packs 2 pixels into 4 bytes (Y0U0Y1V1) but the u and v value is the same for both pixels.

◆ HasAlpha()

MAXON_METHOD Bool HasAlpha ( ) const

Returns true if the pixel format supports alpha.

◆ GetAlphaPixelFormat()

MAXON_METHOD Result<Tuple<PixelFormat, Int> > GetAlphaPixelFormat ( ) const

Returns the alpha pixel format (PixelFormats::ALPHA::U8/GREY16I/GREY32F/GREY64F) if a alpha channel is present. The return value contains a Tuple with the alpha pixel format as first and the byteoffset as the 2nd parameter.

◆ GetColorSpace()

MAXON_METHOD ColorSpace GetColorSpace ( ) const

Returns the color space used by the pixel format.

◆ GetDefaultColorProfile()

MAXON_METHOD const ColorProfile& GetDefaultColorProfile ( ) const

Returns the default color space.

◆ GetConvertPixelFunc() [1/2]

MAXON_METHOD Result<CONVERTPIXELFUNC> GetConvertPixelFunc	(	const PixelFormat &	srcFormatPtr,
		const ChannelOffsets &	srcChannelOffset,
		const ChannelOffsets &	dstChannelOffset,
		const ColorProfile &	srcColorProfile,
		ColorProfile *	dstColorProfile,
		Bool	forceColorProfileConversion,
		Bool &	disableCaching
	)		const

Creates a CONVERTPIXELFUNC which is able to convert from a given srcFormatPtr to the own pixel format. The function builds dynamic code which converts the 2 pixel formats effectively from one into the other. This function is slow and should be cached. It uses spin locks internally.

Parameters

[in]	srcFormatPtr	The pixel format to convert from.
[in]	srcChannelOffset	Channel offset in bytes of the src pixel format.
[in]	dstChannelOffset	Channel offset in bytes of the destination (own) pixel format.
[in]	srcColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion.
[in,out]	dstColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion. Returns the effective destination color profile after the conversion is applied. If the color space of the source and dest pixel format is identical no color profile conversion is performed and the result is srcColorProfile. If the color spaces are different the resulting color profile is the same as dstColorProfile.
[in]	forceColorProfileConversion	True to force the color profile conversion even is the color space is identical, false will not perform color profile transformation if the color space is identical.
[out]	disableCaching	Set to true if the conversion must not be cached (e.g. because a color table is used like in the indexed pixel format). Otherwise let the value unchanged!

Returns: Closure to call directly to convert from one format to the other. This closure is only valid for the given channel offsets of both formats.

◆ GetConvertPixelFunc() [2/2]

MAXON_METHOD Result<CONVERTPIXELFUNC> GetConvertPixelFunc	(	const PixelFormat &	srcFormatPtr,
		const ChannelOffsets &	srcChannelOffset,
		const ChannelOffsets &	dstChannelOffset,
		const ColorProfile &	srcColorProfile,
		ColorProfile *	dstColorProfile,
		Bool	forceColorProfileConversion,
		COLORCONVERSIONFLAGS	colorConversionFlags,
		Bool &	disableCaching
	)		const

Creates a CONVERTPIXELFUNC which is able to convert from a given srcFormatPtr to the own pixel format. The function builds dynamic code which converts the 2 pixel formats effectively from one into the other. This function is slow and should be cached. It uses spin locks internally.

Parameters

[in]	srcFormatPtr	The pixel format to convert from.
[in]	srcChannelOffset	Channel offset in bytes of the src pixel format.
[in]	dstChannelOffset	Channel offset in bytes of the destination (own) pixel format.
[in]	srcColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion.
[in,out]	dstColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion. Returns the effective destination color profile after the conversion is applied. If the color space of the source and dest pixel format is identical no color profile conversion is performed and the result is srcColorProfile. If the color spaces are different the resulting color profile is the same as dstColorProfile.
[in]	forceColorProfileConversion	True to force the color profile conversion even is the color space is identical, false will not perform color profile transformation if the color space is identical.
[in]	colorConversionFlags	Colorconversion flags (with COLORCONVERSIONFLAGS::BLACKPOINTCOMPENSATION, this matches the function without this parameter).
[out]	disableCaching	Set to true if the conversion must not be cached (e.g. because a color table is used like in the indexed pixel format). Otherwise let the value unchanged!

Returns: Closure to call directly to convert from one format to the other. This closure is only valid for the given channel offsets of both formats.

◆ ConvertPixelFromSlow()

MAXON_METHOD Result<void> ConvertPixelFromSlow	(	const ImageMutableBuffer &	dst,
		Int	count,
		const ImageConstBuffer &	src,
		const ColorProfile &	srcColorProfile,
		ColorProfile *	dstColorProfile,
		CONVERTPIXELFLAGS	cflags,
		GETPIXELFLAGS	flags
	)		const

Converts Pixels from one format into another. This is a convenience function. This function is not as fast pixelFormat.GetConvertPixelFunc() followed by calls of the returned closure.

Parameters

[in]	dst	ImageMutableBuffer of the destination data/format.
[in]	count	Number of pixels to convert.
[in]	src	ImageConstBuffer of the source data/format.
[in]	srcColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion.
[in,out]	dstColorProfile	Optional parameter which is only necessary if the color spaces of the given pixel formats doesn't match. In that case the conversion will be performed using the correct color conversion. Returns the effective destination color profile after the conversion is applied. If the color space of the source and dest pixel format is identical no color profile conversion is performed and the result is srcColorProfile. If the color spaces are different the resulting color profile is the same as dstColorProfile.
[in]	cflags	Flags to control the conversion. See CONVERTPIXELFLAGS.
[in]	flags	Flags to control the conversion. See GETPIXELFLAGS;.

Returns: OK on success.

◆ IsIdenticalPixel()

MAXON_METHOD Bool IsIdenticalPixel	(	const ImageConstBuffer &	a,
		const ImageConstBuffer &	b,
		Int	oneTolerance
	)		const

Compares 2 pixels. Both pixels must be in the same pixel format!

Parameters

[in]	a	ImageConstBuffer pointing to the first pixel.
[in]	b	ImageConstBuffer pointing to the second pixel.
[in]	oneTolerance	True if a tolerance of one digit is allowed. Tolerances can happen when converting from formats with different resolutions.

Returns: True if the pixels are identical.

◆ PixToString()

MAXON_METHOD String PixToString ( const Pix * src ) const

Converts a pixel into a readable format.

Parameters

[in] src Pointer to the data of one packed pixel.

Returns: String representation of the pixel.

◆ GetConvertPixelFromFunc()

MAXON_METHOD Result<CONVERTPIXELFUNC> GetConvertPixelFromFunc	(	const PixelFormat &	srcFormatPtr,
		const ChannelOffsets &	srcChannelOffset,
		const ChannelOffsets &	dstChannelOffset,
		Bool	fastSize,
		Bool &	disableCaching
	)		const

For overloading in your own implementation. do not call from outside!

Parameters

[in]	srcFormatPtr	TODO: (Tilo) please document.
[in]	srcChannelOffset	TODO: (Tilo) please document.
[in]	dstChannelOffset	TODO: (Tilo) please document.
[in]	fastSize	TODO: (Tilo) please document.
[out]	disableCaching	Set to true if the conversion must not be cached (e.g. because a color table is used like in the indexed pixel format). Otherwise let the value unchanged!

Returns: Conversion function or nullptr if no conversion found. An error will only be returned in case of a real error (out of memory etc).

◆ GetConvertPixelToFunc()

MAXON_METHOD Result<CONVERTPIXELFUNC> GetConvertPixelToFunc	(	const PixelFormat &	dstFormatPtr,
		const ChannelOffsets &	dstChannelOffset,
		const ChannelOffsets &	srcChannelOffset,
		Bool	fastSize,
		Bool &	disableCaching
	)		const

For overloading in your own implementation. do not call from outside!

Parameters

[in]	dstFormatPtr	TODO: (Tilo) please document.
[in]	dstChannelOffset	TODO: (Tilo) please document.
[in]	srcChannelOffset	TODO: (Tilo) please document.
[in]	fastSize	TODO: (Tilo) please document.
[out]	disableCaching	Set to true if the conversion must not be cached (e.g. because a color table is used like in the indexed pixel format). Otherwise let the value unchanged!

Returns: Conversion function or nullptr if no conversion found. An error will only be returned in case of a real error (out of memory etc.).

◆ GetShortName()

MAXON_METHOD const Char* GetShortName ( ) const

Returns the short name set in the init function.

Detailed Description

Public Member Functions

Private Member Functions

Member Function Documentation

◆ MAXON_INTERFACE()

◆ Init()

◆ GetChannels()

◆ GetPixelFormatGroup()

◆ CreatePix() [1/2]

◆ CreatePix() [2/2]

◆ GetChannelCount()

◆ GetChannelOffsets()

◆ GetBitsPerPixel()

◆ GetBytesPerLine()

◆ GetPackedPixelCount()

◆ HasAlpha()

◆ GetAlphaPixelFormat()

◆ GetColorSpace()

◆ GetDefaultColorProfile()

◆ GetConvertPixelFunc() [1/2]

◆ GetConvertPixelFunc() [2/2]

◆ ConvertPixelFromSlow()

◆ IsIdenticalPixel()

◆ PixToString()

◆ GetConvertPixelFromFunc()

◆ GetConvertPixelToFunc()

◆ GetShortName()