Class TGLImage

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type TGLImage = class(TObject)

Description

Image ready to be drawn on 2D screen.

Hierarchy

  • TObject
  • TGLImage

Overview

Methods

Public constructor Create(const Image: TCastleImage; const AScalingPossible: boolean = false);
Public constructor Create(const URL: string);
Public constructor Create(const URL: string; const LoadAsClass: array of TCastleImageClass; const ResizeToX: Cardinal = 0; const ResizeToY: Cardinal = 0; const Interpolation: TResizeInterpolation = riNearest);
Public constructor Create(const URL: string; const LoadAsClass: array of TCastleImageClass; const AScalingPossible: boolean);
Public destructor Destroy; override;
Public procedure Draw;
Public procedure Draw(const X, Y: Integer);
Public procedure Draw(const Pos: TVector2Integer);
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Integer; const ImageX, ImageY, ImageWidth, ImageHeight: Single);
Public procedure Draw(const ScreenRectangle: TRectangle);
Public procedure Draw(const ScreenRectangle: TRectangle; const ImageX, ImageY, ImageWidth, ImageHeight: Single);
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Integer; const CornerTop, CornerRight, CornerBottom, CornerLeft: Integer);
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Integer; const Corner: TVector4Integer);
Public procedure Draw3x3(const ScreenRectangle: TRectangle; const Corner: TVector4Integer);
Public procedure Load(const Image: TCastleImage);

Properties

Public property Width: Cardinal read FWidth;
Public property Height: Cardinal read FHeight;
Public property Alpha: TAlphaChannel read FAlpha write FAlpha;
Public property IgnoreTooLargeCorners: boolean read FIgnoreTooLargeCorners write FIgnoreTooLargeCorners default false;
Public property Color: TCastleColor read FColor write FColor;

Description

Methods

Public constructor Create(const Image: TCastleImage; const AScalingPossible: boolean = false);

Prepare image for drawing.

Exceptions raised
EImageClassNotSupportedForOpenGL
When Image class is not supported by OpenGL.
Public constructor Create(const URL: string);

Load image from disk, and prepare for drawing.

Parameters
LoadAsClass
Force a specific image class to load. 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 TCastleImageClass; const ResizeToX: Cardinal = 0; const ResizeToY: Cardinal = 0; const Interpolation: TResizeInterpolation = riNearest);
 
Public constructor Create(const URL: string; const LoadAsClass: array of TCastleImageClass; const AScalingPossible: boolean);
 
Public destructor Destroy; override;
 
Public procedure Draw;

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 when TUIControl.RenderStyle returns rs2D. This means that we require that current projection is 2D and lighting / depth test and such are off.

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. You can also use the overloaded version with 8 parameters where you explicitly specify the DrawWidth and DrawHeight of the rectangle on the screen, and explicitly choose the portion of the image to draw. If you want to draw scaled image (that is, use ImageWidth different than DrawWidth or ImageHeight different than DrawHeight) be sure to construct an image with ScalingPossible = True (otherwise runtime scaling may look ugly).

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 ScalingPossible = 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.

Public procedure Draw(const X, Y: Integer);
 
Public procedure Draw(const Pos: TVector2Integer);
 
Public procedure Draw(const X, Y, DrawWidth, DrawHeight: Integer; const ImageX, ImageY, ImageWidth, ImageHeight: Single);
 
Public procedure Draw(const ScreenRectangle: TRectangle);
 
Public procedure Draw(const ScreenRectangle: TRectangle; const ImageX, ImageY, ImageWidth, ImageHeight: Single);
 
Public procedure Draw3x3(const X, Y, DrawWidth, DrawHeight: Integer; const CornerTop, CornerRight, CornerBottom, CornerLeft: Integer);

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: Integer; const Corner: TVector4Integer);
 
Public procedure Draw3x3(const ScreenRectangle: TRectangle; const Corner: TVector4Integer);
 
Public procedure Load(const Image: TCastleImage);

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

Properties

Public property Width: Cardinal read FWidth;
 
Public property Height: Cardinal read FHeight;
 
Public property Alpha: TAlphaChannel read FAlpha write FAlpha;

How to treat alpha channel of the texture.

  • acNone means to ignore it.

  • acSimpleYesNo means to render with alpha-test.

  • acFullRange 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 TGLImage.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 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.


Generated by PasDoc 0.13.0 on 2014-04-30 22:06:43