Class TEncodedImage

Unit

Declaration

type TEncodedImage = class(TObject)

Description

Abstract class for an image with unspecified, possibly compressed, memory format. Both uncompressed images (TCastleImage) and images compressed for GPU (TGPUCompressedImage) are derived from this base class.

Hierarchy

  • TObject
  • TEncodedImage

Overview

Fields

Protected FRawPixels: Pointer;

Methods

Public destructor Destroy; override;
Public function Size: Cardinal; virtual; abstract;
Public function Dimensions: TVector3Cardinal;
Public function IsEmpty: boolean;
Public function HasAlpha: boolean; virtual;
Public function AlphaChannel( const AlphaTolerance: Byte = DefaultAlphaTolerance): TAlphaChannel; virtual;
Public function Rect: TRectangle;
Public function CreateCopy: TEncodedImage; virtual; abstract;
Public procedure FlipVertical; virtual; abstract;
Public function ToFpImage: TInternalCastleFpImage; virtual; deprecated 'interoperability with FpImage may be dropped in the future';

Properties

Public property Url: String read FUrl write FUrl;
Public property Width: Cardinal read FWidth;
Public property Height: Cardinal read FHeight;
Public property Depth: Cardinal read FDepth;
Public property RawPixels: Pointer read FRawPixels;

Description

Fields

Protected FRawPixels: Pointer;

Operate on this by Get/Realloc/FreeMem. It's always freed and nil'ed in destructor.

Methods

Public destructor Destroy; override;

This item has no description.

Public function Size: Cardinal; virtual; abstract;

Size of image contents in bytes.

Public function Dimensions: TVector3Cardinal;

Get a 3D vector with Width, Height, Depth.

Public function IsEmpty: boolean;

Is an image empty.

True means that RawPixels = Nil, and Width * Height * Depth = 0 (so either Width = 0 or Height = 0 or Depth = 0).

False means that RawPixels <> nil and Width * Height * Depth <> 0 (so all Width > 0 and Height > 0 and Depth > 0, since they are Cardinal (unsigned) always).

Public function HasAlpha: boolean; virtual;

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 = DefaultAlphaTolerance): TAlphaChannel; virtual;

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 function Rect: TRectangle;

Rectangle representing the inside of this image. Always (Left,Bottom) are zero, and (Width,Height) correspond to image sizes.

Public function CreateCopy: TEncodedImage; virtual; abstract;

Create a new image object that has exactly the same class and the same data (size, pixels) as this image.

Public procedure FlipVertical; virtual; abstract;

Mirror image vertically.

Public function ToFpImage: TInternalCastleFpImage; virtual; deprecated 'interoperability with FpImage may be dropped in the future';

Warning: this symbol is deprecated: interoperability with FpImage may be dropped in the future

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

Properties

Public property Url: String read FUrl write FUrl;

Url from which this image was loaded, if any.

Public property Width: Cardinal read FWidth;

This item has no description.

Public property Height: Cardinal read FHeight;

This item has no description.

Public property Depth: Cardinal read FDepth;

Depth of the image. For 2D images (most common) this is just 1.

All images in CastleImages can be potentially 3D, which means they can have Depth > 1. A 3D image is just a 3-dimensional array of pixels, and you can use it e.g. as a texture with 3D texture coordinates. A sample use-cases for 3D textures are:

  • Generated colors of some material that you can imagine as a 3D volume, like a volume of wood or marble. This is nice to apply on any complicated 3D shape, because the necessary 3D texture coordinates are trivial, since 3D position of a point on the shape can be used as a reasonable 3D texture coordinate.

  • Medical data, some scans are 3D.

  • Noise (like Perlin noise) used for various effects in shaders.

  • Specialized noise, e.g. a volume of smoke, or a volume of clouds.

Public property RawPixels: Pointer read FRawPixels;

Image data. The layout of this memory is defined by descendants. For example, for TCastleImage it's a simple array of pixels (see TCastleImage docs for exact description of the memory layout), for TGPUCompressedImage it's a compressed data for GPU.

Note that this may be Nil, if Width * Height * Depth = 0. In this case, IsEmpty returns True.


Generated by PasDoc 0.16.0-snapshot.