dali/public-api/actors/camera-actor.h

   1 #ifndef DALI_CAMERA_ACTOR_H
   2 #define DALI_CAMERA_ACTOR_H
   3
   4 /*
   5  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 #include <dali/public-api/actors/actor.h>
  22
  23 namespace Dali
  24 {
  25 /**
  26  * @addtogroup dali_core_actors
  27  * @{
  28  */
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class CameraActor;
  33 }
  34
  35 /**
  36  * @brief Enumeration for camera.
  37  * @SINCE_1_0.0
  38  */
  39 namespace Camera
  40 {
  41 /**
  42  * @brief Enumeration for type determination of how camera operates.
  43  * @SINCE_1_0.0
  44  */
  45 enum Type
  46 {
  47   FREE_LOOK,      ///< Camera orientation is taken from CameraActor @SINCE_1_0.0
  48   LOOK_AT_TARGET, ///< Camera is oriented to always look at a target @SINCE_1_0.0
  49 };
  50
  51 /**
  52  * @brief Enumeration for projection modes.
  53  * @SINCE_1_0.0
  54  */
  55 enum ProjectionMode
  56 {
  57   PERSPECTIVE_PROJECTION,  ///< Distance causes foreshortening; objects further from the camera appear smaller @SINCE_1_0.0
  58   ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects @SINCE_1_0.0
  59 };
  60
  61 } // namespace Camera
  62
  63 /**
  64  * @brief CameraActor controls a camera.
  65  *
  66  * Allows the developer to use actor semantics to control a camera.
  67  *
  68  * DALi has a concept of a camera to display its virtual 3D world to a 2D screen.
  69  * There are 2 ways of using the camera in DALi:
  70  *
  71  * - For 2D applications, you do not need to care about the camera at all. The default camera is already best suited for 2D applications
  72  *   (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).
  73  *   This is a typical way.
  74  *
  75  * - For 3D applications, you can change the view by manipulating the camera. If you config some camera properties,
  76  *   or create camera by @see New3DCamera(), you can translate or rotate the camera whatever you want.
  77  *   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.
  78  *
  79  * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default,
  80  * the camera actor will be FREE_LOOK.
  81  *
  82  * - A FREE_LOOK camera uses actor's orientation to control where the camera is looking.
  83  *   If no additional rotations are specified, the camera looks in the negative Z direction.
  84  *
  85  * - For LOOK_AT_TARGET, the actor's orientation is ignored, instead the camera looks at TARGET_POSITION
  86  *   in world coordinates.
  87  *
  88  * @SINCE_1_0.0
  89  */
  90 class DALI_CORE_API CameraActor : public Actor
  91 {
  92 public:
  93   /**
  94    * @brief Enumeration for the instance of properties belonging to the CameraActor class.
  95    *
  96    * Properties additional to Actor.
  97    * @SINCE_1_0.0
  98    */
  99   struct Property
 100   {
 101     /**
 102      * @brief Enumeration for the instance of properties belonging to the CameraActor class.
 103      *
 104      * Properties additional to Actor.
 105      * @SINCE_1_0.0
 106      */
 107     enum
 108     {
 109       TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type",                  type std::string @SINCE_1_0.0
 110       PROJECTION_MODE,                                   ///< name "projectionMode",        type std::string @SINCE_1_0.0
 111       FIELD_OF_VIEW,                                     ///< name "fieldOfView",           type float @SINCE_1_0.0
 112       ASPECT_RATIO,                                      ///< name "aspectRatio",           type float @SINCE_1_0.0
 113       NEAR_PLANE_DISTANCE,                               ///< name "nearPlaneDistance",     type float @SINCE_1_0.0
 114       FAR_PLANE_DISTANCE,                                ///< name "farPlaneDistance",      type float @SINCE_1_0.0
 115       LEFT_PLANE_DISTANCE,                               ///< name "leftPlaneDistance",     type float @SINCE_1_0.0
 116       RIGHT_PLANE_DISTANCE,                              ///< name "rightPlaneDistance",    type float @SINCE_1_0.0
 117       TOP_PLANE_DISTANCE,                                ///< name "topPlaneDistance",      type float @SINCE_1_0.0
 118       BOTTOM_PLANE_DISTANCE,                             ///< name "bottomPlaneDistance",   type float @SINCE_1_0.0
 119       TARGET_POSITION,                                   ///< name "targetPosition",        type Vector3 @SINCE_1_0.0
 120       PROJECTION_MATRIX,                                 ///< name "projectionMatrix",      type Matrix @SINCE_1_0.0
 121       VIEW_MATRIX,                                       ///< name "viewMatrix",            type Matrix @SINCE_1_0.0
 122       INVERT_Y_AXIS,                                     ///< name "invertYAxis",           type bool @SINCE_1_0.0
 123     };
 124   };
 125
 126   /**
 127    * @brief Creates an uninitialized CameraActor handle.
 128    *
 129    * Initialize it using CameraActor::New().
 130    * Calling member functions with an uninitialized CameraActor handle is not allowed.
 131    * @SINCE_1_0.0
 132    */
 133   CameraActor();
 134
 135   /**
 136    * @brief Creates a CameraActor object.
 137    *
 138    * @note Sets the default camera perspective projection for the size of the scene this is added to. @see SetPerspectiveProjection().
 139    * @note When this actor gets added to a scene, then it's Z position will be modified according to the required perspective projection.
 140    * After modified Z position, 1-world-unit become 1-pixel.
 141    *
 142    * @SINCE_1_0.0
 143    * @return The newly created camera actor
 144    */
 145   static CameraActor New();
 146
 147   /**
 148    * @brief Creates a CameraActor object.
 149    *
 150    * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
 151    *
 152    * @SINCE_1_0.0
 153    * @param[in] size The canvas size
 154    * @return The newly created camera actor
 155    */
 156   static CameraActor New(const Size& size);
 157
 158   /**
 159    * @brief Creates a CameraActor object initialize by 3D parameter.
 160    *
 161    * Intialize default perspective camera s.t. properties as good to be used on 3D app case.
 162    * Default camera positioned at +Z axis, and fit to see 1-world-unit sized cube on world origin.
 163    *
 164    * @SINCE_2_2.15
 165    * @return The newly created camera actor
 166    */
 167   static CameraActor New3DCamera();
 168
 169   /**
 170    * @brief Downcasts a handle to CameraActor handle.
 171    *
 172    * If handle points to a CameraActor, the downcast produces valid handle.
 173    * If not, the returned handle is left uninitialized.
 174    * @SINCE_1_0.0
 175    * @param[in] handle to An object
 176    * @return Handle to a CameraActor or an uninitialized handle
 177    */
 178   static CameraActor DownCast(BaseHandle handle);
 179
 180   /**
 181    * @brief Destructor.
 182    *
 183    * This is non-virtual, since derived Handle types must not contain data or virtual methods.
 184    * @SINCE_1_0.0
 185    */
 186   ~CameraActor();
 187
 188   /**
 189    * @brief Copy constructor.
 190    *
 191    * @SINCE_1_0.0
 192    * @param[in] copy The actor to copy
 193    */
 194   CameraActor(const CameraActor& copy);
 195
 196   /**
 197    * @brief Assignment operator.
 198    *
 199    * @SINCE_1_0.0
 200    * @param[in] rhs The actor to copy
 201    * @return A reference to this
 202    */
 203   CameraActor& operator=(const CameraActor& rhs);
 204
 205   /**
 206    * @brief Move constructor.
 207    *
 208    * @SINCE_2_2.4
 209    * @param[in] rhs A reference to the actor to move
 210    */
 211   CameraActor(CameraActor&& rhs) noexcept;
 212
 213   /**
 214    * @brief Move assignment operator.
 215    *
 216    * @SINCE_2_2.4
 217    * @param[in] rhs A reference to the actor to move
 218    * @return A reference to this
 219    */
 220   CameraActor& operator=(CameraActor&& rhs) noexcept;
 221
 222   /**
 223    * @brief Sets the camera type.
 224    * The default type is Dali::Camera::FREE_LOOK
 225    * @SINCE_1_0.0
 226    * @param[in] type The camera type
 227    */
 228   void SetType(Dali::Camera::Type type);
 229
 230   /**
 231    * @brief Gets the type of the camera.
 232    *
 233    * @SINCE_1_0.0
 234    * @return The type of camera
 235    */
 236   Dali::Camera::Type GetType() const;
 237
 238   /**
 239    * @brief Sets the projection mode.
 240    *
 241    * @SINCE_1_0.0
 242    * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
 243    */
 244   void SetProjectionMode(Dali::Camera::ProjectionMode mode);
 245
 246   /**
 247    * @brief Gets the projection mode.
 248    *
 249    * @SINCE_1_0.0
 250    * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
 251    */
 252   Dali::Camera::ProjectionMode GetProjectionMode() const;
 253
 254   /**
 255    * @brief Sets the field of view.
 256    * Field of view will be used when ProjectionMode is PERSPECTIVE_PROJECTION.
 257    *
 258    * @SINCE_1_0.0
 259    * @param[in] fieldOfView The field of view in radians
 260    */
 261   void SetFieldOfView(float fieldOfView);
 262
 263   /**
 264    * @brief Gets the field of view in Radians.
 265    *
 266    * The default field of view is 45 degrees.
 267    * @SINCE_1_0.0
 268    * @return The field of view in radians
 269    */
 270   float GetFieldOfView();
 271
 272   /**
 273    * @brief Sets the aspect ratio.
 274    *
 275    * @SINCE_1_0.0
 276    * @param[in] aspectRatio The aspect ratio
 277    */
 278   void SetAspectRatio(float aspectRatio);
 279
 280   /**
 281    * @brief Gets the aspect ratio of the camera.
 282    *
 283    * The default aspect ratio is 4.0f/3.0f.
 284    * @SINCE_1_0.0
 285    * @return The aspect ratio
 286    */
 287   float GetAspectRatio();
 288
 289   /**
 290    * @brief Sets the near clipping plane distance.
 291    *
 292    * @SINCE_1_0.0
 293    * @param[in] nearClippingPlane Distance of the near clipping plane
 294    */
 295   void SetNearClippingPlane(float nearClippingPlane);
 296
 297   /**
 298    * @brief Gets the near clipping plane distance.
 299    *
 300    * The default near clipping plane is 800.0f, to match the default screen height.
 301    * Reduce this value to see objects closer to the camera.
 302    * @SINCE_1_0.0
 303    * @return The near clipping plane value
 304    */
 305   float GetNearClippingPlane();
 306
 307   /**
 308    * @brief Sets the far clipping plane distance.
 309    *
 310    * @SINCE_1_0.0
 311    * @param[in] farClippingPlane Distance of the far clipping plane
 312    */
 313   void SetFarClippingPlane(float farClippingPlane);
 314
 315   /**
 316    * @brief Gets the far clipping plane distance.
 317    *
 318    * The default value is the default near clipping plane + (0xFFFF>>4).
 319    * @SINCE_1_0.0
 320    * @return The far clipping plane value
 321    */
 322   float GetFarClippingPlane();
 323
 324   /**
 325    * @brief Sets the target position of the camera.
 326    *
 327    * @SINCE_1_0.0
 328    * @param[in] targetPosition The position of the target to look at
 329    * @pre Camera type is LOOK_AT_TARGET.
 330    */
 331   void SetTargetPosition(const Vector3& targetPosition);
 332
 333   /**
 334    * @brief Gets the Camera Target position.
 335    *
 336    * The default target position is Vector3::ZERO.
 337    * @SINCE_1_0.0
 338    * @return The target position of the camera
 339    * @pre Camera type is LOOK_AT_TARGET.
 340    */
 341   Vector3 GetTargetPosition() const;
 342
 343   /**
 344    * @brief Requests for an inversion on the Y axis on the projection calculation.
 345    *
 346    * The default value is not inverted.
 347    * @SINCE_1_0.0
 348    * @param[in] invertYAxis True if the Y axis should be inverted
 349    */
 350   void SetInvertYAxis(bool invertYAxis);
 351
 352   /**
 353    * @brief Gets whether the Y axis is inverted.
 354    *
 355    * @SINCE_1_0.0
 356    * @return @c True if the Y axis is inverted, @c false otherwise
 357    */
 358   bool GetInvertYAxis();
 359
 360   /**
 361    * @brief Sets the default camera perspective projection for the given canvas size.
 362    *
 363    * Sets the near and far clipping planes, the field of view, the aspect ratio,
 364    * and the Z position of the actor based on the canvas size so that 1 unit in
 365    * XY (z=0) plane is 1 pixel on screen.
 366    * Also, It will set orthographic size be fitted as XY plane.
 367    *
 368    * @SINCE_1_0.0
 369    * @param[in] size The canvas size
 370    * @pre The canvas size must be greater than zero.
 371    * @note If either of the values of size is 0.0f, then we use the default perspective projection for the size of the scene this actor is added to.
 372    * @note This modifies the Z position property of this actor as well.
 373    */
 374   void SetPerspectiveProjection(const Size& size);
 375
 376   /**
 377    * @brief Sets the camera projection to use orthographic projection.
 378    *
 379    * The XY plane is centered on the camera axis. The units in the X/Y
 380    * plane directly equate to pixels on an equivalently sized
 381    * framebuffer.
 382    *
 383    * The Z position of the actor, and the near and far clip planes of the
 384    * bounding box match those that would be created by using
 385    * SetPerspectiveProjection with the same size.
 386    *
 387    * @SINCE_1_0.0
 388    * @param[in] size Size of XY plane (normal to camera axis)
 389    */
 390   void SetOrthographicProjection(const Size& size);
 391
 392 public: // Not intended for use by Application developers
 393   /// @cond internal
 394   /**
 395    * @brief This constructor is used by CameraActor::New() methods.
 396    *
 397    * @SINCE_1_0.0
 398    * @param[in] actor A pointer to a newly allocated Dali resource
 399    */
 400   explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);
 401   /// @endcond
 402 };
 403
 404 /**
 405  * @}
 406  */
 407 } // namespace Dali
 408
 409 #endif // DALI_CAMERA_ACTOR_H