X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Factors%2Fcamera-actor.h;h=8cf1cd26c1a2da254a659ad1a68092f0ff22e5e9;hb=d24adfe7051e62ca7956ffcfa4bdbdb16d1269e5;hp=b7dd645f95fd20c993abc991c35913bd665971fe;hpb=54dff6a35a504884c076a370b660ed9a0a6c6bdb;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 b7dd645..8cf1cd2 100644 --- a/dali/public-api/actors/camera-actor.h +++ b/dali/public-api/actors/camera-actor.h @@ -23,7 +23,7 @@ namespace Dali { /** - * @addtogroup dali-core-actors + * @addtogroup dali_core_actors * @{ */ @@ -32,30 +32,36 @@ namespace Internal DALI_INTERNAL class CameraActor; } +/** + * @brief Camera enumerations. + * @SINCE_1_0.0 + */ namespace Camera { /** * @brief Type determines 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. + * @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. * @@ -68,6 +74,7 @@ enum ProjectionMode * 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 { @@ -75,34 +82,37 @@ public: /** * @brief An enumeration of properties belonging to the CameraActor class. + * * Properties additional to Actor. + * @SINCE_1_0.0 */ struct Property { 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. * - * Initialise it using CameraActor::New(). Calling member functions - * with an uninitialized Dali::Object is not allowed. + * Initialise it using CameraActor::New(). + * Calling member functions with an uninitialized CameraActor handle is not allowed. + * @SINCE_1_0.0 */ CameraActor(); @@ -110,7 +120,8 @@ public: * @brief Create a CameraActor object. * * 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(); @@ -119,18 +130,20 @@ public: * * 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. + * @return The newly created camera actor. */ static CameraActor New( const Size& size ); /** - * @brief Downcast an Object handle to CameraActor. + * @brief Downcast a handle to CameraActor handle. * * 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 ); @@ -138,12 +151,14 @@ public: * @brief Destructor * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~CameraActor(); /** * @brief Copy constructor * + * @SINCE_1_0.0 * @param [in] copy The actor to copy. */ CameraActor(const CameraActor& copy); @@ -151,13 +166,16 @@ public: /** * @brief Assignment operator * + * @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. * The default type is Dali::Camera::FREE_LOOK + * @SINCE_1_0.0 * @param[in] type The camera type */ void SetType( Dali::Camera::Type type ); @@ -165,13 +183,15 @@ public: /** * @brief Get 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. * + * @SINCE_1_0.0 * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION */ void SetProjectionMode( Dali::Camera::ProjectionMode mode ); @@ -179,6 +199,7 @@ public: /** * @brief Get the projection mode. * + * @SINCE_1_0.0 * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION */ Dali::Camera::ProjectionMode GetProjectionMode() const; @@ -186,6 +207,7 @@ public: /** * @brief Set the field of view. * + * @SINCE_1_0.0 * @param[in] fieldOfView The field of view in radians */ void SetFieldOfView( float fieldOfView ); @@ -193,7 +215,8 @@ public: /** * @brief Get 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( ); @@ -201,6 +224,7 @@ public: /** * @brief Set the aspect ratio. * + * @SINCE_1_0.0 * @param[in] aspectRatio The aspect ratio */ void SetAspectRatio( float aspectRatio ); @@ -208,56 +232,63 @@ public: /** * @brief Get 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( ); /** * @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 ); /** * @brief Get 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( ); /** * @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 ); /** * @brief Get 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( ); /** * @brief Set 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 ); /** * @brief Get 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; @@ -265,6 +296,7 @@ public: * @brief Request 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); @@ -272,6 +304,7 @@ public: /** * @brief Get whether the Y axis is inverted. * + * @SINCE_1_0.0 * @return True if the Y axis is inverted, false otherwise */ bool GetInvertYAxis(); @@ -286,9 +319,10 @@ public: * If the canvas size is ZERO, it sets the default camera perspective * projection for the stage's size. * + * @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. */ void SetPerspectiveProjection( const Size& size ); @@ -303,6 +337,7 @@ 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 ); @@ -312,6 +347,7 @@ public: * * 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) @@ -323,8 +359,10 @@ public: public: // Not intended for use by Application developers /** - * @brief This constructor is used by Dali New() methods. + * @internal + * @brief This constructor is used by CameraActor::New() methods. * + * @SINCE_1_0.0 * @param [in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);