API Reference

Class TCastleImageControl

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleControls

Declaration

type TCastleImageControl = class(TCastleUserInterface)

Description

Image control. Size is automatically adjusted to the image size, if Stretch is False (default). You should set TCastleImageControl.Left, TCastleImageControl.Bottom properties, and load your image by setting TCastleImageControl.Url property or straight TCastleImageControl.Image.

We automatically use alpha test or alpha blending based on loaded image alpha channel (see TDrawableImage.Alpha). You can influence this by AlphaChannel property.

Hierarchy

Overview

Methods

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Render; override;
Public procedure GLContextOpen; override;
Public procedure EditorAllowResize( out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure ImageChanged;

Properties

Public property Image: TEncodedImage read GetImage write SetImage;
Public property OwnsImage: boolean read GetOwnsImage write SetOwnsImage default true;
Public property DrawableImage: TDrawableImage read GetDrawableImage write SetDrawableImage;
Public property OwnsDrawableImage: boolean read GetOwnsDrawableImage write SetOwnsDrawableImage default true;
Public property Color: TCastleColor read GetColor write SetColor;
Public property Corners: TVector4Integer read GetCorners write SetCorners; deprecated 'use ProtectedSides';
Public property CenterX: Single read GetCenterX write SetCenterX default 0.5; deprecated 'use RotationCenter';
Public property CenterY: Single read GetCenterY write SetCenterY default 0.5; deprecated 'use RotationCenter';
Public property RotationCenter: TVector2 read GetRotationCenter write SetRotationCenter;
Public property ClipLine: TVector3 read GetClipLine write SetClipLine;
Public property Region: TFloatRectangle read GetRegion write SetRegion;
Public property CustomShader: TGLSLProgram read GetCustomShader write SetCustomShader;
Public property Blending: boolean read GetBlending write SetBlending stored false; deprecated 'use AlphaChannel';
Public property Proportional: boolean read GetProportional write SetProportional stored false default false; deprecated 'use ProportionalScaling';
Public property FileName: string read GetUrl write SetUrl stored false; deprecated 'use Url';
Published property Content: TCastleImagePersistent read FContent;
Published property Url: String read GetUrl write SetUrl stored false;
Published property AlphaChannel: TAutoAlphaChannel read GetAlphaChannel write SetAlphaChannel stored false default acAuto;
Published property SmoothScaling: boolean read GetSmoothScaling write SetSmoothScaling stored false default true;
Published property Stretch: boolean read FStretch write SetStretch default false;
Published property ProportionalScaling: TProportionalScaling read FProportionalScaling write SetProportionalScaling default psNone;
Published property Cache: boolean read GetCache write SetCache stored false default true;
Published property FlipHorizontal: Boolean read GetFlipHorizontal write SetFlipHorizontal stored false default false;
Published property FlipVertical: Boolean read GetFlipVertical write SetFlipVertical stored false default false;
Published property ProtectedSides: TBorder read GetProtectedSides stored false;
Published property DetectScaleFromUrl: Boolean read FDetectScaleFromUrl write SetDetectScaleFromUrl default false;
Published property Rotation: Single read GetRotation write SetRotation stored false default 0;
Published property Clip: boolean read GetClip write SetClip stored false default false;
Published property ColorPersistent: TCastleColorPersistent read FColorPersistent stored false;
Published property ClipLinePersistent: TCastleVector3Persistent read FClipLinePersistent stored false;
Published property RotationCenterPersistent: TCastleVector2Persistent read FRotationCenterPersistent stored false;
Published property RegionPersistent: TFloatRectanglePersistent read FRegionPersistent stored false;

Description

Methods

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;

This item has no description. Showing description inherited from TCastleUserInterface.PreferredSize.

Controls that have a preferred size should override this. By default this contains values derived from Width, WidthFraction, Height, HeightFraction, with Border subtracted.

Note that the arguments should be already scaled, i.e. multiplied by UIScale, i.e. expressed in final device pixels.

Note that the returned PreferredWidth and PreferredHeight must not include the space for Border. Border size will be added later.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Render; override;

This item has no description. Showing description inherited from TCastleUserInterface.Render.

Render a control. Called only when Exists and render context is initialized.

Do not call this method. It will be automatically called by the engine when needed. It will be called when UI is part of TCastleContainer.Controls list or rendered (e.g. for off-screen rendering) by TCastleContainer.RenderControl.

You should only override this method.

See https://castle-engine.io/manual_2d_ui_custom_drawn.php for examples what you can put here.

You can depend on some OpenGL state being set before calling this method. You can depend on it being set, and you can carelessly change it. This state we set:

  • Viewport is set to include whole container.

  • Depth test is off.

  • For ancient fixed-function pipeline (see TGLFeatures.RequestCapabilities):

    • The 2D orthographic projection is always set at the beginning. Useful for 2D controls.

    • The modelview matrix is set to identity. The matrix mode is always modelview.

    • The raster position is set to (0,0). The (deprecated) WindowPos is also set to (0,0).

    • Texturing, lighting, fog is off.

Beware that GLSL RenderContext.CurrentProgram has undefined value when this is called. You should always set it, before making direct OpenGL drawing calls (all the engine drawing routines do it already, this is only a concern if you make direct OpenGL / OpenGLES calls).

Public procedure GLContextOpen; override;

This item has no description. Showing description inherited from TCastleUserInterface.GLContextOpen.

Initialize your OpenGL resources.

This is called when OpenGL context of the container is created, or when the control is added to the already existing context. In other words, this is the moment when you can initialize OpenGL resources, like display lists, VBOs, OpenGL texture names, etc.

As an exception, this is called regardless of the Exists value. This way a control can prepare it's resources, regardless if it exists now.

Public procedure EditorAllowResize( out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;

This item has no description. Showing description inherited from TCastleUserInterface.EditorAllowResize.

Override this to prevent resizing some dimension in CGE editor.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Public procedure ImageChanged;

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

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

Properties

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).

See also
TCastleImagePersistent.Image
Image contents, or Nil if none.
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.

See also
TCastleImagePersistent.OwnsImage
Whether the memory management of assigned Image is automatic.
Public property DrawableImage: TDrawableImage read GetDrawableImage 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.

See also
TCastleImagePersistent.DrawableImage
Image used for drawing.
Public property OwnsDrawableImage: boolean read GetOwnsDrawableImage write SetOwnsDrawableImage 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).

See also
TCastleImagePersistent.OwnsDrawableImage
Whether we should automatically free the DrawableImage instance.
Public property Color: TCastleColor read GetColor 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.

See also
TCastleImagePersistent.Color
Color tint of the image.
Public property Corners: TVector4Integer read GetCorners write SetCorners; deprecated 'use ProtectedSides';

Warning: this symbol is deprecated: use ProtectedSides

Corners and edges of the image that are not stretched even when Stretch is used. See TDrawableImage.Draw3x3 for the details how such drawing works.

Public property CenterX: Single read GetCenterX write SetCenterX default 0.5; deprecated 'use RotationCenter';

Warning: this symbol is deprecated: use RotationCenter

X coordinate of the center of rotation. Value from 0 to 1. Default value 0.5.

Public property CenterY: Single read GetCenterY write SetCenterY default 0.5; deprecated 'use RotationCenter';

Warning: this symbol is deprecated: use RotationCenter

Y coordinate of the center of rotation. Value from 0 to 1. Default value 0.5.

Public property RotationCenter: TVector2 read GetRotationCenter 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).

See also
TCastleImagePersistent.RotationCenter
Center of rotation.
Public property ClipLine: TVector3 read GetClipLine 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.

See also
TCastleImagePersistent.ClipLine
If Clip, this is the line equation used to determine whether we clip the given pixel.
Public property Region: TFloatRectangle read GetRegion write SetRegion;

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

Public property CustomShader: TGLSLProgram read GetCustomShader write SetCustomShader;

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

See also
TCastleImagePersistent.CustomShader
Custom GLSL shading code.
Public property Blending: boolean read GetBlending write SetBlending stored false; deprecated 'use AlphaChannel';

Warning: this symbol is deprecated: use AlphaChannel

This item has no description.

Public property Proportional: boolean read GetProportional write SetProportional stored false default false; deprecated 'use ProportionalScaling';

Warning: this symbol is deprecated: use ProportionalScaling

This item has no description.

Public property FileName: string read GetUrl write SetUrl stored false; deprecated 'use Url';

Warning: this symbol is deprecated: use Url

This item has no description.

Published property Content: TCastleImagePersistent read FContent;

Image contents to display.

Published property Url: String read GetUrl write SetUrl stored false;

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

See also
TCastleImagePersistent.Url
URL of the image.
Published property AlphaChannel: TAutoAlphaChannel read GetAlphaChannel write SetAlphaChannel stored false 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.

See also
TCastleImagePersistent.AlphaChannel
How to treat alpha channel of the assigned image.
Published property SmoothScaling: boolean read GetSmoothScaling write SetSmoothScaling stored false default true;

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

See also
TCastleImagePersistent.SmoothScaling
Is the image scaling mode smooth (bilinear filtering) or not (nearest-pixel filtering).
Published property Stretch: boolean read FStretch write SetStretch default false;

How does the loaded image size affect the size of the image control.

  • When FullSize or AutoSizeToChildren is True, then the value of Stretch, and loaded image size, are ignored. When AutoSizeToChildren, the image is always stretched to surround the children. When FullSize, the image is always stretched to fill the parent.

    Otherwise:

  • If Stretch = False (default), then the displayed size corresponds to the underlying image size.

  • If Stretch = True, the image will be stretched to fill the requested area. The property ProportionalScaling determines how the image will be adjusted to fit the requested size (by Width, WidthFraction, Height, HeightFraction).

    psNone

    The image will be scaled to exactly fill the requested Width and Height (without paying attention to the aspect ratio of the image).

    This is the case when you fully force the displayed size and position, regardless of image size. Displayed image will always exactly fill the requested area.

    psFit

    The image will be proportionally scaled to fit within the requested Width and Height. If the aspect ratio of image will be different than aspect ratio of Width/Height, the scaled image will be centered inside the Width/Height.

    psEnclose

    The image will be proportionally scaled to enclode the requested Width and Height. If the aspect ratio of image will be different than aspect ratio of Width/Height, the scaled image will be larger then the requested area.

Published property ProportionalScaling: TProportionalScaling read FProportionalScaling write SetProportionalScaling default psNone;

This item has no description.

Published property Cache: boolean read GetCache write SetCache stored false default true;

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

See also
TCastleImagePersistent.Cache
If True, the DrawableImage is loaded and freed using a cache.
Published property FlipHorizontal: Boolean read GetFlipHorizontal write SetFlipHorizontal stored false default false;

Display image horizontally flipped.

See also
TCastleImagePersistent.FlipHorizontal
Published property FlipVertical: Boolean read GetFlipVertical write SetFlipVertical stored false default false;

Display image vertically flipped.

See also
TCastleImagePersistent.FlipVertical
Published property ProtectedSides: TBorder read GetProtectedSides stored false;

Corners and edges of the image that are protected from scaling distortion when 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.

See also
TCastleImagePersistent.ProtectedSides
Corners and edges of the image that are protected from scaling distortion when TCastleImageControl.Stretch is used.
Published property DetectScaleFromUrl: Boolean read FDetectScaleFromUrl write SetDetectScaleFromUrl default false;

Set this to auto-detect that image is scaled compared to it's desired size. This detects URL endings like '[email protected]', and we will automatically adjust to it (the size determined by AutoSize will be actually 2x smaller than the PNG size). Preparing images at a 2x or 4x larger size than "desired" is a useful trick when using UI scaling, when you want the image to look good at various scales.

Published property Rotation: Single read GetRotation write SetRotation stored false default 0;

Rotation in radians. Default value 0.

See also
TCastleImagePersistent.Rotation
Rotation in radians.
Published property Clip: boolean read GetClip write SetClip stored false default false;

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

See also
TCastleImagePersistent.Clip
Clip the image by an arbitrary 2D line defined in ClipLine.
Published property ColorPersistent: TCastleColorPersistent read FColorPersistent stored false;

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 stored false;

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 stored false;

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 stored false;

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.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.