Castle Game Engine

Class TCastleOrthographic

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleTransform

Declaration

type TCastleOrthographic = class(TCastleComponent)

Description

Subcomponent used in TCastleCamera.Orthographic to set orthographic projection parameters.

Do not create instances of this class yourself, these are automatically created by TCastleCamera.

Hierarchy

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
Public function EffectiveWidth: Single; deprecated 'use EffectiveRect.Width';
Public function EffectiveHeight: Single; deprecated 'use EffectiveRect.Height';

Properties

Public property Origin: TVector2 read FOrigin write SetOrigin;
Public property EffectiveRect: TFloatRectangle read FEffectiveRect;
Public property Scale: Single read FScale write SetScale default 1; deprecated 'just multiply Width or Height instead of using this';
Public property Stretch: Boolean read FStretch write SetStretch default false; experimental;
Published property Width: Single read FWidth write SetWidth default 0;
Published property Height: Single read FHeight write SetHeight default 0;
Published property OriginPersistent: TCastleVector2Persistent read FOriginPersistent ;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public function PropertySections(const PropertyName: String): TPropertySections; override;
 
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
 
Public function EffectiveWidth: Single; deprecated 'use EffectiveRect.Width';

Warning: this symbol is deprecated: use EffectiveRect.Width

 
Public function EffectiveHeight: Single; deprecated 'use EffectiveRect.Height';

Warning: this symbol is deprecated: use EffectiveRect.Height

 

Properties

Public property Origin: TVector2 read FOrigin write SetOrigin;

Additional translation of the camera. The camera movement applied here is always scaled by the calculated orthographic projection width and height.

By default this equals (0,0) which means that Camera.Translation determines what is visible in the left-bottom corner of the viewport. This 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 TCastleViewport.

You can change it e.g. to (0.5,0.5) to move the camera to the middle of the viewport. In effect, if the camera is at position (0,0,whatever), then the (0,0) position is in the center of the TCastleViewport.

Both values of Origin 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 (0.5,0.5), things will stay "glued" to the center.

  • With (0,0), things will stay "glued" to the left-bottom corner.

Public property EffectiveRect: TFloatRectangle read FEffectiveRect;

Currently used projection dimensions, calculated following the algorithm described at Width and Height, taking into account sizes of the viewport using this camera.

Public property Scale: Single read FScale write SetScale default 1; deprecated 'just multiply Width or Height instead of using this';

Warning: this symbol is deprecated: just multiply Width or Height instead of using this

Scales the projection size derived from Width and Height.

The effect of this scale is also affected by the Origin. When Origin is zero, this behaves like scaling around left-botttom corner of the viewport. When Origin is (0.5,0.5), this behaves like scaling around the middle of the viewport.

Public property Stretch: Boolean read FStretch write SetStretch default false; experimental;

Warning: this symbol is experimental.

Allow non-proportional stretch of projection. In effect the Width and Height (if both non-zero) are applied directly, without correcting them to follow aspect ratio of the viewport.

Published property Width: Single read FWidth write SetWidth default 0;

Orthographic projection width and height.

You can leave one or both of them as zero (default) to automatically calculate effective projection width and height (in EffectiveWidth and EffectiveHeight):

  • When both Width and Height are zero, then the effective projection width and height are based on the viewport width and height. That is, they will follow TCastleViewport.EffectiveWidth and TCastleViewport.EffectiveHeight.

  • When exactly one of Width and Height is non-zero, then it explicitly determines the projection width or height accordingly. This allows to easily display the same piece of the game world, regardless of the viewport size.

    The other size is then calculated to follow the aspect ratio of the viewport control.

  • When both Width and Height are non-zero, they determine the projection width and height following the algorithm outlined below. This also allows to easily display the same piece of the game world, regardless of the viewport size.

    • When Stretch = False (default), they determine the minimum projection width and height along the given axis.

      If the displayed viewport aspect ratio will be different than given Width and Height ratio, then these values will be treated as minimum values, and they will be adjusted (one of them will be increased) for the purposes of rendering. You can read the EffectiveWidth, EffectiveHeight to know the adjusted values.

      Note that the Camera.Translation is considered to be relative to unadjusted Width and Height, not to the adjusted EffectiveWidth, EffectiveHeight. In effect, when Origin is zero, the Camera.Translation does not point to the left-bottom of the whole viewport. It points to the left-bottom of the rectangle of aspect ratio Width / Height within the viewport. This way the enlarged viewport shows equal amount of additional space on the left and the right (or bottom and top) of the Width / Height rectangle within.

    • When Stretch = True, these values are used directly, even if it means that aspect ratio of the projection will not reflect the aspect ratio of the viewport on screen.

      This allows to implement some tricks, like Military Projection, https://github.com/castle-engine/castle-engine/issues/290 .

In all the cases, the resulting size is also multiplied by Scale, by default 1.0.

You can read EffectiveWidth and EffectiveHeight to learn the actual projection width and height, calculated using the above algorithm.

Published property Height: Single read FHeight write SetHeight default 0;
 
Published property OriginPersistent: TCastleVector2Persistent read FOriginPersistent ;

Origin that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write Origin directly.

See also
Origin
Additional translation of the camera.
Generated by PasDoc 0.16.0.