Class TCastleImagePersistent
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
- TObject
- TPersistent
- TCastleImagePersistent
Overview
Methods
Properties
Description
Methods
|
procedure DoChange; virtual; |
This item has no description. |
|
constructor Create; |
This item has no description. |
|
destructor Destroy; override; |
This item has no description. |
|
procedure BeforeDestruction; override; |
This item has no description. |
|
procedure ImageChanged; |
If you modified the Image contents (colors, or maybe even image size) you need to call this.
|
|
function Width: Cardinal; |
Width of drawn image. This is like DrawableImage.Width, but limited by Region.
|
|
function Height: Cardinal; |
Height of drawn image. This is like DrawableImage.Height, but limited by Region.
|
|
function Empty: Boolean; |
Are both Width and Height equal to zero.
|
|
procedure Draw(const ScreenRectangle: TFloatRectangle); |
Draw the image in given screen area.
|
|
procedure DrawUiBegin(const NewScaleCorners: Single); |
Prepare image for typical drawing from UI.
What it does now:
Saves OnChange and Color (to be later restored by DrawUiEnd).
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.
Sets ScaleCorners.
Must be followed by DrawUiEnd.
|
|
procedure DrawUiEnd; |
Finish image usage from typical UI drawing.
What it does now:
Restores OnChange and Color.
|
|
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
|
property OnChange: TNotifyEvent read FOnChange write FOnChange; |
Reserved for parent UI control to listen for changes.
|
|
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).
|
|
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.
|
|
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.
|
|
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).
|
|
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).
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
property InternalVisualizeProtectedSides: Boolean
read FInternalVisualizeProtectedSides write FInternalVisualizeProtectedSides default true; |
This item has no description. |
|
property ScaleFromUrl: Single read FScaleFromUrl; |
This item has no description. |
|
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 .
|
|
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.
|
|
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).
|
|
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.
|
|
property Rotation: Single read FRotation write SetRotation default 0; |
Rotation in radians. Default value 0.
|
|
property Clip: boolean read FClip write SetClip default false; |
Clip the image by an arbitrary 2D line defined in ClipLine.
|
|
property FlipHorizontal: Boolean read FFlipHorizontal write SetFlipHorizontal
default false; |
This item has no description. |
|
property FlipVertical: Boolean read FFlipVertical write SetFlipVertical
default false; |
This item has no description. |
|
property ProtectedSidesScaling: TProtectedSidesScaling
read FProtectedSidesScaling write SetProtectedSidesScaling default pssDefault; |
How are protected sides scaled to match the final drawing area on the screen.
|
|
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.
|
|
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.
|
|
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.