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