Improve Camera documentation. To avoid potential confusion, disable auto aspect ratio mode from Camera if aspect ratio is set explicitly, or if the Vector2 form of Camera::SetOrthoSize() is used.

Source/Engine/Graphics/Camera.cpp

@@ -93,7 +93,7 @@ void Camera::RegisterObject(Context* context)
     ACCESSOR_ATTRIBUTE(Camera, VAR_FLOAT, "Near Clip", GetNearClip, SetNearClip, float, DEFAULT_NEARCLIP, AM_DEFAULT);
     ACCESSOR_ATTRIBUTE(Camera, VAR_FLOAT, "Far Clip", GetFarClip, SetFarClip, float, DEFAULT_FARCLIP, AM_DEFAULT);
     ACCESSOR_ATTRIBUTE(Camera, VAR_FLOAT, "FOV", GetFov, SetFov, float, DEFAULT_FOV, AM_DEFAULT);
-    ACCESSOR_ATTRIBUTE(Camera, VAR_FLOAT, "Aspect Ratio", GetAspectRatio, SetAspectRatio, float, 1.0f, AM_DEFAULT);
+    ACCESSOR_ATTRIBUTE(Camera, VAR_FLOAT, "Aspect Ratio", GetAspectRatio, SetAspectRatioInternal, float, 1.0f, AM_DEFAULT);
     ENUM_ATTRIBUTE(Camera, "Fill Mode", fillMode_, fillModeNames, FILL_SOLID, AM_DEFAULT);
     ATTRIBUTE(Camera, VAR_BOOL, "Auto Aspect Ratio", autoAspectRatio_, true, AM_DEFAULT);
     ACCESSOR_ATTRIBUTE(Camera, VAR_BOOL, "Orthographic", IsOrthographic, SetOrthographic, bool, false, AM_DEFAULT);
@@ -149,6 +149,7 @@ void Camera::SetOrthoSize(float orthoSize)
 
 void Camera::SetOrthoSize(const Vector2& orthoSize)
 {
+    autoAspectRatio_ = false;
     orthoSize_ = orthoSize.y_;
     aspectRatio_ = orthoSize.x_ / orthoSize.y_;
     frustumDirty_ = true;
@@ -158,10 +159,8 @@ void Camera::SetOrthoSize(const Vector2& orthoSize)
 
 void Camera::SetAspectRatio(float aspectRatio)
 {
-    aspectRatio_ = aspectRatio;
-    frustumDirty_ = true;
-    projectionDirty_ = true;
-    MarkNetworkUpdate();
+    autoAspectRatio_ = false;
+    SetAspectRatioInternal(aspectRatio);
 }
 
 void Camera::SetZoom(float zoom)
@@ -556,6 +555,14 @@ const Matrix3x4& Camera::GetView() const
     return view_;
 }
 
+void Camera::SetAspectRatioInternal(float aspectRatio)
+{
+    aspectRatio_ = aspectRatio;
+    frustumDirty_ = true;
+    projectionDirty_ = true;
+    MarkNetworkUpdate();
+}
+
 void Camera::SetReflectionPlaneAttr(Vector4 value)
 {
     SetReflectionPlane(Plane(value));

Source/Engine/Graphics/Camera.h

@@ -55,13 +55,13 @@ public:
     void SetNearClip(float nearClip);
     /// Set far clip distance.
     void SetFarClip(float farClip);
-    /// Set field of view.
+    /// Set vertical field of view in degrees.
     void SetFov(float fov);
     /// Set orthographic mode view uniform size.
     void SetOrthoSize(float orthoSize);
-    /// Set orthographic mode view size.
+    /// Set orthographic mode view non-uniform size. Disables the auto aspect ratio -mode.
     void SetOrthoSize(const Vector2& orthoSize);
-    /// Set aspect ratio.
+    /// Set aspect ratio manually. Disables the auto aspect ratio -mode.
     void SetAspectRatio(float aspectRatio);
     /// Set polygon fill mode to use when rendering a scene.
     void SetFillMode(FillMode mode);
@@ -75,7 +75,7 @@ public:
     void SetViewOverrideFlags(unsigned flags);
     /// Set orthographic mode enabled/disabled.
     void SetOrthographic(bool enable);
-    /// Set automatic aspect ratio based on viewport dimensions.
+    /// Set automatic aspect ratio based on viewport dimensions. Enabled by default.
     void SetAutoAspectRatio(bool enable);
     /// Set projection offset. It needs to be calculated as (offset in pixels) / (viewport dimensions.)
     void SetProjectionOffset(const Vector2& offset);
@@ -94,7 +94,7 @@ public:
     float GetFarClip() const { return farClip_; }
     /// Return near clip distance.
     float GetNearClip() const;
-    /// Return field of view.
+    /// Return vertical field of view in degrees.
     float GetFov() const { return fov_; }
     /// Return orthographic mode size.
     float GetOrthoSize() const { return orthoSize_; } 
@@ -163,6 +163,8 @@ public:
     /// Return if projection parameters are valid for rendering and raycasting.
     bool IsProjectionValid() const;
     
+    /// Set aspect ratio without disabling the "auto aspect ratio" mode. Called internally by View.
+    void SetAspectRatioInternal(float aspectRatio);
     /// Set reflection plane attribute.
     void SetReflectionPlaneAttr(Vector4 value);
     /// Return reflection plane attribute.

Source/Engine/Graphics/View.cpp

@@ -487,7 +487,7 @@ void View::Update(const FrameInfo& frame)
     
     // Set automatic aspect ratio if required
     if (camera_->GetAutoAspectRatio())
-        camera_->SetAspectRatio((float)frame_.viewSize_.x_ / (float)frame_.viewSize_.y_);
+        camera_->SetAspectRatioInternal((float)frame_.viewSize_.x_ / (float)frame_.viewSize_.y_);
     
     GetDrawables();
     GetBatches();
@@ -515,7 +515,7 @@ void View::Render()
     // It is possible, though not recommended, that the same camera is used for multiple main views. Set automatic aspect ratio
     // again to ensure correct projection will be used
     if (camera_->GetAutoAspectRatio())
-        camera_->SetAspectRatio((float)(viewSize_.x_) / (float)(viewSize_.y_));
+        camera_->SetAspectRatioInternal((float)(viewSize_.x_) / (float)(viewSize_.y_));
     
     // Bind the face selection and indirection cube maps for point light shadows
     if (renderer_->GetDrawShadows())