Make new CameraActor creation API for 3D apps

[platform/core/uifw/dali-core.git] / dali / public-api / actors / camera-actor.h

diff --git a/dali/public-api/actors/camera-actor.h b/dali/public-api/actors/camera-actor.h
index 25c6db7..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) 2020 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.
@@ -190,6 +203,23 @@ public:
   CameraActor& operator=(const CameraActor& rhs);
 
   /**
+   * @brief Move constructor.
+   *
+   * @SINCE_2_2.4
+   * @param[in] rhs A reference to the actor to move
+   */
+  CameraActor(CameraActor&& rhs);
+
+  /**
+   * @brief Move assignment operator.
+   *
+   * @SINCE_2_2.4
+   * @param[in] rhs A reference to the actor to move
+   * @return A reference to this
+   */
+  CameraActor& operator=(CameraActor&& rhs);
+
+  /**
    * @brief Sets the camera type.
    * The default type is Dali::Camera::FREE_LOOK
    * @SINCE_1_0.0
@@ -223,6 +253,7 @@ public:
 
   /**
    * @brief Sets the field of view.
+   * Field of view will be used when ProjectionMode is PERSPECTIVE_PROJECTION.
    *
    * @SINCE_1_0.0
    * @param[in] fieldOfView The field of view in radians
@@ -332,6 +363,7 @@ public:
    * Sets the near and far clipping planes, the field of view, the aspect ratio,
    * and the Z position of the actor based on the canvas size so that 1 unit in
    * XY (z=0) plane is 1 pixel on screen.
+   * Also, It will set orthographic size be fitted as XY plane.
    *
    * @SINCE_1_0.0
    * @param[in] size The canvas size
@@ -357,21 +389,6 @@ public:
    */
   void SetOrthographicProjection(const Size& size);
 
-  /**
-   * @brief Sets the camera projection to use orthographic projection with the given clip planes.
-   *
-   * This does not change the Z value of the camera actor.
-   *
-   * @SINCE_1_0.0
-   * @param[in] left Distance to left clip plane (normal to camera axis)
-   * @param[in] right Distance to right clip plane (normal to camera axis)
-   * @param[in] top Distance to top clip plane (normal to camera axis)
-   * @param[in] bottom Distance to bottom clip plane (normal to camera axis)
-   * @param[in] near Distance to the near clip plane (along camera axis)
-   * @param[in] far Distance to the far clip plane (along camera axis)
-   */
-  void SetOrthographicProjection(float left, float right, float top, float bottom, float near, float far);
-
 public: // Not intended for use by Application developers
   /// @cond internal
   /**