A 3D perspective projection with bounding planes in camera space. More...

Public Member Functions
	Projection (const Any &any)
	Must be of the format produced by the Any cast, e.g.,. More...

	Projection ()

	Projection (const Matrix4 &proj, const Vector2 &viewportExtent=Vector2::nan())

virtual	~Projection ()

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...

void	deserialize (class BinaryInput &bi)

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

float	fieldOfViewAngle () const

float	fieldOfViewAngleDegrees () const

Vector2	fieldOfViewAngles (const Rect2D &viewport) const
	Returns full horizontal and vertical field of view angles in radians. More...

FOVDirection	fieldOfViewDirection () const

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...

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...

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...

const Vector2 &	pixelOffset () const

float	pixelsPerMeter (float z, int width, int height) const
	Returns the scale factor between a length orthogonal to the viewing axis and screen pixels, at a given (negative) distance z along the viewing axis. More...

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

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

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

Vector3	reconstructFromDepthClipInfo () const
	Computes the clipInfo arg used in reconstructFromDepth.glsl. More...

ProjInfo	reconstructFromDepthProjInfo (int width, int height) const
	Computes the projInfo arg used in reconstructFromDepth.glsl. More...

void	serialize (class BinaryOutput &bo) const
	Read and Write projection parameters. 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)

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

void	setPixelOffset (const Vector2 &p)
	Displacement relative to the pixel center measured to the right and down added in pixels in screen space to the projection matrix. More...

Any	toAny () 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...

Detailed Description

A 3D perspective projection with bounding planes in camera space.

The area that a computer graphics 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.

See also: Matrix4, CoordinateFrame, Frustum

Constructor & Destructor Documentation

◆ Projection() [1/3]

G3D::Projection::Projection ( const Any & any )

Must be of the format produced by the Any cast, e.g.,.

Projection {
    nearPlaneZ = -0.5,
    farPlaneZ = -50,
    fovDirection = "HORIZONTAL",
    fovAngleDegrees = 90
}

Missing fields are filled from the default Projection constructor.

◆ Projection() [2/3]

G3D::Projection::Projection ( )

◆ Projection() [3/3]

G3D::Projection::Projection	(	const Matrix4 &	proj,
		const Vector2 &	viewportExtent = `Vector2::nan()`
	)

Parameters

viewportExtent Required if there is a pixel offset in proj (i.e., it has asymmetric clip planes)

◆ ~Projection()

virtual G3D::Projection::~Projection ( )

virtual

Member Function Documentation

◆ convertFromUnitToNormal()

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

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

◆ deserialize()

void G3D::Projection::deserialize ( class BinaryInput & bi )

◆ farPlaneZ()

float G3D::Projection::farPlaneZ ( ) const

inline

Returns a negative z-value.

Referenced by G3D::Camera::farPlaneZ().

◆ fieldOfViewAngle()

float G3D::Projection::fieldOfViewAngle ( ) const

inline

Referenced by G3D::Camera::fieldOfViewAngle().

◆ fieldOfViewAngleDegrees()

float G3D::Projection::fieldOfViewAngleDegrees ( ) const

inline

Referenced by G3D::Camera::fieldOfViewAngleDegrees().

◆ fieldOfViewAngles()

Vector2 G3D::Projection::fieldOfViewAngles ( const Rect2D & viewport ) const

Returns full horizontal and vertical field of view angles in radians.

Angle order is guaranteed to be: horizontal FOV, vertical FOV.

◆ fieldOfViewDirection()

FOVDirection G3D::Projection::fieldOfViewDirection ( ) const

inline

Referenced by G3D::Camera::_fieldOfViewDirectionInt(), and G3D::Camera::fieldOfViewDirection().

◆ frustum() [1/2]

void G3D::Projection::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::Projection::frustum ( const Rect2D & viewport ) const

◆ getClipPlanes()

void G3D::Projection::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::Projection::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::Projection::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.

Referenced by G3D::Camera::getFieldOfView().

◆ getNearViewportCorners()

void G3D::Projection::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::Projection::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().

◆ getProjectUnitMatrix()

void G3D::Projection::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

◆ imagePlanePixelsPerMeter()

float G3D::Projection::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.

◆ nearPlaneViewportHeight()

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

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

◆ nearPlaneViewportWidth()

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

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

◆ nearPlaneZ()

float G3D::Projection::nearPlaneZ ( ) const

inline

Returns a negative z-value.

Referenced by G3D::Camera::nearPlaneZ().

◆ pixelOffset()

const Vector2& G3D::Projection::pixelOffset ( ) const

inline

Referenced by G3D::Camera::jitterMotion().

◆ pixelsPerMeter()

float G3D::Projection::pixelsPerMeter	(	float	z,
		int	width,
		int	height
	)		const

Returns the scale factor between a length orthogonal to the viewing axis and screen pixels, at a given (negative) distance z along the viewing axis.

For example, this is the scale factor to multiply the radius of a viewer-aligned disk by to obtain its pixel radius under perspective projection.

Parameters

z	must be negative

◆ project()

Point3 G3D::Projection::project	(	const Point3 &	point,
		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

◆ projectUnit()

Point3 G3D::Projection::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.

◆ ray()

Ray G3D::Projection::ray	(	float	x,
		float	y,
		const class Rect2D &	viewport
	)		const

Returns the world space ray passing through pixel (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 camera's look vector.

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 integer x and y.

The Rect2D::x0y0() coordinate is added to (x, y) before casting to account for guard bands.

◆ reconstructFromDepthClipInfo()

Vector3 G3D::Projection::reconstructFromDepthClipInfo ( ) const

Computes the clipInfo arg used in reconstructFromDepth.glsl.

◆ reconstructFromDepthProjInfo()

ProjInfo G3D::Projection::reconstructFromDepthProjInfo	(	int	width,
		int	height
	)		const

Computes the projInfo arg used in reconstructFromDepth.glsl.

◆ serialize()

void G3D::Projection::serialize ( class BinaryOutput & bo ) const

Read and Write projection parameters.

◆ setFarPlaneZ()

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

inline

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

Referenced by G3D::Camera::setFarPlaneZ().

◆ setFieldOfView()

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

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.

Referenced by G3D::Camera::setFieldOfView().

◆ setFieldOfViewAngle()

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

inline

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

Referenced by G3D::Camera::setFieldOfViewAngle(), and setFieldOfViewAngleDegrees().

◆ setFieldOfViewAngleDegrees()

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

inline

Referenced by G3D::Camera::setFieldOfViewAngleDegrees().

◆ setFieldOfViewDirection()

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

inline

Referenced by G3D::Camera::_setFieldOfViewDirectionInt(), and G3D::Camera::setFieldOfViewDirection().

◆ setNearPlaneZ()

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

inline

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

Referenced by G3D::Camera::setNearPlaneZ().

◆ setPixelOffset()

void G3D::Projection::setPixelOffset ( const Vector2 & p )

inline

Displacement relative to the pixel center measured to the right and down added in pixels in screen space to the projection matrix.

This is useful for shifting the sampled location from the pixel center (OpenGL convention) to other locations, such as the upper-left.

The default is (0, 0).

◆ toAny()

Any G3D::Projection::toAny ( ) const

◆ unproject()

Point3 G3D::Projection::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::Projection::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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Projection() [1/3]

◆ Projection() [2/3]

◆ Projection() [3/3]

◆ ~Projection()

Member Function Documentation

◆ convertFromUnitToNormal()

◆ deserialize()

◆ farPlaneZ()

◆ fieldOfViewAngle()

◆ fieldOfViewAngleDegrees()

◆ fieldOfViewAngles()

◆ fieldOfViewDirection()

◆ frustum() [1/2]

◆ frustum() [2/2]

◆ getClipPlanes()

◆ getFarViewportCorners()

◆ getFieldOfView()

◆ getNearViewportCorners()

◆ getProjectPixelMatrix()

◆ getProjectUnitMatrix()

◆ imagePlanePixelsPerMeter()

◆ nearPlaneViewportHeight()

◆ nearPlaneViewportWidth()

◆ nearPlaneZ()

◆ pixelOffset()

◆ pixelsPerMeter()

◆ project()

◆ projectUnit()

◆ ray()

◆ reconstructFromDepthClipInfo()

◆ reconstructFromDepthProjInfo()

◆ serialize()

◆ setFarPlaneZ()

◆ setFieldOfView()

◆ setFieldOfViewAngle()

◆ setFieldOfViewAngleDegrees()

◆ setFieldOfViewDirection()

◆ setNearPlaneZ()

◆ setPixelOffset()

◆ toAny()

◆ unproject()

◆ unprojectUnit()