Class TEncodedImage

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type TEncodedImage = class(TObject)

Description

Abstract class for an image with unspecified, possibly compressed, memory format. The idea is that both uncompressed images (TCastleImage) and compressed images (TS3TCImage) are derived from this class.

Hierarchy

  • TObject
  • TEncodedImage

Overview

Fields

Protected FRawPixels: Pointer;

Methods

Public destructor Destroy; override;
Public function IsEmpty: boolean;
Public function HasAlpha: boolean; virtual;
Public function AlphaChannel( const AlphaTolerance: Byte = DefaultAlphaTolerance): TAlphaChannel; virtual;
Public function Rect: TRectangle;

Properties

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;
 
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. AlphaChannel answers always atNone if HasAlpha = false, and always acSimpleYesNo or acFullRange if HasAlpha = true. But AlphaChannel may perform longer analysis of pixels (to differ between acSimpleYesNo and acFullRange), 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;

Check does an image have an alpha channel, and if yes analyze alpha channel: is it a single yes-no (only full or none values), or does it have alpha values in between?

This is quite useful for automatic detection how alpha textures should be displayed: for simple yes/no alpha, OpenGL alpha_test is a simple solution. For full range alpha, OpenGL blending should be used. Blending is a little problematic, since it requires special rendering order, since it doesn't cooperate nicely with Z-buffer. That's why we try to detect simple yes/no alpha textures, so that we're able to use simpler alpha test for them.

We return "simple yes/no alpha channel" is 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 "full range alpha channel". Note that for 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.

Properties

Public property Width: Cardinal read FWidth;
 
Public property Height: Cardinal read FHeight;
 
Public property Depth: Cardinal read FDepth;
 
Public property RawPixels: Pointer read FRawPixels;