Class TCastleImagePersistent

This item has no description.

This item has no description.

This item has no description.

This item has no description.

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

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

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

Are both Width and Height equal to zero.

Draw the image in given screen area.

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.

Finish image usage from typical UI drawing.

What it does now:

1. Restores OnChange and Color.

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.

Reserved for parent UI control to listen for changes.

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

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.

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.

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

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

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.

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

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.

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.

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

This item has no description.

This item has no description.

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.

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.

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

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

Rotation in radians. Default value 0.

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

This item has no description.

This item has no description.

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.

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

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.

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.

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.

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.