The FBlock class provides a mean of storing and manipulating digital images in various formats, with direct access to pixel data. More...

Inheritance diagram for FBlock:

Public Member Functions
	FBlock (const FBlock &)=delete

	FBlock (uint16 iWidth, uint16 iHeight, eFormat iFormat=eFormat::Format_RGBA8, const FColorSpace *iColorSpace=nullptr, const FOnInvalidBlock &iOnInvalid=FOnInvalidBlock(), const FOnCleanupData &iOnCleanup=FOnCleanupData(&OnCleanup_FreeMemory))

	FBlock (uint8 iData=nullptr, uint16 iWidth=0, uint16 iHeight=0, eFormat iFormat=eFormat::Format_RGBA8, const FColorSpace iColorSpace=nullptr, const FOnInvalidBlock &iOnInvalid=FOnInvalidBlock(), const FOnCleanupData &iOnCleanup=FOnCleanupData())

	~FBlock ()

uint8 *	Bits ()

const uint8 *	Bits () const

uint32	BytesPerPlane () const

uint32	BytesPerScanLine () const

uint64	BytesTotal () const

FColor	Color (uint16 iX, uint16 iY) const

uint32	CRC32 () const

void	Dirty (bool iCallOnInvalid=true) const

void	Dirty (const FRectI &iRect, bool iCallOnInvalid=true) const

void	Dirty (const FRectI *iRectList, const uint32 iNumRects=1, bool iCallOnInvalid=true) const

bool	IsHollow () const

void	LoadFromData (uint8 iData, uint16 iWidth, uint16 iHeight, eFormat iFormat, const FColorSpace iColorSpace=nullptr, const FOnInvalidBlock &iOnInvalid=FOnInvalidBlock(), const FOnCleanupData &iOnCleanup=FOnCleanupData())

FBlock	MakeHollow ()

const FOnCleanupData &	OnCleanup () const

void	OnCleanup (const FOnCleanupData &iOnCleanup)

const FOnInvalidBlock &	OnInvalid () const

void	OnInvalid (const FOnInvalidBlock &iOnInvalid)

FBlock &	operator= (const FBlock &)=delete

FPixel	Pixel (uint16 iX, uint16 iY)

const FPixel	Pixel (uint16 iX, uint16 iY) const

uint8 *	PixelBits (uint16 iX, uint16 iY)

const uint8 *	PixelBits (uint16 iX, uint16 iY) const

uint8 *	PlaneBits (uint16 iPlane)

const uint8 *	PlaneBits (uint16 iPlane) const

void	ReallocInternalData (uint16 iWidth, uint16 iHeight, eFormat iFormat, const FColorSpace *iColorSpace=nullptr, const FOnInvalidBlock &iOnInvalid=FOnInvalidBlock(), const FOnCleanupData &iOnCleanup=FOnCleanupData())

FColor	Sample (int16 iX, int16 iY, eBorderMode iBorderMode=eBorderMode::Border_Transparent, const FColor &iConstant=FColor::Transparent) const

FColor	SampleSubpixel (float iX, float iY, eBorderMode iBorderMode=eBorderMode::Border_Transparent, const FColor &iConstant=FColor::Transparent, bool iCompensateBlackDrifting=true) const

uint8 *	ScanlineBits (uint16 iRow)

const uint8 *	ScanlineBits (uint16 iRow) const

void	SetPixel (uint16 iX, uint16 iY, const ISample &iSample)

void	SetPixelSafe (uint16 iX, uint16 iY, const ISample &iSample)

Public Member Functions inherited from IHasFormat
	~IHasFormat ()

uint8	AlphaIndex () const

uint8	BytesPerPixel () const

uint8	BytesPerSample () const

uint8	DefaultProfileCode () const

eFormat	Format () const

const FFormatMetrics &	FormatMetrics () const

bool	HasAlpha () const

const uint8 *	IndexTable () const

bool	Linear () const

eColorModel	Model () const

uint8	NumColorChannels () const

bool	Planar () const

bool	Premultiplied () const

uint8	RedirectedIndex (uint8 iIndex) const

bool	Reversed () const

uint8	SamplesPerPixel () const

bool	Swapped () const

eType	Type () const

Public Member Functions inherited from IHasColorSpace
	~IHasColorSpace ()

void	AssignColorSpace (const FColorSpace *iColorSpace)

const FColorSpace *	ColorSpace () const

Public Member Functions inherited from IHasSize2D
	~IHasSize2D ()

uint32	Area () const

uint16	Height () const

FRectI	Rect () const

FVec2I	Size () const

uint16	Width () const

Protected Attributes
uint8 *	mBitmap
	Contiguous memory storage buffer for the block. More...

uint32	mBytesPerPlane
	Cached number of bytes per plane. More...

uint32	mBytesPerScanline
	Cached number of bytes per scanline. More...

uint64	mBytesTotal
	Cached number of bytes for the whole buffer. More...

FOnCleanupData	mOnCleanup
	The callback for when the block is destroyed. More...

FOnInvalidBlock	mOnInvalid
	The callback for when the block is dirty. More...

Additional Inherited Members
Protected Member Functions inherited from IHasFormat
	IHasFormat (eFormat iFormat)

void	ReinterpretFormat (eFormat iFormat)

Protected Member Functions inherited from IHasColorSpace
	IHasColorSpace (const FColorSpace *iColorSpace=nullptr)

Protected Member Functions inherited from IHasSize2D
	IHasSize2D (const FVec2UI16 &iSize)

void	ReinterpretSize (const FVec2UI16 &iSize)

Detailed Description

FBlock is the primary class to use when manipulating images with ULIS.

The block has a format which specifies the type, memory layout, color model, and other informations about the image. The underlying data is always a regular contiguous buffer storage that lives on RAM with no alignment requirement.

The FBlock class is very lightweight, the memory load is in the data it points to, and the class never performs any kind of heavy operations. It does not communicate with the GPU or use any kind of hardware accelerated feature just by itself.

Copy, wether deep or shallow, is explicitly forbidden, If you need to copy image data, you can use the explicit Copy or XCopy functions that ULIS provides.

FBlock supports loading an external data pointer and treat it as its own storage: this is useful for sharing memory without having to copy it and you can grab or release ownership at any time with the help of the cleanup callbacks, just make sure to use the proper deallocator when providing external data which was allocated with a custom allocator. However the data is not reference counted.

You can also provide custom callbacks to signal when the block is dirty, for example use it to upload a small rect of the image to a GPU texture when triggered.

It is perfectly fine to create FBlock objects on the stack:

    { // Begin local scope
        FBlock image( 64, 64, eFormat::Format_RGBA8 );
        // Work with your image.
    } // End local scope, image is destroyed and so is the underlying data.

But you can also allocate blocks dynamically:

    FBlock* image = new FBlock( 64, 64, eFormat::Format_RGBA8 );
    // Work with your image.
    delete  image;

Constructor & Destructor Documentation

◆ ~FBlock()

FBlock::~FBlock ( )

Destroy the block and invoke the cleanup callback.

◆ FBlock() [1/3]

FBlock::FBlock	(	uint16	iWidth,
		uint16	iHeight,
		eFormat	iFormat = `eFormat::Format_RGBA8`,
		const FColorSpace *	iColorSpace = `nullptr`,
		const FOnInvalidBlock &	iOnInvalid = `FOnInvalidBlock()`,
		const FOnCleanupData &	iOnCleanup = `FOnCleanupData(&OnCleanup_FreeMemory)`
	)

Construct a block with input size and format.

The underlying bitmap data will be allocated with enough storage space as required by the size and format depth. The data is left uninitialized.

Warning: The iWidth and iHeight parameters should be greater than zero. A block doesn't own nor manage lifetime of its color-space.

◆ FBlock() [2/3]

FBlock::FBlock	(	uint8 *	iData = `nullptr`,
		uint16	iWidth = `0`,
		uint16	iHeight = `0`,
		eFormat	iFormat = `eFormat::Format_RGBA8`,
		const FColorSpace *	iColorSpace = `nullptr`,
		const FOnInvalidBlock &	iOnInvalid = `FOnInvalidBlock()`,
		const FOnCleanupData &	iOnCleanup = `FOnCleanupData()`
	)

Construct a block from an existing external buffer with input size and format.

The input buffer data is used and no allocation is done here, if coherent visual data was present in the buffer it will remain as is. Make sure to chose the appropriate size and format, given the buffer length. Bad values could result in misinterpreting the visual information or accessing the buffer out of bounds and crash or corrupt memory.

Warning: The block will not delete the external input data by default, unless you provide and appropriate cleanup callback to handle that. The data can be shared with other representations but it must remain valid at least as long as the block lifetime.; The iWidth and iHeight parameters should be greater than zero. A block doesn't own nor manage lifetime of its color-space.

◆ FBlock() [3/3]

FBlock::FBlock ( const FBlock & )

delete

explicitly disabled copy constructor.

If you need to make a shallow copy with shared image data, use the explicit constructor from external data.

If you need to make a deep copy of the image data, use the explicit Copy or XCopy functions that ULIS provides.

Member Function Documentation

◆ Bits() [1/2]

uint8* FBlock::Bits ( )

Obtain a pointer to the raw data at the base element of the underlying image buffer.

This data is the same as the one used by the block. It is non-const and can be modified safely, as long as you don't dereference elements outside of the buffer boundaries, or trigger race conditions when applying multithreaded operations on the same data.

See also: ScanlineBits(); PixelBits()

◆ Bits() [2/2]

const uint8* FBlock::Bits ( ) const

Obtain a pointer to the raw data at the base element of the underlying image buffer.

This data is the same as the one used by the block. It is const so it cannot be modified, but it can be read freely, as long as you don't dereference elements outside of the buffer boundaries.

See also: ScanlineBits(); PixelBits()

◆ BytesPerPlane()

uint32 FBlock::BytesPerPlane ( ) const

Return the numbers of bytes per plane

See also: BytesTotal(); BytesPerScanLine()

◆ BytesPerScanLine()

uint32 FBlock::BytesPerScanLine ( ) const

Return the numbers of bytes per scanline

See also: BytesTotal()

◆ BytesTotal()

uint64 FBlock::BytesTotal ( ) const

Return the total numbers of bytes in the block.

See also: BytesPerScanLine()

◆ Color()

FColor FBlock::Color	(	uint16	iX,
		uint16	iY
	)		const

Return the color of the pixel at the given coordinates.

The FColor is a copy of the pixel data, safe to read and write without altering the block contents.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Pixel(); PixelBits(); FColor

◆ CRC32()

uint32 FBlock::CRC32 ( ) const

Get CRC32 Hash for Tile

◆ Dirty() [1/3]

void FBlock::Dirty ( bool iCallOnInvalid = true ) const

Dirty the entire block and trigger the invalid callback if set.

The optional iCallOnInvalid parameter can be set to false in order to conditionaly disable the callback trigger depending on your needs.

In the case of many successive calls to dirty, it can be more efficient to just disable them first and call it only once later.

◆ Dirty() [2/3]

void FBlock::Dirty	(	const FRectI &	iRect,
		bool	iCallOnInvalid = `true`
	)		const

Dirty a part of the block according to the input rect and trigger the invalid callback if set.

The optional iCallOnInvalid parameter can be set to false in order to conditionaly disable the callback trigger depending on your needs.

In the case of many successive calls to dirty with different small geometries, it can be more efficient to just disable them first and call it only once later with the union of all invalid rects, or use the array version of the Dirty function.

◆ Dirty() [3/3]

void FBlock::Dirty	(	const FRectI *	iRectList,
		const uint32	iNumRects = `1`,
		bool	iCallOnInvalid = `true`
	)		const

Dirty parts of the block from the input array of rects and trigger the invalid callback if set.

The optional iCallOnInvalid parameter can be set to false in order to conditionaly disable the callback trigger depending on your needs.

◆ IsHollow()

bool FBlock::IsHollow ( ) const

Check wether a block is hollow.

◆ LoadFromData()

void FBlock::LoadFromData	(	uint8 *	iData,
		uint16	iWidth,
		uint16	iHeight,
		eFormat	iFormat,
		const FColorSpace *	iColorSpace = `nullptr`,
		const FOnInvalidBlock &	iOnInvalid = `FOnInvalidBlock()`,
		const FOnCleanupData &	iOnCleanup = `FOnCleanupData()`
	)

Reconstruct the internal representation from an existing external buffer with input size and format.

If a cleanup callback was setup, it will be called beforehand, effectively cleaning the data if needed. Although the format might change, references to the format info object itself are not invalidated.

See also: FBlock()

◆ MakeHollow()

FBlock FBlock::MakeHollow ( )

Construct a hollow block with no internal data or size.

◆ OnCleanup() [1/2]

const FOnCleanupData& FBlock::OnCleanup ( ) const

Optain the cleanup callback for convenience when reloading data or propagating.

See also: OnCleanup()

◆ OnCleanup() [2/2]

void FBlock::OnCleanup ( const FOnCleanupData & iOnCleanup )

Set a new cleanup callback that will be called on destruction.

See also: OnInvalid()

◆ OnInvalid() [1/2]

const FOnInvalidBlock& FBlock::OnInvalid ( ) const

Optain the invalid callback for convenience when reloading data or propagating.

See also: OnCleanup()

◆ OnInvalid() [2/2]

void FBlock::OnInvalid ( const FOnInvalidBlock & iOnInvalid )

Set a new invalid callback that will be called on dirty.

See also: OnCleanup()

◆ operator=()

FBlock& FBlock::operator= ( const FBlock & )

delete

explicitly disabled copy assignment operator.

If you need to make a shallow copy with shared image data, use the explicit constructor from external data.

If you need to make a deep copy of the image data, use the explicit Copy or XCopy functions that ULIS provides.

◆ Pixel() [1/2]

FPixel FBlock::Pixel	(	uint16	iX,
		uint16	iY
	)

Return the pixel at the given coordinates.

The FPixel is an implicitely shared representation of the block data at the input pixel location, if you modify it you will alter the contents of the block. It is sometimes more convenient than PixelBits() in order to read or modify the values, and does not perform a copy.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Color(); PixelBits(); FPixel

◆ Pixel() [2/2]

const FPixel FBlock::Pixel	(	uint16	iX,
		uint16	iY
	)		const

Return the const pixel at the given coordinates.

The FPixel is an implicitely shared representation of the block data at the input pixel location It is sometimes more convenient than PixelBits() in order to read the values, and does not perform a copy.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Color(); PixelBits(); FPixel

◆ PixelBits() [1/2]

uint8* FBlock::PixelBits	(	uint16	iX,
		uint16	iY
	)

Obtain a pointer to the raw data at the specified pixel location of the underlying image buffer.

This data is the same as the one used by the block. It is non-const and can be modified safely, as long as you don't dereference elements outside of the buffer boundaries, or trigger race conditions when applying multithreaded operations on the same data.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Bits(); ScanlineBits()

◆ PixelBits() [2/2]

const uint8* FBlock::PixelBits	(	uint16	iX,
		uint16	iY
	)		const

Obtain a pointer to the raw data at the specified pixel location of the underlying image buffer.

This data is the same as the one used by the block. It is const so it cannot be modified, but it can be read freely, as long as you don't dereference elements outside of the buffer boundaries.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Bits(); ScanlineBits()

◆ PlaneBits() [1/2]

uint8* FBlock::PlaneBits ( uint16 iPlane )

Obtain a pointer to the raw data at the specified plane element of the underlying image buffer.

This data is the same as the one used by the block. It is non-const and can be modified safely, as long as you don't dereference elements outside of the buffer boundaries, or trigger race conditions when applying multithreaded operations on the same data.

Warning: If you specify a plane that is negative or bigger than the block sample count, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds , leading to potential memory corruption or crashes further down the line.

See also: Bits(); PixelBits(); ScanlineBits()

◆ PlaneBits() [2/2]

const uint8* FBlock::PlaneBits ( uint16 iPlane ) const

Obtain a pointer to the raw data at the specified plane element of the underlying image buffer.

This data is the same as the one used by the block. It is non-const and can be modified safely, as long as you don't dereference elements outside of the buffer boundaries, or trigger race conditions when applying multithreaded operations on the same data.

Warning: If you specify a plane that is negative or bigger than the block sample count, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds , leading to potential memory corruption or crashes further down the line.

See also: Bits(); PixelBits(); ScanlineBits()

◆ ReallocInternalData()

void FBlock::ReallocInternalData	(	uint16	iWidth,
		uint16	iHeight,
		eFormat	iFormat,
		const FColorSpace *	iColorSpace = `nullptr`,
		const FOnInvalidBlock &	iOnInvalid = `FOnInvalidBlock()`,
		const FOnCleanupData &	iOnCleanup = `FOnCleanupData()`
	)

Reconstruct the internal representation with input size and format.

If a cleanup callback was setup, it will be called beforehand, effectively cleaning the data if needed. Although the format might change, references to the format info object itself are not invalidated.

See also: FBlock()

◆ Sample()

FColor FBlock::Sample	(	int16	iX,
		int16	iY,
		eBorderMode	iBorderMode = `eBorderMode::Border_Transparent`,
		const FColor &	iConstant = `FColor::Transparent`
	)		const

Return the color sample at the given coordinates.

The FColor has its own storage that represents a subpixel color, safe to read and write without altering the block contents.

See also: Pixel(); PixelBits(); FColor

◆ SampleSubpixel()

FColor FBlock::SampleSubpixel	(	float	iX,
		float	iY,
		eBorderMode	iBorderMode = `eBorderMode::Border_Transparent`,
		const FColor &	iConstant = `FColor::Transparent`,
		bool	iCompensateBlackDrifting = `true`
	)		const

Return the color at the given subpixel coordinates.

The FColor has its own storage that represents a subpixel color, safe to read and write without altering the block contents.

See also: Pixel(); PixelBits(); FColor

◆ ScanlineBits() [1/2]

uint8* FBlock::ScanlineBits ( uint16 iRow )

Obtain a pointer to the raw data at the specified scanline row element of the underlying image buffer.

This data is the same as the one used by the block. It is non-const and can be modified safely, as long as you don't dereference elements outside of the buffer boundaries, or trigger race conditions when applying multithreaded operations on the same data.

Warning: If you specify a row that is negative or bigger than the block height, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds , leading to potential memory corruption or crashes further down the line.

See also: Bits(); PixelBits()

◆ ScanlineBits() [2/2]

const uint8* FBlock::ScanlineBits ( uint16 iRow ) const

Obtain a pointer to the raw data at the specified scanline row element of the underlying image buffer.

This data is the same as the one used by the block. It is const so it cannot be modified, but it can be read freely, as long as you don't dereference elements outside of the buffer boundaries.

Warning: If you specify a row that is negative or bigger than the block height, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Bits(); PixelBits()

◆ SetPixel()

void FBlock::SetPixel	(	uint16	iX,
		uint16	iY,
		const ISample &	iSample
	)

Set the pixel at the given coordinates from input ISample. The sample will be converted to the appropriate format. This function is here for convenience but is not recommended to used for intensive raster tasks, as it does not provide any kind of optimizations.

Warning: If you specify X and Y coordinates that are either negative or bigger than the block width and height respectively, the function will trigger an assert and crash in debug builds, but it will fail silently and access the buffer out of bounds in release builds, leading to potential memory corruption or crashes further down the line.

See also: Color(); PixelBits(); ISample

◆ SetPixelSafe()

void FBlock::SetPixelSafe	(	uint16	iX,
		uint16	iY,
		const ISample &	iSample
	)

Set the pixel at the given coordinates from input ISample. The sample will be converted to the appropriate format. This function is here for convenience but is not recommended to used for intensive raster tasks, as it does not provide any kind of optimizations.

Safe version that checks if the pixel set is in the block bounds. Slow but useful in some cases. The usage of this function usually means that optimization is possible where it is used.

See also: Color(); PixelBits(); ISample

Member Data Documentation

◆ mBitmap

uint8* FBlock::mBitmap

protected

◆ mBytesPerPlane

uint32 FBlock::mBytesPerPlane

protected

◆ mBytesPerScanline

uint32 FBlock::mBytesPerScanline

protected

◆ mBytesTotal

uint64 FBlock::mBytesTotal

protected

◆ mOnCleanup

FOnCleanupData FBlock::mOnCleanup

protected

◆ mOnInvalid

FOnInvalidBlock FBlock::mOnInvalid

protected

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~FBlock()

◆ FBlock() [1/3]

◆ FBlock() [2/3]

◆ FBlock() [3/3]

Member Function Documentation

◆ Bits() [1/2]

◆ Bits() [2/2]

◆ BytesPerPlane()

◆ BytesPerScanLine()

◆ BytesTotal()

◆ Color()

◆ CRC32()

◆ Dirty() [1/3]

◆ Dirty() [2/3]

◆ Dirty() [3/3]

◆ IsHollow()

◆ LoadFromData()

◆ MakeHollow()

◆ OnCleanup() [1/2]

◆ OnCleanup() [2/2]

◆ OnInvalid() [1/2]

◆ OnInvalid() [2/2]

◆ operator=()

◆ Pixel() [1/2]

◆ Pixel() [2/2]

◆ PixelBits() [1/2]

◆ PixelBits() [2/2]

◆ PlaneBits() [1/2]

◆ PlaneBits() [2/2]

◆ ReallocInternalData()

◆ Sample()

◆ SampleSubpixel()

◆ ScanlineBits() [1/2]

◆ ScanlineBits() [2/2]

◆ SetPixel()

◆ SetPixelSafe()

Member Data Documentation

◆ mBitmap

◆ mBytesPerPlane

◆ mBytesPerScanline

◆ mBytesTotal

◆ mOnCleanup

◆ mOnInvalid