Class GorgonCameraCommon

Common functionality for a camera.

Inheritance

object

GorgonCameraCommon

GorgonOrthoCamera

GorgonPerspectiveCamera

Implements

IGorgonGraphicsObject

IGorgonNamedObject

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Renderers.Cameras

Assembly: Gorgon.Graphics.Core.dll

Syntax

public abstract class GorgonCameraCommon : IGorgonGraphicsObject, IGorgonNamedObject

Constructors

GorgonCameraCommon(GorgonGraphics, Size2F, float, float, string)

Initializes a new instance of the GorgonCameraCommon class.

Declaration

protected GorgonCameraCommon(GorgonGraphics graphics, Size2F viewDimensions, float minDepth, float maximumDepth, string name)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface to use with this object.
Size2F	viewDimensions	The view dimensions.
float	minDepth	[Optional] The minimum depth value.
float	maximumDepth	[Optional] The maximum depth value.
string	name	[Optional] The name of the camera.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics parameter is null.

Properties

AllowUpdateOnResize

Property to set or return a flag to indicate that the renderer should automatically update this camera when the render target size changes.

Declaration

public bool AllowUpdateOnResize { get; set; }

Property Value

Type	Description
bool

Remarks

When this flag is set to true, the renderer will automatically update the ViewDimensions for this camera when the current render target is resized (typically in response to a window resize event). However, this is not always desirable, and when set to false, the camera ViewDimensions will not be resized.

If this value is set to false, then it is the responsibility of the developer to update the camera manually when required.

AspectRatio

Property to return the horizontal and vertical aspect ratio for the camera view area.

Declaration

public Vector2 AspectRatio { get; }

Property Value

Type	Description
Vector2

Changes

Property to return what has changed on the camera since the last update.

Declaration

public CameraChange Changes { get; protected set; }

Property Value

Type	Description
CameraChange

Graphics

Property to return graphics instance for this camera.

Declaration

public GorgonGraphics Graphics { get; }

Property Value

Type	Description
GorgonGraphics

MaximumDepth

Property to set or return the maximum depth for the camera.

Declaration

public float MaximumDepth { get; set; }

Property Value

Type	Description
float

MinimumDepth

Property to set or return the minimum depth for the camera.

Declaration

public float MinimumDepth { get; set; }

Property Value

Type	Description
float

Name

Property to return the name of this object.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Position

Property to set or return the camera position.

Declaration

public Vector3 Position { get; set; }

Property Value

Type	Description
Vector3

PositionRef

Property to return direct access to the position data by reference.

Declaration

protected ref Vector3 PositionRef { get; }

Property Value

Type	Description
Vector3

Target

Property to set or return the render target to use for camera calculations.

Declaration

public GorgonRenderTargetView Target { get; set; }

Property Value

Type	Description
GorgonRenderTargetView

Remarks

If this value is null, then the first render target on RenderTargets is used.

TargetHeight

Property to return the height of the current target.

Declaration

public int TargetHeight { get; }

Property Value

Type	Description
int

TargetWidth

Property to return the width of the current target.

Declaration

public int TargetWidth { get; }

Property Value

Type	Description
int

ViewDimensions

Property to set or return the projection view dimensions for the camera.

Declaration

public Size2F ViewDimensions { get; set; }

Property Value

Type	Description
Size2F

ViewableRegion

Property to return the viewable region for the camera.

Declaration

public abstract RectangleF ViewableRegion { get; }

Property Value

Type	Description
RectangleF

Remarks

This represents the boundaries of viewable space for the camera using its coordinate system. The upper left of the region corresponds with the upper left of the active render target at minimum Z depth, and the lower right of the region corresponds with the lower right of the active render target at minimum Z depth.

Methods

DiscardChanges()

Function to discard pending changes on the camera.

Declaration

public void DiscardChanges()

GetProjectionMatrix()

Function to retrieve the projection matrix for the camera type.

Declaration

public ref readonly Matrix4x4 GetProjectionMatrix()

Returns

Type	Description
Matrix4x4	A read only reference to the projection matrix.

GetTarget()

Function to retrieve the render target assigned to this camera.

Declaration

protected GorgonRenderTargetView GetTarget()

Returns

Type	Description
GorgonRenderTargetView	The render target bound to the camera.

GetViewMatrix()

Function to retrieve the view matrix for the camera.

Declaration

public ref readonly Matrix4x4 GetViewMatrix()

Returns

Type	Description
Matrix4x4	A read only reference to the view matrix.

Project(Vector3, Size2, bool)

Function to project a screen position into camera space.

Declaration

public Vector3 Project(Vector3 screenPosition, Size2 targetSize, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	screenPosition	3D Position on the screen.
Size2	targetSize	The size of the render target
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Returns

Type	Description
Vector3	The projected 3D position of the screen.

Remarks

Use this to convert a position in screen space into the camera view/projection space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Project(Vector3, bool)

Function to project a screen position into camera space.

Declaration

public Vector3 Project(Vector3 screenPosition, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	screenPosition	3D Position on the screen.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Returns

Type	Description
Vector3	The projected 3D position of the screen.

Remarks

Use this to convert a position in screen space into the camera view/projection space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Project(ref Vector3, out Vector3, Size2, bool)

Function to project a screen position into camera space.

Declaration

public void Project(ref Vector3 screenPosition, out Vector3 result, Size2 targetSize, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	screenPosition	3D Position on the screen.
Vector3	result	The resulting projected position.
Size2	targetSize	The size of the render target.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Remarks

Use this to convert a position in screen space into the camera view/projection space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Project(ref Vector3, out Vector3, bool)

Function to project a screen position into camera space.

Declaration

public void Project(ref Vector3 screenPosition, out Vector3 result, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	screenPosition	3D Position on the screen.
Vector3	result	The resulting projected position.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Remarks

Use this to convert a position in screen space into the camera view/projection space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Unproject(Vector3, Size2, bool)

Function to unproject a world space position into screen space.

Declaration

public Vector3 Unproject(Vector3 worldSpacePosition, Size2 targetSize, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	worldSpacePosition	A position in world space.
Size2	targetSize	The size of the render target.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Returns

Type	Description
Vector3	The unprojected world space coordinates.

Remarks

Use this to convert a position in world space into the screen space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Unproject(Vector3, bool)

Function to unproject a world space position into screen space.

Declaration

public Vector3 Unproject(Vector3 worldSpacePosition, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	worldSpacePosition	A position in world space.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Returns

Type	Description
Vector3	The unprojected world space coordinates.

Remarks

Use this to convert a position in world space into the screen space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Unproject(in Vector3, out Vector3, Size2, bool)

Function to unproject a world space position into screen space.

Declaration

public void Unproject(in Vector3 worldSpacePosition, out Vector3 result, Size2 targetSize, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	worldSpacePosition	A position in world space.
Vector3	result	The resulting projected position.
Size2	targetSize	The size of the render target.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Remarks

Use this to convert a position in world space into the screen space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

Unproject(in Vector3, out Vector3, bool)

Function to unproject a world space position into screen space.

Declaration

public void Unproject(in Vector3 worldSpacePosition, out Vector3 result, bool includeViewTransform = true)

Parameters

Type	Name	Description
Vector3	worldSpacePosition	A position in world space.
Vector3	result	The resulting projected position.
bool	includeViewTransform	[Optional] true to include the view transformation in the projection calculations, false to only use the projection.

Remarks

Use this to convert a position in world space into the screen space. If the includeViewTransform is set to true, then both the camera position, rotation and zoom will be taken into account when projecting. If it is set to false only the projection will be used to convert the position. This means if the camera is moved or moving, then the converted screen point will not reflect that.

UpdateProjectionMatrix(ref Matrix4x4)

Function to update the projection matrix.

Declaration

protected abstract void UpdateProjectionMatrix(ref Matrix4x4 projectionMatrix)

Parameters

Type	Name	Description
Matrix4x4	projectionMatrix	The instance of the matrix to update.

UpdateViewMatrix(ref Matrix4x4)

Function to update the view matrix.

Declaration

protected abstract void UpdateViewMatrix(ref Matrix4x4 viewMatrix)

Parameters

Type	Name	Description
Matrix4x4	viewMatrix	The instance of the matrix to update.

Implements

IGorgonGraphicsObject

IGorgonNamedObject

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)