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