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