This week I finished the last big engine API change before the next release! TCastleSceneManager is now deprecated: instead you should use TCastleViewport to display 3D models. This makes things much simpler, and it allowed me to make TCastleViewport defaults much better.

1. TCastleViewport

A simplest working source code demonstrating this (it will compile — get the engine and test it!) looks like this:

uses SysUtils,
  CastleWindow, CastleSceneCore, CastleScene, CastleViewport, CastleCameras, CastleVectors;

var
  Window: TCastleWindowBase;
  Viewport: TCastleViewport;
  Scene: TCastleScene;
begin
  Window := TCastleWindowBase.Create(Application);
  Window.Open;

  Viewport := TCastleViewport.Create(Application);
  Viewport.FullSize := true;
  Viewport.AutoCamera := true;
  Viewport.AutoNavigation := true;
  Window.Controls.InsertFront(Viewport);

  Scene := TCastleScene.Create(Application);
  Scene.Load('data/bridge_final.x3dv');

  Viewport.Items.Add(Scene);
  Viewport.Items.MainScene := Scene;

  Application.Run;
end.

See the CGE examples: 3d_rendering_processing/view_3d_model_basic.lpr for a complete code with some additional comments.

The advantages of the new approach:

1. The API is simpler (easier to explain and use).

   Previously, TCastleViewport was in most practical cases reserved for “secondary viewport”, that shows something also visible in the “primary viewport”. The “primary viewport” was TCastleSceneManager with DefaultViewport = true. This entire complication (and complication of terminology – “how is scene manager different from viewport”) no longer exists.

   Now you just use TCastleViewport to display a world (composed from a tree of TCastleTransform and TCastleScene). Period.

   To display the same world from two cameras, just copy one TCastleViewport.Items to another. Or assign the same TCastleRootTransform instance to two TCastleViewport.Items.

   To have multiple viewports (cameras) display the same world, simply assign the Items property of one TCastleViewport to another. You can also create your own TCastleRootTransform instance and assign it to as many TCastleViewport.Items properties as you want. Demo of this is inside CGE examples: 3d_rendering_processing/multiple_viewports.lpr.

   So all previous use-cases are covered in a more natural way.

2. Moreover, this allowed me to minimize compatibility break while still changing some defaults. Since TCastleViewport was so seldom used, we change it’s default properties:

   • TCastleViewport.FullSize is now by default false
   • TCastleViewport.AutoCamera is now by default false
   • TCastleViewport.AutoNavigation is now by default false

   The FullSize=false default is consistent with all other UI controls. This way it is less surprising (when instantiating from code or in CGE editor).

   The AutoCamera=false and AutoNavigation=false are better defaults after recent camera refactor. The “false” default on these properties makes more sense — while the auto-detection is nice for quick demos, it is bothersome and sometimes surprising for non-trivial applications, so it’s best to have the auto-detection “off” by default.

   On TCastleSceneManager these defaults do not change (as it would undoubtedly cause a lot of breakage, since you use TCastleSceneManager so much in existing applications).

2. TCastleWindowBase, TCastleControlBase

Also TCastleWindow and TCastleControl are deprecated, in favour of their “Base” counterparts: TCastleWindowBase and TCastleControlBase. Why:

• This way you don’t have a default viewport (scene manager) instance, which avoids some traps (the default navigation may catch some keys), and it is often not necessary.

• This way you create the TCastleViewport yourself, as many as you need. So you have more power over the engine. This way it is clear that TCastleViewport is just a regular user-interface class: you can create it as many times as needed, you can position and resize it however you like.

• This way you can create and adjust the TCastleViewport using CGE editor, just like any other UI control.

Many parts of the manual and examples have been updated to show “the new approach”. I’m working to finish updating the manual now.