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