Class TCastleImagePersistent

Unit

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

  • TObject
  • TPersistent
  • TCastleImagePersistent

Overview

Methods

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

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 Region: TFloatRectangle read FRegion write SetRegion;
Public property InternalVisualizeProtectedSides: Boolean read FInternalVisualizeProtectedSides write FInternalVisualizeProtectedSides default true;
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 ProtectedSidesScaling: TProtectedSidesScaling read FProtectedSidesScaling write SetProtectedSidesScaling default pssDefault;
Published property ColorPersistent: TCastleColorPersistent read FColorPersistent ;
Published property ClipLinePersistent: TCastleVector3Persistent read FClipLinePersistent ;
Published property RotationCenterPersistent: TCastleVector2Persistent read FRotationCenterPersistent ;
Published property RegionPersistent: TFloatRectanglePersistent read FRegionPersistent ;

Description

Methods

Protected procedure DoChange; virtual;

This item has no description.

Public constructor Create;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure BeforeDestruction; override;

This item has no description.

Public procedure ImageChanged;

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

Public function Width: Cardinal;

Width of drawn image. This is like DrawableImage.Width, but limited by Region.

Public function Height: Cardinal;

Height of drawn image. This is like DrawableImage.Height, but limited by Region.

Public function Empty: Boolean;

Are both Width and Height equal to zero.

Public procedure Draw(const ScreenRectangle: TFloatRectangle);

Draw the image in given screen area.

Public procedure DrawUiBegin(const NewScaleCorners: Single);

Prepare image for typical drawing from UI.

What it does now:

  1. Saves OnChange and Color (to be later restored by DrawUiEnd).

  2. Clears OnChange (so that changes between DrawUiBegin and DrawUiEnd do not cause OnChange, which is typically used to make repaint).

    Together with the previous point, this allows the rendering code to easily customize color between DrawUiBegin and DrawUiEnd, e.g. doing

    MyPersistentImage.DrawUiBegin(...);
    MyPersistentImage.Color := MyPersistentImage.Color * Tint;
    MyPersistentImage.Draw(...);
    MyPersistentImage.DrawUiEnd;

    Such change to color is guaranteed to be temporary and internal: DrawUiEnd will revert it, OnChange will not report it outside.

  3. Sets ScaleCorners.

Must be followed by DrawUiEnd.

Public procedure DrawUiEnd;

Finish image usage from typical UI drawing.

What it does now:

  1. Restores OnChange and Color.

Public procedure ReloadUrl;

Load again the image from current URL. This makes sense to be used when underlying file on disk changed, and you want to reload it.

TODO: In case image is shared with other TCastleImagePersistent instances, for now this method will not load new image from disk. That's because the previous image contents will "survive" in the cache.

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.

This is deliberately not published, because in typical usage this value is updated by UI control that owns this, before every render.

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 Region: TFloatRectangle read FRegion write SetRegion;

Image region to which we should limit the display. Empty (following TFloatRectangle.Empty) means using the whole image.

Public property InternalVisualizeProtectedSides: Boolean read FInternalVisualizeProtectedSides write FInternalVisualizeProtectedSides default true;

This item has no description.

Public property ScaleFromUrl: Single read FScaleFromUrl;

This item has no description.

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;

This item has no description.

Published property FlipVertical: Boolean read FFlipVertical write SetFlipVertical default false;

This item has no description.

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 ProtectedSidesScaling: TProtectedSidesScaling read FProtectedSidesScaling write SetProtectedSidesScaling default pssDefault;

How are protected sides scaled to match the final drawing area on the screen.

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.
Published property RegionPersistent: TFloatRectanglePersistent read FRegionPersistent ;

Region 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 Region directly.

See also
Region
Image region to which we should limit the display.

Generated by PasDoc 0.16.0-snapshot.