There are a few ways to display an image using Castle Game Engine.
The last method is to load the image to
TDrawableImage. This is the low-level approach, where you will need to manually handle drawing the image at the appropriate moment, following manual about custom-drawing UI things in CGE.
The approaches 1 and 2 can be used when designing the game in the editor and are more advised.
All approaches handle all the image formats supported by CGE, like PNG or JPG; see castle-view-image docs for the full list.
TCastleImageControl is a descendant of
TCastleUserInterface and allows to use the image as part of the UI. It refers to
TCastleImagePersistent to load image contents using cache. It is a trivial user-interface control to render image on the screen. It can be added and configured in the editor.
TEncodedImage is an image loaded to a regular memory (RAM) to operate on it by Pascal code (that is, on CPU).
Important descendant of
TEncodedImage is TCastleImage which is an image that is expressed in memory as directly-accessible array of pixels. It has more descendants for grayscale, RGB, RGBA, float-based images etc. If you want to edit image on CPU, this is what you will use. E.g. create TRGBAlphaImage and iterate over TRGBAlphaImage.Pixels. There are many methods to draw lines, shapes, text to the image.
Images are usually 2D, but we also support 3D, for 3D (volumetric) textures.
TDrawableImage holds an image (loaded from
TEncodedImage) on GPU. It can be actually rendered on the screen.
TCastleImagePersistent is a container around
TDrawableImage. It is using cache to load images. It is visually configurable in the CGE editor.
It’s like a
TPicture in VCL — it doesn’t draw the image, but it has everything else to describe how to load and draw the image. It’s used by
There are a few X3D nodes to express images. The most important are
TODO: There are too many classes above. In time, we hope to hide this complexity more, some of these classes should become internal (or not necessary at all).
You can load the image to
TCastleScene, using the
TCastleScene.Load method (or by setting
TCastleScene.URL). While traditionally
TCastleScene is used for "heavier" 3D and 2D assets, it is perfectly suitable to also just use it to render a trivial rectangle with a simple image. See CGE manual about loading and using scenes.
Under the hood, this method creates nodes to define a rectangle, and applies the image as a texture. The "manual" way of achieving the same is presented in the example code here.
This approach is deprecated now, as
TCastleImageTransform is better.
By default we display an entire image. Alternatively, when loading the image to
TCastleScene, you can use a special syntax with URL anchors to specify a subset of the image. That is, instead of
you can load
This will cut the appropriate subset of the image.
These are the parameters:
Left coordinate of chosen rectangle (in image pixels)
Bottom coordinate of chosen rectangle (in image pixels)
Width of chosen rectangle (in image pixels)
Height of chosen rectangle (in image pixels)
All the parameters are integers (we have not yet found a use-case to make them floats, but please tell us if you have such use-case).
Note that if you specify area that is too large (outside of the actual image area), the excessive pixels will show the clamped image border (the image is simply rendered as a texture with repeat=FALSE).
To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.
Copyright Michalis Kamburelis and Castle Game Engine Contributors.