Abstraction of a lens or pinhole camera. More...

Inherits G3D::Entity.

Public Member Functions
	Camera (const Matrix4 &proj, const CFrame &frame)

virtual	~Camera ()

bool	canCauseCollisions () const

bool	canChange () const
	True if this Entity can change (when not Scene::editing(); all objects can change when in editing mode). More...

float	circleOfConfusionRadiusPixels (float z, const class Rect2D &viewport) const
	Circle of confusion radius, in pixels, for a point at negative position z from the center of projection along the camera-space z axis. More...

Point3	convertFromUnitToNormal (const Point3 &in, const Rect2D &viewport) const
	Converts projected points from OpenGL standards (-1, 1) to normal 3D coordinate standards (0, 1) More...

virtual void	copyParametersFrom (const shared_ptr< Camera > &camera)

DepthOfFieldSettings &	depthOfFieldSettings ()

const DepthOfFieldSettings &	depthOfFieldSettings () const

float	farPlaneZ () const
	Returns a negative z-value. More...

float	fieldOfViewAngle () const

float	fieldOfViewAngleDegrees () const

FOVDirection	fieldOfViewDirection () const

FilmSettings &	filmSettings ()

const FilmSettings &	filmSettings () const

const CoordinateFrame &	frame () const
	Current position, i.e., as of last onSimulation call. More...

void	frustum (const Rect2D &viewport, Frustum &f) const
	Returns the world space view frustum, which is a truncated pyramid describing the volume of space seen by this camera. More...

Frustum	frustum (const Rect2D &viewport) const

void	getClipPlanes (const Rect2D &viewport, Array< Plane > &outClip) const
	Returns the clipping planes of the frustum, in world space. More...

void	getFarViewportCorners (const class Rect2D &viewport, Point3 &outUR, Point3 &outUL, Point3 &outLL, Point3 &outLR) const
	Returns the world space 3D viewport corners under pinhole projection. More...

void	getFieldOfView (float &angle, FOVDirection &direction) const
	Returns the current full field of view angle (from the left side of the viewport to the right side) and direction. More...

virtual void	getLastBounds (class AABox &box) const
	Return a world-space axis-aligned bounding box as of the last call to onPose(). More...

virtual void	getLastBounds (class Sphere &sphere) const
	Return a world-space bounding sphere as of the last call to onPose(). More...

virtual void	getLastBounds (class Box &box) const
	Return a world-space bounding box as of the last call to onPose(). More...

void	getNearViewportCorners (const class Rect2D &viewport, Point3 &outUR, Point3 &outUL, Point3 &outLL, Point3 &outLR) const
	Returns the world space 3D viewport corners under pinhole projection. More...

void	getProjectPixelMatrix (const Rect2D &viewport, Matrix4 &P) const
	Sets P equal to the matrix that transforms points to pixel coordinates on the given viewport. More...

void	getProjectUnitMatrix (const Rect2D &viewport, Matrix4 &P) const
	Sets P equal to the camera's projection matrix. More...

float	imagePlanePixelsPerMeter (const class Rect2D &viewport) const
	The number of pixels per meter at z=-1 for the given viewport. More...

virtual bool	intersect (const Ray &R, float &maxDistance, Model::HitInfo &info=Model::HitInfo::ignore) const

virtual bool	intersectBounds (const Ray &R, float &maxDistance, Model::HitInfo &info=Model::HitInfo::ignore) const
	Returns true if there is conservatively some intersection with the object's bounds closer than maxDistance to the ray origin. More...

Vector2	jitterMotion () const
	Difference in projection().pixelOffset from the previous frame. More...

virtual const Array< Box > &	lastBoxBoundArray () const
	Return a world-space bounding box array for all surfaces produced by this Entity as of the last call to onPose(). More...

bool	lastBoxBoundArraysOverlap (const shared_ptr< Entity > &other) const
	Returns true if the world space bounds of these two entities overlap. More...

RealTime	lastChangeTime () const
	Wall-clock time at which this entity changed in some way, e.g., that might require recomputing a spatial data structure. More...

void	lookAt (const Point3 &position, const Vector3 &up=Vector3::unitY())
	Rotate the camera in place to look at the target. More...

virtual void	makeGUI (GuiPane p, GApp app) override
	Create a user interface for controlling the properties of this Entity. More...

void	markChanged ()
	Sets the lastChangeTime() to the current System::time() More...

float	mass () const

float	maxCircleOfConfusionRadiusPixels (const Rect2D &viewport)
	Returns the maximum of the absolute value of Camera::circleOfConfusionRadiusPixels() values that can be returned for the current depth of field settings and viewport. More...

MotionBlurSettings &	motionBlurSettings ()

const MotionBlurSettings &	motionBlurSettings () const

const String &	name () const

float	nearPlaneViewportHeight (const class Rect2D &viewport) const
	Returns the camera space height of the viewport in meters at the near plane. More...

float	nearPlaneViewportWidth (const class Rect2D &viewport) const
	Returns the camera space width in meters of the viewport at the near plane. More...

float	nearPlaneZ () const
	Returns a negative z-value. More...

virtual void	onPose (Array< shared_ptr< class Surface > > &surfaceArray) override
	Pose as of the last simulation time. More...

virtual void	onSimulation (SimTime absoluteTime, SimTime deltaTime) override
	If m_overridePixelOffset is true, then applies jitter if FilmSettings::enableTemporalAntialiasing is set and forces to pixelOffset to zero. More...

bool	physicalSimulation () const

virtual shared_ptr< SoundEntity >	playSound (const shared_ptr< Sound > &sound, const CFrame &childFrame=CFrame(), bool attach=true)
	Creates a new G3D::SoundEntity attached to this Entity at childFrame by an Entity::EntityTrack and returns it. More...

const CoordinateFrame &	previousFrame () const

const Projection &	previousProjection () const
	Projection from the previous frame. More...

Point3	project (const Point3 &wsPoint, const class Rect2D &viewport) const
	Pinhole projects a world space point onto a width x height screen. More...

const Projection &	projection () const
	The view frustum parameters. More...

Projection &	projection ()

Point3	projectUnit (const Point3 &point, const class Rect2D &viewport) const
	Pinhole projects a world space point onto a unit cube. More...

virtual void	setCanCauseCollisions (bool c)
	If true, causes collisions for other objects during physical simulation. More...

void	setFarPlaneZ (float z)
	Sets a new value for the far clipping plane Expects a negative value More...

void	setFieldOfView (float edgeToEdgeAngleRadians, FOVDirection direction)
	Sets the field of view, in radians. More...

void	setFieldOfViewAngle (float edgeToEdgeAngleRadians)
	Set the edge-to-edge FOV angle along the current fieldOfViewDirection in radians. More...

void	setFieldOfViewAngleDegrees (float edgeToEdgeAngleDegrees)

void	setFieldOfViewDirection (FOVDirection d)

virtual void	setFrame (const CFrame &f, bool updatePreviousFrame=true)
	This sets the position of the Entity for the current simulation step. More...

virtual void	setFrameSpline (const PhysicsFrameSpline &spline)
	If there is a controller on this object and it is a SplineTrack, mutate it to store this value. More...

virtual void	setMass (float m)
	Set to a negative number to tell the physics system to use the absolute value as a density and infer the mass from the mesh on load. More...

void	setNearPlaneZ (float z)
	Sets a new value for the near clipping plane Expects a negative value More...

void	setOverridePixelOffset (bool p)
	For TAA. More...

virtual void	setPhysicalSimulation (bool s)
	If true, this object should receive physical simulation for its motion. More...

void	setPosition (const Point3 &t)

virtual void	setPreviousFrame (const CFrame &f)
	Explicitly override the previous frame value used for computing motion vectors. More...

void	setPreviousProjection (const Projection &P)

void	setProjection (const Projection &p)

virtual void	setShaderArgs (class UniformTable &args, const Vector2 &screenSize, const String &prefix="") const
	Binds: More...

void	setShouldBeSaved (bool b)

virtual void	setTrack (const shared_ptr< Track > &c)

bool	shouldBeSaved () const
	True if this Entity should be saved when the scene is converted to Any for saving/serialization. More...

Any	toAny (const bool forceAll=false) const override
	Converts the current Entity to an Any. More...

virtual shared_ptr< Track >	track () const

Point3	unproject (const Point3 &v, const Rect2D &viewport) const
	Gives the world-space coordinates of screen space point v, where v.x is in pixels from the left, v.y is in pixels from the top, and v.z is on the range 0 (near plane) to 1 (far plane). More...

Point3	unprojectUnit (const Point3 &v, const Rect2D &viewport) const
	Gives the world-space coordinates of unit cube point v, where v varies from -1 to 1 on all axes. More...

float	visualizationScale () const

virtual void	visualize (RenderDevice *rd, bool isSelected, const class SceneVisualizationSettings &s, const shared_ptr< GFont > &font, const shared_ptr< Camera > &camera)
	Called by Scene::visualize every frame. More...

Ray	worldRay (float x, float y, const class Rect2D &viewport) const
	Returns the world space ray passing through pixel coordinates (x, y) on the image plane under pinhole projection. More...

Ray	worldRay (float x, float y, float u, float v, const class Rect2D &viewport) const
	World space ray from a lens camera. More...

Static Public Member Functions
static shared_ptr< Entity >	create (const String &name, Scene *scene, AnyTableReader &propertyTable, const ModelTable &modelTable=ModelTable(), const Scene::LoadOptions &options=Scene::LoadOptions())

static shared_ptr< Camera >	create (const String &name="Camera")

Public Attributes
float	m_closestNearPlaneZForDepthOfField = -0.2f

float	m_viewportFractionMaxCircleOfConfusion = 0.03f

Protected Member Functions
	Camera ()

int	_fieldOfViewDirectionInt () const

void	_setFieldOfViewDirectionInt (int d)

void	init (AnyTableReader &propertyTable)

void	init (const String &name, Scene *scene, AnyTableReader &propertyTable)
	The initialization sequence for Entity and its subclasses is different than for typical C++ classes. More...

void	init (const String &name, Scene *scene, const CFrame &frame, const shared_ptr< Track > &controller, bool canChange, bool shouldBeSaved)

Vector2	nextTAAOffset ()

void	onOverwriteCameraFromDebug ()

void	onOverwriteDebugFromCamera ()

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
bool	m_canCauseCollisions = false

bool	m_canChange
	If true, the canChange() method returns true. More...

DepthOfFieldSettings	m_depthOfFieldSettings

float	m_exposureTime
	Non-negative, in seconds. More...

FilmSettings	m_filmSettings

CoordinateFrame	m_frame
	Current position. More...

AABox	m_lastAABoxBounds
	Bounds at the last pose() call, in world space. More...

RealTime	m_lastBoundsTime
	Time at which the bounds were computed. More...

Array< Box >	m_lastBoxBoundArray
	Bounds on all of the surfaces from the last pose() call, in world space. More...

Box	m_lastBoxBounds
	Bounds at the last pose() call, in world space. More...

RealTime	m_lastChangeTime

AABox	m_lastObjectSpaceAABoxBounds
	Bounds at the last pose() call, in object space. More...

Sphere	m_lastSphereBounds
	Bounds at the last pose() call, in world space. More...

float	m_mass = 1

MotionBlurSettings	m_motionBlurSettings

bool	m_movedSinceLoad
	True if the frame has changed since load. More...

bool	m_movedSinceSimulation = false
	Has this Entity been explicitly moved by setFrame() since it was last simulated? If so, onSimulation will not update the m_previousFrame because it assumes some external logic is moving the Entity. More...

String	m_name

bool	m_overridePixelOffset = true

bool	m_physicalSimulation = false

CoordinateFrame	m_previousFrame
	Frame before onSimulation(). More...

Projection	m_previousProjection

Projection	m_projection

Scene *	m_scene

bool	m_shouldBeSaved
	True if this Entity should be saved when the scene is converted to Any for saving/serialization. More...

Any	m_sourceAny
	The Any from which this was originally constructed. More...

int	m_taaSampleIndex = 0

shared_ptr< Track >	m_track
	Basic simulation behavior for the Entity. More...

float	m_visualizationScale
	Used to scale camera visualizations. More...

Friends
class	CameraControlWindow

Detailed Description

Abstraction of a lens or pinhole camera.

The area a camera sees is called a frustum. It is bounded by the near plane, the far plane, and the sides of the view frame projected into the scene. It has the shape of a pyramid with the top cut off.

Cameras can project points from 3D to 2D. The "unit" projection matches OpenGL. It maps the entire view frustum to a cube of unit radius (i.e., edges of length 2) centered at the origin. The non-unit projection then maps that cube to the specified pixel viewport in X and Y and the range [0, 1] in Z. The projection is reversable as long as the projected Z value is known.

All viewport arguments are the pixel bounds of the viewport– e.g., RenderDevice::viewport().

See http://bittermanandy.wordpress.com/2009/04/10/a-view-to-a-thrill-part-one-camera-concepts/ for a nice introduction to camera transformations.

Constructor & Destructor Documentation

◆ Camera() [1/2]

G3D::Camera::Camera ( )

protected

◆ Camera() [2/2]

G3D::Camera::Camera	(	const Matrix4 &	proj,
		const CFrame &	frame
	)

Deprecated:

◆ ~Camera()

virtual G3D::Camera::~Camera ( )

virtual

Member Function Documentation

◆ _fieldOfViewDirectionInt()

int G3D::Camera::_fieldOfViewDirectionInt ( ) const

inlineprotected

◆ _setFieldOfViewDirectionInt()

void G3D::Camera::_setFieldOfViewDirectionInt ( int d )

inlineprotected

◆ canCauseCollisions()

bool G3D::Entity::canCauseCollisions ( ) const

inlineinherited

◆ canChange()

bool G3D::Entity::canChange ( ) const

inlineinherited

True if this Entity can change (when not Scene::editing(); all objects can change when in editing mode).

It is safe to build static data structures over Entitys that cannot change.

◆ circleOfConfusionRadiusPixels()

float G3D::Camera::circleOfConfusionRadiusPixels	(	float	z,
		const class Rect2D &	viewport
	)		const

Circle of confusion radius, in pixels, for a point at negative position z from the center of projection along the camera-space z axis.

If negative, then z is closer to the camera than the focus depth (near field) If positive, then z is farther.

◆ convertFromUnitToNormal()

Point3 G3D::Camera::convertFromUnitToNormal	(	const Point3 &	in,
		const Rect2D &	viewport
	)		const

Converts projected points from OpenGL standards (-1, 1) to normal 3D coordinate standards (0, 1)

◆ copyParametersFrom()

virtual void G3D::Camera::copyParametersFrom ( const shared_ptr< Camera > & camera )

virtual

◆ create() [1/2]

static shared_ptr<Entity> G3D::Camera::create	(	const String &	name,
		Scene *	scene,
		AnyTableReader &	propertyTable,
		const ModelTable &	modelTable = `ModelTable()`,
		const Scene::LoadOptions &	options = `Scene::LoadOptions()`
	)

static

◆ create() [2/2]

static shared_ptr<Camera> G3D::Camera::create ( const String & name = "Camera" )

static

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ depthOfFieldSettings() [1/2]

DepthOfFieldSettings& G3D::Camera::depthOfFieldSettings ( )

inline

◆ depthOfFieldSettings() [2/2]

const DepthOfFieldSettings& G3D::Camera::depthOfFieldSettings ( ) const

inline

◆ farPlaneZ()

float G3D::Camera::farPlaneZ ( ) const

inline

Returns a negative z-value.

Deprecated:

◆ fieldOfViewAngle()

float G3D::Camera::fieldOfViewAngle ( ) const

inline

Deprecated:

◆ fieldOfViewAngleDegrees()

float G3D::Camera::fieldOfViewAngleDegrees ( ) const

inline

Deprecated:

◆ fieldOfViewDirection()

FOVDirection G3D::Camera::fieldOfViewDirection ( ) const

inline

Deprecated:

◆ filmSettings() [1/2]

FilmSettings& G3D::Camera::filmSettings ( )

inline

◆ filmSettings() [2/2]

const FilmSettings& G3D::Camera::filmSettings ( ) const

inline

◆ frame()

const CoordinateFrame& G3D::Entity::frame ( ) const

inlineinherited

Current position, i.e., as of last onSimulation call.

◆ frustum() [1/2]

void G3D::Camera::frustum	(	const Rect2D &	viewport,
		Frustum &	f
	)		const

Returns the world space view frustum, which is a truncated pyramid describing the volume of space seen by this camera.

◆ frustum() [2/2]

Frustum G3D::Camera::frustum ( const Rect2D & viewport ) const

◆ getClipPlanes()

void G3D::Camera::getClipPlanes	(	const Rect2D &	viewport,
		Array< Plane > &	outClip
	)		const

Returns the clipping planes of the frustum, in world space.

The planes have normals facing into the view frustum.

The plane order is guaranteed to be: Near, Right, Left, Top, Bottom, [Far]

If the far plane is at infinity, the resulting array will have 5 planes, otherwise there will be 6.

The viewport is used only to determine the aspect ratio of the screen; the absolute dimensions and xy values don't matter.

◆ getFarViewportCorners()

void G3D::Camera::getFarViewportCorners	(	const class Rect2D &	viewport,
		Point3 &	outUR,
		Point3 &	outUL,
		Point3 &	outLL,
		Point3 &	outLR
	)		const

Returns the world space 3D viewport corners under pinhole projection.

These are at the Far clipping plane. The corners are constructed from the nearPlaneZ, farPlaneZ, viewportWidth, and viewportHeight. "left" and "right" are from the Camera's perspective.

◆ getFieldOfView()

void G3D::Camera::getFieldOfView	(	float &	angle,
		FOVDirection &	direction
	)		const

inline

Returns the current full field of view angle (from the left side of the viewport to the right side) and direction.

Deprecated:

◆ getLastBounds() [1/3]

virtual void G3D::Entity::getLastBounds ( class AABox & box ) const

virtualinherited

Return a world-space axis-aligned bounding box as of the last call to onPose().

◆ getLastBounds() [2/3]

virtual void G3D::Entity::getLastBounds ( class Sphere & sphere ) const

virtualinherited

Return a world-space bounding sphere as of the last call to onPose().

◆ getLastBounds() [3/3]

virtual void G3D::Entity::getLastBounds ( class Box & box ) const

virtualinherited

Return a world-space bounding box as of the last call to onPose().

This is always at least as tight as the AABox bounds and often tighter.

◆ getNearViewportCorners()

void G3D::Camera::getNearViewportCorners	(	const class Rect2D &	viewport,
		Point3 &	outUR,
		Point3 &	outUL,
		Point3 &	outLL,
		Point3 &	outLR
	)		const

Returns the world space 3D viewport corners under pinhole projection.

These are at the near clipping plane. The corners are constructed from the nearPlaneZ, viewportWidth, and viewportHeight. "left" and "right" are from the Camera's perspective.

◆ getProjectPixelMatrix()

void G3D::Camera::getProjectPixelMatrix	(	const Rect2D &	viewport,
		Matrix4 &	P
	)		const

Sets P equal to the matrix that transforms points to pixel coordinates on the given viewport.

A point correspoinding to the top-left corner of the viewport in camera space will transform to viewport.x0y0() and the bottom-right to viewport.x1y1().

Deprecated:: Now on Projection

◆ getProjectUnitMatrix()

void G3D::Camera::getProjectUnitMatrix	(	const Rect2D &	viewport,
		Matrix4 &	P
	)		const

Sets P equal to the camera's projection matrix.

This is the matrix that maps points to the homogeneous clip cube that varies from -1 to 1 on all axes. The projection matrix does not include the camera transform.

For rendering direct to an OSWindow (vs. rendering to Texture/Framebuffer), multiply this matrix by Matrix4::scale(1, -1, 1).

This is the matrix that a RenderDevice (or OpenGL) uses as the projection matrix.

See also: RenderDevice::setProjectionAndCameraMatrix, RenderDevice::setProjectionMatrix, Matrix4::perspectiveProjection, gluPerspective

Deprecated:: Now on Projection

◆ imagePlanePixelsPerMeter()

float G3D::Camera::imagePlanePixelsPerMeter ( const class Rect2D & viewport ) const

The number of pixels per meter at z=-1 for the given viewport.

This is useful for performing explicit projections and for transforming world-space values like circle of confusion into screen space.

Deprecated:

◆ init() [1/3]

void G3D::Camera::init ( AnyTableReader & propertyTable )

protected

See also: Entity::init. Note that this is not an override; there is no case where it is desirable to dynamically dispatch this method or invoke it externally.

◆ init() [2/3]

void G3D::Entity::init	(	const String &	name,
		Scene *	scene,
		AnyTableReader &	propertyTable
	)

protectedinherited

The initialization sequence for Entity and its subclasses is different than for typical C++ classes.

That is because they must avoid throwing exceptions from a constructor when parsing, need to support both AnyTableReader and direct parameter versions, and have to verify that all fields from an AnyTableReader are actually consumed. See samples/entity and G3D::VisibleEntity for examples of how to initialize an Entity subclass.

Parameters

name The name of this Entity, e.g., "Player 1"

propertyTable

The form is given below. It is intended that subclasses replace the table name and add new fields.

<some base class name> {
    model     = <modelname>;
    frame     = <initial CFrame or equivalent; overriden if a controller is present>
    track     = <see Entity::Track>;
    canChange = <boolean>
}

The pose field is optional. The Entity base class reads this field. Other subclasses read their own fields.
The original caller (typically, a Scene subclass createEntity or Entity subclass create method) should invoke AnyTableReader::verifyDone to ensure that all of the fields specified were read by some subclass along the inheritance chain.
See VisibleEntity::init for an example of using this method. This method is separate from the constructor solely because it will throw an exception on a parse error, which is dangerous to do during a constructor because the destructor will not run.

scene May be nullptr so long as no entity() controller is used

◆ init() [3/3]

void G3D::Entity::init	(	const String &	name,
		Scene *	scene,
		const CFrame &	frame,
		const shared_ptr< Track > &	controller,
		bool	canChange,
		bool	shouldBeSaved
	)

protectedinherited

◆ intersect()

virtual bool G3D::Entity::intersect	(	const Ray &	R,
		float &	maxDistance,
		Model::HitInfo &	info = `Model::HitInfo::ignore`
	)		const

virtualinherited

Reimplemented in G3D::VisibleEntity, G3D::MarkerEntity, and G3D::SoundEntity.

◆ intersectBounds()

virtual bool G3D::Entity::intersectBounds	(	const Ray &	R,
		float &	maxDistance,
		Model::HitInfo &	info = `Model::HitInfo::ignore`
	)		const

virtualinherited

Returns true if there is conservatively some intersection with the object's bounds closer than maxDistance to the ray origin.

If so, updates maxDistance with the intersection distance.

The bounds used may be more accurate than any of the given getLastBounds() results because the method may recurse into individual parts of the scene graph within the Entity.

Reimplemented in G3D::VisibleEntity.

◆ jitterMotion()

Vector2 G3D::Camera::jitterMotion ( ) const

inline

Difference in projection().pixelOffset from the previous frame.

Used for Temporal Antialiasing by G3D::Film.

◆ lastBoxBoundArray()

virtual const Array<Box>& G3D::Entity::lastBoxBoundArray ( ) const

inlinevirtualinherited

Return a world-space bounding box array for all surfaces produced by this Entity as of the last call to onPose().

◆ lastBoxBoundArraysOverlap()

bool G3D::Entity::lastBoxBoundArraysOverlap ( const shared_ptr< Entity > & other ) const

inherited

Returns true if the world space bounds of these two entities overlap.

See also: lastBoxBoundArray

◆ lastChangeTime()

RealTime G3D::Entity::lastChangeTime ( ) const

inlineinherited

Wall-clock time at which this entity changed in some way, e.g., that might require recomputing a spatial data structure.

◆ lookAt()

void G3D::Camera::lookAt	(	const Point3 &	position,
		const Vector3 &	up = `Vector3::unitY()`
	)

Rotate the camera in place to look at the target.

Does not persistently look at that location when the camera moves; i.e., if you move the camera and still want it to look at the old target, you must call lookAt again after moving the camera.)

◆ makeGUI()

virtual void G3D::Camera::makeGUI	(	GuiPane *	pane,
		GApp *	app
	)

overridevirtual

Create a user interface for controlling the properties of this Entity.

Called by SceneEditorWindow on selection.

Parameters

app	May be nullptr.

Reimplemented from G3D::Entity.

◆ markChanged()

void G3D::Entity::markChanged ( )

inlineinherited

Sets the lastChangeTime() to the current System::time()

◆ mass()

float G3D::Entity::mass ( ) const

inlineinherited

◆ maxCircleOfConfusionRadiusPixels()

float G3D::Camera::maxCircleOfConfusionRadiusPixels ( const Rect2D & viewport )

Returns the maximum of the absolute value of Camera::circleOfConfusionRadiusPixels() values that can be returned for the current depth of field settings and viewport.

Limits the radius to viewportFractionMax for physical blur, which has no inherent limit.

◆ motionBlurSettings() [1/2]

MotionBlurSettings& G3D::Camera::motionBlurSettings ( )

inline

◆ motionBlurSettings() [2/2]

const MotionBlurSettings& G3D::Camera::motionBlurSettings ( ) const

inline

◆ name()

const String& G3D::Entity::name ( ) const

inlineinherited

Referenced by G3D::Light::spotTarget().

◆ nearPlaneViewportHeight()

float G3D::Camera::nearPlaneViewportHeight ( const class Rect2D & viewport ) const

Returns the camera space height of the viewport in meters at the near plane.

Deprecated:

◆ nearPlaneViewportWidth()

float G3D::Camera::nearPlaneViewportWidth ( const class Rect2D & viewport ) const

Returns the camera space width in meters of the viewport at the near plane.

Deprecated:

◆ nearPlaneZ()

float G3D::Camera::nearPlaneZ ( ) const

inline

Returns a negative z-value.

Deprecated:

◆ nextTAAOffset()

Vector2 G3D::Camera::nextTAAOffset ( )

protected

◆ onOverwriteCameraFromDebug()

void G3D::Camera::onOverwriteCameraFromDebug ( )

protected

◆ onOverwriteDebugFromCamera()

void G3D::Camera::onOverwriteDebugFromCamera ( )

protected

◆ onPose()

virtual void G3D::Camera::onPose ( Array< shared_ptr< class Surface > > & surfaceArray )

overridevirtual

Pose as of the last simulation time.

Reimplemented from G3D::Entity.

◆ onSimulation()

virtual void G3D::Camera::onSimulation	(	SimTime	absoluteTime,
		SimTime	deltaTime
	)

overridevirtual

If m_overridePixelOffset is true, then applies jitter if FilmSettings::enableTemporalAntialiasing is set and forces to pixelOffset to zero.

Reimplemented from G3D::Entity.

◆ physicalSimulation()

bool G3D::Entity::physicalSimulation ( ) const

inlineinherited

◆ playSound()

virtual shared_ptr<SoundEntity> G3D::Entity::playSound	(	const shared_ptr< Sound > &	sound,
		const CFrame &	childFrame = `CFrame()`,
		bool	attach = `true`
	)

virtualinherited

Creates a new G3D::SoundEntity attached to this Entity at childFrame by an Entity::EntityTrack and returns it.

The new SoundEntity is automatically added to the Scene and will remain rigidly attached to the Entity.

You do not need to retain the pointer to the created sound for it to remain playing and in the scene. The SoundEntity will automatically remove itself from the Scene when it stops playing.

If attach == false, then the EntityTrack is not created and the sound will remain fixed in space.

◆ previousFrame()

const CoordinateFrame& G3D::Entity::previousFrame ( ) const

inlineinherited

◆ previousProjection()

const Projection& G3D::Camera::previousProjection ( ) const

inline

Projection from the previous frame.

Set by onPose.

Referenced by jitterMotion().

◆ project()

Point3 G3D::Camera::project	(	const Point3 &	wsPoint,
		const class Rect2D &	viewport
	)		const

Pinhole projects a world space point onto a width x height screen.

The returned coordinate uses pixmap addressing: x = right and y = down. The resulting z value is 0 at the near plane, 1 at the far plane, and is a linear compression of unit cube projection.

If the point is behind the camera, Point3::inf() is returned.

See also: RenderDevice::invertY

◆ projection() [1/2]

const Projection& G3D::Camera::projection ( ) const

inline

The view frustum parameters.

Referenced by jitterMotion().

◆ projection() [2/2]

Projection& G3D::Camera::projection ( )

inline

◆ projectUnit()

Point3 G3D::Camera::projectUnit	(	const Point3 &	point,
		const class Rect2D &	viewport
	)		const

Pinhole projects a world space point onto a unit cube.

The resulting x,y,z values range between -1 and 1, where z is -1 at the near plane and 1 at the far plane and varies hyperbolically in between.

If the point is behind the camera, Point3::inf() is returned.

◆ setCanCauseCollisions()

virtual void G3D::Entity::setCanCauseCollisions ( bool c )

inlinevirtualinherited

If true, causes collisions for other objects during physical simulation.

It may not react to those collisions if physicalSimulation is false. Default is true for VisibleEntity and false for other subclasses.

◆ setFarPlaneZ()

void G3D::Camera::setFarPlaneZ ( float z )

inline

Sets a new value for the far clipping plane Expects a negative value

Deprecated:

◆ setFieldOfView()

void G3D::Camera::setFieldOfView	(	float	edgeToEdgeAngleRadians,
		FOVDirection	direction
	)

inline

Sets the field of view, in radians.

The initial angle is toRadians(55). Must specify the direction of the angle.

This is the full angle, i.e., from the left side of the viewport to the right side.

The field of view is specified for the pinhole version of the camera.

Deprecated:

◆ setFieldOfViewAngle()

void G3D::Camera::setFieldOfViewAngle ( float edgeToEdgeAngleRadians )

inline

Set the edge-to-edge FOV angle along the current fieldOfViewDirection in radians.

Deprecated:

◆ setFieldOfViewAngleDegrees()

void G3D::Camera::setFieldOfViewAngleDegrees ( float edgeToEdgeAngleDegrees )

inline

Deprecated:

◆ setFieldOfViewDirection()

void G3D::Camera::setFieldOfViewDirection ( FOVDirection d )

inline

Deprecated:

◆ setFrame()

virtual void G3D::Entity::setFrame	(	const CFrame &	f,
		bool	updatePreviousFrame = `true`
	)

virtualinherited

This sets the position of the Entity for the current simulation step.

If there is a controller set and the base class Entity::onSimulation is invoked, it will override the value assigned here.

◆ setFrameSpline()

virtual void G3D::Entity::setFrameSpline ( const PhysicsFrameSpline & spline )

virtualinherited

If there is a controller on this object and it is a SplineTrack, mutate it to store this value.

Otherwise, create a new SplineTrack to overwrite the current controller.

See also: setTrack

Used by SceneEditorWindow

◆ setMass()

virtual void G3D::Entity::setMass ( float m )

inlinevirtualinherited

Set to a negative number to tell the physics system to use the absolute value as a density and infer the mass from the mesh on load.

Default is -10 (kg/m^3).

◆ setNearPlaneZ()

void G3D::Camera::setNearPlaneZ ( float z )

inline

Sets a new value for the near clipping plane Expects a negative value

Deprecated:

◆ setOverridePixelOffset()

void G3D::Camera::setOverridePixelOffset ( bool p )

inline

For TAA.

◆ setPhysicalSimulation()

virtual void G3D::Entity::setPhysicalSimulation ( bool s )

inlinevirtualinherited

If true, this object should receive physical simulation for its motion.

If true, canMove must also be true and there must be no Track on this Entity.

◆ setPosition()

void G3D::Camera::setPosition ( const Point3 & t )

◆ setPreviousFrame()

virtual void G3D::Entity::setPreviousFrame ( const CFrame & f )

inlinevirtualinherited

Explicitly override the previous frame value used for computing motion vectors.

This is very rarely needed because simulation automatically updates this value.

◆ setPreviousProjection()

void G3D::Camera::setPreviousProjection ( const Projection & P )

inline

◆ setProjection()

void G3D::Camera::setProjection ( const Projection & p )

inline

◆ setShaderArgs()

virtual void G3D::Camera::setShaderArgs	(	class UniformTable &	args,
		const Vector2 &	screenSize,
		const String &	prefix = `""`
	)		const

virtual

Binds:

mat4x3 prefix#previousFrame mat4x3 prefix#frame float3 prefix##clipInfo ProjInfo prefix##projInfo

to args.

Inside a shader, these arguments can be automatically defined using the macro

#include <Camera/Camera.glsl>

uniform_Camera(name_)

See also: uniform_Texture, uniform_GBuffer

◆ setShouldBeSaved()

void G3D::Entity::setShouldBeSaved ( bool b )

inlineinherited

◆ setTrack()

virtual void G3D::Entity::setTrack ( const shared_ptr< Track > & c )

inlinevirtualinherited

See also: Entity::Track

◆ shouldBeSaved()

bool G3D::Entity::shouldBeSaved ( ) const

inlineinherited

True if this Entity should be saved when the scene is converted to Any for saving/serialization.

Defaults to true. Set to false for transient objects. For example, a character's spawn point Entity might have shouldBeSaved() = true, while the character itself might have shouldBeSaved() = false. This would allow editing of the scene while the simulation loop is running without having the scene at the end of the editing session reflecting the result of the character moving about.

◆ toAny()

Any G3D::Camera::toAny ( const bool forceAll = false ) const

overridevirtual

Converts the current Entity to an Any.

Subclasses should modify at least the name of the Table, which will be "Entity" if not changed.

See also: shouldBeSaved

Reimplemented from G3D::Entity.

◆ track()

virtual shared_ptr<Track> G3D::Entity::track ( ) const

inlinevirtualinherited

See also: Entity::Track

◆ unproject()

Point3 G3D::Camera::unproject	(	const Point3 &	v,
		const Rect2D &	viewport
	)		const

Gives the world-space coordinates of screen space point v, where v.x is in pixels from the left, v.y is in pixels from the top, and v.z is on the range 0 (near plane) to 1 (far plane).

◆ unprojectUnit()

Point3 G3D::Camera::unprojectUnit	(	const Point3 &	v,
		const Rect2D &	viewport
	)		const

Gives the world-space coordinates of unit cube point v, where v varies from -1 to 1 on all axes.

The unproject first transforms the point into a pixel location for the viewport, then calls unproject

◆ visualizationScale()

float G3D::Camera::visualizationScale ( ) const

inline

◆ visualize()

virtual void G3D::Entity::visualize	(	RenderDevice *	rd,
		bool	isSelected,
		const class SceneVisualizationSettings &	s,
		const shared_ptr< GFont > &	font,
		const shared_ptr< Camera > &	camera
	)

virtualinherited

Called by Scene::visualize every frame.

During this, Entitys may make rendering calls according to the SceneVisualizationSettings to display control points and other features.

Parameters

isSelected True if this entity is selected by a sceneEditorWindow, which may trigger additional visualization for it.

Reimplemented in G3D::MarkerEntity, and G3D::SoundEntity.

◆ worldRay() [1/2]

Ray G3D::Camera::worldRay	(	float	x,
		float	y,
		const class Rect2D &	viewport
	)		const

Returns the world space ray passing through pixel coordinates (x, y) on the image plane under pinhole projection.

The pixel x and y axes are opposite the 3D object space axes: (0,0) is the upper left corner of the screen. They are in viewport coordinates, not screen coordinates.

The ray origin is at the camera-space origin, that is, in world space it is at Camera::coordinateFrame().translation. To start it at the image plane, move it forward by imagePlaneDepth/ray.direction.z along the ray's direction.

Integer (x, y) values correspond to the upper left corners of pixels. If you want to cast rays through pixel centers, add 0.5 to x and y.

◆ worldRay() [2/2]

Ray G3D::Camera::worldRay	(	float	x,
		float	y,
		float	u,
		float	v,
		const class Rect2D &	viewport
	)		const

World space ray from a lens camera.

(u, v) are signed (-1, 1) that should lie within a unit-radius disc.

Friends And Related Function Documentation

◆ CameraControlWindow

friend class CameraControlWindow

friend

Member Data Documentation

◆ m_canCauseCollisions

bool G3D::Entity::m_canCauseCollisions = false

protectedinherited

Referenced by G3D::Entity::canCauseCollisions(), and G3D::Entity::setCanCauseCollisions().

◆ m_canChange

bool G3D::Entity::m_canChange

protectedinherited

If true, the canChange() method returns true.

Defaults to true.

It is illegal to set m_canChange to false if m_frameSpline has more than one control point because a spline implies animation.

Subclasses should set this to false during initialization if the object will never move so that other classes can precompute data structures that are affected by the Entity.

Referenced by G3D::Entity::canChange().

◆ m_closestNearPlaneZForDepthOfField

float G3D::Camera::m_closestNearPlaneZForDepthOfField = -0.2f

BETA API Likely to receive incompatible changes in future releases. maxCircleOfConfusionRadiusPixels

◆ m_depthOfFieldSettings

DepthOfFieldSettings G3D::Camera::m_depthOfFieldSettings

protected

Referenced by depthOfFieldSettings().

◆ m_exposureTime

float G3D::Camera::m_exposureTime

protected

Non-negative, in seconds.

◆ m_filmSettings

FilmSettings G3D::Camera::m_filmSettings

protected

Referenced by filmSettings().

◆ m_frame

CoordinateFrame G3D::Entity::m_frame

protectedinherited

Current position.

Do not directly mutate–invoke setFrame() to ensure that times are modified correctly.

Referenced by G3D::Light::distance(), G3D::Entity::frame(), G3D::Light::frame(), and G3D::Light::position().

◆ m_lastAABoxBounds

AABox G3D::Entity::m_lastAABoxBounds

protectedinherited

Bounds at the last pose() call, in world space.

◆ m_lastBoundsTime

RealTime G3D::Entity::m_lastBoundsTime

protectedinherited

Time at which the bounds were computed.

◆ m_lastBoxBoundArray

Array<Box> G3D::Entity::m_lastBoxBoundArray

protectedinherited

Bounds on all of the surfaces from the last pose() call, in world space.

Referenced by G3D::Entity::lastBoxBoundArray().

◆ m_lastBoxBounds

Box G3D::Entity::m_lastBoxBounds

protectedinherited

Bounds at the last pose() call, in world space.

◆ m_lastChangeTime

RealTime G3D::Entity::m_lastChangeTime

protectedinherited

Referenced by G3D::Entity::lastChangeTime(), G3D::Entity::markChanged(), G3D::Light::setEnabled(), and G3D::Light::setShadowsEnabled().

◆ m_lastObjectSpaceAABoxBounds

AABox G3D::Entity::m_lastObjectSpaceAABoxBounds

protectedinherited

Bounds at the last pose() call, in object space.

◆ m_lastSphereBounds

Sphere G3D::Entity::m_lastSphereBounds

protectedinherited

Bounds at the last pose() call, in world space.

◆ m_mass

float G3D::Entity::m_mass = 1

protectedinherited

Referenced by G3D::Entity::mass(), and G3D::Entity::setMass().

◆ m_motionBlurSettings

MotionBlurSettings G3D::Camera::m_motionBlurSettings

protected

Referenced by motionBlurSettings().

◆ m_movedSinceLoad

bool G3D::Entity::m_movedSinceLoad

protectedinherited

True if the frame has changed since load.

Used by toAny() to decide if m_sourceAny is out of date.

◆ m_movedSinceSimulation

bool G3D::Entity::m_movedSinceSimulation = false

protectedinherited

Has this Entity been explicitly moved by setFrame() since it was last simulated? If so, onSimulation will not update the m_previousFrame because it assumes some external logic is moving the Entity.

◆ m_name

String G3D::Entity::m_name

protectedinherited

Referenced by G3D::Entity::name().

◆ m_overridePixelOffset

bool G3D::Camera::m_overridePixelOffset = true

protected

Referenced by setOverridePixelOffset().

◆ m_physicalSimulation

bool G3D::Entity::m_physicalSimulation = false

protectedinherited

Referenced by G3D::Entity::physicalSimulation(), and G3D::Entity::setPhysicalSimulation().

◆ m_previousFrame

CoordinateFrame G3D::Entity::m_previousFrame

protectedinherited

Frame before onSimulation().

Used for tracking poses and for velocity estimation.

Referenced by G3D::Entity::previousFrame(), and G3D::Entity::setPreviousFrame().

◆ m_previousProjection

Projection G3D::Camera::m_previousProjection

protected

Referenced by previousProjection(), and setPreviousProjection().

◆ m_projection

Projection G3D::Camera::m_projection

protected

Referenced by _fieldOfViewDirectionInt(), _setFieldOfViewDirectionInt(), farPlaneZ(), fieldOfViewAngle(), fieldOfViewAngleDegrees(), fieldOfViewDirection(), getFieldOfView(), nearPlaneZ(), projection(), setFarPlaneZ(), setFieldOfView(), setFieldOfViewAngle(), setFieldOfViewAngleDegrees(), setFieldOfViewDirection(), setNearPlaneZ(), and setProjection().

◆ m_scene

Scene* G3D::Entity::m_scene

protectedinherited

◆ m_shouldBeSaved

bool G3D::Entity::m_shouldBeSaved

protectedinherited

True if this Entity should be saved when the scene is converted to Any for saving/serialization.

Defaults to true. Set to false for transient objects. For example, a character's spawn point Entity might have shouldBeSaved() = true, while the character itself might have shouldBeSaved() = false. This would allow editing of the scene while the simulation loop is running without having the scene at the end of the editing session reflecting the result of the character moving about.

Referenced by G3D::Entity::setShouldBeSaved(), and G3D::Entity::shouldBeSaved().

◆ m_sourceAny

Any G3D::Entity::m_sourceAny

protectedinherited

The Any from which this was originally constructed.

◆ m_taaSampleIndex

int G3D::Camera::m_taaSampleIndex = 0

protected

◆ m_track

shared_ptr<Track> G3D::Entity::m_track

protectedinherited

Basic simulation behavior for the Entity.

If nullptr, the Entity is never moved by the base class' onSimulation method. You can subclass Track, but it is usually easier to subclass Entity and override onSimulation directly when creating behaviors more complex than those supported by the default Track language.

Referenced by G3D::Entity::setTrack(), and G3D::Entity::track().

◆ m_viewportFractionMaxCircleOfConfusion

float G3D::Camera::m_viewportFractionMaxCircleOfConfusion = 0.03f

BETA API Likely to receive incompatible changes in future releases. maxCircleOfConfusionRadiusPixels

◆ m_visualizationScale

float G3D::Camera::m_visualizationScale

protected

Used to scale camera visualizations.

Referenced by visualizationScale().

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Camera() [1/2]

◆ Camera() [2/2]

◆ ~Camera()

Member Function Documentation

◆ _fieldOfViewDirectionInt()

◆ _setFieldOfViewDirectionInt()

◆ canCauseCollisions()

◆ canChange()

◆ circleOfConfusionRadiusPixels()

◆ convertFromUnitToNormal()

◆ copyParametersFrom()

◆ create() [1/2]

◆ create() [2/2]

◆ createShared()

◆ depthOfFieldSettings() [1/2]

◆ depthOfFieldSettings() [2/2]

◆ farPlaneZ()

◆ fieldOfViewAngle()

◆ fieldOfViewAngleDegrees()

◆ fieldOfViewDirection()

◆ filmSettings() [1/2]

◆ filmSettings() [2/2]

◆ frame()

◆ frustum() [1/2]

◆ frustum() [2/2]

◆ getClipPlanes()

◆ getFarViewportCorners()

◆ getFieldOfView()

◆ getLastBounds() [1/3]

◆ getLastBounds() [2/3]

◆ getLastBounds() [3/3]

◆ getNearViewportCorners()

◆ getProjectPixelMatrix()

◆ getProjectUnitMatrix()

◆ imagePlanePixelsPerMeter()

◆ init() [1/3]

◆ init() [2/3]

◆ init() [3/3]

◆ intersect()

◆ intersectBounds()

◆ jitterMotion()

◆ lastBoxBoundArray()

◆ lastBoxBoundArraysOverlap()

◆ lastChangeTime()

◆ lookAt()

◆ makeGUI()

◆ markChanged()

◆ mass()

◆ maxCircleOfConfusionRadiusPixels()

◆ motionBlurSettings() [1/2]

◆ motionBlurSettings() [2/2]

◆ name()

◆ nearPlaneViewportHeight()

◆ nearPlaneViewportWidth()

◆ nearPlaneZ()

◆ nextTAAOffset()

◆ onOverwriteCameraFromDebug()

◆ onOverwriteDebugFromCamera()

◆ onPose()

◆ onSimulation()

◆ physicalSimulation()

◆ playSound()

◆ previousFrame()

◆ previousProjection()

◆ project()

◆ projection() [1/2]

◆ projection() [2/2]

◆ projectUnit()

◆ setCanCauseCollisions()

◆ setFarPlaneZ()

◆ setFieldOfView()