Class CameraComponentExtensions

Namespace

Stride.CommunityToolkit.Engine

Assembly

Stride.CommunityToolkit.dll

Provides a set of static methods for working with CameraComponent instances.

public static class CameraComponentExtensions

Inheritance

object

CameraComponentExtensions

Remarks

This class includes extension methods for performing various operations with CameraComponent instances, such as raycasting, converting screen positions to world positions, and more. These methods are useful for implementing features like object picking, camera control, and coordinate transformations in a 3D environment.

Methods

CalculateRayFromScreenPosition(CameraComponent, Vector2)

Calculates a ray from the camera's position through a specified point on the screen, projecting from screen space into the 3D world space.

public static (Vector3 nearPoint, Vector3 farPoint) CalculateRayFromScreenPosition(this CameraComponent camera, Vector2 screenPosition)

Parameters

camera CameraComponent

The CameraComponent used to generate the view and projection matrices for the calculation.

screenPosition Vector2

The normalized position on the screen (typically the mouse position), with coordinates ranging from (0,0) at the bottom-left to (1,1) at the top-right.

Returns

(Vector3 nearPoint, Vector3 farPoint)

A tuple containing two points: nearPoint, which is the world-space position on the near plane, and farPoint, which is the world-space position on the far plane. These two points define the ray from the camera into the 3D world through the specified screen position.

Remarks

This method is typically used for raycasting and object picking in 3D space, where you need to determine what objects lie under a particular screen-space position, such as the mouse cursor. The ray is defined by transforming the screen position into world space, calculating points on the near and far planes of the camera's view frustum.

GetPickRay(CameraComponent, Vector2)

Calculates a ray from the camera through a specified point on the screen, projecting into the 3D world space.

public static Ray GetPickRay(this CameraComponent camera, Vector2 screenPosition)

Parameters

camera CameraComponent

The CameraComponent used for the ray calculation.

screenPosition Vector2

The position on the screen, typically the mouse position, normalized between (0,0) (bottom-left) and (1,1) (top-right).

Returns

Ray

A Ray starting from the camera and pointing into the 3D world through the specified screen position.

Remarks

This method is commonly used for object picking or raycasting operations, where interaction with 3D objects is based on screen space coordinates (e.g., mouse cursor). The ray is calculated by transforming the screen position into world space, creating a direction vector from the camera's near plane to its far plane.

LogicDirectionToWorldDirection(CameraComponent, Vector2)

Converts a 2D logical direction into a 3D world direction relative to the camera's orientation.

public static Vector3 LogicDirectionToWorldDirection(this CameraComponent camera, Vector2 logicDirection)

Parameters

camera CameraComponent

The camera component used for the calculation.

logicDirection Vector2

The 2D logical direction (e.g., input from a joystick or keyboard), typically normalized between -1 and 1.

Returns

Vector3

The corresponding 3D world direction vector.

Remarks

This method is useful for converting 2D input commands into 3D movements in the world, taking into account the camera's current orientation.

LogicDirectionToWorldDirection(CameraComponent, Vector2, Vector3)

Converts a 2D logical direction into a 3D world direction relative to the camera's orientation, using a specified up vector.

public static Vector3 LogicDirectionToWorldDirection(this CameraComponent camera, Vector2 logicDirection, Vector3 upVector)

Parameters

camera CameraComponent

The camera component used for the calculation.

logicDirection Vector2

The 2D logical direction (e.g., input from a joystick or keyboard), typically normalized between -1 and 1.

upVector Vector3

The up vector to be used for the calculation, defining the vertical direction in world space.

Returns

Vector3

The corresponding 3D world direction vector.

Remarks

This method is useful for converting 2D input commands into 3D movements in the world, taking into account the camera's current orientation and a custom vertical orientation.

Raycast(CameraComponent, ScriptComponent, Vector2, CollisionFilterGroups, CollisionFilterGroupFlags)

Performs a raycasting operation from the specified CameraComponent's position through the specified screen position in world coordinates, using the Simulation from the specified ScriptComponent, and returns information about the hit result.

public static HitResult Raycast(this CameraComponent camera, ScriptComponent component, Vector2 screenPosition, CollisionFilterGroups collisionGroups = CollisionFilterGroups.DefaultFilter, CollisionFilterGroupFlags collisionFilterGroupFlags = CollisionFilterGroupFlags.DefaultFilter)

Parameters

camera CameraComponent

The CameraComponent from which the ray should be cast.

component ScriptComponent

The ScriptComponent that contains the Simulation used for raycasting.

screenPosition Vector2

The screen position in world coordinates through which the ray should be cast.

collisionGroups CollisionFilterGroups

Optional. The collision filter group to consider during the raycasting. Default is DefaultFilter.

collisionFilterGroupFlags CollisionFilterGroupFlags

Optional. The collision filter group flags to consider during the raycasting. Default is DefaultFilter.

Returns

HitResult

A HitResult containing information about the hit result, including the hit location and other collision data.

Raycast(CameraComponent, Simulation, Vector2, CollisionFilterGroups, CollisionFilterGroupFlags)

Performs a raycasting operation from the specified CameraComponent's position through a specified screen position, using the provided Simulation, and returns information about the hit result.

public static HitResult Raycast(this CameraComponent camera, Simulation simulation, Vector2 screenPosition, CollisionFilterGroups collisionGroups = CollisionFilterGroups.DefaultFilter, CollisionFilterGroupFlags collisionFilterGroupFlags = CollisionFilterGroupFlags.DefaultFilter)

Parameters

camera CameraComponent

The CameraComponent from which the ray should be cast.

simulation Simulation

The Simulation used to perform the raycasting operation.

screenPosition Vector2

The screen position in normalized screen coordinates (e.g., mouse position) where the ray should be cast.

collisionGroups CollisionFilterGroups

Optional. The collision filter group to consider during the raycasting. Default is DefaultFilter.

collisionFilterGroupFlags CollisionFilterGroupFlags

Optional. The collision filter group flags to consider during the raycasting. Default is DefaultFilter.

Returns

HitResult

A HitResult containing information about the raycasting hit, including the hit location and other collision data.

Remarks

This method is useful for implementing features like object picking, where you want to select or interact with objects in the 3D world based on screen coordinates.

RaycastMouse(CameraComponent, ScriptComponent, CollisionFilterGroups, CollisionFilterGroupFlags)

Performs a raycasting operation from the specified CameraComponent's position through the mouse cursor position in screen coordinates, using input from the specified ScriptComponent, and returns information about the hit result.

public static HitResult RaycastMouse(this CameraComponent camera, ScriptComponent component, CollisionFilterGroups collisionGroups = CollisionFilterGroups.DefaultFilter, CollisionFilterGroupFlags collisionFilterGroupFlags = CollisionFilterGroupFlags.DefaultFilter)

Parameters

camera CameraComponent

The CameraComponent from which the ray should be cast.

component ScriptComponent

The ScriptComponent from which the mouse position should be taken.

collisionGroups CollisionFilterGroups

Optional. The collision filter group to consider during the raycasting. Default is DefaultFilter.

collisionFilterGroupFlags CollisionFilterGroupFlags

Optional. The collision filter group flags to consider during the raycasting. Default is DefaultFilter.

Returns

HitResult

A HitResult containing information about the hit result, including the hit location and other collision data.

RaycastMouse(CameraComponent, Simulation, Vector2, CollisionFilterGroups, CollisionFilterGroupFlags)

Performs a raycasting operation from the specified CameraComponent's position through a specified screen position, using the provided Simulation, and returns information about the hit result.

public static HitResult RaycastMouse(this CameraComponent camera, Simulation simulation, Vector2 screenPosition, CollisionFilterGroups collisionGroups = CollisionFilterGroups.DefaultFilter, CollisionFilterGroupFlags collisionFilterGroupFlags = CollisionFilterGroupFlags.DefaultFilter)

Parameters

camera CameraComponent

The CameraComponent from which the ray should be cast.

simulation Simulation

The Simulation used to perform the raycasting operation.

screenPosition Vector2

The screen position in screen coordinates (e.g., mouse position) from which the ray should be cast.

collisionGroups CollisionFilterGroups

Optional. The collision filter group to consider during the raycasting. Default is DefaultFilter.

collisionFilterGroupFlags CollisionFilterGroupFlags

Optional. The collision filter group flags to consider during the raycasting. Default is DefaultFilter.

Returns

HitResult

A HitResult containing information about the hit result, including the hit location and other collision data.

ScreenPointToRay(CameraComponent, Vector2)

Calculates the near and far vectors for a ray that starts at the camera and passes through a given screen point. The ray is in world space, starting at the near plane of the camera and extending through the specified pixel coordinates on the screen.

public static (Vector4 VectorNear, Vector4 VectorFar) ScreenPointToRay(this CameraComponent camera, Vector2 screenPosition)

Parameters

camera CameraComponent

The camera component used to calculate the ray.

screenPosition Vector2

The screen position (in normalized coordinates) through which the ray passes.

Returns

(Vector4 VectorNear, Vector4 VectorFar)

A tuple containing the near vector (VectorNear) and the far vector (VectorFar) of the ray in world space.

ScreenToWorldPoint(CameraComponent, Vector3)

Converts the screen position to a point in world coordinates relative to cameraComponent.

public static Vector3 ScreenToWorldPoint(this CameraComponent cameraComponent, Vector3 position)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from the near camera plane. Passed by value, which may be simpler to use but less efficient in memory-constrained environments.

Returns

Vector3

The world position calculated from the screen position.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or its containing EntityTransformComponent has been modified since the last frame, you may need to call the Update() method first.

This method takes the position parameter by value, which is simpler to use but may involve a copy of the vector, which could be less efficient for large or frequent transformations.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

ScreenToWorldPoint(CameraComponent, ref Vector3)

Converts the screen position to a point in world coordinates relative to cameraComponent.

public static Vector3 ScreenToWorldPoint(this CameraComponent cameraComponent, ref Vector3 position)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from the near camera plane. Passed by reference, allowing for potential optimizations in memory usage.

Returns

Vector3

The world position calculated from the screen position.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or its containing EntityTransformComponent has been modified since the last frame, you may need to call the Update() method first.

This method takes the position parameter by reference (ref), which may optimize memory usage and prevent unnecessary copies of the vector.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

ScreenToWorldPoint(CameraComponent, ref Vector3, out Vector3)

Converts the screen position to a point in world coordinates.

public static void ScreenToWorldPoint(this CameraComponent cameraComponent, ref Vector3 position, out Vector3 result)

Parameters

cameraComponent CameraComponent

position Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from near camera plane.

result Vector3

Position in world coordinates.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

If the cameraComponent argument is null.

ScreenToWorldRaySegment(CameraComponent, Vector2)

Converts the screen position to a RaySegment in world coordinates.

public static RaySegment ScreenToWorldRaySegment(this CameraComponent cameraComponent, Vector2 position)

Parameters

cameraComponent CameraComponent

position Vector2

Returns

RaySegment

RaySegment, starting at near plain and ending at the far plain.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

If the cameraComponent argument is null.

ScreenToWorldRaySegment(CameraComponent, ref Vector2, out RaySegment)

Converts the screen position to a RaySegment in world coordinates.

public static void ScreenToWorldRaySegment(this CameraComponent cameraComponent, ref Vector2 position, out RaySegment result)

Parameters

cameraComponent CameraComponent

position Vector2

result RaySegment

RaySegment, starting at near plain and ending at the far plain.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

WorldToClip(CameraComponent, ref Vector3)

Transforms a world-space position to clip space coordinates relative to camera, using the camera's view-projection matrix. The result is returned as a Vector3.

public static Vector3 WorldToClip(this CameraComponent cameraComponent, ref Vector3 position)

Parameters

cameraComponent CameraComponent

The camera component whose view-projection matrix will be used.

position Vector3

The world-space position to be transformed.

Returns

Vector3

The position in clip space as a Vector3.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

WorldToClip(CameraComponent, ref Vector3, out Vector3)

Transforms a world-space position to clip space coordinates relative to camera, using the camera's view-projection matrix. The result is returned via the result parameter.

public static void WorldToClip(this CameraComponent cameraComponent, ref Vector3 position, out Vector3 result)

Parameters

cameraComponent CameraComponent

The camera component whose view-projection matrix will be used.

position Vector3

The world-space position to be transformed.

result Vector3

The resulting position in clip space.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

WorldToScreenPoint(CameraComponent, Vector3)

Converts the world position to screen space coordinates relative to cameraComponent.

public static Vector3 WorldToScreenPoint(this CameraComponent cameraComponent, Vector3 position)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The world space position to be converted to screen space. Passed by value, which may be simpler to use but less efficient in memory-constrained environments.

Returns

Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from near camera plane.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or its containing EntityTransformComponent has been modified since the last frame, you may need to call the Update() method first.

This method takes the position parameter by value, which is simpler to use but may involve a copy of the vector, which could be less efficient for large or frequent transformations.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

WorldToScreenPoint(CameraComponent, ref Vector3)

Converts the world position to screen space coordinates relative to cameraComponent.

public static Vector3 WorldToScreenPoint(this CameraComponent cameraComponent, ref Vector3 position)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The world space position to be converted to screen space. Passed by reference, allowing for potential optimizations in memory usage.

Returns

Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from near camera plane.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or its containing EntityTransformComponent has been modified since the last frame, you may need to call the Update() method first.

This method takes the position parameter by reference (ref), which may optimize memory usage and prevent unnecessary copies of the vector.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

WorldToScreenPoint(CameraComponent, ref Vector3, out Vector3)

Converts the world position to screen space coordinates relative to camera.

public static void WorldToScreenPoint(this CameraComponent cameraComponent, ref Vector3 position, out Vector3 result)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The world space position to be converted to screen space.

result Vector3

The screen position in normalized X, Y coordinates. Top-left is (0,0), bottom-right is (1,1). Z is in world units from near camera plane.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

Thrown if cameraComponent is null.

WorldToScreenPoint(CameraComponent, ref Vector3, GraphicsDevice)

Converts the world position to screen space coordinates relative to cameraComponent and the window size of the graphicsDevice.

public static Vector2 WorldToScreenPoint(this CameraComponent cameraComponent, ref Vector3 position, GraphicsDevice graphicsDevice)

Parameters

cameraComponent CameraComponent

The camera component used to perform the calculation.

position Vector3

The world space position to be converted to screen space.

graphicsDevice GraphicsDevice

The graphics device providing information about the window size.

Returns

Vector2

The screen position as normalized X * graphicsDevice width, normalized Y * graphicsDevice height. Z is always 0.

Remarks

This method does not update the ViewMatrix or ProjectionMatrix before performing the transformation. If the CameraComponent or it's containing EntityTransformComponenthas been modified since the last frame you may need to call the Update() method first.

Exceptions

ArgumentNullException

If the cameraComponent argument is null.