Class TCastleApplication

If VideoResize, then next VideoChange call will try to resize the screen to given VideoResizeWidth / VideoResizeHeight. Otherwise, next TryVideoChange and VideoChange will use default screen size.

This item has no description.

This item has no description.

Override TCustomApplication to pass TCustomApplication.Log to CastleLog logger.

Every backend must override this. TCustomApplication will automatically catch exceptions occuring inside DoRun.

This item has no description.

Describe the changes recorded in variables VideoXxx, used by VideoChange and TryVideoChange. This is a multiline string, each line is indented by 2 spaces, always ends with CastleUtils.NL.

Change the screen size, color bits and such, following the directions you set in VideoColorBits, VideoResize, VideoResizeWidth / VideoResizeHeight, and VideoFrequency variables. Returns True if success.

See example code examples/user_interface/screen_resolution_change for a working example.

Simple example usage:

unit GameChangeVideoResolution;

interface

var
  // TODO: Allow user to configure it somehow
  UserWantsToChangeScreenResolution: Boolean = true;

{ Change screen resolution, if desired by UserWantsToChangeScreenResolution. }
procedure ChangeResolution;

implementation

uses CastleWindow, CastleLog, CastleConfig;

procedure ChangeResolution;
begin
  if UserWantsToChangeScreenResolution then
  begin
    Application.VideoResize := true;
    // TODO: Allow user to choose the desired resolution
    Application.VideoResizeWidth := 1024;
    Application.VideoResizeHeight := 768;
    if not Application.TryVideoChange then
      WritelnWarning('Cannot change screen resolution, continuing with current settings');
  end;
end;

initialization
  UserWantsToChangeScreenResolution := UserConfig.GetValue('video/change_resolution', false);
  ChangeResolution;
finalization
  Application.VideoReset;
end.

TODO: Expose methods like EnumeratePossibleVideoConfigurations to predict what video settings are possible.

TODO: Prefix "Video" for the family of these functions is not clear. Something like "Screen" would be better.

Change the screen size, color bits and such, following the directions you set in VideoColorBits, VideoResize, VideoResizeWidth / VideoResizeHeight, and VideoFrequency variables. This actually just calls TryVideoChange and checks the result.

If not success: if OnErrorWarnUserAndContinue then we'll display a warning and continue. If not OnErrorWarnUserAndContinue then we'll raise an Exception.

Exceptions raised

Exception

If video mode change failed, and OnErrorWarnUserAndContinue = false.

Return default screen video mode. If you never called TryVideoChange (with success), then this does nothing. This is automatically called in Application.Destroy, so at finalization of this unit. This way your game nicely restores screen resolution for user.

This item has no description.

This item has no description.

List of all open windows.

Process messages from the window system. You have to call this repeatedly to process key presses, mouse events, redraws and everything else. Messages are processed and appropriate methods of TCastleUserInterface instances (including TCastleView) are called.

For simple programs calling the Run method is usually the best solution, Run just calls ProcessMessage in a loop. Manually using the ProcessMessage method allows you to implement modal dialog boxes (generally any kind of "display something until something happens" behavior). Make your own event loop like this:

while not SomethingHappened do
  Application.ProcessMessage(...);

This can used to implement routines that wait until a modal dialog box returns, like MessageOK or MessageYesNo.

For comfort, returns not Terminated. So it returns True if we should continue, that is if Terminate method was not called (directly or by closing the last window). If you want to check it (if you allow the user at all to close the application during modal box or such) you can do:

while not SomethingHappened do
  if not Application.ProcessMessage(...) then
    Break;

Do not assume too much about message processing internals. For example, not all ProcessMessage calls cause redraw, even if redraw is requested by Invalidate. When we have messages to process, we generally don't call redraw or even OnUpdate.

Parameters

WaitForMessage

If True (and some other conditions are met, for example we do not have to call OnUpdate continuosly) then we can block, waiting for an event to process.

Set this to True whenever you can, that is whenever your program only responds to user inputs (as opposed to making some operations, like animation or loading or ray-tracing something). Generally, when SomethingHappened from the example pseudo-code above can only be changed by user events (e.g. user has to click something; nothing happens if user doesn't click for 5 minutes or 5 hours). This allows to let OS and CPU have some rest, and spend time on other applications, or just sleep and conserve laptop battery power.

WaitToLimitFPS

If True, then we have backup mechanism for limiting CPU usage. When WaitForMessage mechanism cannot be used (becasue WaitForMessage is False or some other conditions disallow it), and user doesn't throw events at us (we don't want to sleep when user produces many events e.g. by mouse move), then we can do a small sleep to stabilize number of ProcessMessage calls at LimitFPS per second.

Set this to True whenever you can, that is whenever you don't need ProcessMessage to return as fast as it can. For example, when you're displaying some animation, then displaying LimitFPS frames should be enough. OTOH, if you really do something that should be done as fast as possible (like loading some file or ray-tracing) you probably have to set this to False.

Processes all pending messages. Do not wait for anything.

Contrast this with ProcessMessage method, that processes only a single event. Or no event at all (when no events were pending and AllowSuspend = False). This means that after calling ProcessMessage once, you may have many messages left in the queue (especially mouse move together with key presses typically makes a lot of events). So it's not good to use if you want to react timely to some user requests, e.g. when you do something time-consuming and allow user to break the task with Escape key.

ProcessAllMessages is like calling in a loop ProcessMessage(false, false), ends when ProcessMessage(false, false) didn't process any message or when quit was called (or last window closed).

So ProcessAllMessages makes sure we have processed all pending events, thus we are up-to-date with window system requests.

This item has no description.

Run the program using TCastleWindow, by doing the event loop. Think of it as just a shortcut for "while ProcessMessage do ;".

Note that this does nothing if OpenWindowsCount = 0, that is there are no open windows. Besides the obvious reason (you didn't call TCastleWindow.Open on any window...) this may also happen if you called Close (or Application.Terminate) from your window OnOpen / OnResize callback. In such case no event would probably reach our program, and user would have no chance to quit, so Run just refuses to work and exits immediately without any error.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Parse some command-line options and remove them from Parameters list. These are standard command-line parameters of Castle Game Engine programs.

See TCastleWindow.ParseParameters for more options specific to each window.

-h / --help

Output help, exit.

-v / --version

Output version, exit, Uses ApplicationProperties.Version.

--log-file FILE-NAME

Force log to given file, sets LogFileName.

--display X-DISPLAY-NAME

Sets Application.XDisplayName under Unix.

-psvn_x_xxx

(Only relevant on macOS.) A special parameter -psvn_x_xxx will be found and removed from the Parameters list. See http://forums.macrumors.com/showthread.php?t=207344 and http://stackoverflow.com/questions/10242115/os-x-strange-psn-command-line-parameter-when-launched-from-finder .

--no-limit-fps

Allows to disable ApplicationProperties.LimitFps, to allows to observe maximum FPS, see http://castle-engine.io/manual_optimization.php

--capabilities automatic|force-fixed-function|force-modern

Force OpenGL context to have specific capabilities, to test rendering on modern or ancient GPUs.

Moreover this also handles parameters from TCastleWindow.ParseParameters, if MainWindow is set already. But note that our templates do not set MainWindow so early. We recommend to explicitly set window size / Window.FullScreen from code and call TCastleWindow.ParseParameters right after, to allow user to override.

Moreover this also handles parameters from TSoundEngine.ParseParameters.

This item has no description.

Are we using OpenGLES for rendering.

Set XDisplay name, this will be used for all TCastleWindow that will be subsequently initialized by TCastleWindow.Open.

Note that this is exposed by GTK even for non-XWindows platforms, but I don't know what it does there.

Color bits per pixel that will be set by next VideoChange call, and that are tried to be used at TCastleWindow.Open. Zero means that system default is used.

Video frequency to set in next VideoChange call. Leave as 0 to use system default.

This item has no description.

The application and CastleWindow backend is initialized. Called only once, at the very beginning of the game, when we're ready to load everything and the first OpenGL context is initialized (right before calling TCastleUserInterface.GLContextOpen on all UIs).

For targets like Android or iOS, you should not do anything (even reading files) before this callback occurs. Only when this occurs, we know that external process told us "Ok, you're ready". So you should put all the game initialization in an Application.OnInitialize callback. It will be automatically called by CastleWindow backend when we're really ready (actually, a little later — when OpenGL context is active, to allow you to display progress bars etc. when loading).

This item has no description.

Used on platforms that can only show a single window (TCastleWindow) at a time, like mobile or web applications.

In other exceptional situations when we need a single window (e.g. to display CGE uncaught exception) we may also use this window, if set (otherwise we may use the 1st currently open window).

Warning: this symbol is deprecated: use ApplicationProperties.LimitFps

This item has no description.

Warning: this symbol is deprecated: use ApplicationProperties.Version

This item has no description.

Warning: this symbol is deprecated: use ApplicationProperties.TouchDevice

This item has no description.