X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Factors%2Fcamera-actor.h;h=00337f220c886f39f9735f639957f620c8a07c34;hb=9c6cd5cbe26eb355f2f0daeaae85a28a8d81a3b3;hp=8b1d6e2033d55eafe107c3a58be0a3b7fbcf926f;hpb=2054d4988006f0a2285f068e25f1b27cf6afbf4a;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 8b1d6e2..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. @@ -33,13 +33,13 @@ class CameraActor; } /** - * @brief Camera enumerations. + * @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 @@ -49,13 +49,13 @@ enum Type }; /** - * @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 @SINCE_1_0.0 - ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects @SINCE_1_0.0 + 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 @@ -65,39 +65,45 @@ enum ProjectionMode * * Allows the developer to use actor semantics to control a camera. * - * DALi has a concept of a camera to display its virtual 3D world to a 2D screen. + * 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. You can translate or rotate the camera in this case. + * - 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 + * 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. * - * - For LOOK_AT_TARGET the actor's orientation is ignored, instead the camera looks at TARGET_POSITION + * - 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 @SINCE_1_0.0 @@ -118,80 +124,111 @@ public: }; /** - * @brief Create an uninitialized CameraActor handle. + * @brief Creates an uninitialized CameraActor handle. * - * Initialise it using CameraActor::New(). + * 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(). * @SINCE_1_0.0 - * @return The newly created camera actor. + * @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(). * * @SINCE_1_0.0 - * @param[in] size The canvas size. - * @return The newly created camera actor. + * @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 a handle to CameraActor handle. + * @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 */ - 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. * * @SINCE_1_0.0 - * @param [in] copy The actor to copy. + * @param[in] copy The actor to copy */ CameraActor(const CameraActor& copy); /** - * @brief Assignment operator + * @brief Assignment operator. * * @SINCE_1_0.0 - * @param [in] rhs The actor to copy. + * @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. * * @SINCE_1_0.0 * @return The type of camera @@ -199,15 +236,15 @@ public: 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 @@ -215,38 +252,39 @@ public: 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. * @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. * @SINCE_1_0.0 * @return The aspect ratio */ - float GetAspectRatio( ); + float GetAspectRatio(); /** * @brief Sets the near clipping plane distance. @@ -254,17 +292,17 @@ public: * @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. * @SINCE_1_0.0 * @return The near clipping plane value */ - float GetNearClippingPlane( ); + float GetNearClippingPlane(); /** * @brief Sets the far clipping plane distance. @@ -272,28 +310,28 @@ public: * @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). * @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. * * @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 default target position is Vector3::ZERO. * @SINCE_1_0.0 @@ -303,7 +341,7 @@ public: 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 @@ -312,29 +350,28 @@ public: void SetInvertYAxis(bool invertYAxis); /** - * @brief Get whether the Y axis is inverted. + * @brief Gets whether the Y axis is inverted. * * @SINCE_1_0.0 - * @return True if the Y axis is inverted, false otherwise + * @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. - * - * If the canvas size is ZERO, it sets the default camera perspective - * projection for the stage's size. + * Also, It will set orthographic size be fitted as XY plane. * * @SINCE_1_0.0 - * @param[in] size The canvas size. - * @pre If size is non ZERO, \e width and \e height must be greater than zero. - * + * @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. @@ -350,22 +387,7 @@ public: * @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. - * - * @SINCE_1_0.0 - * @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 @@ -373,7 +395,7 @@ public: // Not intended for use by Application developers * @brief This constructor is used by CameraActor::New() methods. * * @SINCE_1_0.0 - * @param [in] actor A pointer to a newly allocated Dali resource + * @param[in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor); /// @endcond @@ -384,4 +406,4 @@ public: // Not intended for use by Application developers */ } // namespace Dali -#endif // __DALI_CAMERA_ACTOR_H__ +#endif // DALI_CAMERA_ACTOR_H