Unit CastleWindow

Description

Window with rendering context suitable for rendering of "Castle Game Engine". Provides a window that can render hierarchy of TCastleUserInterface, which includes a hierarchy of 3D and 2D scenes inside TCastleViewport. Use the TCastleWindow as your window class.

Application object (instance of class TCastleApplication) is a central manager of all open TCastleWindow windows.

Using this unit:

  1. Declare and create TCastleWindow instance. (Or a descendant like TCastleWindow.)

  2. Assign Window properties and callbacks like OnRender, OnResize, Width, Height, Caption.

  3. To initialize your game, you usually want to use Application.OnInitialize.

    If you only care about standalone programs (for normal OSes like Linux, Windows, MacOSX, but not Android) you may also just initialize your game in the main program block, although using Application.OnInitialize is still often comfortable.

  4. Call Window.Open, this will actually show the window and it's associated OpenGL context.

    The first window open calls Application.OnInitialize. It also calls OnOpen and OnResize callbacks.

  5. Call Application.Run. This will enter message loop that will call appropriate windows' callbacks at appropriate times (OnRender, OnPress, OnRelease, OnResize, OnUpdate and many more). There are also some Application callbacks, like Application.OnUpdate.

    For more advanced needs you can use something like

    while Application.ProcessMessage do <something>;

    instead of Application.Run.

    You can also call Window.OpenAndRun, this is just a shortcut for Window.Open + Application.Run.

  6. Application.Run ends when you call Application.Quit or when you close last visible window using Close(true).

    User is also allowed to close a window using WindowManager facilities (clicking on "X" button in the frame corner, pressing Alt+F4 or something like that). By default, such user action will make window close (but you can freely customize what your program does when user tries to close the window using callback OnCloseQuery).

So the simplest example of using this unit can look like this:

uses CastleWindow;

var
  Window: TCastleWindow;

procedure Render(Sender: TCastleContainer);
begin
  // ... e.g. DrawRectangle or TDrawableImage.Draw calls inside
end;

begin
  Window := TCastleWindow.Create(Application);
  Window.OnResize := @Resize;
  Window.Caption := 'Simplest CastleWindow example';
  Window.OpenAndRun;
end.

More component-like approach: For larger programs, it makes more sense to divide functionality into controls, which are classes descending from TCastleUserInterface. You can override TCastleUserInterface methods to render, capture input and so on (see e.g. TCastleUserInterface.Render, TCastleUserInterface.Press, TCastleUserInterface.Update.) You can then add your control to the TCastleWindow.Controls list.

Some features list:

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TMenuEntry A basic class representing basic menu building block.
Class TMenuEntryWithCaption  
Class TMenu TMenuEntry that contains a list of menu entries.
Class TMenuItem TMenuEntry that is a simple, clickable menu item.
Class TMenuSeparator TMenuEntry that acts as a visual separator (horizontal line or something like that) between menu items.
Class TMenuItemChecked TMenuItem that should visualize Checked state somehow to the user.
Class TMenuItemRadio Menu radio item.
Class TMenuItemRadioGroup A group of radio buttons.
Class TMenuItemToggleFullScreen Menu item that toggles TCastleWindow.FullScreen.
Class EGLContextNotPossible  
Class TWindowContainer Non-abstract implementation of TCastleContainer that cooperates with TCastleWindow.
Class TCastleWindow Window to render everything (3D or 2D) with Castle Game Engine.
Class TWindowList  
Class TCastleApplication Application, managing all open TCastleWindow (OpenGL windows).

Functions and Procedures

function Application: TCastleApplication;
procedure Resize2D(Container: TCastleContainer);
function KeyToString(const KeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean;
function KeyString(const AKeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean; deprecated 'use KeyToString';
function MenuItemFromSmallId(SearchSmallId: Integer): TMenuItem;
function SRemoveMnemonics(const S: string): string;
function SQuoteMenuEntryCaption(const S: string): string;

Types

TWindowParseOption = (...);
TWindowParseOptions = set of TWindowParseOption;
PWindowParseOptions = ˆTWindowParseOptions;
TAntiAliasing = (...);
TUIContainer = CastleUIControls.TCastleContainer deprecated 'use TCastleContainer';
TCastleContainer = CastleUIControls.TCastleContainer;
TMenuEntryList = specialize TObjectList<TMenuEntry>;
TWindowMessageType = (...);
TUpdateFunc = procedure;
TMenuClickFunc = procedure (Container: TCastleContainer; Item: TMenuItem);
TDropFilesFunc = procedure (Container: TCastleContainer; const FileNames: array of string);
TGLContextRetryOpenFunc = function (Window: TCastleWindow): boolean;
TResizeAllowed = (...);
TCaptionPart = (...);
PGtkGLArea = PGtkWidget;
TCastleWindowCustom = TCastleWindow deprecated 'use TCastleWindow';
TCastleWindowBase = TCastleWindow deprecated 'use TCastleWindow';
TCastleWindowClass = class of TCastleWindow;
TGLApplication = TCastleApplication deprecated;

Constants

WindowPositionCenter = -1000000;
WindowDefaultSize = -1000000;
StandardParseOptions = [poGeometry, poScreenGeometry, poDisplay, poMacOsXProcessSerialNumber, poLimitFps];
DefaultDepthBits = 24;
DepthBitsFallback = 16;
DefaultFpsCaptionUpdateDelay = 1.0;
DefaultLimitFPS = TCastleApplicationProperties.DefaultLimitFPS deprecated 'use TCastleApplicationProperties.DefaultLimitFPS';
DefaultAntiAliasing = aaNone;
AntiAliasingNames: array [TAntiAliasing] of string = ( 'None', '2 samples (faster)', '2 samples (nicer)', '4 samples (faster)', '4 samples (nicer)', '8 samples (faster) (only latest GPUs)', '8 samples (nicer) (only latest GPUs)', '16 samples (faster) (only latest GPUs)', '16 samples (nicer) (only latest GPUs)' );

Description

Functions and Procedures

function Application: TCastleApplication;

Single global instance of TCastleApplication. Automatically created / destroyed by CastleWindow unit.

procedure Resize2D(Container: TCastleContainer);

A simple TCastleWindow.OnResize callback implementation, that sets 2D projection. You can use it like Window.OnResize := Resize2D; or just by calling it directly from your OnResize callback.

It does

RenderContext.Viewport := Window.Rect;
OrthoProjection(0, Window.Width, 0, Window.Height);

function KeyToString(const KeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean;

Describe given key. Key is given as combination of character (UTF-8 character as String, may be '') and Key code (may be keyNone), and additional required Modifiers (although some modifiers may be already implied by KeyString, e.g. when it is CtrlA). See TMenuItem.Key and TMenuItem.KeyString and TMenuItem.Modifiers.

Only when Key = keyNone and KeyString = '' then this combination doesn't describe any key, and we return False. Otherwise we return True and set S.

function KeyString(const AKeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean; deprecated 'use KeyToString';

Warning: this symbol is deprecated: use KeyToString

This item has no description.

function MenuItemFromSmallId(SearchSmallId: Integer): TMenuItem;

Search for menu item with given SmallId. SearchSmallId must be a SmallId of some existing (i.e. created and not destroyed yet) TMenuItem. This function returns this TMenuItem.

function SRemoveMnemonics(const S: string): string;

Returns S with each '__' replaced with single '_', any other '_' removed.

In other words: with mnemonics (as defined by TMenuEntryWithCaption.Caption removed.

function SQuoteMenuEntryCaption(const S: string): string;

Returns S with each underscore '_' replaced by two underscores, '__'.

In other words: S will not contain any mnemonics. If you will assign S to TMenuEntryWithCaption.Caption, then this menu entry caption will display exactly S, without any mnemonics. Single '_' in S will be displayed exactly as single '_'.

Types

TWindowParseOption = (...);

This item has no description.

Values
  • poGeometry
  • poScreenGeometry
  • poDisplay
  • poMacOsXProcessSerialNumber
  • poLimitFps
TWindowParseOptions = set of TWindowParseOption;

This item has no description.

PWindowParseOptions = ˆTWindowParseOptions;

This item has no description.

TAntiAliasing = (...);

Anti-aliasing values for TCastleWindow.AntiAliasing.

Values
  • aaNone
  • aa2SamplesFaster: 2 samples, "don't care" hint.
  • aa2SamplesNicer: 2 samples, "nicest" hint (quincunx (5 taps) for NVidia).
  • aa4SamplesFaster: 4 samples, "don't care" hint.
  • aa4SamplesNicer: 4 samples, "nicest" hint (9 taps for NVidia).
  • aa8SamplesFaster: 8 samples, "don't care" hint.
  • aa8SamplesNicer: 8 samples, "nicest" hint.
  • aa16SamplesFaster: 16 samples, "don't care" hint.
  • aa16SamplesNicer: 16 samples, "nicest" hint.
TUIContainer = CastleUIControls.TCastleContainer deprecated 'use TCastleContainer';

Warning: this symbol is deprecated: use TCastleContainer

This item has no description.

TCastleContainer = CastleUIControls.TCastleContainer;

This item has no description.

TMenuEntryList = specialize TObjectList<TMenuEntry>;

This item has no description.

TWindowMessageType = (...);

Type of message box, for TCastleWindow.MessageOK and TCastleWindow.MessageYesNo.

Values
  • mtInfo
  • mtWarning
  • mtQuestion
  • mtError
  • mtOther
TUpdateFunc = procedure;

This item has no description.

TMenuClickFunc = procedure (Container: TCastleContainer; Item: TMenuItem);

This item has no description.

TDropFilesFunc = procedure (Container: TCastleContainer; const FileNames: array of string);

This item has no description.

TGLContextRetryOpenFunc = function (Window: TCastleWindow): boolean;

This item has no description.

TResizeAllowed = (...);

This item has no description.

Values
  • raNotAllowed
  • raOnlyAtOpen
  • raAllowed
TCaptionPart = (...);

This item has no description.

Values
  • cpPublic
  • cpFps
PGtkGLArea = PGtkWidget;

For now I use GtkDrawingArea when CASTLE_WINDOW_GTK_2. But, really, GLAreaGtk could be any gtk widget with CASTLE_WINDOW_GTK_2.

TCastleWindowCustom = TCastleWindow deprecated 'use TCastleWindow';

Warning: this symbol is deprecated: use TCastleWindow

This item has no description.

TCastleWindowBase = TCastleWindow deprecated 'use TCastleWindow';

Warning: this symbol is deprecated: use TCastleWindow

This item has no description.

TCastleWindowClass = class of TCastleWindow;

This item has no description.

TGLApplication = TCastleApplication deprecated;

Warning: this symbol is deprecated.

Deprecated name for TCastleApplication.

Constants

WindowPositionCenter = -1000000;

This item has no description.

WindowDefaultSize = -1000000;

This item has no description.

StandardParseOptions = [poGeometry, poScreenGeometry, poDisplay, poMacOsXProcessSerialNumber, poLimitFps];

All "normal" command-line options, that most programs using CastleWindow should be able to handle without any problems.

In other words, most programs calling TCastleWindow.ParseParameters method can safely pass as the 1st parameter this constant, StandardParseOptions. Or they can simply call overloaded version of TCastleWindow.ParseParameters that doesn't take any parameters, it is always equivalent to calling TCastleWindow.ParseParameters(StandardParseOptions).

DefaultDepthBits = 24;

This item has no description.

DepthBitsFallback = 16;

This item has no description.

DefaultFpsCaptionUpdateDelay = 1.0;

This item has no description.

DefaultLimitFPS = TCastleApplicationProperties.DefaultLimitFPS deprecated 'use TCastleApplicationProperties.DefaultLimitFPS';

Warning: this symbol is deprecated: use TCastleApplicationProperties.DefaultLimitFPS

This item has no description.

DefaultAntiAliasing = aaNone;

This item has no description.

AntiAliasingNames: array [TAntiAliasing] of string = ( 'None', '2 samples (faster)', '2 samples (nicer)', '4 samples (faster)', '4 samples (nicer)', '8 samples (faster) (only latest GPUs)', '8 samples (nicer) (only latest GPUs)', '16 samples (faster) (only latest GPUs)', '16 samples (nicer) (only latest GPUs)' );

This item has no description.


Generated by PasDoc 0.16.0.