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

   1 #ifndef __DALI_CAMERA_ACTOR_H__
   2 #define __DALI_CAMERA_ACTOR_H__
   3
   4 /*
   5  * Copyright (c) 2015 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  * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default,
  69  * the camera actor will be FREE_LOOK.
  70  *
  71  * A FREE_LOOK camera uses actor's orientation to control where the camera is looking.
  72  * If no additional rotations are specified, the camera looks in the negative Z direction.
  73  *
  74  * For LOOK_AT_TARGET, the actor's orientation is ignored, instead the camera looks at TARGET_POSITION
  75  * in world coordinates.
  76  *
  77  * @SINCE_1_0.0
  78  */
  79 class DALI_IMPORT_API CameraActor : public Actor
  80 {
  81 public:
  82
  83   /**
  84    * @brief Enumeration for the instance of properties belonging to the CameraActor class.
  85    *
  86    * Properties additional to Actor.
  87    * @SINCE_1_0.0
  88    */
  89   struct Property
  90   {
  91     /**
  92      * @brief Enumeration for the instance of properties belonging to the CameraActor class.
  93      *
  94      * Properties additional to Actor.
  95      * @SINCE_1_0.0
  96      */
  97     enum
  98     {
  99       TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type",                  type std::string @SINCE_1_0.0
 100       PROJECTION_MODE,                                   ///< name "projectionMode",        type std::string @SINCE_1_0.0
 101       FIELD_OF_VIEW,                                     ///< name "fieldOfView",           type float @SINCE_1_0.0
 102       ASPECT_RATIO,                                      ///< name "aspectRatio",           type float @SINCE_1_0.0
 103       NEAR_PLANE_DISTANCE,                               ///< name "nearPlaneDistance",     type float @SINCE_1_0.0
 104       FAR_PLANE_DISTANCE,                                ///< name "farPlaneDistance",      type float @SINCE_1_0.0
 105       LEFT_PLANE_DISTANCE,                               ///< name "leftPlaneDistance",     type float @SINCE_1_0.0
 106       RIGHT_PLANE_DISTANCE,                              ///< name "rightPlaneDistance",    type float @SINCE_1_0.0
 107       TOP_PLANE_DISTANCE,                                ///< name "topPlaneDistance",      type float @SINCE_1_0.0
 108       BOTTOM_PLANE_DISTANCE,                             ///< name "bottomPlaneDistance",   type float @SINCE_1_0.0
 109       TARGET_POSITION,                                   ///< name "targetPosition",        type Vector3 @SINCE_1_0.0
 110       PROJECTION_MATRIX,                                 ///< name "projectionMatrix",      type Matrix @SINCE_1_0.0
 111       VIEW_MATRIX,                                       ///< name "viewMatrix",            type Matrix @SINCE_1_0.0
 112       INVERT_Y_AXIS,                                     ///< name "invertYAxis",           type bool @SINCE_1_0.0
 113     };
 114   };
 115
 116   /**
 117    * @brief Creates an uninitialized CameraActor handle.
 118    *
 119    * Initialize it using CameraActor::New().
 120    * Calling member functions with an uninitialized CameraActor handle is not allowed.
 121    * @SINCE_1_0.0
 122    */
 123   CameraActor();
 124
 125   /**
 126    * @brief Creates a CameraActor object.
 127    *
 128    * Sets the default camera perspective projection for the stage's size. @see SetPerspectiveProjection().
 129    * @SINCE_1_0.0
 130    * @return The newly created camera actor
 131    */
 132   static CameraActor New();
 133
 134   /**
 135    * @brief Creates a CameraActor object.
 136    *
 137    * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
 138    *
 139    * @SINCE_1_0.0
 140    * @param[in] size The canvas size
 141    * @return The newly created camera actor
 142    */
 143   static CameraActor New( const Size& size );
 144
 145   /**
 146    * @brief Downcasts a handle to CameraActor handle.
 147    *
 148    * If handle points to a CameraActor, the downcast produces valid handle.
 149    * If not, the returned handle is left uninitialized.
 150    * @SINCE_1_0.0
 151    * @param[in] handle to An object
 152    * @return Handle to a CameraActor or an uninitialized handle
 153    */
 154   static CameraActor DownCast( BaseHandle handle );
 155
 156   /**
 157    * @brief Destructor.
 158    *
 159    * This is non-virtual, since derived Handle types must not contain data or virtual methods.
 160    * @SINCE_1_0.0
 161    */
 162   ~CameraActor();
 163
 164   /**
 165    * @brief Copy constructor.
 166    *
 167    * @SINCE_1_0.0
 168    * @param[in] copy The actor to copy
 169    */
 170   CameraActor(const CameraActor& copy);
 171
 172   /**
 173    * @brief Assignment operator.
 174    *
 175    * @SINCE_1_0.0
 176    * @param[in] rhs The actor to copy
 177    * @return A reference to this
 178    */
 179   CameraActor& operator=(const CameraActor& rhs);
 180
 181   /**
 182    * @brief Sets the camera type.
 183    * The default type is Dali::Camera::FREE_LOOK
 184    * @SINCE_1_0.0
 185    * @param[in] type The camera type
 186    */
 187   void SetType( Dali::Camera::Type type );
 188
 189   /**
 190    * @brief Gets the type of the camera.
 191    *
 192    * @SINCE_1_0.0
 193    * @return The type of camera
 194    */
 195   Dali::Camera::Type GetType() const;
 196
 197   /**
 198    * @brief Sets the projection mode.
 199    *
 200    * @SINCE_1_0.0
 201    * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
 202    */
 203   void SetProjectionMode( Dali::Camera::ProjectionMode mode );
 204
 205   /**
 206    * @brief Gets the projection mode.
 207    *
 208    * @SINCE_1_0.0
 209    * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
 210    */
 211   Dali::Camera::ProjectionMode GetProjectionMode() const;
 212
 213   /**
 214    * @brief Sets the field of view.
 215    *
 216    * @SINCE_1_0.0
 217    * @param[in] fieldOfView The field of view in radians
 218    */
 219   void SetFieldOfView( float fieldOfView );
 220
 221   /**
 222    * @brief Gets the field of view in Radians.
 223    *
 224    * The default field of view is 45 degrees.
 225    * @SINCE_1_0.0
 226    * @return The field of view in radians
 227    */
 228   float GetFieldOfView( );
 229
 230   /**
 231    * @brief Sets the aspect ratio.
 232    *
 233    * @SINCE_1_0.0
 234    * @param[in] aspectRatio The aspect ratio
 235    */
 236   void SetAspectRatio( float aspectRatio );
 237
 238   /**
 239    * @brief Gets the aspect ratio of the camera.
 240    *
 241    * The default aspect ratio is 4.0f/3.0f.
 242    * @SINCE_1_0.0
 243    * @return The aspect ratio
 244    */
 245   float GetAspectRatio( );
 246
 247   /**
 248    * @brief Sets the near clipping plane distance.
 249    *
 250    * @SINCE_1_0.0
 251    * @param[in] nearClippingPlane Distance of the near clipping plane
 252    */
 253   void SetNearClippingPlane( float nearClippingPlane );
 254
 255   /**
 256    * @brief Gets the near clipping plane distance.
 257    *
 258    * The default near clipping plane is 800.0f, to match the default screen height.
 259    * Reduce this value to see objects closer to the camera.
 260    * @SINCE_1_0.0
 261    * @return The near clipping plane value
 262    */
 263   float GetNearClippingPlane( );
 264
 265   /**
 266    * @brief Sets the far clipping plane distance.
 267    *
 268    * @SINCE_1_0.0
 269    * @param[in] farClippingPlane Distance of the far clipping plane
 270    */
 271   void SetFarClippingPlane( float farClippingPlane );
 272
 273   /**
 274    * @brief Gets the far clipping plane distance.
 275    *
 276    * The default value is the default near clipping plane + (0xFFFF>>4).
 277    * @SINCE_1_0.0
 278    * @return The far clipping plane value
 279    */
 280   float GetFarClippingPlane( );
 281
 282   /**
 283    * @brief Sets the target position of the camera.
 284    *
 285    * @SINCE_1_0.0
 286    * @param[in] targetPosition The position of the target to look at
 287    * @pre Camera type is LOOK_AT_TARGET.
 288    */
 289   void SetTargetPosition( const Vector3& targetPosition );
 290
 291   /**
 292    * @brief Gets the Camera Target position.
 293    *
 294    * The default target position is Vector3::ZERO.
 295    * @SINCE_1_0.0
 296    * @return The target position of the camera
 297    * @pre Camera type is LOOK_AT_TARGET.
 298    */
 299   Vector3 GetTargetPosition() const;
 300
 301   /**
 302    * @brief Requests for an inversion on the Y axis on the projection calculation.
 303    *
 304    * The default value is not inverted.
 305    * @SINCE_1_0.0
 306    * @param[in] invertYAxis True if the Y axis should be inverted
 307    */
 308   void SetInvertYAxis(bool invertYAxis);
 309
 310   /**
 311    * @brief Gets whether the Y axis is inverted.
 312    *
 313    * @SINCE_1_0.0
 314    * @return @c True if the Y axis is inverted, @c false otherwise
 315    */
 316   bool GetInvertYAxis();
 317
 318   /**
 319    * @brief Sets the default camera perspective projection for the given canvas size.
 320    *
 321    * Sets the near and far clipping planes, the field of view, the aspect ratio,
 322    * and the Z position of the actor based on the canvas size so that 1 unit in
 323    * XY (z=0) plane is 1 pixel on screen.
 324    *
 325    * If the canvas size is ZERO, it sets the default camera perspective
 326    * projection for the stage's size.
 327    *
 328    * @SINCE_1_0.0
 329    * @param[in] size The canvas size
 330    * @pre If size is non ZERO, \e width and \e height must be greater than zero.
 331    *
 332    */
 333   void SetPerspectiveProjection( const Size& size );
 334
 335   /**
 336    * @brief Sets the camera projection to use orthographic projection.
 337    *
 338    * The XY plane is centered on the camera axis. The units in the X/Y
 339    * plane directly equate to pixels on an equivalently sized
 340    * framebuffer.
 341    *
 342    * The Z position of the actor, and the near and far clip planes of the
 343    * bounding box match those that would be created by using
 344    * SetPerspectiveProjection with the same size.
 345    *
 346    * @SINCE_1_0.0
 347    * @param[in] size Size of XY plane (normal to camera axis)
 348    */
 349   void SetOrthographicProjection( const Size& size );
 350
 351   /**
 352    * @brief Sets the camera projection to use orthographic projection with the given clip planes.
 353    *
 354    * This does not change the Z value of the camera actor.
 355    *
 356    * @SINCE_1_0.0
 357    * @param[in] left Distance to left clip plane (normal to camera axis)
 358    * @param[in] right Distance to right clip plane (normal to camera axis)
 359    * @param[in] top Distance to top clip plane (normal to camera axis)
 360    * @param[in] bottom Distance to bottom clip plane (normal to camera axis)
 361    * @param[in] near Distance to the near clip plane (along camera axis)
 362    * @param[in] far Distance to the far clip plane (along camera axis)
 363    */
 364   void SetOrthographicProjection( float left, float right, float top, float bottom, float near, float far );
 365
 366 public: // Not intended for use by Application developers
 367   /**
 368    * @internal
 369    * @brief This constructor is used by CameraActor::New() methods.
 370    *
 371    * @SINCE_1_0.0
 372    * @param[in] actor A pointer to a newly allocated Dali resource
 373    */
 374   explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);
 375 };
 376
 377 /**
 378  * @}
 379  */
 380 } // namespace Dali
 381
 382 #endif // __DALI_CAMERA_ACTOR_H__