Castle Game Engine

Class TCastleImagePersistent

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleGLImages

Declaration

type TCastleImagePersistent = class(TPersistent)

Description

Image that can be easily loaded from URL (possibly reusing a cache), drawn, and serialized to/from file.

Hierarchy

Overview

Methods

Protected procedure DoChange; virtual;
Public constructor Create;
Public destructor Destroy; override;
Public procedure ImageChanged;
Public function Width: Cardinal;
Public function Height: Cardinal;
Public function Empty: Boolean;
Public procedure Draw(const ScreenRectangle: TFloatRectangle);

Properties

Public property OnChange: TNotifyEvent read FOnChange write FOnChange;
Public property Image: TEncodedImage read GetImage write SetImage;
Public property OwnsImage: boolean read GetOwnsImage write SetOwnsImage default true;
Public property DrawableImage: TDrawableImage read FDrawableImage write SetDrawableImage;
Public property OwnsDrawableImage: boolean read FOwnsDrawableImage write FOwnsDrawableImage default true;
Public property RotationCenter: TVector2 read FRotationCenter write SetRotationCenter;
Public property ClipLine: TVector3 read FClipLine write SetClipLine;
Public property CustomShader: TGLSLProgram read FCustomShader write SetCustomShader;
Public property ScaleCorners: Single read FScaleCorners write SetScaleCorners default 1;
Public property Color: TCastleColor read FColor write SetColor;
Public property InternalVisualizeProtectedSides: Boolean read FInternalVisualizeProtectedSides write FInternalVisualizeProtectedSides;
Public property ScaleFromUrl: Single read FScaleFromUrl;
Published property URL: String read FURL write SetURL;
Published property AlphaChannel: TAutoAlphaChannel read FAlphaChannel write SetAlphaChannel default acAuto;
Published property Cache: Boolean read FCache write SetCache default true;
Published property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling default true;
Published property Rotation: Single read FRotation write SetRotation default 0;
Published property Clip: boolean read FClip write SetClip default false;
Published property FlipHorizontal: Boolean read FFlipHorizontal write SetFlipHorizontal default false;
Published property FlipVertical: Boolean read FFlipVertical write SetFlipVertical default false;
Published property ProtectedSides: TBorder read FProtectedSides;
Published property ColorPersistent: TCastleColorPersistent read FColorPersistent ;
Published property ClipLinePersistent: TCastleVector3Persistent read FClipLinePersistent ;
Published property RotationCenterPersistent: TCastleVector2Persistent read FRotationCenterPersistent ;

Description

Methods

Protected procedure DoChange; virtual;
 
Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure ImageChanged;

If you modified the Image contents (colors, or maybe even image size) you need to call this.

Public function Width: Cardinal;
 
Public function Height: Cardinal;
 
Public function Empty: Boolean;
 
Public procedure Draw(const ScreenRectangle: TFloatRectangle);

Draw the image in given screen area.

Properties

Public property OnChange: TNotifyEvent read FOnChange write FOnChange;

Reserved for parent UI control to listen for changes.

Public property Image: TEncodedImage read GetImage write SetImage;

Image contents, or Nil if none. You can set it by setting URL, or by setting this property directly, or by setting DrawableImage.

Note that by default the TEncodedImage instance assigned here is owned by this component (see OwnsImage). So if you set this property to your custom TEncodedImage instance you should leave memory management of this instance to this component. You can either create a copy by TEncodedImage.MakeCopy if you want to give here only a copy, or you can change OwnsImage to False.

It is allowed to modify the contents or even size of this image. Just make sure to call ImageChanged after the modifications are done to update the rendered image (and possibly the UI control size, e.g. in case TCastleImageControl uses this TCastleImagePersistent, and TCastleImageControl.Stretch=false).

Public property OwnsImage: boolean read GetOwnsImage write SetOwnsImage default true;

Whether the memory management of assigned Image is automatic. See Image documentation for details.

Note that setting URL changes Image, and changes OwnsImage unconditionally to True.

Note that setting DrawableImage changes Image too, and changes OwnsImage to the value present in TDrawableImage.OwnsImage.

Public property DrawableImage: TDrawableImage read FDrawableImage write SetDrawableImage;

Image used for drawing. Never Nil. Always TDrawableImage.Image equals our Image.

Usually you do not want to change this property. You can change URL, or Image, and the drawable image will reflect this. But there are good use-cases to change the DrawableImage directly: e.g. you can use fast image-to-image drawing using TDrawableImage.DrawFrom. Or you can set a new instance of TDrawableImage here. Be sure to adjust OwnsDrawableImage as needed.

Note that when OpenGL(ES) context is lost and recreated (which can happen at any moment on mobile devices), the contents of this are reinitialized from Image.

Public property OwnsDrawableImage: boolean read FOwnsDrawableImage write FOwnsDrawableImage default true;

Whether we should automatically free the DrawableImage instance. Note that this is restored to True when we need to recreate the TDrawableImage internally, e.g. when Image instance changed (when even size changed, we have to recreate TDrawableImage).

Public property RotationCenter: TVector2 read FRotationCenter write SetRotationCenter;

Center of rotation. Expressed as a fraction within the drawn ScreenRectangle, (0,0) means bottom-left corner, (1,1) means top-right corner. Default (0.5,0.5).

Public property ClipLine: TVector3 read FClipLine write SetClipLine;

If Clip, this is the line equation used to determine whether we clip the given pixel. Given a line (A, B, C) and pixel (x, y), the pixel is clipped (rejected) if A * x + B * y + C < 0.

The equation is calculated in the coordinates in which image X, Y spans from (0, 0) (bottom-left) to (1, 1) (top-right). For example ClipLine = (1, 0, -0.5) means that we reject pixels where 1 * x + 0 * y - 0.5 < 0. In other words, we reject pixels where x < 0.5, so we reject the left half of the image.

Public property CustomShader: TGLSLProgram read FCustomShader write SetCustomShader;

Custom GLSL shading code. See TDrawableImage.CustomShader for explanation.

Public property ScaleCorners: Single read FScaleCorners write SetScaleCorners default 1;

In case of TDrawableImage.Draw3x3 the corners on screen are scaled by this amount. This is especially useful for UI scaling, see TCastleContainer.UIScaling and TCastleUserInterface.UIScale.

Public property Color: TCastleColor read FColor write SetColor;

Color tint of the image. This simply multiplies the image RGBA components, just like TDrawableImage.Color. By default this is opaque white, which means that image colors are unchanged.

Public property InternalVisualizeProtectedSides: Boolean read FInternalVisualizeProtectedSides write FInternalVisualizeProtectedSides;
 
Public property ScaleFromUrl: Single read FScaleFromUrl;
 
Published property URL: String read FURL write SetURL;

URL of the image. Set this to load a new image, you can set to '' to clear the image.

Changing this also changes Image and DrawableImage. OwnsDrawableImage and OwnsImage always change to True.

Published property AlphaChannel: TAutoAlphaChannel read FAlphaChannel write SetAlphaChannel default acAuto;

How to treat alpha channel of the assigned image. By default, this is acAuto, which means that image contents together with current Color determine how the alpha of image is treated (opaque, alpha test, alpha blending). Set this to force specific treatment.

Published property Cache: Boolean read FCache write SetCache default true;

If True, the DrawableImage is loaded and freed using a cache. This can save memory and loading time a lot, if you reuse the same URL in many TCastleImagePersistent instances.

The limitation is that you shouldn't change the Image contents (e.g. changing TCastleImage.Colors) or DrawableImage contents (e.g. by using TDrawableImage.RenderToImageBegin), or you will change all shared images.

Note that if you assign DrawableImage (instead of URL) and we should free it ourselves (because OwnsDrawableImage) then we assume it was not loaded through our internal cache.

Note that if you assign Image (instead of URL) then we assume it was not loaded through our internal cache. (We make sure to detach the TDrawableImage from cache too, in this case.)

Changing this property reloads the image (if some URL was set).

Published property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling default true;

Is the image scaling mode smooth (bilinear filtering) or not (nearest-pixel filtering). See TDrawableImage.SmoothScaling.

Published property Rotation: Single read FRotation write SetRotation default 0;

Rotation in radians. Default value 0.

Published property Clip: boolean read FClip write SetClip default false;

Clip the image by an arbitrary 2D line defined in ClipLine.

Published property FlipHorizontal: Boolean read FFlipHorizontal write SetFlipHorizontal default false;
 
Published property FlipVertical: Boolean read FFlipVertical write SetFlipVertical default false;
 
Published property ProtectedSides: TBorder read FProtectedSides;

Corners and edges of the image that are protected from scaling distortion when TCastleImageControl.Stretch is used. We use the 9-slicing algorithm, described at TDrawableImage.Draw3x3 and https://en.wikipedia.org/wiki/9-slice_scaling to scale the image.

Published property ColorPersistent: TCastleColorPersistent read FColorPersistent ;

Color that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write Color directly.

See also
Color
Color tint of the image.
Published property ClipLinePersistent: TCastleVector3Persistent read FClipLinePersistent ;

ClipLine that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write ClipLine directly.

See also
ClipLine
If Clip, this is the line equation used to determine whether we clip the given pixel.
Published property RotationCenterPersistent: TCastleVector2Persistent read FRotationCenterPersistent ;

RotationCenter that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write RotationCenter directly.

See also
RotationCenter
Center of rotation.
Generated by PasDoc 0.16.0.