gem::MapCamera Class Reference

MapCamera object. More...

Inheritance diagram for gem::MapCamera:

Collaboration diagram for gem::MapCamera:

Public Member Functions
MapCamera &	setPosition (const Tuple3d &cameraPosition) noexcept
	Sets the camera's position in a 3D space.
MapCamera &	setOrientation (const Tuple4d &cameraOrientation) noexcept
	Sets the camera's orientation using quaternion values.
Tuple3d	getPosition () const noexcept
	Retrieves the current position of the camera.
Tuple4d	getOrientation () const noexcept
	Retrieves the current orientation of the camera.
DataBuffer	saveCameraState () const noexcept
	Saves the current state of the camera into a binary format.
int	restoreCameraState (const DataBuffer &buff) noexcept
	Restores the camera's state from a previously saved binary format.
DataBuffer	getCameraState () const noexcept
	Gets the current state of the camera into a binary format.
int	setCameraState (const DataBuffer &buff) noexcept
	Sets the camera's state from a previously saved binary format.
StrongPointer< MapScene >	getScene () const noexcept
	Retrieves the MapScene associated with this camera.
int	generatePositionAndOrientation (const Coordinates &lonLatDegAltMeters, Tuple3d &resultPosition, Tuple4d &resultOrientation) const
	Generate a position at lon,lat in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the center of the sphere, north up.
int	generatePositionAndOrientation (const Coordinates &lonLatDegAltMeters, const Tuple3d &headingPitchRollDeg, Tuple3d &resultPosition, Tuple4d &resultOrientation) const
	Generate a position at lon,lat in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the specified heading, pitch and roll.
MapCamera &	setCameraPosition (const Coordinates &lonLatDegAltMeters)
	Set camera lon,lat position in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the center of the sphere, north up.
MapCamera &	setCameraOrientation (const Tuple3d &headingPitchRollDeg)
	Set camera orientation, with respect to surface of focused sphere, and current camera position, using heading in degrees (0=N, 90=E, 180=S, 270=W).
int	generatePositionAndOrientationTargetCentered (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &cameraHeadingPitchDegDistanceMeters, Tuple3d &resultPosition, Tuple4d &resultOrientation) const noexcept
	Generate a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to sphere).
MapCamera &	setCameraTargetCentered (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &cameraHeadingPitchDegDistanceMeters) noexcept
	Set camera looking toward a target position, all in the coordinate system of the focused sphere.
int	generatePositionAndOrientationRelativeToCenteredTarget (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &targetHeadingPitchRollDeg, const Tuple3d &cameraHeadingPitchDegDistanceMeters, Tuple3d &resultPosition, Tuple4d &resultOrientation) const noexcept
	Generate a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to target).
MapCamera &	setCameraRelativeToCenteredTarget (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &targetHeadingPitchRollDeg, const Tuple3d &cameraHeadingPitchDegDistanceMeters) noexcept
	Set camera looking toward a target position, all in the coordinate system of the focused target.
int	generatePositionAndOrientationRelativeToTarget (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &targetHeadingPitchRollDeg, const Tuple3d &cameraHeadingPitchDegDistanceMeters, const Tuple3d &cameraHeadingPitchRollDeg, Tuple3d &resultPosition, Tuple4d &resultOrientation) const noexcept
	Generate a position and orientation relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target.
MapCamera &	setCameraRelativeToTarget (const Coordinates &targetLonLatDegAltMeters, const Tuple3d &targetHeadingPitchRollDeg, const Tuple3d &cameraHeadingPitchDegDistanceMeters, const Tuple3d &cameraHeadingPitchRollDeg) noexcept
	Set camera relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target.

Static Public Member Functions
static StrongPointer< MapCamera >	produce (StrongPointer< MapScene > scene=StrongPointer< MapScene >()) noexcept
	Create a MapCamera object with or without a given scene.
static StrongPointer< MapCamera >	produce (Tuple3d cameraPosition, Tuple4d cameraOrientation, StrongPointer< MapScene > scene=StrongPointer< MapScene >()) noexcept
	Create a MapCamera object with position (x,y,z), orientation (x,y,z,w) and/or scene.

Detailed Description

MapCamera object.

Implements share-read / write Api object over ICamera.

Member Function Documentation

generatePositionAndOrientation() [1/2]

int gem::MapCamera::generatePositionAndOrientation ( const Coordinates & lonLatDegAltMeters, const Tuple3d & headingPitchRollDeg, Tuple3d & resultPosition, Tuple4d & resultOrientation ) const

inline

Generate a position at lon,lat in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the specified heading, pitch and roll.

Parameters

[in]	lonLatDegAltMeters	desired lon, lat and alt
[in]	headingPitchRollDeg	desired heading, pitch and roll
[out]	resultPosition	computed position
[out]	resultOrientation	computed orientation

The heading is 0 deg=North with respect to the focused sphere, 90 deg=East, 180 deg=South, 270 deg or -90 deg=west.

Pitch is 0 deg=the object (or camera) forward vector looking toward the center of the focused sphere, 90 deg=looking at horizon.

Roll is a rotation about the forward vector, positive deg to the left and negative deg to the right.

The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.

Returns

0 on success, non-zero on failure

generatePositionAndOrientation() [2/2]

int gem::MapCamera::generatePositionAndOrientation ( const Coordinates & lonLatDegAltMeters, Tuple3d & resultPosition, Tuple4d & resultOrientation ) const

inline

Generate a position at lon,lat in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the center of the sphere, north up.

Parameters

[in]	lonLatDegAltMeters	desired lon, lat and alt
[out]	resultPosition	computed position
[out]	resultOrientation	computed orientation

The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.

Returns

0 on success, non-zero on failure

generatePositionAndOrientationRelativeToCenteredTarget()

int gem::MapCamera::generatePositionAndOrientationRelativeToCenteredTarget ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & targetHeadingPitchRollDeg, const Tuple3d & cameraHeadingPitchDegDistanceMeters, Tuple3d & resultPosition, Tuple4d & resultOrientation ) const

inlinenoexcept

Generate a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to target).

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	targetHeadingPitchRollDeg	desired heading, pitch and roll for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading pitch and distance for camera
[out]	resultPosition	computed position
[out]	resultOrientation	computed orientation

The specified target position is at lon,lat in degrees, with respect to surface of the focused sphere, altitude in meters above sphere (sea level).

The target has the specified orientation where heading in degrees (0=N, 90=E, 180=S, 270=W) is with respect to the surface of the focused sphere,

pitch in degrees (0=the target forward vector is oriented to the center of the focused sphere, 90=the target forward vector is oriented toward the horizon),

and roll in degrees about the target forward vector, positive to the left and negative to the right.

The generated orientation is toward, and with respect to, the target position, where heading in degrees (0=in the direction of the target heading,

90=looking at the target from its right/starboard side, 180=looking at the target from the front, 270=looking at the target from its left/port side).

Pitch in degrees (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is

the plane containing the target forward and right vectors, 180=looking at the target from below). The roll is always 0, so the horizon is level.

The generated position is at the specified distance in meters from the target center.

The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.

Returns

0 on success, non-zero on failure

generatePositionAndOrientationRelativeToTarget()

int gem::MapCamera::generatePositionAndOrientationRelativeToTarget ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & targetHeadingPitchRollDeg, const Tuple3d & cameraHeadingPitchDegDistanceMeters, const Tuple3d & cameraHeadingPitchRollDeg, Tuple3d & resultPosition, Tuple4d & resultOrientation ) const

inlinenoexcept

Generate a position and orientation relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target.

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	targetHeadingPitchRollDeg	desired heading, pitch and roll for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading pitch and distance for camera
[in]	cameraHeadingPitchRollDeg	desired heading pitch and roll for camera
[out]	resultPosition	computed position
[out]	resultOrientation	computed orientation

This function is the same as GeneratePositionAndOrientationRelativeToCenteredTarget, except the orientation can be in a direction other than centered on the target.

The orientation is centered on the target when the 4th parameter, the camera/observer heading, pitch, roll = 0, 0, 0. A nonzero heading, in degrees, specifies a rotation

about the observer/camera up axis, going through the observer/camera position. A nonzero pitch, in degrees, specifies a rotation about the observer/camera right axis,

going through the observer/camera position. A nonzero roll, in degrees, specifies a rotation about the observer/camera forward vector.

See GeneratePositionAndOrientationRelativeToCenteredTarget.

Returns

0 on success, non-zero on failure

generatePositionAndOrientationTargetCentered()

int gem::MapCamera::generatePositionAndOrientationTargetCentered ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & cameraHeadingPitchDegDistanceMeters, Tuple3d & resultPosition, Tuple4d & resultOrientation ) const

inlinenoexcept

Generate a position and orientation relative to, and oriented toward/centered on, a target position which is relative to the focused sphere (orientation relative to sphere).

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading, pitch and distance for camera
[out]	resultPosition	computed position
[out]	resultOrientation	computed orientation

The specified target position is at lon,lat in degrees, with respect to surface of the focused sphere, altitude in meters above sphere (sea level).

The target position does not have an orientation, so it can be considered a point.

The generated orientation is toward the target position, where heading in degrees (0=N, 90=E, 180=S, 270=W) is with respect to the surface of the focused sphere,

so heading 0 is looking at the target toward the north, from a position south of the target (the generated position is at 180 degrees as seen from the target).

Pitch in degrees (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is

the plane containing the target forward and right vectors). The roll is always 0, so the horizon is level.

The generated position is at the specified distance in meters from the target center.

The camera position and orientation are unchanged. The camera or any other object can then be set at the resulting position and with the resulting orientation.

Returns

0 on success, non-zero on failure

getCameraState()

DataBuffer gem::MapCamera::getCameraState ( ) const

inlinenoexcept

Gets the current state of the camera into a binary format.

Returns

A DataBuffer instance containing the binary representation of the camera's current state.

Note

The returned buffer can be used to restore the camera state at a later time.

getOrientation()

Tuple4d gem::MapCamera::getOrientation ( ) const

inlinenoexcept

Retrieves the current orientation of the camera.

Returns

A Tuple4d struct representing the current (x,y,z,w) orientation of the camera.

getPosition()

Tuple3d gem::MapCamera::getPosition ( ) const

inlinenoexcept

Retrieves the current position of the camera.

Returns

A Tuple3d struct representing the current (x,y,z) position of the camera.

getScene()

StrongPointer< MapScene > gem::MapCamera::getScene ( ) const

inlinenoexcept

Retrieves the MapScene associated with this camera.

Returns

A StrongPointer to the MapScene object to which this camera belongs.

produce() [1/2]

StrongPointer< MapCamera > gem::MapCamera::produce ( StrongPointer< MapScene > scene = StrongPointer<MapScene>() )

inlinestaticnoexcept

Create a MapCamera object with or without a given scene.

If scene is not given, a new one is created for it. (reference to scene held internally)

Returns

A StrongPointer to the MapCamera object

Parameters

[in]

scene

The scene to which the camera belongs

produce() [2/2]

StrongPointer< MapCamera > gem::MapCamera::produce ( Tuple3d cameraPosition, Tuple4d cameraOrientation, StrongPointer< MapScene > scene = StrongPointer<MapScene>() )

inlinestaticnoexcept

Create a MapCamera object with position (x,y,z), orientation (x,y,z,w) and/or scene.

If scene is not given, a new one is created for it. (reference to scene held internally)

Returns

A StrongPointer to the MapCamera object

Parameters

[in]	cameraPosition	The position of the camera
[in]	cameraOrientation	The orientation of the camera
[in]	scene	The scene to which the camera belongs

restoreCameraState()

int gem::MapCamera::restoreCameraState ( const DataBuffer & buff )

inlinenoexcept

Restores the camera's state from a previously saved binary format.

Deprecated

Use setCameraState() instead.

Parameters

buff	A DataBuffer instance containing the binary data to restore the camera's state from.

Returns

An integer indicating the success (0) or failure (non-zero) of the operation.

saveCameraState()

DataBuffer gem::MapCamera::saveCameraState ( ) const

inlinenoexcept

Saves the current state of the camera into a binary format.

Deprecated

Use getCameraState() instead.

Returns

A DataBuffer instance containing the binary representation of the camera's current state.

Note

The returned buffer can be used to restore the camera state at a later time.

setCameraOrientation()

MapCamera & gem::MapCamera::setCameraOrientation ( const Tuple3d & headingPitchRollDeg )

inline

Set camera orientation, with respect to surface of focused sphere, and current camera position, using heading in degrees (0=N, 90=E, 180=S, 270=W).

Parameters

[in]

headingPitchRollDeg

desired heading, pitch and roll

Returns

A reference to this MapCamera instance, allowing for method chaining.

setCameraPosition()

MapCamera & gem::MapCamera::setCameraPosition ( const Coordinates & lonLatDegAltMeters )

inline

Set camera lon,lat position in degrees, with respect to surface of focused sphere, altitude in meters above sphere (sea level), oriented toward the center of the sphere, north up.

Parameters

[in]

lonLatDegAltMeters

desired lon, lat and alt

Returns

A reference to this MapCamera instance, allowing for method chaining.

setCameraRelativeToCenteredTarget()

MapCamera & gem::MapCamera::setCameraRelativeToCenteredTarget ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & targetHeadingPitchRollDeg, const Tuple3d & cameraHeadingPitchDegDistanceMeters )

inlinenoexcept

Set camera looking toward a target position, all in the coordinate system of the focused target.

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	targetHeadingPitchRollDeg	desired heading, pitch and roll for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading pitch and distance for camera

Target coordinates are lon, lat position in degrees, with respect to the focused sphere surface, altitude in meters above the sphere.

The camera is centered on the target, at the specified distance in meters from the target, heading (0=looking at the target from behind it, in the direction of the target's heading,

90=looking at the target from its right/starboard side, 180=looking at the target from the front, 270=looking at the target from its left/port side) with respect to the focused target,

and pitch (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is

the plane containing the target forward and right vectors, 180=looking at the target from below). The roll is always 0, so the horizon is level.

See GeneratePositionAndOrientationRelativeToCenteredTarget.

Returns

A reference to this MapCamera instance, allowing for method chaining.

setCameraRelativeToTarget()

MapCamera & gem::MapCamera::setCameraRelativeToTarget ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & targetHeadingPitchRollDeg, const Tuple3d & cameraHeadingPitchDegDistanceMeters, const Tuple3d & cameraHeadingPitchRollDeg )

inlinenoexcept

Set camera relative to a target position, looking in any direction relative to the direction toward the target, all in the coordinate system of the focused target.

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	targetHeadingPitchRollDeg	desired heading, pitch and roll for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading pitch and distance for camera
[in]	cameraHeadingPitchRollDeg	desired heading pitch and roll for camera

This function is the same as SetCameraRelativeToCenteredTarget, except the camera can be oriented in a direction other than centered on the target.

The camera is centered on the target when the 4th parameter, the camera/observer heading, pitch, roll = 0, 0, 0. A nonzero heading, in degrees, specifies a rotation

about the observer/camera up axis, going through the observer/camera position. A nonzero pitch, in degrees, specifies a rotation about the observer/camera right axis,

going through the observer/camera position. A nonzero roll, in degrees, specifies a rotation about the observer/camera forward vector.

See GeneratePositionAndOrientationRelativeToTarget.

Returns

A reference to this MapCamera instance, allowing for method chaining.

setCameraState()

int gem::MapCamera::setCameraState ( const DataBuffer & buff )

inlinenoexcept

Sets the camera's state from a previously saved binary format.

Parameters

buff	A DataBuffer instance containing the binary data to restore the camera's state from.

Returns

An integer indicating the success (0) or failure (non-zero) of the operation.

setCameraTargetCentered()

MapCamera & gem::MapCamera::setCameraTargetCentered ( const Coordinates & targetLonLatDegAltMeters, const Tuple3d & cameraHeadingPitchDegDistanceMeters )

inlinenoexcept

Set camera looking toward a target position, all in the coordinate system of the focused sphere.

Parameters

[in]	targetLonLatDegAltMeters	desired lon, lat and alt for target
[in]	cameraHeadingPitchDegDistanceMeters	desired heading pitch and distance for camera

Target coordinates are lon, lat position in degrees, with respect to the focused sphere surface, altitude in meters above the sphere (sea level).

The camera is centered on the target, at the specified distance in meters from the target, heading (0=N, 90=E, 180=S, 270=W) with respect to the focused sphere,

and pitch (0=looking toward the target center from above the target, 90=looking at the target center from the horizontal plane/equator of the target, which is

the plane containing the target forward and right vectors). The roll is always 0, so the horizon is level.

See GeneratePositionAndOrientationTargetCentered.

Returns

A reference to this MapCamera instance, allowing for method chaining.

setOrientation()

MapCamera & gem::MapCamera::setOrientation ( const Tuple4d & cameraOrientation )

inlinenoexcept

Sets the camera's orientation using quaternion values.

Parameters

cameraOrientation

A Tuple4d struct representing the new (x,y,z,w) orientation of the camera.

Returns

A reference to this MapCamera instance, allowing for method chaining.

setPosition()

MapCamera & gem::MapCamera::setPosition ( const Tuple3d & cameraPosition )

inlinenoexcept

Sets the camera's position in a 3D space.

Parameters

cameraPosition

A Tuple3d struct representing the new (x,y,z) position of the camera.

Returns

A reference to this MapCamera instance, allowing for method chaining.