Make new CameraActor creation API for 3D apps

Default CameraActor's behavior is not helpful for formal 3D app side.
For example, 3D app don't care about "scene", but CameraActor::New()
change some properties by engine side automaticaly.

To make 3D app developer use CameraActor easly, make new API that fit
good to 3D cases.

Change-Id: Iaf2a792b0fd98cd31d2c655da61918133e211ff0
Signed-off-by: Eunki, Hong <eunkiki.hong@samsung.com>

diff --git a/automated-tests/src/dali/utc-Dali-CameraActor.cpp b/automated-tests/src/dali/utc-Dali-CameraActor.cpp
index 6c8af27..28159af 100644 (file)
--- a/automated-tests/src/dali/utc-Dali-CameraActor.cpp
+++ b/automated-tests/src/dali/utc-Dali-CameraActor.cpp
@@ -211,6 +211,21 @@ int UtcDaliCameraActorNewP(void)
   END_TEST;
 }
 
+int UtcDaliCameraActorNew3DCameraP(void)
+{
+  TestApplication application;
+  tet_infoline("Testing Dali::CameraActor::New3DCamera (P)");
+
+  CameraActor actor = CameraActor::New3DCamera();
+
+  DALI_TEST_CHECK(actor);
+
+  actor.Reset();
+
+  DALI_TEST_CHECK(!actor);
+  END_TEST;
+}
+
 int UtcDaliCameraActorNewDefaultPerspectiveProjection(void)
 {
   TestApplication application;

diff --git a/dali/internal/event/actors/camera-actor-impl.cpp b/dali/internal/event/actors/camera-actor-impl.cpp
index beefc38..883a28d 100644 (file)
--- a/dali/internal/event/actors/camera-actor-impl.cpp
+++ b/dali/internal/event/actors/camera-actor-impl.cpp
@@ -178,9 +178,41 @@ struct OrthographicSizeConverter
   Dali::DevelCameraActor::ProjectionDirection mProjectionDirection;
 };
 
+static const float DEFAULT_NEAR_CLIPPING_PLANE_FOR_3D = 0.1f;
+static const float DEFAULT_FAR_CLIPPING_PLANE_FOR_3D  = 100.0f;
+
+static const Dali::Camera::ProjectionMode                DEFAULT_MODE_FOR_3D                 = SceneGraph::Camera::DEFAULT_MODE;
+static const Dali::DevelCameraActor::ProjectionDirection DEFAULT_PROJECTION_DIRECTION_FOR_3D = SceneGraph::Camera::DEFAULT_PROJECTION_DIRECTION;
+
+static const float      DEFAULT_FIELD_OF_VIEW_FOR_3D     = SceneGraph::Camera::DEFAULT_FIELD_OF_VIEW;
+static const float      DEFAULT_POSITIN_Z_FOR_3D         = 5.0f;
+static const Quaternion DEFAULT_ORIENTATION_FOR_3D       = Quaternion(Dali::ANGLE_180, Vector3::YAXIS);
+static const float      DEFAULT_ORTHOGRAPHIC_SIZE_FOR_3D = 2.071068f; // DEFAULT_POSITIN_Z_FOR_3D * std::tan(DEFAULT_FIELD_OF_VIEW_FOR_3D * 0.5f); // Rectangle size of z=0.
+
+/**
+ * @brief Setup CameraActor's parameters  for 3D apps.
+ * Conceptually, We can must see 1 world unit cube at world origin.
+ * Detail value can be changed by UX.
+ *
+ * @param[in,out] cameraActorObject CameraActor who need to apply default camera parameters.
+ */
+void SetupDefault3DCameraProperties(Internal::CameraActor& cameraActorObject)
+{
+  cameraActorObject.SetNearClippingPlane(DEFAULT_NEAR_CLIPPING_PLANE_FOR_3D);
+  cameraActorObject.SetFarClippingPlane(DEFAULT_FAR_CLIPPING_PLANE_FOR_3D);
+
+  cameraActorObject.SetProjectionMode(DEFAULT_MODE_FOR_3D);
+  cameraActorObject.SetProjectionDirection(DEFAULT_PROJECTION_DIRECTION_FOR_3D);
+  cameraActorObject.SetFieldOfView(DEFAULT_FIELD_OF_VIEW_FOR_3D);
+  cameraActorObject.SetZ(DEFAULT_POSITIN_Z_FOR_3D);
+  cameraActorObject.SetOrientation(DEFAULT_ORIENTATION_FOR_3D);
+
+  cameraActorObject.SetOrthographicSize(DEFAULT_ORTHOGRAPHIC_SIZE_FOR_3D);
+}
+
 } // namespace
 
-CameraActorPtr CameraActor::New(const Size& size)
+CameraActorPtr CameraActor::New(const Size& size, bool hintFor3D)
 {
   // create camera. Cameras are owned by the update manager
   SceneGraph::Camera*            camera = SceneGraph::Camera::New();
@@ -198,11 +230,19 @@ CameraActorPtr CameraActor::New(const Size& size)
   actor->Initialize();
 
   actor->SetName("DefaultCamera");
-  actor->SetPerspectiveProjection(size);
+  if(hintFor3D)
+  {
+    // Initialize camera property for 3D case.
+    SetupDefault3DCameraProperties(*actor);
+  }
+  else
+  {
+    actor->SetPerspectiveProjection(size);
 
-  // By default Actors face in the positive Z direction in world space
-  // CameraActors should face in the negative Z direction, towards the other actors
-  actor->SetOrientation(Quaternion(Dali::ANGLE_180, Vector3::YAXIS));
+    // By default Actors face in the positive Z direction in world space
+    // CameraActors should face in the negative Z direction, towards the other actors
+    actor->SetOrientation(Quaternion(Dali::ANGLE_180, Vector3::YAXIS));
+  }
 
   return actor;
 }

diff --git a/dali/internal/event/actors/camera-actor-impl.h b/dali/internal/event/actors/camera-actor-impl.h
index 6ecb3ed..74ccac5 100644 (file)
--- a/dali/internal/event/actors/camera-actor-impl.h
+++ b/dali/internal/event/actors/camera-actor-impl.h
@@ -2,7 +2,7 @@
 #define DALI_INTERNAL_CAMERA_ACTOR_H
 
 /*
- * Copyright (c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,13 +42,14 @@ public:
   /**
    * Create an initialised camera actor.
    *
-   * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
+   * If hintFor3D is false, Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
    *
    * @param[in] size The canvas size.
+   * @param[in] hintFor3D True if user set hint that this camera used for 3D. Default is false.
    *
    * @return A smart-pointer to a newly allocated camera actor.
    */
-  static CameraActorPtr New(const Size& size);
+  static CameraActorPtr New(const Size& size, bool hintFor3D = false);
 
   /**
    * Sets the reflection plane for the camera

diff --git a/dali/public-api/actors/camera-actor.cpp b/dali/public-api/actors/camera-actor.cpp
index 01fc8e2..10593d7 100644 (file)
--- a/dali/public-api/actors/camera-actor.cpp
+++ b/dali/public-api/actors/camera-actor.cpp
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,6 +37,13 @@ CameraActor CameraActor::New(const Size& size)
   return CameraActor(internal.Get());
 }
 
+CameraActor CameraActor::New3DCamera()
+{
+  Internal::CameraActorPtr internal = Internal::CameraActor::New(Size::ZERO, true);
+
+  return CameraActor(internal.Get());
+}
+
 CameraActor::CameraActor(Internal::CameraActor* internal)
 : Actor(internal)
 {

diff --git a/dali/public-api/actors/camera-actor.h b/dali/public-api/actors/camera-actor.h
index 3f85351..00337f2 100644 (file)
--- a/dali/public-api/actors/camera-actor.h
+++ b/dali/public-api/actors/camera-actor.h
@@ -2,7 +2,7 @@
 #define DALI_CAMERA_ACTOR_H
 
 /*
- * Copyright (c) 2022 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -72,7 +72,8 @@ enum ProjectionMode
  *   (configured to have the origin of the coordinate system at the top-left corner of the screen, and unit 1 as 1 pixel of the screen).
  *   This is a typical way.
  *
- * - For 3D applications, you can change the view by manipulating the camera. You can translate or rotate the camera in this case.
+ * - For 3D applications, you can change the view by manipulating the camera. If you config some camera properties,
+ *   or create camera by @see New3DCamera(), you can translate or rotate the camera whatever you want.
  *   Note that the top-left corner of the screen and unit 1 no longer are (0,0,0) and 1 pixel after manipulating the camera.
  *
  * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default,
@@ -136,6 +137,7 @@ public:
    *
    * @note Sets the default camera perspective projection for the size of the scene this is added to. @see SetPerspectiveProjection().
    * @note When this actor gets added to a scene, then it's Z position will be modified according to the required perspective projection.
+   * After modified Z position, 1-world-unit become 1-pixel.
    *
    * @SINCE_1_0.0
    * @return The newly created camera actor
@@ -154,6 +156,17 @@ public:
   static CameraActor New(const Size& size);
 
   /**
+   * @brief Creates a CameraActor object initialize by 3D parameter.
+   *
+   * Intialize default perspective camera s.t. properties as good to be used on 3D app case.
+   * Default camera positioned at +Z axis, and fit to see 1-world-unit sized cube on world origin.
+   *
+   * @SINCE_2_2.15
+   * @return The newly created camera actor
+   */
+  static CameraActor New3DCamera();
+
+  /**
    * @brief Downcasts a handle to CameraActor handle.
    *
    * If handle points to a CameraActor, the downcast produces valid handle.