Class TRGBAlphaImage

Unit

CastleImages

Declaration

type TRGBAlphaImage = class(TCastleImage)

Description

An abstract class representing image as a simple array of pixels. RawPixels is a pointer to Width * Height * Depth of pixels.

What exactly is a "pixel" is undefined in this class. Each descendant of TCastleImage defines it's own pixel encoding and interpretation. The only requirement is that all pixels have the same size (PixelSize). For example, for TRGBImage a "pixel" is a TVector3Byte type representing a (red, green, blue) color value.

When Depth > 1, the image is actually a 3D (not just 2D!) image. We call the particular 2D layers then "slices". Although some TCastleImage methods (and functions in other units, like CastleGLImages) still operate only on the 1st "slice", that is the 2D image on Depth = 0 — be careful. But many methods correctly take the depth into consideration.

Pixels in RawPixels are ordered in slices, each slice is ordered in rows, in each row pixels are specified from left to right, rows are specified starting from lower row to upper. This means that you can think of RawPixels as

ˆ(packed array[0..Depth - 1, 0..Height - 1, 0..Width - 1] of TPixel)

Assuming the above definition, RawPixelsˆ[z, y, x] is color of pixel at position z, x, y.

Note that specifying rows from lower to upper follows an OpenGL standard, this makes using this unit with OpenGL straightforward.

Don't ever operate on RawPixels pointer directly — allocating, reallocating, freeing memory pointed to by RawPixels is handled inside this class. You must only worry to always free created TCastleImage instances (like with any class).

Note that the only valid states of instances of this class are when (Width * Height * Depth > 0 and RawPixels <> nil) or (Width * Height * Depth = 0 and RawPixels = nil). Otherwise the fundamental assumption that RawPixels is a pointer to Width * Height * Depth pixels would be broken (as nil pointer cannot point to anything, and on the other side it's rather useless to have a pointer to 0 bytes (since you can never dereference it anyway) even if theoretically every PtrInt value can be treated as valid pointer to 0 bytes).

Note about coordinates:

1. All X, Y, Z coordinates of pixels are 0-based (X in range 0..Width-1, and Y in 0..Height-1, and Z in 0..Depth-1).

2. If documentation for some method does not specify otherwise, correctness of coordinates is *not* checked in method, which can lead to various errors at runtime if you will pass incorrect coordinates to given routine.

Hierarchy

• TObject
• TEncodedImage
• TCastleImage
• TRGBAlphaImage

Overview

Methods

	procedure DrawFromCore(Source: TCastleImage; X, Y, SourceX, SourceY, SourceWidth, SourceHeight: Integer; const Mode: TDrawMode); override;
	function GetColors(const X, Y, Z: Integer): TCastleColor; override;
	procedure SetColors(const X, Y, Z: Integer; const C: TCastleColor); override;
	class function PixelSize: Cardinal; override;
	class function ColorComponentsCount: Cardinal; override;
	function PixelPtr(const X, Y: Cardinal; const Z: Cardinal = 0): PVector4Byte;
	function RowPtr(const Y: Cardinal; const Z: Cardinal = 0): PVector4ByteArray;
	procedure InvertColors; override;
	procedure Clear(const Pixel: TVector4Byte); override;
	function IsClear(const Pixel: TVector4Byte): boolean; override;
	procedure ClearAlpha(const Alpha: Byte);
	procedure TransformRGB(const Matrix: TMatrix3); override;
	procedure ModulateRGB(const ColorModulator: TColorModulatorByteFunc); override;
	procedure AlphaDecide(const AlphaColor: TVector3Byte; Tolerance: Byte; AlphaOnColor: Byte; AlphaOnNoColor: Byte);
	procedure Compose(RGB: TRGBImage; AGrayscale: TGrayscaleImage);
	function HasAlpha: boolean; override;
	function AlphaChannel( const AlphaTolerance: Byte): TAlphaChannel; override;
	procedure LerpWith(const Value: Single; SecondImage: TCastleImage); override;
	class procedure MixColors(const OutputColor: Pointer; const Weights: TVector4; const AColors: TVector4Pointer); override;
	procedure Assign(const Source: TCastleImage); override;
	function ToRGBImage: TRGBImage; deprecated 'create TRGBImage and use TRGBImage.Assign';
	function ToGrayscaleAlphaImage: TGrayscaleAlphaImage; deprecated 'create TGrayscaleAlphaImage and use TGrayscaleAlphaImage.Assign';
	function ToGrayscaleImage: TGrayscaleImage; deprecated 'create TGrayscaleImage and use TGrayscaleImage.Assign';
	function ToFpImage: TInternalCastleFpImage; override;
	procedure PremultiplyAlpha;
	procedure AlphaBleed(const ProgressTitle: string = ''); override;
	function MakeAlphaBleed(const ProgressTitle: string = ''): TCastleImage; override;
	procedure FillEllipse(const x, y: single; const aRadiusX, aRadiusY: single; const aColor: TCastleColor); override;
	procedure Ellipse(const x, y: single; const aRadiusX, aRadiusY: single; const aWidth: single; const aColor: TCastleColor); override;
	procedure FillRectangle(const x1, y1, x2, y2: single; const aColor: TCastleColor); override;
	procedure Rectangle(const x1, y1, x2, y2: single; const aWidth: single; const aColor: TCastleColor); override;
	procedure Line(const x1, y1, x2, y2: single; const aWidth: single; const aColor: TCastleColor); override;

Properties

	property Pixels: PVector4Byte read GetPixels;
	property AlphaPixels: PVector4Byte read GetPixels; deprecated 'use Pixels';
	property PixelsArray: PVector4ByteArray read GetPixelsArray;
	property PremultipliedAlpha: boolean read FPremultipliedAlpha;

Description

Methods

	procedure DrawFromCore(Source: TCastleImage; X, Y, SourceX, SourceY, SourceWidth, SourceHeight: Integer; const Mode: TDrawMode); override;

	function GetColors(const X, Y, Z: Integer): TCastleColor; override;

	procedure SetColors(const X, Y, Z: Integer; const C: TCastleColor); override;

	class function PixelSize: Cardinal; override;

	class function ColorComponentsCount: Cardinal; override;

	function PixelPtr(const X, Y: Cardinal; const Z: Cardinal = 0): PVector4Byte;

	function RowPtr(const Y: Cardinal; const Z: Cardinal = 0): PVector4ByteArray;

	procedure InvertColors; override;

	procedure Clear(const Pixel: TVector4Byte); override;

	function IsClear(const Pixel: TVector4Byte): boolean; override;

	procedure ClearAlpha(const Alpha: Byte);
Set alpha channel on every pixel to the same given value.

	procedure TransformRGB(const Matrix: TMatrix3); override;

	procedure ModulateRGB(const ColorModulator: TColorModulatorByteFunc); override;

	procedure AlphaDecide(const AlphaColor: TVector3Byte; Tolerance: Byte; AlphaOnColor: Byte; AlphaOnNoColor: Byte);
Set alpha of every pixel to either AlphaOnColor (when color of pixel is equal to AlphaColor with Tolerance, see EqualRGB) or AlphaOnNoColor.

	procedure Compose(RGB: TRGBImage; AGrayscale: TGrayscaleImage);
Copy RGB contents from one image, and alpha contents from the other. RGB channels are copied from the RGB image, alpha channel is copied from the Grayscale image. Given RGB and Grayscale images must have the same size, and this is the resulting size of this image after Compose call.

	function HasAlpha: boolean; override;

	function AlphaChannel( const AlphaTolerance: Byte): TAlphaChannel; override;

	procedure LerpWith(const Value: Single; SecondImage: TCastleImage); override;

	class procedure MixColors(const OutputColor: Pointer; const Weights: TVector4; const AColors: TVector4Pointer); override;

	procedure Assign(const Source: TCastleImage); override;

	function ToRGBImage: TRGBImage; deprecated 'create TRGBImage and use TRGBImage.Assign';
Warning: this symbol is deprecated: create TRGBImage and use TRGBImage.Assign Remove alpha channel.

	function ToGrayscaleAlphaImage: TGrayscaleAlphaImage; deprecated 'create TGrayscaleAlphaImage and use TGrayscaleAlphaImage.Assign';
Warning: this symbol is deprecated: create TGrayscaleAlphaImage and use TGrayscaleAlphaImage.Assign Flatten to grayscale.

	function ToGrayscaleImage: TGrayscaleImage; deprecated 'create TGrayscaleImage and use TGrayscaleImage.Assign';
Warning: this symbol is deprecated: create TGrayscaleImage and use TGrayscaleImage.Assign Flatten to grayscale and remove alpha channel.

	function ToFpImage: TInternalCastleFpImage; override;

procedure PremultiplyAlpha;

Premultiply the RGB channel with alpha, to make it faster to use this image as source for TCastleImage.DrawTo and TCastleImage.DrawFrom operations. Changes PremultipliedAlpha from False to True. Unless PremultipliedAlpha was already True, in which case this method does nothing — this way it is safe to call this many times, we will not repeat multiplying. The image with premultiplied alpha can only be used with a subset of image routines that actually support premultiplied alpha. Right now, these are only TCastleImage.DrawTo and TCastleImage.DrawFrom. Image with PremultipliedAlpha can be used as a source for drawing, and the results will be the same as without premultiplying, but faster.

	procedure AlphaBleed(const ProgressTitle: string = ''); override;

	function MakeAlphaBleed(const ProgressTitle: string = ''): TCastleImage; override;

	procedure FillEllipse(const x, y: single; const aRadiusX, aRadiusY: single; const aColor: TCastleColor); override;

	procedure Ellipse(const x, y: single; const aRadiusX, aRadiusY: single; const aWidth: single; const aColor: TCastleColor); override;

	procedure FillRectangle(const x1, y1, x2, y2: single; const aColor: TCastleColor); override;

	procedure Rectangle(const x1, y1, x2, y2: single; const aWidth: single; const aColor: TCastleColor); override;

	procedure Line(const x1, y1, x2, y2: single; const aWidth: single; const aColor: TCastleColor); override;

Properties

	property Pixels: PVector4Byte read GetPixels;
Pointer to pixels. Same as RawPixels, only typecasted to PVector4Byte.

	property AlphaPixels: PVector4Byte read GetPixels; deprecated 'use Pixels';
Warning: this symbol is deprecated: use Pixels

	property PixelsArray: PVector4ByteArray read GetPixelsArray;
Pointer to pixels. Same as RawPixels, only typecasted to PVector4ByteArray.

	property PremultipliedAlpha: boolean read FPremultipliedAlpha;