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
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, and AFormat`. |
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, and
AFormat`.
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