Class TRGBAlphaImage

Unit

Declaration

type TRGBAlphaImage = class(TCastleImage)

Description

This item has no description. Showing description inherited from TCastleImage.

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

Overview

Methods

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

Properties

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

Description

Methods

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

This item has no description. Showing description inherited from TCastleImage.DrawFromCore.

Like DrawFrom, but can assume that all coordinates and sizes are valid. Override this to add copying using some more sophisticated method than just memory copying (so also for handling mode other than dmBlend).

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

This item has no description.

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

This item has no description.

Public class function PixelSize: Cardinal; override;

This item has no description. Showing description inherited from TCastleImage.PixelSize.

Size of TPixel in bytes for this TCastleImage descendant.

Public class function ColorComponentsCount: Cardinal; override;

This item has no description. Showing description inherited from TCastleImage.ColorComponentsCount.

Number of color components in TPixel.

E.g. RGB is 3 components and RGB+Alpha is 4 components, RGB+Exponent is 3 components (because it describes only Red, Green and Blue values (Exponent value is just used to correctly interpret these, it's not a 4th component)).

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

This item has no description.

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

This item has no description.

Public procedure InvertColors; override;

This item has no description. Showing description inherited from TCastleImage.InvertColors.

Inverts all colors (RGB or grayscale, but doesn't touch alpha channel). "Inverting" means changing color C in range [0..1] to 1-C, so black becomes white, white becomes black etc.

For descendants implementors: Override it if necessary, otherwise the default implementation in this class will raise EInternalError.

Public procedure Clear(const Pixel: TVector4Byte); override;

This item has no description. Showing description inherited from TCastleImage.Clear.

Set all image pixels to the same color.

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

This item has no description. Showing description inherited from TCastleImage.IsClear.

Check do all image pixels have the same color.

Public procedure ClearAlpha(const Alpha: Byte);

Set alpha channel on every pixel to the same given value.

Public procedure TransformRGB(const Matrix: TMatrix3); override;

This item has no description. Showing description inherited from TCastleImage.TransformRGB.

Multiply each RGB color by a matrix. This is a useful routine for many various conversions of image colors. Every pixel's RGB color is multiplied by given Matrix, i.e. PixelRGBColor := Matrix * PixelRGBColor.

If some value in some channel will be < 0, it will be set to 0. And if it will be > High(Byte), it will be set to High(Byte).

Examples: when Matrix = TMatrix3.Identity, this is NOOP. Matrix = ((2, 0, 0), (0, 1, 0), (0, 0, 1)) red channel is made lighter. Matrix = ((0, 0, 1), (0, 1, 0), (1, 0, 0)) swaps red and blue channel. Matrix = ((0.33, 0.33, 0.33), (0.33, 0.33, 0.33), (0.33, 0.33, 0.33)) is a simple conversion to grayscale (actually incorrect, even if often visually acceptable; actually instead of 0.33 one has to use GrayscaleFloat/ByteValues, this is already implemented in ImageTransformColorsVar function)

Note: it's often more optimal to hard-code necessary color transformations as TColorModulatorFunc and use ModulateRGB.

This function is only implemented for images that represent Pixel as RGB values, for now this means TRGBImage and TRGBAlphaImage. In case of TRGBAlphaImage (or any other class that represents colors as RGB + something more) alpha channel (i.e. "something more") is ignored (i.e. left without any modification).

In this class this simply raises EInternalError to say 'not implemented'. This also means that you must not call inherited in descendants when overriding this method.

Public procedure ModulateRGB(const ColorModulator: TColorModulatorByteFunc); override;

This item has no description. Showing description inherited from TCastleImage.ModulateRGB.

Process each pixel by given function. If ColorModulator = nil then this procedure does nothing. Else, every RGB color value of an image will be transformed using ColorModulator.

Like TransformRGB: This function is only implemented for images that represent Pixel as RGB values, for now this means TRGBImage and TRGBAlphaImage. In case of TRGBAlphaImage (or any other class that represents colors as RGB + something more) alpha channel (i.e. "something more") is ignored (i.e. left without any modification).

In this class this simply raises EInternalError to say 'not implemented'. This also means that you must not call inherited in descendants when overriding this method.

Public 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.

Public 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.

Public function HasAlpha: boolean; override;

This item has no description. Showing description inherited from TEncodedImage.HasAlpha.

Does an image have an alpha channel.

You may also be interested in the AlphaChannel that can make a distinction between alpha channel for blending and for alpha test. AlphaChannel answers always atNone if HasAlpha = false, and always acTest or acBlending if HasAlpha = true. But AlphaChannel may perform longer analysis of pixels (to differ between acTest and acBlending), while this function always executes ultra-fast (as it's constant for each TCastleImage descendant).

Descendants implementors notes: in this class, TCastleImage, this returns False. Override to return True for images with alpha channel.

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

This item has no description. Showing description inherited from TEncodedImage.AlphaChannel.

Analyze image contents to determine if, and what kind, of alpha channel it has.

This may be a time-consuming operation. When the image has alpha channel and we need to decide whether it's suitable for "alpha test" (only fully opaque or fully transparent pixels) or "alpha blending" (any alpha value makes sense) then this method needs to iterate over image pixels.

For this reason, the result of this operation is cached at various levels, e.g. TImageTextureNode and TDrawableImage cache it internally.

We determine "alpha test - simple yes/no alpha channel" if all the alpha values (for every pixel) are 0, or 255, or (when AlphaTolerance <> 0) are close to them by AlphaTolerance. So, to be precise, alpha value must be <= AlphaTolerance, or >= 255 - AlphaTolerance. If any alpha value is between [AlphaTolerance + 1, 255 - AlphaTolerance - 1] then we return "alpha blending - full range alpha channel".

Note that big values of AlphaTolerance make it easier to quality image as "alpha test - simple yes/no alpha channel". When AlphaTolerance >= 128, all images are treated as "simple yes/no alpha". Usually, you want to keep AlphaTolerance small.

Descendants implementors notes: in this class, this simply always returns atNone. For descendants that have alpha channel, implement it, honouring AlphaTolerance as described.

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

This item has no description. Showing description inherited from TCastleImage.LerpWith.

Makes linear interpolation of colors from this image and the SecondImage. Intuitively, every pixel in new image is set to

(1 - Value) * Self[pixel] + Value * SecondImage[pixel]

Both images need to have the exact same size. If they are not, EImageLerpDifferentSizes is raised.

Not all TCastleImage combinations are allowed. Every subclass is required to override this to at least handle Lerp between itself. That is, TRGBImage.Lerp has to handle Lerp with other TRGBImage, TRGBAlphaImage.Lerp has to handle Lerp with other TRGBAlphaImage etc. Other combinations may be permitted, if useful and implemented. EImageLerpInvalidClasses is raised if given class combinations are not allowed.

In this class, this simply always raises EImageLerpInvalidClasses.

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

This item has no description. Showing description inherited from TCastleImage.MixColors.

Mix 4 colors, with 4 weights, into a resulting color. All 4 Colors and OutputColor must be pointers to a pixel of current image class, that is they must point to PixelSize bytes of memory.

Public procedure Assign(const Source: TCastleImage); override;

This item has no description. Showing description inherited from TCastleImage.Assign.

Copy size and contents from Source. This sets our size (Width, Height and Depth) to match Source image, and copies pixels from the Source image, converting them as closely as possible. For example, converting RGBA to RGB will strip alpha channel, but copy RGB values.

When implementing descendants: the base implementation of this method in TCastleImage handles only the case when Image class equals our own class. And raises EImageAssignmentError in other cases. Override this method if you want to actually handle some conversions when assignning.

Public function ToRGBImage: TRGBImage; deprecated 'create TRGBImage and use TRGBImage.Assign';

Warning: this symbol is deprecated: create TRGBImage and use TRGBImage.Assign

Remove alpha channel.

Public function ToGrayscaleAlphaImage: TGrayscaleAlphaImage; deprecated 'create TGrayscaleAlphaImage and use TGrayscaleAlphaImage.Assign';

Warning: this symbol is deprecated: create TGrayscaleAlphaImage and use TGrayscaleAlphaImage.Assign

Flatten to grayscale.

Public 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.

Public function ToFpImage: TInternalCastleFpImage; override;

This item has no description. Showing description inherited from TEncodedImage.ToFpImage.

Convert image contents to FpImage instance. The resulting instance is owned by the caller.

Public 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.

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

This item has no description. Showing description inherited from TCastleImage.AlphaBleed.

Set the RGB colors for transparent pixels to the nearest non-transparent colors. This fixes problems with black/white borders around the texture regions, when the texture is scaled down (by any means – on CPU, during rendering on GPU...).

The algorithm implemented here, for now, is really slow (but also really correct). It should only be used as a last resort, when your normal tool (like Spine atlas packer) cannot do a decent job on a given image. You should use this when creating assets, and save the resulting image to disk (avoid doing this at runtime during the game, since it's really really slow).

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

This item has no description.

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

This item has no description. Showing description inherited from TCastleImage.FillEllipse.

Draw simple geometric shapes like circles, rectangles, lines, etc.

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

This item has no description.

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

This item has no description.

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

This item has no description.

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

This item has no description.

Properties

Public property Pixels: PVector4Byte read GetPixels;

Pointer to pixels. Same as RawPixels, only typecasted to PVector4Byte.

Public property AlphaPixels: PVector4Byte read GetPixels; deprecated 'use Pixels';

Warning: this symbol is deprecated: use Pixels

This item has no description.

Public property PixelsArray: PVector4ByteArray read GetPixelsArray;

Pointer to pixels. Same as RawPixels, only typecasted to PVector4ByteArray.

Public property PremultipliedAlpha: boolean read FPremultipliedAlpha;

This item has no description.


Generated by PasDoc 0.16.0-snapshot.