Class TGLImageCore

Unit

Declaration

type TGLImageCore = class(TNoParameterlessContructor)

Description

Image ready to be drawn on 2D screen. This image can be drawn in various rendering methods and events, e.g. inside overridden TUIControl.Render or from events TCastleWindowCustom.OnRender or TCastleControlCustom.OnRender.

An alternative way to show a 2D image is to use the full-featured 2D control TCastleImageControl. This will perform the drawing by itself, you only add it to TCastleWindowCustom.Controls or TCastleControlCustom.Controls.

An instance of this class can only exist when the OpenGL context is open. So usually you create this in TUIControl.GLContextOpen and destroy in TUIControl.GLContextClose. Or create in TCastleWindowCustom.OnOpen and destroy in TCastleWindowCustom.OnClose. Use the descendant class TGLImage for more comfort. The TGLImage instance can be created / destroyed at any moment, regardless of the OpenGL context. This is especially important on platforms when the OpenGL context may get lost at any moment, like on Android.

Hierarchy

Overview

Nested Types

Published TColorTreatment = (...);

Fields

Public nested const DefaultBlendingSourceFactor = bsSrcAlpha;
Public nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;
Public nested const DefaultBlendingConstantColor: TVector4 = (Data: (1, 1, 1, 1));

Methods

Public constructor Create(const Image: TEncodedImage; const ASmoothScaling: boolean); overload;
Public constructor Create(const Image: TEncodedImage); overload; deprecated 'use Create(Image, ASmoothScaling) and specify ASmoothScaling explicitly';
Public constructor Create(const URL: string; const ASmoothScaling: boolean = true); overload;
Public constructor Create(const URL: string; const LoadAsClass: array of TEncodedImageClass; const ResizeToX: Cardinal = 0; const ResizeToY: Cardinal = 0; const Interpolation: TResizeInterpolation = riBilinear); overload;
Public constructor Create(const URL: string; const LoadAsClass: array of TEncodedImageClass; const ASmoothScaling: boolean); overload;
Public destructor Destroy; override;
Public function Rect: TRectangle;
Public procedure Draw; overload; deprecated 'use the Draw overload that takes position as explicit parameter';
Public procedure Draw(const X, Y: Single); overload;
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Single); overload;
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Single; const ImageX, ImageY, ImageWidth, ImageHeight: Single); overload;
Public procedure Draw(const Pos: TVector2Integer); overload;
Public procedure Draw(const ScreenRect: TFloatRectangle); overload;
Public procedure Draw(const ScreenRect, ImageRect: TFloatRectangle); overload;
Public procedure Draw(const ScreenRect: TRectangle); overload;
Public procedure Draw(const ScreenRect: TRectangle; const ImageX, ImageY, ImageWidth, ImageHeight: Single); overload;
Public procedure Draw(const ScreenRect, ImageRect: TRectangle); overload;
Public procedure Draw(ScreenRects, ImageRects: PFloatRectangleArray; const Count: Integer); overload; virtual;
Public procedure DrawFlipped(const ScreenRect: TRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; ImageRect: TFloatRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Single; const CornerTop, CornerRight, CornerBottom, CornerLeft: Integer); overload;
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Single; const Corner: TVector4Integer); overload;
Public procedure Draw3x3(const ScreenRect: TRectangle; const Corner: TVector4Integer); overload;
Public procedure Load(const AImage: TEncodedImage); virtual;
Public procedure PrepareResources; virtual;

Properties

Public property Width: Cardinal read GetWidth;
Public property Height: Cardinal read GetHeight;
Public property Alpha: TAutoAlphaChannel read FAlpha write FAlpha default acAuto;
Public property BlendingSourceFactor: TBlendingSourceFactor read FBlendingSourceFactor write FBlendingSourceFactor default DefaultBlendingSourceFactor;
Public property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write FBlendingDestinationFactor default DefaultBlendingDestinationFactor;
Public property BlendingConstantColor: TVector4 read FBlendingConstantColor write FBlendingConstantColor;
Public property ScaleCorners: Single read FScaleCorners write FScaleCorners default 1;
Public property IgnoreTooLargeCorners: boolean read FIgnoreTooLargeCorners write FIgnoreTooLargeCorners default false;
Public property Color: TCastleColor read FColor write FColor;
Public property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling;
Public property ScalingPossible: boolean read FSmoothScaling write SetSmoothScaling; deprecated 'use SmoothScaling';
Public property CenterX: Single read FCenterX write FCenterX default 0.5;
Public property CenterY: Single read FCenterY write FCenterY default 0.5;
Public property Rotation: Single read FRotation write FRotation default 0;
Public property Clip: boolean read FClip write FClip;
Public property ClipLine: TVector3 read FClipLine write FClipLine;

Description

Nested Types

Published TColorTreatment = (...);

Used only in shader pipeline

Values
  • ctPureTexture: Use texture color to draw.
  • ctColorMultipliesTexture: Use constant color * texture (on all RGBA channels).
  • ctColorMultipliesTextureAlpha: Use constant color for RGB, for alpha use constant color.a * texture. Useful when texture has no alpha information.

Fields

Public nested const DefaultBlendingSourceFactor = bsSrcAlpha;
 
Public nested const DefaultBlendingDestinationFactor = bdOneMinusSrcAlpha;
 
Public nested const DefaultBlendingConstantColor: TVector4 = (Data: (1, 1, 1, 1));
 

Methods

Public constructor Create(const Image: TEncodedImage; const ASmoothScaling: boolean); overload;

Prepare image for drawing.

Parameters
Image
Initial image contents. The TGLImageCore class loads it immediately, so you can freely free the Image instance later. Be careful – TGLImage descendant has a different approach, it needs the TEncodedImage instance to exist throuout the whole TGLImage lifetime.
ASmoothScaling
The initial value of SmoothScaling, determines whether the image scaling is smooth (bilinear filtering) or not (nearest-pixel filtering). You can always change it later through the SmoothScaling property. But each change has a small cost, so it's more efficient to just set the initial value correctly.
Exceptions raised
EImageClassNotSupportedForOpenGL
When Image class is not supported by OpenGL.
Public constructor Create(const Image: TEncodedImage); overload; deprecated 'use Create(Image, ASmoothScaling) and specify ASmoothScaling explicitly';

Warning: this symbol is deprecated: use Create(Image, ASmoothScaling) and specify ASmoothScaling explicitly

 
Public constructor Create(const URL: string; const ASmoothScaling: boolean = true); overload;

Load image from disk, and prepare for drawing.

Parameters
URL
URL (or filename) from which to load the image. Often you want to pass here the result ot ApplicationData function, like:

Image := TGLImageCore.Create(ApplicationData('textures/my_image.png'), ...);

ASmoothScaling
The initial value of SmoothScaling, determines whether the image scaling is smooth (bilinear filtering) or not (nearest-pixel filtering). You can always change it later through the SmoothScaling property. But each change has a small cost, so it's more efficient to just set the initial value correctly.
Public constructor Create(const URL: string; const LoadAsClass: array of TEncodedImageClass; const ResizeToX: Cardinal = 0; const ResizeToY: Cardinal = 0; const Interpolation: TResizeInterpolation = riBilinear); overload;

Load image from disk, and prepare for drawing.

Parameters
URL
URL (or filename) from which to load the image. Often you want to pass here the result ot ApplicationData function, like:

Image := TGLImageCore.Create(ApplicationData('textures/my_image.png'), ...);

LoadAsClass
Constrain the possible image classes to load into. This can force removing (or adding) an alpha channel, or converting contents to grayscale or RGB, regardless of the preferred image file format. Must be a subset of PixelsImageClasses, as other classes cannot be loaded into OpenGL 2D images, otherwise you may get EImageClassNotSupportedForOpenGL exception. Pass empty set [] to load into any allowed class (it's equivalent to passing LoadAsClass = PixelsImageClasses).

You can pass e.g. [TRGBImage] to force loading into an RGB image without an alpha channel (it will be stripped from the image if necessary).

ResizeToX
After loading, resize to given width. Pass 0 to not resize width.
ResizeToY
After loading, resize to given height. Pass 0 to not resize height.
Interpolation
If any resizing will be needed (if ResizeToX / ResizeToY parameters request some specific size, and it is different than loaded image size) then the resize operation will use given interpolation.
Exceptions raised
EImageClassNotSupportedForOpenGL
When image class is not supported by OpenGL.
Public constructor Create(const URL: string; const LoadAsClass: array of TEncodedImageClass; const ASmoothScaling: boolean); overload;

Load image from disk, and prepare for drawing.

Parameters
URL
URL (or filename) from which to load the image. Often you want to pass here the result ot ApplicationData function, like:

Image := TGLImageCore.Create(ApplicationData('textures/my_image.png'), ...);

LoadAsClass
Constrain the possible image classes to load into. This can force removing (or adding) an alpha channel, or converting contents to grayscale or RGB, regardless of the preferred image file format. Must be a subset of PixelsImageClasses, as other classes cannot be loaded into OpenGL 2D images, otherwise you may get EImageClassNotSupportedForOpenGL exception. Pass empty set [] to load into any allowed class (it's equivalent to passing LoadAsClass = PixelsImageClasses).

You can pass e.g. [TRGBImage] to force loading into an RGB image without an alpha channel (it will be stripped from the image if necessary).

ASmoothScaling
The initial value of SmoothScaling, determines whether the image scaling is smooth (bilinear filtering) or not (nearest-pixel filtering). You can always change it later through the SmoothScaling property. But each change has a small cost, so it's more efficient to just set the initial value correctly.
Public destructor Destroy; override;
 
Public function Rect: TRectangle;

Rectangle representing the inside of this image. Always (Left,Bottom) are zero, and (Width,Height) correspond to image sizes.

Public procedure Draw; overload; deprecated 'use the Draw overload that takes position as explicit parameter';

Warning: this symbol is deprecated: use the Draw overload that takes position as explicit parameter

Draw the image as 2D on screen.

The X, Y parameters determine where the left-bottom corner of the image will be placed (from 0 to size - 1). The overloaded version without X, Y parameters uses current WindowPos.

You should only use this inside TUIControl.Render. We require that current projection is 2D and lighting / depth test and such are off, which is the default state there.

The image is drawn in 2D. In normal circumstances 1 pixel of the image is just placed over 1 pixel of the screen, and we draw the whole image. But you can use the overloaded versions where you specify DrawWidth, DrawHeight or ScreenRect, and then the indicated image portion is stretched over the designated screen area. Note: if you plan to use such stretching when drawing the image, then you usually want to create the image with SmoothScaling = True (otherwise the scaling will look pixelated).

Note that the image position (ImageX, ImageY) is specified like a texture coordinate. So (0, 0) is actually the left-bottom corner of the left-bottom pixel, and (Width,Height) is the right-top corner of the right-top pixel. That is why image position and sizes are floats, it makes sense to render partial pixels this way (make sure you have SmoothScaling = True to get nice scaling of image contents).

You can also flip the image horizontally or vertically, e.g. use ImageX = Width and ImageWidth = -Width to mirror image horizontally. Although it's usually more comfortable to flip using DrawFlipped methods.

Public procedure Draw(const X, Y: Single); overload;
 
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Single); overload;
 
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Single; const ImageX, ImageY, ImageWidth, ImageHeight: Single); overload;
 
Public procedure Draw(const Pos: TVector2Integer); overload;
 
Public procedure Draw(const ScreenRect: TFloatRectangle); overload;
 
Public procedure Draw(const ScreenRect, ImageRect: TFloatRectangle); overload;
 
Public procedure Draw(const ScreenRect: TRectangle); overload;
 
Public procedure Draw(const ScreenRect: TRectangle; const ImageX, ImageY, ImageWidth, ImageHeight: Single); overload;
 
Public procedure Draw(const ScreenRect, ImageRect: TRectangle); overload;
 
Public procedure Draw(ScreenRects, ImageRects: PFloatRectangleArray; const Count: Integer); overload; virtual;
 
Public procedure DrawFlipped(const ScreenRect: TRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
 
Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
 
Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; ImageRect: TFloatRectangle; const FlipHorizontal, FlipVertical: boolean); overload;
 
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Single; const CornerTop, CornerRight, CornerBottom, CornerLeft: Integer); overload;

Draw the image on the screen, divided into 3x3 parts for corners, sides, and inside.

Just like the regular Draw method, this fills a rectangle on the 2D screen, with bottom-left corner in (X, Y), and size (DrawWidth, DrawHeight). The image is divided into 3 * 3 = 9 parts:

  • 4 corners, used to fill the corners of the screen rectangle. They are not stretched.

  • 4 sides, used to fill the sides of the screen rectangle between the corners. They are scaled in one dimension, to fill the space between corners completely.

  • the inside. Used to fill the rectangular inside. Scaled in both dimensions as necessary.

Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Single; const Corner: TVector4Integer); overload;
 
Public procedure Draw3x3(const ScreenRect: TRectangle; const Corner: TVector4Integer); overload;
 
Public procedure Load(const AImage: TEncodedImage); virtual;

Load the given image contents. Use this to efficiently replace the image contents on GPU. Updates the Width, Height, Alpha to correspond to new image.

Public procedure PrepareResources; virtual;

Prepare all the possible resources. For descendants that load some stuf on demand (TGLImageOnDemand and TGLImage) this method can be used to force loading it now (if possible). This is only useful if you want to avoid slowdown when loading it later, and prefer to do the loading now.

Properties

Public property Width: Cardinal read GetWidth;
 
Public property Height: Cardinal read GetHeight;
 
Public property Alpha: TAutoAlphaChannel read FAlpha write FAlpha default acAuto;

How to render the alpha channel of the texture.

  • acAuto means to guess correct alpha channel from the loaded image contents, and the current Color. We use alpha blending if the loaded image alpha indicates so, or Color[3] < 1. Otherwise we use alpha testing if the loaded image alpha indicates so. Otherwise we don't use any alpha, we render image opaque.

  • acNone means to ignore it.

  • acTest means to render with alpha-test.

  • acBlending means to render with blending.

This is initialized based on loaded image class and data. This means that e.g. if you have smooth alpha channel in the image, it will be automatically rendered with nice blending.

You can change the value of this property to force a specific rendering method, for example to force using alpha test or alpha blending regardless of alpha values. Or to disable alpha channel usage, because your image must always cover pixels underneath.

Remember that you can also change the alpha channel existence at loading: use LoadAsClass parameters of LoadImage or TGLImageCore.Create to force your image to have/don't have an alpha channel (e.g. use LoadAsClass=[TRGBImage] to force RGB image without alpha, use LoadAsClass=[TRGBAlphaImage] to force alpha channel).

Public property BlendingSourceFactor: TBlendingSourceFactor read FBlendingSourceFactor write FBlendingSourceFactor default DefaultBlendingSourceFactor;

Blending source factor, if we use blending (see Alpha).

Public property BlendingDestinationFactor: TBlendingDestinationFactor read FBlendingDestinationFactor write FBlendingDestinationFactor default DefaultBlendingDestinationFactor;

Blending destination factor, if we use blending (see Alpha).

Public property BlendingConstantColor: TVector4 read FBlendingConstantColor write FBlendingConstantColor;

For some blending source or destination factors (see BlendingSourceFactor, BlendingDestinationFactor), this constant color (or it's alpha value) take part in the blending equation. Used only if blending (see Alpha). By default, opaque white.

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

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

Public property IgnoreTooLargeCorners: boolean read FIgnoreTooLargeCorners write FIgnoreTooLargeCorners default false;

Ignore (do not log to CastleLog) situations when Draw3x3 cannot work because corners are larger than draw area size. Set this to True when it's perfectly possible (you do not want to even see it in log) for Draw3x3 calls to fail because corners are larger than draw area size.

Public property Color: TCastleColor read FColor write FColor;

Color to multiply the texture contents (all RGBA channels). By default this is White, which is (1, 1, 1, 1) as RGBA, and it means that texture contents are not actually modified. This case is also optimized when possible, to no multiplication will actually happen.

Note that the alpha of this color does not determine our alpha rendering mode (it cannot, as you can change this color at any point, and after creation the Alpha is never automatically updated). If you set a color with alpha <> 1, consider setting also Alpha property to whatever you need.

Note that if use TGrayscaleImage with TGrayscaleImage.TreatAsAlpha (which means that texture does not contain any RGB information), then only this color's RGB values determine the drawn RGB color.

Public property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling;

Is the image scaling mode smooth (bilinear filtering) or not (nearest-pixel filtering). This is important if you draw the image such that one image pixel does not perfectly fit one screen pixel.

If you will not ever do any scaling, then set this to False. It may cause minimally faster drawing, and avoids any possible artifacts from bilinear filtering.

If you will do scaling, you usually want to set this to True, unless you deliberately want a pixelated look (for pixelart).

Note that switching this property after this object is constructed is possible, but costly.

Public property ScalingPossible: boolean read FSmoothScaling write SetSmoothScaling; deprecated 'use SmoothScaling';

Warning: this symbol is deprecated: use SmoothScaling

 
Public property CenterX: Single read FCenterX write FCenterX default 0.5;

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

Public property CenterY: Single read FCenterY write FCenterY default 0.5;

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

Public property Rotation: Single read FRotation write FRotation default 0;

Rotation in radians. Increase to rotate in a counter-clockwise direction. Hint: use function like ArcTan2 from Math unit to convert 2D direction into a rotation angle.

Public property Clip: boolean read FClip write FClip;

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

Public property ClipLine: TVector3 read FClipLine write FClipLine;

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. This provides a functionality similar to desktop OpenGL glClipPlane (working on all platforms – desktop, mobile).


Generated by PasDoc 0.15.0.