Skip to content

TBLImage

2D raster image.

Raster image holds pixel data and additional information such as pixel format. The underlying image data can be shared between multiple instances of TBLImage, which can be used by multiple threads. Atomic reference counting is used to safely manage the internal reference count of the underlying image data.

When an image is copied to another TBLImage instance its called a weak-copy as the underlying data is not copied, but the reference count is increased instead (atomically).

Definition

Unit: Blend2D

type TBLImage = record ... end;

Properties

Name Description
Depth Image depth (in bits).
Format The image format.
Height Image height (in pixels).
IsEmpty Whether the image is empty (such image has no size and a pixel format is equal to TBLFormat.None.
Size Image size (in pixels).
Width Image width (in pixels).

Constructors

Name Description
Assign Creates a weak copy of ASrc image by incrementing the reference count of the underlying representation.
Create Creates a new image data of [AWidth, AHeight] size (specified in pixels) having the given pixel AFormat.
Finalize Destroys the image data held by the instance.
Initialize Creates a default constructed image, which is an empty image having

Operators

Name Description
Equal(TBLImage, TBLImage) Tests whether the ALeft image is equal with ARight image. See Equals for more details about image equality.
Equal(TBLImage, Pointer) Used to compare against nil.
NotEqual(TBLImage, TBLImage) Tests whether the ALeft image is not equal with ARight image. See Equals for more details about image equality.
NotEqual(TBLImage, Pointer) Used to compare against nil.

Methods

Name Description
AssignDeep Create a deep copy of the AOther image.
AssignShallow Copy assignment replaces the underlying data of this image with AOther.
Convert Converts the image to a different pixel AFormat.
Equals Tests whether the image is equal to AOther image.
GetData Returns immutable in ADataOut, which contains pixel pointer, stride, and other image properties like size and pixel format.
Make Creates a new image of a specified 'AWidth,AHeight, andAFormat`.
MakeFromData Creates a new image from external data passed in APixelData.
MakeMutable Makes the image data mutable and returns them in ADataOut.
ReadFromData(TBLArrayView<Byte>, TBLArray<TBLImageCodec>) Reads an image from an existing byte-view passed via AView by using image codecs passed via ACodecs parameter.
ReadFromData(TBLArrayView<Byte>) Reads an image from an existing byte-view passed via AView.
ReadFromData(TBytes, TBLArray<TBLImageCodec>) Reads an image from an existing byte-buffer passed via AArray by using image codecs passed via ACodecs parameter.
ReadFromData(TBytes) Reads an image from an existing byte-buffer passed via AArray.
ReadFromData(TBLArray<Byte>, TBLArray<TBLImageCodec>) Reads an image from an existing byte-buffer passed via AArray by using image codecs passed via ACodecs parameter.
ReadFromData(TBLArray<Byte>) Reads an image from an existing byte-buffer passed via AArray.
ReadFromData(Pointer, NativeInt, TBLArray<TBLImageCodec>) Reads an image from an existing byte-array starting at AData and having ASize bytes by using image codecs passed via ACodecs parameter.
ReadFromData(Pointer, NativeInt) Reads an image from an existing byte-array starting at AData and having ASize bytes.
ReadFromFile(String, TBLArray<TBLImageCodec>) Reads an image from a file specified by AFilename by using image codecs passed via ACodecs parameter.
ReadFromFile(String) Reads an image from a file specified by AFileName.
Reset Resets the image to a default constructed image.
Scale Scales the ASrc image to the specified ASize by using AFilter and writes the scaled image to ADst.
Swap Swaps the underlying data with the AOther image.
WriteToData(TBLImageCodec) Encodes the image using the specified image ACodec and returns the encoded data.
WriteToData(TBLArray<Byte>, TBLImageCodec) Writes an encoded image to a buffer ADst using the specified image ACodec to encode the image.
WriteToFile(String, TBLImageCodec) Writes an encoded image to a file specified by AFileName using the specified image ACodec to encode the image.
WriteToFile(String) Writes an encoded image to a file specified by AFilename.

Property Descriptions

Depth

Image depth (in bits).

property Depth: Integer read GetDepth

Type: Integer


Format

The image format.

property Format: TBLFormat read GetFormat

Type: TBLFormat

See Also

Remarks

When an image IsEmpty, the pixel format returned is always TBLFormat.None.


Height

Image height (in pixels).

property Height: Integer read GetHeight

Type: Integer


IsEmpty

Whether the image is empty (such image has no size and a pixel format is equal to TBLFormat.None.

property IsEmpty: Boolean read GetIsEmpty

Type: Boolean

See Also


Size

Image size (in pixels).

property Size: TBLSizeI read GetSize

Type: TBLSizeI


Width

Image width (in pixels).

property Width: Integer read GetWidth

Type: Integer


Constructor Descriptions

Assign

Creates a weak copy of ASrc image by incrementing the reference count of the underlying representation.

constructor Assign(var ADest: TBLImage; const ASrc: TBLImage); inline

Parameters

ADest: TBLImage

ASrc: TBLImage

Exceptions

EBlend2DError: Raised on failure.


Create

Creates a new image data of [AWidth, AHeight] size (specified in pixels) having the given pixel AFormat.

To create a valid image, both AWidth and AHeight must be greater than zero and the pixel AFormat cannot be TBLFormat.None.

constructor Create(const AWidth, AHeight: Integer; const AFormat: TBLFormat)

Parameters

AWidth: Integer

AHeight: Integer

AFormat: TBLFormat

Exceptions

EBlend2DError: Raised on failure.


Finalize

Destroys the image data held by the instance.

The pixel data held by the image will only be deallocated if the reference count of the underlying representation gets decremented to zero.

destructor Finalize(var ADest: TBLImage)

Parameters

ADest: TBLImage

Exceptions

EBlend2DError: Raised on failure.


Initialize

Creates a default constructed image, which is an empty image having

constructor Initialize(out ADest: TBLImage)

Parameters

ADest: TBLImage

Exceptions

EBlend2DError: Raised on failure.

See Also


Operator Descriptions

Equal(TBLImage, TBLImage)

Tests whether the ALeft image is equal with ARight image. See Equals for more details about image equality.

class operator Equal(const ALeft, ARight: TBLImage): Boolean; inline; static

Parameters

ALeft: TBLImage

ARight: TBLImage

Returns

Boolean


Equal(TBLImage, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TBLImage; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TBLImage

ARight: Pointer

Returns

Boolean


NotEqual(TBLImage, TBLImage)

Tests whether the ALeft image is not equal with ARight image. See Equals for more details about image equality.

class operator NotEqual(const ALeft, ARight: TBLImage): Boolean; inline; static

Parameters

ALeft: TBLImage

ARight: TBLImage

Returns

Boolean


NotEqual(TBLImage, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TBLImage; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TBLImage

ARight: Pointer

Returns

Boolean


Method Descriptions

AssignDeep(TBLImage)

Create a deep copy of the AOther image.

procedure AssignDeep(const AOther: TBLImage); inline

Parameters

AOther: TBLImage


AssignShallow(TBLImage)

Copy assignment replaces the underlying data of this image with AOther.

procedure AssignShallow(const AOther: TBLImage); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AOther: TBLImage


Convert(TBLFormat)

Converts the image to a different pixel AFormat.

This operation could be lossy if the given pixel AFormat has less channels than this image.

procedure Convert(const AFormat: TBLFormat); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AFormat: TBLFormat

See Also

Remarks

If the image IsEmpty the image format would not be changed. It will stay TBLFormat.None and an error with code TBLResult.NotInitialized will be raised.


Equals(TBLImage)

Tests whether the image is equal to AOther image.

Images are equal when the size, pixel format, and pixel data match. This means that this operation could be very expensive if the images are large.

function Equals(const AOther: TBLImage): Boolean; inline

Parameters

AOther: TBLImage

Returns

Boolean


GetData(TBLImageData)

Returns immutable in ADataOut, which contains pixel pointer, stride, and other image properties like size and pixel format.

procedure GetData(out ADataOut: TBLImageData); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ADataOut: TBLImageData

See Also

Remarks

Although the data is filled in TBLImageData, which holds a PixelData pointer, the data is immutable. If you intend to modify the data, use MakeMutable method instead, which would copy the image data if it's shared with another TBLImage instance.


Make(Integer, Integer, TBLFormat)

Creates a new image of a specified 'AWidth,AHeight, andAFormat`.

procedure Make(const AWidth, AHeight: Integer; const AFormat: TBLFormat); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AWidth: Integer

AHeight: Integer

AFormat: TBLFormat

Remarks

If invalid arguments (invalid size or format) were passed to the method, an error with code TBLResult.InvalidValue will be returned and no data will be allocated. It's also important to notice that this method would not change anything if it fails (the previous image content would be kept as is in such case).


MakeFromData(Integer, Integer, TBLFormat, Pointer, IntPtr, TBLDataAccessFlags, TBLDestroyExternalDataFunc, Pointer)

Creates a new image from external data passed in APixelData.

Blend2D can use pixel-data allocated outside of Blend2D, which is useful for rendering into images that can be allocated by other libraries. The only thing that the user should pay extra attention to is the passed pixel AFormat and AStride.

If the image data you are passing is read-only, pass TBLDataAccessFlag.Read in AAccessFlags, in that case Blend2D would never attempt to modify the passed data and would create a copy instead if such image gets modified.

Additionally, if you would like to get notified about the destruction of the image (and thus Blend2D not holding the passed APixelData anymore, pass your own function in ADestroyFunc parameter with an optional AUserData).

procedure MakeFromData(const AWidth, AHeight: Integer; const AFormat: TBLFormat; const APixelData: Pointer; const AStride: IntPtr; const AAccessFlags: TBLDataAccessFlags = TBLDataAccessFlags.RW; const ADestroyFunc: TBLDestroyExternalDataFunc = nil; const AUserData: Pointer = nil); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AWidth: Integer

AHeight: Integer

AFormat: TBLFormat

APixelData: Pointer

AStride: IntPtr

AAccessFlags: TBLDataAccessFlags = TBLDataAccessFlags.RW

ADestroyFunc: TBLDestroyExternalDataFunc = nil

AUserData: Pointer = nil


MakeMutable(TBLImageData)

Makes the image data mutable and returns them in ADataOut.

procedure MakeMutable(out ADataOut: TBLImageData); inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ADataOut: TBLImageData


ReadFromData(TBLArrayView<Byte>, TBLArray<TBLImageCodec>)

Reads an image from an existing byte-view passed via AView by using image codecs passed via ACodecs parameter.

Image reader will automatically detect the image format by checking whether it's supported by the passed image ACodecs - only codecs passed in will be considered.

procedure ReadFromData(const AView: TBLArrayView<Byte>; const ACodecs: TBLArray<TBLImageCodec>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AView: TBLArrayView<Byte>

ACodecs: TBLArray<TBLImageCodec>


ReadFromData(TBLArrayView<Byte>)

Reads an image from an existing byte-view passed via AView.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by TBLImageCodec.BuiltInCodecs.

procedure ReadFromData(const AView: TBLArrayView<Byte>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AView: TBLArrayView<Byte>

See Also


ReadFromData(TBytes, TBLArray<TBLImageCodec>)

Reads an image from an existing byte-buffer passed via AArray by using image codecs passed via ACodecs parameter.

Image reader will automatically detect the image format by checking whether it's supported by the passed image ACodecs - only codecs passed in will be considered.

procedure ReadFromData(const AArray: TBytes; const ACodecs: TBLArray<TBLImageCodec>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AArray: TBytes

ACodecs: TBLArray<TBLImageCodec>


ReadFromData(TBytes)

Reads an image from an existing byte-buffer passed via AArray.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by TBLImageCodec.BuiltInCodecs.

procedure ReadFromData(const AArray: TBytes); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AArray: TBytes

See Also


ReadFromData(TBLArray<Byte>, TBLArray<TBLImageCodec>)

Reads an image from an existing byte-buffer passed via AArray by using image codecs passed via ACodecs parameter.

Image reader will automatically detect the image format by checking whether it's supported by the passed image ACodecs - only codecs passed in will be considered.

procedure ReadFromData(const AArray, ACodecs: TBLArray<TBLImageCodec>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AArray: TBLArray<Byte>

ACodecs: TBLArray<TBLImageCodec>


ReadFromData(TBLArray<Byte>)

Reads an image from an existing byte-buffer passed via AArray.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by TBLImageCodec.BuiltInCodecs.

procedure ReadFromData(const AArray: TBLArray<Byte>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AArray: TBLArray<Byte>

See Also


ReadFromData(Pointer, NativeInt, TBLArray<TBLImageCodec>)

Reads an image from an existing byte-array starting at AData and having ASize bytes by using image codecs passed via ACodecs parameter.

Image reader will automatically detect the image format by checking whether it's supported by the passed image ACodecs - only codecs passed in will be considered.

procedure ReadFromData(const AData: Pointer; const ASize: NativeInt; const ACodecs: TBLArray<TBLImageCodec>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AData: Pointer

ASize: NativeInt

ACodecs: TBLArray<TBLImageCodec>


ReadFromData(Pointer, NativeInt)

Reads an image from an existing byte-array starting at AData and having ASize bytes.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by TBLImageCodec.BuiltInCodecs.

procedure ReadFromData(const AData: Pointer; const ASize: NativeInt); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AData: Pointer

ASize: NativeInt

See Also


ReadFromFile(String, TBLArray<TBLImageCodec>)

Reads an image from a file specified by AFilename by using image codecs passed via ACodecs parameter.

Image reader will automatically detect the image format by checking whether it's supported by the passed image ACodecs - only codecs passed in will be considered.

procedure ReadFromFile(const AFilename: String; const ACodecs: TBLArray<TBLImageCodec>); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AFilename: String

ACodecs: TBLArray<TBLImageCodec>


ReadFromFile(String)

Reads an image from a file specified by AFileName.

Image reader will automatically detect the image format by checking whether it's supported by available image codecs, which can be retrieved by TBLImageCodec.BuiltInCodecs.

procedure ReadFromFile(const AFilename: String); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AFilename: String

See Also


Reset

Resets the image to a default constructed image.

A default constructed image has zero size and a pixel format equal to TBLFormat.None. Such image is considered IsEmpty and holds no data that could be used by the rendering context or as a pattern.

procedure Reset; inline

Exceptions

EBlend2DError: Raised on failure.

See Also


Scale(TBLImage, TBLImage, TBLSizeI, TBLImageScaleFilter)

Scales the ASrc image to the specified ASize by using AFilter and writes the scaled image to ADst.

If the destination image ADst doesn't match ASize and the source pixel format the underlying image data will be re-created.

class procedure Scale(const ADst, ASrc: TBLImage; const ASize: TBLSizeI; const AFilter: TBLImageScaleFilter); inline; static

Exceptions

EBlend2DError: Raised on failure.

Parameters

ADst: TBLImage

ASrc: TBLImage

ASize: TBLSizeI

AFilter: TBLImageScaleFilter


Swap(TBLImage)

Swaps the underlying data with the AOther image.

procedure Swap(var AOther: TBLImage); inline

Parameters

AOther: TBLImage


WriteToData(TBLImageCodec)

Encodes the image using the specified image ACodec and returns the encoded data.

function WriteToData(const ACodec: TBLImageCodec): TBytes; overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ACodec: TBLImageCodec

Returns

TBytes


WriteToData(TBLArray<Byte>, TBLImageCodec)

Writes an encoded image to a buffer ADst using the specified image ACodec to encode the image.

procedure WriteToData(const ADst: TBLArray<Byte>; const ACodec: TBLImageCodec); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

ADst: TBLArray<Byte>

ACodec: TBLImageCodec


WriteToFile(String, TBLImageCodec)

Writes an encoded image to a file specified by AFileName using the specified image ACodec to encode the image.

procedure WriteToFile(const AFilename: String; const ACodec: TBLImageCodec); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AFilename: String

ACodec: TBLImageCodec


WriteToFile(String)

Writes an encoded image to a file specified by AFilename.

Image writer detects the image codec by inspecting the extension of a file passed via AFilename.

procedure WriteToFile(const AFilename: String); overload; inline

Exceptions

EBlend2DError: Raised on failure.

Parameters

AFilename: String