TCastleWindow
class represents a window suitable for Castle Game Engine rendering.
Most CGE applications use this class (although there is an alternative TCastleControl, but we advise TCastleWindow
for most cases).
The TCastleWindow
has a number of alternative backends, using different libraries underneath to manage the window and OpenGL(ES) context properties. By default, we use a backend that is considered "best" for the current operating system you’re compiling to, but you can override this choice by defining a symbol CASTLE_WINDOW_xxx
at the compilation time. You can define this symbol in various places, e.g. in CastleEngineManifest.xml file.
Right now, we always use exactly one "backend", which is determined at the compile-time when you compile your application. In the future, we want to rework the CastleWindow infrastructure to enable you to use multiple backends, each backend in a separate unit, and (optionally) allow you to select the best backend at runtime.
The default backend on Windows. Looks native and supports everything.
Uses Windows API (WinAPI). By default it uses wgl
to initialize OpenGL context. Can be also used (when symbol OpenGLES
is defined) to initialize OpenGLES context using EGL. This way, you can test OpenGLES rendered on desktop Windows systems.
Supported platforms:
Windows only.
Advantages:
TCastleWindow.MainMenu
is implemented as actual Windows menu bar, so it looks good and native.
Dialog windows like TCastleWindow.FileDialog
are implemented using standard Windows dialog boxes, so again they look nice and native.
Supports both OpenGL (by wgl
) and OpenGLES (by EGL
) contexts.
The default backend on most Unix systems, like Linux. Looks native and supports everything (except changing screen resolution, see below). Uses GTK 2. Initializes OpenGL(ES) context using Xlib + glX (for OpenGL) or EGL (for OpenGLES).
At some point, this will be also available under CASTLE_WINDOW_GTK
symbol. At some further point, we will add backend CASTLE_WINDOW_GTK_3
and when it’s stable, CASTLE_WINDOW_GTK
will be equivalent to CASTLE_WINDOW_GTK_3
.
Supported platforms:
Works on any OS where GTK + glX / EGL works. Currently tested under Linux, FreeBSD, macOS.
Advantages:
TCastleWindow.MainMenu
is implemented using GTK menu bar.
Dialog windows like TCastleWindow.FileDialog
are implemented using GTK dialogs. So they look good and native.
Supports both OpenGL (by glX
) and OpenGLES (by EGL
) contexts.
Known problems:
Tab
key cannot work as menu item shortcut (it’s always only for switching focus). This is an issue with GTK 2.
Application.TryVideoChange
(to change screen resolution at runtime) is not finished, i.e. always returns false. See TODOs near CASTLE_WINDOW_USE_XF86VMODE
definition.
History: at some point this was using GtkGlExt, and was portable to any system using GTK (even to Windows). This has changed because:
This way our dependencies are simpler (not every system has GtkGlExt),
there was not practical usage of this backend outside of GTK+Xlib anyway.
A backend useful on most Unix systems, like Linux, that use X11.
Advantages compared to CASTLE_WINDOW_GTK
(which supports similar platforms):
Doesn’t depend on GTK (one less dependency of your application).
Application.TryVideoChange
works.
Supports both OpenGL (by glX
) and OpenGLES (by EGL
) contexts. By default it uses glX
to initialize OpenGL context. But when symbol OpenGLES
is defined, it uses EGL to initialize OpenGLES context. This way, you can test OpenGLES renderer on desktop Unix systems.
Known problems:
Doesn’t provide nicely-looking menu bar (TCastleWindow.MainMenu
). Menu bar is not visible.
Doesn’t provide nicely-looking dialog boxes (TCastleWindow.FileDialog
). The dialog boxes are implemented using simple modal boxes in CastleMessages
instead, which works OK but doesn’t look pretty.
Full-screen (TCastleWindow.FullScreen
) is realized using an obsolete method ("override_redirect") that doesn’t allow to switch applications with Alt+Tab from a fullscreen window.
Backend that uses TForm
and other LCL / FMX components to create a window. It is fully-functional:
of course, has OpenGL rendering area filling the window,
supports main menu (TCastleWindow.MainMenu
),
supports native dialogs (TCastleWindow.FileDialog
and others)
supports fullscreen toggling (TCastleWindow.FullScreen
).
To use this define CASTLE_WINDOW_FORM
.
It is automatically used right now when you compile with Delphi for non-Windows platforms (Linux, macOS, Android, iOS…).
Moreover, to use this from Lazarus (LCL):
Add castle_components
package to the requirements of the castle_window
Lazarus package.
It will also automatically add LazOpenGLContext
package as dependency, which is good. We need castle_components
package for LCL helpers (like converting mouse/keys between LCL and CastleKeysMouse), and we need LazOpenGLContext
package for TOpenGLControl.
Or you can use alternative_castle_window_based_on_lcl.lpk
instead of castle_window.lpk
in the project. This should take care of above 2 things.
Usually you should compile programs using Lazarus then (IDE or lazbuild
), to automatically have correct LCL paths used. If you use our build tool or CGE editor, set build_using_lazbuild="true"
in CastleEngineManifest.xml.
Supported platforms: everywhere where LCL or FMX runs.
Advantages:
Can use any LCL or FMX backend, so in principle allows to use TCastleWindow
everywhere where they work.
Even some optional (not available in all backends) features are implemented: TCastleWindow.MainMenu
or TCastleWindow.FileDialog
or TCastleWindow.FullScreen
.
Known problems:
LCL: Various small things don’t work perfectly using this backend, due to small problems/unfinished features in LCL. In practice we don’t advise this backend anymore with FPC or Lazarus — for all supported platform, we have a better specialized backend when you come from FPC, that also doesn’t depend on LCL.
Screen resizing (Application.TryVideoChange
) is not implemented. LCL doesn’t implement it.
LCL: Message loop may stutter in case of a lot of mouse movement (may be visible in case of "mouse look" navigation).
LCL: Doesn’t support OpenGLES, as underlying TOpenGLControl
doesn’t support it.
Backend using Android NDK cooperating with Castle Game Engine Android activity code. Used when you compile for Android, which you should always do using our build tool.
Use existing OpenGL(ES) context. This is useful when the engine is used as a library, and an external code initializes OpenGL(ES) context, merely informing CGE about it. Useful for various cases, e.g. to "drive" Castle Game Engine rendering from another programming language. See examples/library/
for an example of wrapping CGE in a library.
Also, this is the only possible backend to use CGE on iOS or Nintendo Switch and it is automatically used there.
Supported platforms: All platforms. But note that using this backend requires additional "outside" code to manage our library. In case of iOS and Nintendo Switch, this is automatically provided when building using our build tool.
Backend using Cocoa with AppKit library, coded using Objective-Pascal. This is the technology to create native applications on macOS.
This backend is only available for macOS, and also is the advised backend there. It gives a native look for macOS applications, and covers all standard TCastleWindow
features:
Opening and closing multiple windows with OpenGL context.
Key and mouse handling, including mouse wheel events.
TCastleWindow.MainMenu
, realized as native macOS menu, with submenus, key shortcuts, checked, enabled menu items.
TCastleWindow.FileDialog
, native dialog to open/save files.
TCastleWindow.ColorDialog
, native dialog to pick a color.
TCastleWindow.MessageOK
, TCastleWindow.MessageYesNo
- native alerts to notify about something or ask a question.
Opening associated files on macOS, see CastleEngineManifest.xml - Associated file types, is also supported with some necessary code in this backend.
Known problems:
TODO: Fullscreen is not correct. The menu bar and macOS dock remain visible, covering parts of the fullscreen window. We have a code in place to deal with it… unsuccessfully, so far.
TODO: Hiding mouse cursor doesn’t work. Again we have a code to hide/unhide cursor, but it doesn’t work properly for unknown (yet!) reason.
When building, a few messages like warning: section "__datacoal_nt" is deprecated: .section __DATA, __datacoal_nt, coalesced
are displayed. Compiling LCL app on macOS shows these warnings too. There is no solution for now, but the warnings can be safely ignored.
A dummy backend that does nothing, but compiles. Can be used as a starting point when developing new CastleWindow backends.
Supported platforms: All platforms.
Invent a symbol CASTLE_WINDOW_FOO
for a new backend, document it in the "available backends list" above.
Create a file castlewindow_foo.inc
with contents from castlewindow_backend_template.inc
and conditionally include it from castlewindow_backend.inc
.
Adjust defining CASTLE_WINDOW_HAS_VIDEO_CHANGE
and CASTLE_WINDOW_USE_PRIVATE_MODIFIERS_DOWN
for your backend.
Implement all methods in castlewindow_foo.inc
.
Call TCastleWindow.DoXxx
functions at appropriate places from your backend. You can call all DoUpdate
all Application.OpenWindows
using Application.FOpenWindows.DoUpdate
.
Call ApplicationProperties._Update
when appropriate. Remember that you can always assume that the ONLY existing instance of TCastleApplication
is Application
.
Remember that probably you will have to call ReleaseAllKeysAndMouse
when user switches to another window or activates MainMenu.
To improve this documentation just edit this page and create a pull request to cge-www repository.
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.