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