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