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

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