Class TCastle2DSceneManager

Unit

Declaration

type TCastle2DSceneManager = class(TCastleSceneManager)

Description

Scene manager best suited for 2D worlds.

Features:

  • The default camera position, direction, up is suitable for 2D worlds that span horizontally in X, span vertically in Y, and are more-or-less flat around the Z = 0 plane.

    More precisely, the camera is positioned at the point (0, 0, DefaultCameraZ), and looks along the -Z direction, with "up" vector in +Y.

  • The camera does not give the user any automatic way to move in the world. Because you typically want to code yourself all your camera movement for 2D games.

    More precisely, the NavigationType is ntNone by default.

  • Sets 2D projection. By default our visible X range is [0..scene manager width in pixels], visible Y range is [0..scene manager height in pixels].

    You can set the ProjectionAutoSize to False, and then set ProjectionWidth or ProjectionHeight to explicitly control the size of the game world inside the scene manager, regardless of the size of the scene manager control. This is a trivial way to scale your 2D game contents.

    You can set the ProjectionOriginCenter to control where the origin is (how does the Camera.Position affect the view).

    Such projection is set regardless of the X3D viewpoint nodes present in the MainScene. This is in contrast to the ancestor TCastleSceneManager, that sets projection using a flexible algorithm that takes into account X3D viewpoint nodes, TViewpointNode, in TCastleSceneManager.MainScene.

Hierarchy

Overview

Fields

Public nested const DefaultProjectionSpan = 1000.0;
Public nested const DefaultCameraZ = DefaultProjectionSpan / 2;

Methods

Protected function CalculateProjection: TProjection; override;
Public constructor Create(AOwner: TComponent); override;
Public procedure AssignDefaultCamera; override;
Public function PositionTo2DWorld(const Position: TVector2; const ScreenCoordinates: Boolean): TVector2;

Properties

Public property CurrentProjectionWidth: Single read FCurrentProjectionWidth;
Public property CurrentProjectionHeight: Single read FCurrentProjectionHeight;
Published property ProjectionAutoSize: boolean read FProjectionAutoSize write FProjectionAutoSize default true;
Published property ProjectionHeight: Single read FProjectionHeight write FProjectionHeight default 0;
Published property ProjectionWidth: Single read FProjectionWidth write FProjectionWidth default 0;
Published property ProjectionSpan: Single read FProjectionSpan write FProjectionSpan default DefaultProjectionSpan;
Published property ProjectionOriginCenter: boolean read FProjectionOriginCenter write FProjectionOriginCenter default false;

Description

Fields

Public nested const DefaultProjectionSpan = 1000.0;
 
Public nested const DefaultCameraZ = DefaultProjectionSpan / 2;
 

Methods

Protected function CalculateProjection: TProjection; override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public procedure AssignDefaultCamera; override;
 
Public function PositionTo2DWorld(const Position: TVector2; const ScreenCoordinates: Boolean): TVector2;

Convert 2D position into "world coordinates", which is the coordinate space seen by TCastleTransform / TCastleScene inside scene manager Items.

The interpretation of Position depends on ScreenCoordinates, and is similar to e.g. TCastleTiledMapControl.PositionToTile:

  • When ScreenCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    And it is expressed in real device coordinates, just like TInputPressReleaseEvent.Position when mouse is being clicked, or like TInputMotionEvent.Position when mouse is moved.

  • When ScreenCoordinates = False, then Position is relative to this UI control.

    And it is expressed in coordinates after UI scaling. IOW, if the size of this control is Width = 100, then Position.X between 0 and 100 reflects the visible range of this control.

This assumes that camera up is +Y, and it is looking along the negative Z axis, which is the default camera direction and up. In other words, you can only change the camera position, compared to the initial camera vectors.

Properties

Public property CurrentProjectionWidth: Single read FCurrentProjectionWidth;
 
Public property CurrentProjectionHeight: Single read FCurrentProjectionHeight;
 
Published property ProjectionAutoSize: boolean read FProjectionAutoSize write FProjectionAutoSize default true;

When ProjectionAutoSize is True, the size of the world visible in our viewport depends on scene manager size. ProjectionHeight and ProjectionWidth are ignored then.

When ProjectionAutoSize is False, ProjectionHeight and ProjectionWidth are used to determine the world visible in our viewport. If one of them is zero, the other is automatically adjusted to follow aspect ratio of viewport size. If both of them are zero, projection is automatically calculated just as if ProjectionAutoSize was True.

In all cases, CurrentProjectionWidth and CurrentProjectionHeight can be checked to see actual projection dimensions.

Published property ProjectionHeight: Single read FProjectionHeight write FProjectionHeight default 0;
 
Published property ProjectionWidth: Single read FProjectionWidth write FProjectionWidth default 0;
 
Published property ProjectionSpan: Single read FProjectionSpan write FProjectionSpan default DefaultProjectionSpan;

Determines the minimum and maximum depth visible, relative to the camera Z.

Higher values allow to see more. The objects are visible in Z range [Camera.Position.Z - ProjectionSpan .. Camera.Position.Z + ProjectionSpan].

Lower values improve depth buffer precision.

Published property ProjectionOriginCenter: boolean read FProjectionOriginCenter write FProjectionOriginCenter default false;

Where is the (0,0) world point with respect to the viewport.

If False, the (0,0) is in the left-bottom corner, which matches the typical 2D drawing coordinates used throughout our engine. In other words, if the camera is at position (0,0,whatever), then the (0,0) position in 2D is in the left-bottom corner of the scene manager rectangle.

If True, the (0,0) is in the middle of the viewport. In other words, if the camera is at position (0,0,whatever), then the (0,0) position is in the center of the scene manager rectangle.

Both values of ProjectionOriginCenter make sense, it depends on the game type and how you prefer to think in 2D coordinates. And how do you want the result to behave when aspect ratio changes:

  • With ProjectionOriginCenter = True, things will stay "glued" to the center.

  • With ProjectionOriginCenter = False, things will stay "glued" to the left-bottom corner.


Generated by PasDoc 0.15.0.