# CCamera

You are here: Common > Math > CCamera Class
CCamera Class
Class Hierarchy
C++
`class CCamera;`
File

Cry_Camera.h

Description

Implements essential operations like calculation of a view-matrix and frustum-culling with simple geometric primitives (Point, Sphere, AABB, OBB). All calculation are based on the CryENGINE coordinate-system

We are using a "right-handed" coordinate systems, where the positive X-Axis points to the right, the positive Y-Axis points away from the viewer and the positive Z-Axis points up. The following illustration shows our coordinate system.

``` z-axis
^
|
|   y-axis
|  /
| /
|/
+---------------->   x-axis     ```

This same system is also used in 3D-Studio-MAX. It is not unusual for 3D-APIs like D3D9 or OpenGL to use a different coordinate system. Currently in D3D9 we use a coordinate system in which the X-Axis points to the right, the Y-Axis points down and the Z-Axis points away from the viewer. To convert from the CryEngine system into D3D9 we are just doing a clockwise rotation of pi/2 about the X-Axis. This conversion happens in the renderer.

The 6 DOFs (degrees-of-freedom) are stored in one single 3x4 matrix ("m_Matrix"). The 3 orientation-DOFs are stored in the 3x3 part and the 3 position-DOFs are stored in the translation- vector. You can use the member-functions "GetMatrix()" or "SetMatrix(Matrix34(orientation,positon))" to change or access the 6 DOFs.

There are helper-function in Cry_Math.h to create the orientation:

This function builds a 3x3 orientation matrix using a view-direction and a radiant to rotate about Y-axis. Matrix33 orientation=Matrix33::CreateOrientation( Vec3(0,1,0), 0 );

This function builds a 3x3 orientation matrix using Yaw-Pitch-Roll angles. Matrix33 orientation=CCamera::CreateOrientationYPR( Ang3(1.234f,0.342f,0) );

CCamera::ScissorInfo Structure
C++
```struct ScissorInfo {
uint16 x1, y1, x2, y2;
};```
File

Cry_Camera.h

CCamera::ScissorInfo::x1 Data Member
C++
`uint16 x1;`
CCamera::ScissorInfo::x2 Data Member
C++
`uint16 x2;`
CCamera::ScissorInfo::y1 Data Member
C++
`uint16 y1;`
CCamera::ScissorInfo::y2 Data Member
C++
`uint16 y2;`
CCamera::ScissorInfo::ScissorInfo Constructor
C++
`ScissorInfo();`
CCamera::m_JustActivated Data Member
C++
`int m_JustActivated;`
Description

Camera activated in this frame, used for disabling motion blur effect at camera changes in movies

CCamera::m_OccPosition Data Member
C++
`Vec3 m_OccPosition;`
Description

Position for calculate occlusions (needed for portals rendering)

CCamera::m_pMultiCamera Data Member
C++
`class PodArray<CCamera> * m_pMultiCamera;`
Description

maybe used for culling instead of this camera

CCamera::m_pPortal Data Member
C++
`struct IVisArea* m_pPortal;`
Description

pointer to portal used to create this camera

CCamera::m_ScissorInfo Data Member
C++
`ScissorInfo m_ScissorInfo;`
CCamera::~CCamera Destructor
C++
`~CCamera();`
CCamera::CalcScreenBounds Method
C++
`void CalcScreenBounds(int * vOut, const AABB * pAABB, int nWidth, int nHeight) const;`
CCamera::CCamera Constructor
C++
`CCamera();`
CCamera::CreateAnglesYPR Method (Matrix33&)
C++
`static Ang3 CreateAnglesYPR(const Matrix33& m);`
Description
```x-YAW
y-PITCH (negative=looking down / positive=looking up)
z-ROLL ```
Notes

If we are looking along the z-axis, its not possible to specify the x and z-angle

CCamera::CreateAnglesYPR Method (Vec3&, f32)
C++
`static Ang3 CreateAnglesYPR(const Vec3& vdir, f32 r = 0);`
Description
```x-YAW
y-PITCH (negative=looking down / positive=looking up)
z-ROLL (its not possile to extract a "roll" from a view-vector)```
Notes

if we are looking along the z-axis, its not possible to specify the rotation about the z-axis

CCamera::CreateOrientationYPR Method
C++
`static Matrix33 CreateOrientationYPR(const Ang3& ypr);`
Description

This function builds a 3x3 orientation matrix using YPR-angles Rotation order for the orientation-matrix is Z-X-Y. (Zaxis=YAW / Xaxis=PITCH / Yaxis=ROLL)

``` COORDINATE-SYSTEM

z-axis
^
|
|  y-axis
|  /
| /
|/
+--------------->   x-axis     ```
Example

Matrix33 orientation=CCamera::CreateOrientationYPR( Ang3(1,2,3) );

CCamera::CreateViewdir Method (Ang3&)
C++
`static Vec3 CreateViewdir(const Ang3& ypr);`
Description
```x=yaw
y=pitch
z=roll (we ignore this element, since its not possible to convert the roll-component into a vector)```
CCamera::CreateViewdir Method (Matrix33&)
C++
`static Vec3 CreateViewdir(const Matrix33& m);`
CCamera::GetAngles Method
C++
`inline Ang3 GetAngles() const;`
CCamera::GetAngularResolution Method
C++
`f32 GetAngularResolution() const;`
CCamera::GetAsymB Method
C++
`f32 GetAsymB() const;`
CCamera::GetAsymL Method
C++
`f32 GetAsymL() const;`
CCamera::GetAsymR Method
C++
`f32 GetAsymR() const;`
CCamera::GetAsymT Method
C++
`f32 GetAsymT() const;`
CCamera::GetEdgeF Method
C++
`Vec3 GetEdgeF() const;`
CCamera::GetEdgeN Method
C++
`Vec3 GetEdgeN() const;`
CCamera::GetEdgeP Method
C++
`Vec3 GetEdgeP() const;`
CCamera::GetFarPlane Method
C++
`f32 GetFarPlane() const;`
CCamera::GetFov Method
C++
`f32 GetFov() const;`
CCamera::GetFPVertex Method
C++
`const Vec3& GetFPVertex(int nId) const;`
Description

get far-plane vertices

get far-plane vertices

CCamera::GetFrustumPlane Method
C++
`const Plane* GetFrustumPlane(int numplane) const;`
CCamera::GetFrustumVertices Method

Return frustum vertices in world space

C++
`void GetFrustumVertices(Vec3 * pVerts) const;`
Description

Takes pointer to array of 8 elements

CCamera::GetFrustumVerticesCam Method
C++
`void GetFrustumVerticesCam(Vec3 * pVerts) const;`
CCamera::GetHorizontalFov Method
C++
`float GetHorizontalFov() const;`
CCamera::GetMatrix Method
C++
`const Matrix34& GetMatrix() const;`
CCamera::GetMemoryUsage Method
C++
`void GetMemoryUsage(ICrySizer * pSizer) const;`
CCamera::GetNearPlane Method
C++
`f32 GetNearPlane() const;`
CCamera::GetNPVertex Method
C++
`const Vec3& GetNPVertex(int nId) const;`
Description

get near-plane vertices

get near-plane vertices

CCamera::GetOccPos Method
C++
`inline const Vec3& GetOccPos() const;`
CCamera::GetPixelAspectRatio Method
C++
`f32 GetPixelAspectRatio() const;`
CCamera::GetPosition Method
C++
`Vec3 GetPosition() const;`
CCamera::GetPPVertex Method
C++
`const Vec3& GetPPVertex(int nId) const;`
Description

get projection-plane vertices

CCamera::GetProjRatio Method
C++
`f32 GetProjRatio() const;`
CCamera::GetViewdir Method
C++
`Vec3 GetViewdir() const;`
CCamera::GetViewMatrix Method
C++
`Matrix34 GetViewMatrix() const;`
CCamera::GetViewPort Method
C++
`void GetViewPort(int & nPosX, int & nPosY, int & nSizeX, int & nSizeY) const;`
CCamera::GetViewSurfaceX Method
C++
`int GetViewSurfaceX() const;`
CCamera::GetViewSurfaceZ Method
C++
`int GetViewSurfaceZ() const;`
CCamera::GetZRangeMax Method
C++
`float GetZRangeMax() const;`
CCamera::GetZRangeMin Method
C++
`float GetZRangeMin() const;`
CCamera::IsAABBVisible_E Method
C++
`bool IsAABBVisible_E(const AABB& aabb) const;`
Description

Exact

This function checks if an AABB and the camera-frustum overlap. The AABB is assumed to be in world-space. This test can reject even such AABBs that overlap a frustum-plane far outside the view-frustum. IMPORTANT: This function is only useful if you really need exact-culling. It's about 30% slower then "IsAABBVisible_F(aabb)"

Example

int InOut=camera.IsAABBVisible_E(aabb);

return values: CULL_EXCLUSION = AABB outside of frustum (very fast rejection-test) CULL_OVERLAP = AABB either intersects the borders of the frustum or is totally inside

CCamera::IsAABBVisible_EH Method (AABB&)
C++
`uint8 IsAABBVisible_EH(const AABB& aabb) const;`
Description

Improved approach to check if an AABB and the camera-frustum overlap, or if the AABB is totally inside the camera-frustum. The AABB is assumed to be in world-space. This test can reject even such AABBs that overlap a frustum-plane far outside the view-frustum. IMPORTANT: This function is only useful if you really need exact-culling. It's about 30% slower then "IsAABBVisible_FH(aabb)"

Example

int InOut=camera.IsAABBVisible_EH(aabb);

return values: CULL_EXCLUSION = AABB outside of frustum (very fast rejection-test) CULL_OVERLAP = AABB intersects the borders of the frustum, further checks necessary CULL_INCLUSION = AABB is complete inside the frustum, no further checks necessary

CCamera::IsAABBVisible_EH Method (AABB&, bool *)
C++
`uint8 IsAABBVisible_EH(const AABB& aabb, bool * pAllInside) const;`
CCamera::IsAABBVisible_EHM Method
C++
`bool IsAABBVisible_EHM(const AABB& aabb, bool * pAllInside) const;`
Description

Multi-camera

Makes culling taking into account presence of m_pMultiCamera If m_pMultiCamera exists - object is visible if at least one of cameras see's it

return values: true - box visible true - not visible

CCamera::IsAABBVisible_EM Method
C++
`bool IsAABBVisible_EM(const AABB& aabb) const;`
Description

Makes culling taking into account presence of m_pMultiCamera If m_pMultiCamera exists - object is visible if at least one of cameras see's it

return values: true - box visible true - not visible

CCamera::IsAABBVisible_F Method
C++
`bool IsAABBVisible_F(const AABB& aabb) const;`
Description

AABB-frustum test Fast

Simple approach to check if an AABB and the camera-frustum overlap. The AABB is assumed to be in world-space. This is a very fast method, just one single dot-product is necessary to check an AABB against a plane. Actually there is no significant speed-different between culling a sphere or an AABB.

Example

bool InOut=camera.IsAABBVisible_F(aabb);

return values CULL_EXCLUSION = AABB outside of frustum (very fast rejection-test) CULL_OVERLAP = AABB either intersects the borders of the frustum or is totally inside

CCamera::IsAABBVisible_FH Method (AABB&)
C++
`uint8 IsAABBVisible_FH(const AABB& aabb) const;`
Description

Hierarchical approach to check if an AABB and the camera-frustum overlap, or if the AABB is totally inside the camera-frustum. The AABB is assumed to be in world-space.

Example

int InOut=camera.IsAABBVisible_FH(aabb);

return values CULL_EXCLUSION = AABB outside of frustum (very fast rejection-test) CULL_OVERLAP = AABB intersects the borders of the frustum, further checks necessary CULL_INCLUSION = AABB is complete inside the frustum, no further checks necessary

CCamera::IsAABBVisible_FH Method (AABB&, bool *)
C++
`uint8 IsAABBVisible_FH(const AABB& aabb, bool * pAllInside) const;`
Description

Hierarchical approach to check if an AABB and the camera-frustum overlap, or if the AABB is totally inside the camera-frustum. The AABB is assumed to be in world-space.

Example

int InOut=camera.IsAABBVisible_FH(aabb);

return values CULL_EXCLUSION = AABB outside of frustum (very fast rejection-test) CULL_OVERLAP = AABB intersects the borders of the frustum, further checks necessary CULL_INCLUSION = AABB is complete inside the frustum, no further checks necessary

CCamera::IsAABBVisible_FM Method
C++
`bool IsAABBVisible_FM(const AABB& aabb) const;`
Description

Makes culling taking into account presence of m_pMultiCamera If m_pMultiCamera exists - object is visible if at least one of cameras see's it

return values: true - box visible true - not visible

CCamera::IsJustActivated Method
C++
`bool IsJustActivated() const;`
CCamera::IsOBBVisible_E Method
C++
`bool IsOBBVisible_E(const Vec3& wpos, const OBB& obb, f32 uscale) const;`
Description

This function checks if an OBB and the camera-frustum overlap. This test can reject even such OBBs that overlap a frustum-plane far outside the view-frustum. IMPORTANT: It is about 10% slower then "IsOBBVisibleFast(obb)"

Example

int InOut=camera.IsOBBVisible_E(OBB);

return values: CULL_EXCLUSION = OBB outside of frustum (very fast rejection-test) CULL_OVERLAP = OBB intersects the borders of the frustum or is totally inside

CCamera::IsOBBVisible_EH Method
C++
`uint8 IsOBBVisible_EH(const Vec3& wpos, const OBB& obb, f32 uscale) const;`
Description

Improved approach to check if an OBB and the camera-frustum intersect, or if the OBB is totally inside the camera-frustum. The bounding-box of the OBB is assumed to be in world-space. This test can reject even such OBBs that intersect a frustum-plane far outside the view-frustum

Example

int InOut=camera.IsOBBVisible_EH(obb);

return values: CULL_EXCLUSION = OBB outside of frustum (very fast rejection-test) CULL_OVERLAP = OBB intersects the borders of the frustum, further checks necessary CULL_INCLUSION = OBB is complete inside the frustum, no further checks necessary

CCamera::IsOBBVisible_F Method
C++
`bool IsOBBVisible_F(const Vec3& wpos, const OBB& obb) const;`
Description

OBB-frustum test

Fast check if an OBB and the camera-frustum overlap, using the separating-axis-theorem (SAT) The center of the OOBB is assumed to be in world-space.

Notes

even if the OBB is totally inside the frustum, this function returns CULL_OVERLAP For hierarchical frustum-culling this function is not perfect.

Example

bool InOut=camera.IsOBBVisibleFast(obb);

return values: CULL_EXCLUSION = OBB outside of frustum (very fast rejection-test) CULL_OVERLAP = OBB and frustum intersects or OBB in totally inside frustum

CCamera::IsOBBVisible_FH Method
C++
`uint8 IsOBBVisible_FH(const Vec3& wpos, const OBB& obb) const;`
CCamera::IsPointVisible Method
C++
`bool IsPointVisible(const Vec3& p) const;`
Description

Check if a point lies within camera's frustum

CCamera::IsSphereVisible_F Method
C++
`bool IsSphereVisible_F(const Sphere & s) const;`
Description

sphere-frustum test

Conventional method to check if a sphere and the camera-frustum overlap The center of the sphere is assumed to be in world-space.

Example

u8 InOut=camera.IsSphereVisible_F(sphere);

return values CULL_EXCLUSION = sphere outside of frustum (very fast rejection-test) CULL_INTERSECT = sphere and frustum intersects or sphere in completely inside frustum

CCamera::IsSphereVisible_FH Method
C++
`uint8 IsSphereVisible_FH(const Sphere & s) const;`
Description

this is going to be the exact version of sphere-culling

Conventional method to check if a sphere and the camera-frustum overlap, or if the sphere is completely inside the camera-frustum. The center of the sphere is assumed to be in world-space.

Example

u8 InOut=camera.IsSphereVisible_FH(sphere);

return values CULL_EXCLUSION = sphere outside of frustum (very fast rejection-test) CULL_INTERSECT = sphere intersects the borders of the frustum, further checks necessary CULL_INCLUSION = sphere is complete inside the frustum, no further checks necessary

CCamera::Project Method
C++
`bool Project(const Vec3& p, Vec3& result, Vec2i topLeft = Vec2i(0,0), Vec2i widthHeight = Vec2i(0,0)) const;`
Description
```p=world space position
result=spreen space pos
retval=is visible on screen```
CCamera::SetAngles Method
C++
`void SetAngles(const Ang3 & angles);`
CCamera::SetAsymmetry Method
C++
`void SetAsymmetry(float l, float r, float b, float t);`
CCamera::SetFrustum Method
C++
`void SetFrustum(int nWidth, int nHeight, f32 FOV = DEFAULT_FOV, f32 nearplane = DEFAULT_NEAR, f32 farpane = DEFAULT_FAR, f32 fPixelAspectRatio = 1.0f);`
CCamera::SetFrustumPlane Method
C++
`inline void SetFrustumPlane(int i, const Plane & plane);`
CCamera::SetFrustumVertices Method
C++
`void SetFrustumVertices(Vec3 * arrvVerts);`
Description

OLD STUFF

CCamera::SetJustActivated Method
C++
`void SetJustActivated(const bool justActivated);`
CCamera::SetMatrix Method
C++
`void SetMatrix(const Matrix34& mat);`
CCamera::SetMatrixNoUpdate Method
C++
`void SetMatrixNoUpdate(const Matrix34& mat);`
CCamera::SetPosition Method
C++
`void SetPosition(const Vec3& p);`
CCamera::SetPositionNoUpdate Method
C++
`void SetPositionNoUpdate(const Vec3& p);`
CCamera::SetPPVertex Method
C++
`void SetPPVertex(int nId, const Vec3 & vVert);`
CCamera::SetViewPort Method
C++
`void SetViewPort(int nPosX, int nPosY, int nSizeX, int nSizeY);`
CCamera::SetZRange Method
C++
`void SetZRange(float zmin, float zmax);`
Description

Z-Buffer ranges. This values are defining near/far clipping plane, it only used to specify z-buffer range. Use it only when you want to override default z-buffer range. Valid values for are: 0 <= zrange <= 1

CCamera::Unproject Method
C++
`bool Unproject(const Vec3& viewportPos, Vec3& result, Vec2i topLeft = Vec2i(0,0), Vec2i widthHeight = Vec2i(0,0)) const;`
CCamera::UpdateFrustum Method
C++
`void UpdateFrustum();`
Description

! *

• Updates all parameters required by the render-engine:

*

• 3d-view-frustum and all matrices

• No labels