X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Factors%2Fcamera-actor.h;h=00337f220c886f39f9735f639957f620c8a07c34;hb=9c6cd5cbe26eb355f2f0daeaae85a28a8d81a3b3;hp=618b0fcdf8f2ea2adb601a294b4478f5f9ae49aa;hpb=199d46a42f943543a9d43cc3166a0d8b7cf63fd4;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/actors/camera-actor.h b/dali/public-api/actors/camera-actor.h index 618b0fc..00337f2 100644 --- a/dali/public-api/actors/camera-actor.h +++ b/dali/public-api/actors/camera-actor.h @@ -1,8 +1,8 @@ -#ifndef __DALI_CAMERA_ACTOR_H__ -#define __DALI_CAMERA_ACTOR_H__ +#ifndef DALI_CAMERA_ACTOR_H +#define DALI_CAMERA_ACTOR_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2023 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,272 +22,356 @@ namespace Dali { +/** + * @addtogroup dali_core_actors + * @{ + */ namespace Internal DALI_INTERNAL { class CameraActor; } - +/** + * @brief Enumeration for camera. + * @SINCE_1_0.0 + */ namespace Camera { /** - * @brief Type determines how camera operates. + * @brief Enumeration for type determination of how camera operates. + * @SINCE_1_0.0 */ enum Type { - FREE_LOOK, ///< Camera orientation is taken from CameraActor - LOOK_AT_TARGET, ///< Camera is oriented to always look at a target + FREE_LOOK, ///< Camera orientation is taken from CameraActor @SINCE_1_0.0 + LOOK_AT_TARGET, ///< Camera is oriented to always look at a target @SINCE_1_0.0 }; /** - * @brief Projection modes. + * @brief Enumeration for projection modes. + * @SINCE_1_0.0 */ enum ProjectionMode { - PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller - ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects + PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller @SINCE_1_0.0 + ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects @SINCE_1_0.0 }; } // namespace Camera /** - * @brief Controls a camera. + * @brief CameraActor controls a camera. * * Allows the developer to use actor semantics to control a camera. * - * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default + * DALi has a concept of a camera to display its virtual 3D world to a 2D screen. + * There are 2 ways of using the camera in DALi: + * + * - For 2D applications, you do not need to care about the camera at all. The default camera is already best suited for 2D applications + * (configured to have the origin of the coordinate system at the top-left corner of the screen, and unit 1 as 1 pixel of the screen). + * This is a typical way. + * + * - For 3D applications, you can change the view by manipulating the camera. If you config some camera properties, + * or create camera by @see New3DCamera(), you can translate or rotate the camera whatever you want. + * Note that the top-left corner of the screen and unit 1 no longer are (0,0,0) and 1 pixel after manipulating the camera. + * + * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default, * the camera actor will be FREE_LOOK. * - * A FREE_LOOK camera uses actor's orientation to control where the camera is looking. - * If no additional rotations are specified, the camera looks in the negative Z direction. + * - A FREE_LOOK camera uses actor's orientation to control where the camera is looking. + * If no additional rotations are specified, the camera looks in the negative Z direction. * - * For LOOK_AT_TARGET the actor's orientation is ignored, instead the camera looks at TARGET_POSITION - * in world coordinates. + * - For LOOK_AT_TARGET, the actor's orientation is ignored, instead the camera looks at TARGET_POSITION + * in world coordinates. * + * @SINCE_1_0.0 */ -class DALI_IMPORT_API CameraActor : public Actor +class DALI_CORE_API CameraActor : public Actor { public: - /** - * @brief An enumeration of properties belonging to the CameraActor class. + * @brief Enumeration for the instance of properties belonging to the CameraActor class. + * * Properties additional to Actor. + * @SINCE_1_0.0 */ struct Property { + /** + * @brief Enumeration for the instance of properties belonging to the CameraActor class. + * + * Properties additional to Actor. + * @SINCE_1_0.0 + */ enum { - TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type std::string - PROJECTION_MODE, ///< name "projection-mode", type std::string - FIELD_OF_VIEW, ///< name "field-of-view", type float - ASPECT_RATIO, ///< name "aspect-ratio", type float - NEAR_PLANE_DISTANCE, ///< name "near-plane-distance", type float - FAR_PLANE_DISTANCE, ///< name "far-plane-distance", type float - LEFT_PLANE_DISTANCE, ///< name "left-plane-distance", type float - RIGHT_PLANE_DISTANCE, ///< name "right-plane-distance", type float - TOP_PLANE_DISTANCE, ///< name "top-plane-distance", type float - BOTTOM_PLANE_DISTANCE, ///< name "bottom-plane-distance", type float - TARGET_POSITION, ///< name "target-position", type Vector3 - PROJECTION_MATRIX, ///< name "projection-matrix", type Matrix - VIEW_MATRIX, ///< name "view-matrix", type Matrix - INVERT_Y_AXIS, ///< name "invert-y-axis", type bool + TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type std::string @SINCE_1_0.0 + PROJECTION_MODE, ///< name "projectionMode", type std::string @SINCE_1_0.0 + FIELD_OF_VIEW, ///< name "fieldOfView", type float @SINCE_1_0.0 + ASPECT_RATIO, ///< name "aspectRatio", type float @SINCE_1_0.0 + NEAR_PLANE_DISTANCE, ///< name "nearPlaneDistance", type float @SINCE_1_0.0 + FAR_PLANE_DISTANCE, ///< name "farPlaneDistance", type float @SINCE_1_0.0 + LEFT_PLANE_DISTANCE, ///< name "leftPlaneDistance", type float @SINCE_1_0.0 + RIGHT_PLANE_DISTANCE, ///< name "rightPlaneDistance", type float @SINCE_1_0.0 + TOP_PLANE_DISTANCE, ///< name "topPlaneDistance", type float @SINCE_1_0.0 + BOTTOM_PLANE_DISTANCE, ///< name "bottomPlaneDistance", type float @SINCE_1_0.0 + TARGET_POSITION, ///< name "targetPosition", type Vector3 @SINCE_1_0.0 + PROJECTION_MATRIX, ///< name "projectionMatrix", type Matrix @SINCE_1_0.0 + VIEW_MATRIX, ///< name "viewMatrix", type Matrix @SINCE_1_0.0 + INVERT_Y_AXIS, ///< name "invertYAxis", type bool @SINCE_1_0.0 }; }; /** - * @brief Create an uninitialized CameraActor handle. + * @brief Creates an uninitialized CameraActor handle. * - * Initialise it using CameraActor::New(). Calling member functions - * with an uninitialized Dali::Object is not allowed. + * Initialize it using CameraActor::New(). + * Calling member functions with an uninitialized CameraActor handle is not allowed. + * @SINCE_1_0.0 */ CameraActor(); /** - * @brief Create a CameraActor object. + * @brief Creates a CameraActor object. + * + * @note Sets the default camera perspective projection for the size of the scene this is added to. @see SetPerspectiveProjection(). + * @note When this actor gets added to a scene, then it's Z position will be modified according to the required perspective projection. + * After modified Z position, 1-world-unit become 1-pixel. * - * Sets the default camera perspective projection for the stage's size. @see SetPerspectiveProjection(). - * @return the newly created camera actor. + * @SINCE_1_0.0 + * @return The newly created camera actor */ static CameraActor New(); /** - * @brief Create a CameraActor object. + * @brief Creates a CameraActor object. * * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection(). * - * @param[in] size The canvas size. - * @return the newly created camera actor. + * @SINCE_1_0.0 + * @param[in] size The canvas size + * @return The newly created camera actor + */ + static CameraActor New(const Size& size); + + /** + * @brief Creates a CameraActor object initialize by 3D parameter. + * + * Intialize default perspective camera s.t. properties as good to be used on 3D app case. + * Default camera positioned at +Z axis, and fit to see 1-world-unit sized cube on world origin. + * + * @SINCE_2_2.15 + * @return The newly created camera actor */ - static CameraActor New( const Size& size ); + static CameraActor New3DCamera(); /** - * @brief Downcast an Object handle to CameraActor. + * @brief Downcasts a handle to CameraActor handle. * - * If handle points to a CameraActor the downcast produces valid - * handle. If not the returned handle is left uninitialized. + * If handle points to a CameraActor, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 * @param[in] handle to An object - * @return handle to a CameraActor or an uninitialized handle + * @return Handle to a CameraActor or an uninitialized handle */ - static CameraActor DownCast( BaseHandle handle ); + static CameraActor DownCast(BaseHandle handle); /** - * @brief Destructor + * @brief Destructor. * - * This is non-virtual since derived Handle types must not contain data or virtual methods. + * This is non-virtual, since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~CameraActor(); /** - * @brief Copy constructor + * @brief Copy constructor. * - * @param [in] copy The actor to copy. + * @SINCE_1_0.0 + * @param[in] copy The actor to copy */ CameraActor(const CameraActor& copy); /** - * @brief Assignment operator + * @brief Assignment operator. * - * @param [in] rhs The actor to copy. + * @SINCE_1_0.0 + * @param[in] rhs The actor to copy + * @return A reference to this */ CameraActor& operator=(const CameraActor& rhs); /** - * @brief Set the camera type. + * @brief Move constructor. + * + * @SINCE_2_2.4 + * @param[in] rhs A reference to the actor to move + */ + CameraActor(CameraActor&& rhs); + + /** + * @brief Move assignment operator. + * + * @SINCE_2_2.4 + * @param[in] rhs A reference to the actor to move + * @return A reference to this + */ + CameraActor& operator=(CameraActor&& rhs); + + /** + * @brief Sets the camera type. * The default type is Dali::Camera::FREE_LOOK + * @SINCE_1_0.0 * @param[in] type The camera type */ - void SetType( Dali::Camera::Type type ); + void SetType(Dali::Camera::Type type); /** - * @brief Get the type of the camera. + * @brief Gets the type of the camera. * - * @return the type of camera + * @SINCE_1_0.0 + * @return The type of camera */ Dali::Camera::Type GetType() const; /** - * @brief Set the projection mode. + * @brief Sets the projection mode. * + * @SINCE_1_0.0 * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION */ - void SetProjectionMode( Dali::Camera::ProjectionMode mode ); + void SetProjectionMode(Dali::Camera::ProjectionMode mode); /** - * @brief Get the projection mode. + * @brief Gets the projection mode. * + * @SINCE_1_0.0 * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION */ Dali::Camera::ProjectionMode GetProjectionMode() const; /** - * @brief Set the field of view. + * @brief Sets the field of view. + * Field of view will be used when ProjectionMode is PERSPECTIVE_PROJECTION. * + * @SINCE_1_0.0 * @param[in] fieldOfView The field of view in radians */ - void SetFieldOfView( float fieldOfView ); + void SetFieldOfView(float fieldOfView); /** - * @brief Get the field of view in Radians. + * @brief Gets the field of view in Radians. * - * The default field of view is 45 degrees + * The default field of view is 45 degrees. + * @SINCE_1_0.0 * @return The field of view in radians */ - float GetFieldOfView( ); + float GetFieldOfView(); /** - * @brief Set the aspect ratio. + * @brief Sets the aspect ratio. * + * @SINCE_1_0.0 * @param[in] aspectRatio The aspect ratio */ - void SetAspectRatio( float aspectRatio ); + void SetAspectRatio(float aspectRatio); /** - * @brief Get the aspect ratio of the camera. + * @brief Gets the aspect ratio of the camera. * - * The default aspect ratio is 4.0f/3.0f - * @return the aspect ratio + * The default aspect ratio is 4.0f/3.0f. + * @SINCE_1_0.0 + * @return The aspect ratio */ - float GetAspectRatio( ); + float GetAspectRatio(); /** * @brief Sets the near clipping plane distance. * - * @param[in] nearClippingPlane distance of the near clipping plane + * @SINCE_1_0.0 + * @param[in] nearClippingPlane Distance of the near clipping plane */ - void SetNearClippingPlane( float nearClippingPlane ); + void SetNearClippingPlane(float nearClippingPlane); /** - * @brief Get the near clipping plane distance. + * @brief Gets the near clipping plane distance. * - * The default near clipping plane is 800.0f, to match the default screen height - * Reduce this value to see objects closer to the camera - * @return the near clipping plane value + * The default near clipping plane is 800.0f, to match the default screen height. + * Reduce this value to see objects closer to the camera. + * @SINCE_1_0.0 + * @return The near clipping plane value */ - float GetNearClippingPlane( ); + float GetNearClippingPlane(); /** * @brief Sets the far clipping plane distance. * - * @param[in] farClippingPlane distance of the far clipping plane + * @SINCE_1_0.0 + * @param[in] farClippingPlane Distance of the far clipping plane */ - void SetFarClippingPlane( float farClippingPlane ); + void SetFarClippingPlane(float farClippingPlane); /** - * @brief Get the far clipping plane distance. + * @brief Gets the far clipping plane distance. * - * The default value is the default near clipping plane + (0xFFFF>>4) - * @return the far clipping plane value + * The default value is the default near clipping plane + (0xFFFF>>4). + * @SINCE_1_0.0 + * @return The far clipping plane value */ - float GetFarClippingPlane( ); + float GetFarClippingPlane(); /** - * @brief Set the target position of the camera. + * @brief Sets the target position of the camera. * - * @pre Camera type is LOOK_AT_TARGET + * @SINCE_1_0.0 * @param[in] targetPosition The position of the target to look at + * @pre Camera type is LOOK_AT_TARGET. */ - void SetTargetPosition( const Vector3& targetPosition ); + void SetTargetPosition(const Vector3& targetPosition); /** - * @brief Get Camera Target position. + * @brief Gets the Camera Target position. * - * The target position is Vector3::ZERO - * @pre Camera type is LOOK_AT_TARGET + * The default target position is Vector3::ZERO. + * @SINCE_1_0.0 * @return The target position of the camera + * @pre Camera type is LOOK_AT_TARGET. */ Vector3 GetTargetPosition() const; /** - * @brief Request for an inversion on the Y axis on the projection calculation. + * @brief Requests for an inversion on the Y axis on the projection calculation. * * The default value is not inverted. + * @SINCE_1_0.0 * @param[in] invertYAxis True if the Y axis should be inverted */ void SetInvertYAxis(bool invertYAxis); /** - * @brief Get whether the Y axis is inverted. + * @brief Gets whether the Y axis is inverted. * - * @return True if the Y axis is inverted, false otherwise + * @SINCE_1_0.0 + * @return @c True if the Y axis is inverted, @c false otherwise */ bool GetInvertYAxis(); /** * @brief Sets the default camera perspective projection for the given canvas size. * - * Sets the near and far clipping planes, the field of view, the aspect ratio + * Sets the near and far clipping planes, the field of view, the aspect ratio, * and the Z position of the actor based on the canvas size so that 1 unit in * XY (z=0) plane is 1 pixel on screen. + * Also, It will set orthographic size be fitted as XY plane. * - * If the canvas size is ZERO, it sets the default camera perspective - * projection for the stage's size. - * - * @pre If size is non ZERO, \e width and \e height must be greater than zero. - * - * @param[in] size The canvas size. + * @SINCE_1_0.0 + * @param[in] size The canvas size + * @pre The canvas size must be greater than zero. + * @note If either of the values of size is 0.0f, then we use the default perspective projection for the size of the scene this actor is added to. + * @note This modifies the Z position property of this actor as well. */ - void SetPerspectiveProjection( const Size& size ); + void SetPerspectiveProjection(const Size& size); /** * @brief Sets the camera projection to use orthographic projection. @@ -300,33 +384,26 @@ public: * bounding box match those that would be created by using * SetPerspectiveProjection with the same size. * + * @SINCE_1_0.0 * @param[in] size Size of XY plane (normal to camera axis) */ - void SetOrthographicProjection( const Size& size ); - - /** - * @brief Sets the camera projection to use orthographic projection with the given clip planes. - * - * This does not change the Z value of the camera actor. - * - * @param[in] left Distance to left clip plane (normal to camera axis) - * @param[in] right Distance to right clip plane (normal to camera axis) - * @param[in] top Distance to top clip plane (normal to camera axis) - * @param[in] bottom Distance to bottom clip plane (normal to camera axis) - * @param[in] near Distance to the near clip plane (along camera axis) - * @param[in] far Distance to the far clip plane (along camera axis) - */ - void SetOrthographicProjection( float left, float right, float top, float bottom, float near, float far ); + void SetOrthographicProjection(const Size& size); public: // Not intended for use by Application developers + /// @cond internal /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by CameraActor::New() methods. * - * @param [in] actor A pointer to a newly allocated Dali resource + * @SINCE_1_0.0 + * @param[in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor); + /// @endcond }; +/** + * @} + */ } // namespace Dali -#endif // __DALI_CAMERA_ACTOR_H__ +#endif // DALI_CAMERA_ACTOR_H