X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Frender-tasks%2Frender-task.h;h=68f241c2d1d8effe719058e217232d6dfc24db4c;hb=refs%2Fchanges%2F16%2F83116%2F1;hp=9094f5a3996181c9f1e7e3acea67d967cccdb15d;hpb=8096da59d2ec742f85ed05d4b8d6bc6164552874;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/render-tasks/render-task.h b/dali/public-api/render-tasks/render-task.h index 9094f5a..68f241c 100644 --- a/dali/public-api/render-tasks/render-task.h +++ b/dali/public-api/render-tasks/render-task.h @@ -27,13 +27,14 @@ namespace Dali { /** - * @addtogroup dali-core-render-tasks + * @addtogroup dali_core_rendering_effects * @{ */ class Actor; class CameraActor; class FrameBufferImage; +class FrameBuffer; struct Vector4; namespace Internal DALI_INTERNAL @@ -78,6 +79,7 @@ class RenderTask; * | %Signal Name | Method | * |--------------|-----------------------| * | finished | @ref FinishedSignal() | + * @SINCE_1_0.0 */ class DALI_IMPORT_API RenderTask : public Handle { @@ -85,24 +87,48 @@ public: /** * @brief An enumeration of properties belonging to the RenderTask class. + * @SINCE_1_0.0 */ struct Property { enum { - VIEWPORT_POSITION = DEFAULT_OBJECT_PROPERTY_START_INDEX, ///< name "viewport-position", type Vector2 - VIEWPORT_SIZE, ///< name "viewport-size", type Vector2 - CLEAR_COLOR, ///< name "clear-color", type Vector4 + /** + * @brief name "viewportPosition", type Vector2 + * @SINCE_1_0.0 + */ + VIEWPORT_POSITION = DEFAULT_OBJECT_PROPERTY_START_INDEX, + /** + * @brief name "viewportSize", type Vector2 + * @SINCE_1_0.0 + */ + VIEWPORT_SIZE, + /** + * @brief name "clearColor", type Vector4 + * @SINCE_1_0.0 + */ + CLEAR_COLOR, + /** + * @brief name "requiresSync", type BOOLEAN + * @details By default, the sync object is not created. + * When native image source is used as render target, in order to track when the render to pixmap is completed, the GL sync should be enabled. + * Thus the RENDER_ONCE finished signal can be emit at the correct timing. + * @note The use of GL sync might cause deadlock with multiple access to the single pixmap happening in the same time. + * @SINCE_1_1.29 + */ + REQUIRES_SYNC, }; }; /** * @brief Typedef for signals sent by this class. + * @SINCE_1_0.0 */ typedef Signal< void (RenderTask& source) > RenderTaskSignalType; /** * @brief A pointer to a function for converting screen to frame-buffer coordinates. + * @SINCE_1_0.0 * @param[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen. * @return True if the conversion was successful, otherwise coordinates should be unmodified. */ @@ -110,6 +136,7 @@ public: /** * @brief A pointer to a function for converting screen to frame-buffer coordinates. + * @SINCE_1_0.0 * @param[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen. * @return True if the conversion was successful, otherwise coordinates should be unmodified. */ @@ -132,11 +159,12 @@ public: /** * @brief The refresh-rate of the RenderTask. + * @SINCE_1_0.0 */ enum RefreshRate { - REFRESH_ONCE = 0, ///< Process once only e.g. take a snap-shot of the scene. - REFRESH_ALWAYS = 1 ///< Process every frame. + REFRESH_ONCE = 0, ///< Process once only e.g. take a snap-shot of the scene. @SINCE_1_0.0 + REFRESH_ALWAYS = 1 ///< Process every frame. @SINCE_1_0.0 }; static const bool DEFAULT_EXCLUSIVE; ///< false @@ -150,6 +178,7 @@ public: * @brief Create an empty RenderTask handle. * * This can be initialised with RenderTaskList::CreateRenderTask(). + * @SINCE_1_0.0 */ RenderTask(); @@ -158,6 +187,7 @@ public: * * If handle points to a RenderTask the * downcast produces valid handle. If not the returned handle is left uninitialized. + * @SINCE_1_0.0 * @param[in] handle A handle to an object. * @return A handle to a RenderTask or an uninitialized handle. */ @@ -167,12 +197,14 @@ public: * @brief Destructor * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~RenderTask(); /** * @brief This copy constructor is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] handle A reference to the copied handle */ RenderTask(const RenderTask& handle); @@ -180,6 +212,7 @@ public: /** * @brief This assignment operator is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] rhs A reference to the copied handle * @return A reference to this */ @@ -187,6 +220,7 @@ public: /** * @brief Set the actors to be rendered. + * @SINCE_1_0.0 * @param[in] actor This actor and its children will be rendered. * If actor is an empty handle, then nothing will be rendered. */ @@ -194,18 +228,21 @@ public: /** * @brief Retrieve the actors to be rendered. + * @SINCE_1_0.0 * @return This actor and its children will be rendered. */ Actor GetSourceActor() const; /** * @brief Set whether the RenderTask has exclusive access to the source actors; the default is false. + * @SINCE_1_0.0 * @param[in] exclusive True if the source actors will only be rendered by this render-task. */ void SetExclusive( bool exclusive ); /** * @brief Query whether the RenderTask has exclusive access to the source actors. + * @SINCE_1_0.0 * @return True if the source actors will only be rendered by this render-task. */ bool IsExclusive() const; @@ -217,50 +254,72 @@ public: * and has a valid source & camera actor. * A RenderTask targetting a frame-buffer can still be hit-tested, provided that the screen->frame-buffer * coordinate conversion is successful; see also SetScreenToFrameBufferFunction(). + * @SINCE_1_0.0 * @param[in] enabled True if the render-task should be considered for input handling. */ void SetInputEnabled( bool enabled ); /** * @brief Query whether the render-task should be considered for input handling. + * @SINCE_1_0.0 * @return True if the render-task should be considered for input handling. */ bool GetInputEnabled() const; /** * @brief Set the actor from which the scene is viewed. + * @SINCE_1_0.0 * @param[in] cameraActor The scene is viewed from the perspective of this actor. */ void SetCameraActor( CameraActor cameraActor ); /** * @brief Retrieve the actor from which the scene is viewed. + * @SINCE_1_0.0 * @return The scene is viewed from the perspective of this actor. */ CameraActor GetCameraActor() const; /** * @brief Set the frame-buffer used as a render target. + * @SINCE_1_0.0 * @param[in] frameBuffer A valid frame-buffer handle to enable off-screen rendering, or an uninitialized handle to disable. */ void SetTargetFrameBuffer( FrameBufferImage frameBuffer ); /** * @brief Retrieve the frame-buffer used as a render target. + * @SINCE_1_0.0 * @return A valid frame-buffer handle, or an uninitialised handle if off-screen rendering is disabled. */ FrameBufferImage GetTargetFrameBuffer() const; /** + * @brief Set the frame-buffer used as a render target. + * @SINCE_1_1.38 + * @param[in] frameBuffer er A valid FrameBuffer handle to enable off-screen rendering, or an uninitialized handle to disable it. + */ + void SetFrameBuffer( FrameBuffer frameBuffer ); + + /** + * @brief Retrieve the frame-buffer used as a render target. + * @SINCE_1_1.38 + * @return The framebuffer + */ + FrameBuffer GetFrameBuffer() const; + + /** * @brief Set the function used to convert screen coordinates to frame-buffer coordinates. * * This is useful for hit-testing actors which are rendered off-screen. + * @SINCE_1_0.0 * @param[in] conversionFunction The conversion function. */ void SetScreenToFrameBufferFunction( ScreenToFrameBufferFunction conversionFunction ); /** * @brief Retrieve the function used to convert screen coordinates to frame-buffer coordinates. + * @SINCE_1_0.0 * @return The conversion function. */ ScreenToFrameBufferFunction GetScreenToFrameBufferFunction() const; @@ -270,13 +329,15 @@ public: * * The local coordinates of the actor are mapped as frame-buffer coordinates. * This is useful for hit-testing actors which are rendered off-screen. - * Note: The mapping actor needs to be rendered by the default render task to make the mapping work properly. + * @SINCE_1_0.0 * @param[in] mappingActor The actor used for conversion. + * @note The mapping actor needs to be rendered by the default render task to make the mapping work properly. */ void SetScreenToFrameBufferMappingActor( Actor mappingActor ); /** * @brief Retrieve the actor used to convert screen coordinates to frame-buffer coordinates. + * @SINCE_1_0.0 * @return The actor used for conversion. */ Actor GetScreenToFrameBufferMappingActor() const; @@ -286,13 +347,15 @@ public: * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. - * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. + * @SINCE_1_0.0 * @param[in] position The viewports position (x,y) + * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. */ void SetViewportPosition( Vector2 position ); /** * @brief Retrieve the GL viewport position used when rendering. + * @SINCE_1_0.0 * @return The viewport. */ Vector2 GetCurrentViewportPosition() const; @@ -302,12 +365,14 @@ public: * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. + * @SINCE_1_0.0 * @param[in] size The viewports size (width,height) */ void SetViewportSize( Vector2 size ); /** * @brief Retrieve the GL viewport size used when rendering. + * @SINCE_1_0.0 * @return The viewport. */ Vector2 GetCurrentViewportSize() const; @@ -317,27 +382,31 @@ public: * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. - * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. + * @SINCE_1_0.0 * @param[in] viewport The new viewport. + * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. */ void SetViewport( Viewport viewport ); /** * @brief Retrieve the GL viewport used when rendering. + * @SINCE_1_0.0 * @return The viewport. */ Viewport GetViewport() const; /** * @brief Set the clear color used when SetClearEnabled(true) is used. + * @SINCE_1_0.0 * @param[in] color The new clear color. */ void SetClearColor( const Vector4& color ); /** * @brief Retrieve the clear color used when SetClearEnabled(true) is used. - * @note This property can be animated; the return value may not match the value written with SetClearColor(). + * @SINCE_1_0.0 * @return The clear color. + * @note This property can be animated; the return value may not match the value written with SetClearColor(). */ Vector4 GetClearColor() const; @@ -346,17 +415,19 @@ public: * * The default is false. * + * @SINCE_1_0.0 + * @param[in] enabled True if the render-task should clear. * @note The default GL surface is cleared automatically at the * beginning of each frame; this setting is only useful when 2+ * render-tasks are used, and the result of the first task needs to * be (partially) cleared before rendering the second. * - * @param[in] enabled True if the render-task should clear. */ void SetClearEnabled( bool enabled ); /** * @brief Query whether the render-task will clear the results of previous render-tasks. + * @SINCE_1_0.0 * @return True if the render-task should clear. */ bool GetClearEnabled() const; @@ -364,15 +435,18 @@ public: /** * @brief Set whether the render task will cull the actors to the camera's view frustum. * - * Note that this will only affect image actors that use the default vertex shader. - * The default mode is to cull actors. + * @SINCE_1_0.0 * @param[in] cullMode True if the renderers should be culled. + * @note The default mode is to cull actors. + * @note If the shader uses @ref Shader::HINT_MODIFIES_GEOMETRY then culling optimizations are disabled. + * @see Shader::ShaderHints */ void SetCullMode( bool cullMode ); /** * @brief Get the cull mode. * + * @SINCE_1_0.0 * @return True if the render task should cull the actors to the camera's view frustum */ bool GetCullMode() const; @@ -392,20 +466,49 @@ public: * Repeatedly calling SetRefreshRate(REFRESH_ONCE) will cause more * snap-shots to be taken. * + * @SINCE_1_0.0 * @param[in] refreshRate The new refresh rate. */ void SetRefreshRate( unsigned int refreshRate ); /** * @brief Query the refresh-rate of the RenderTask. + * @SINCE_1_0.0 * @return The refresh-rate. */ unsigned int GetRefreshRate() const; + /* + * @brief Get viewport coordinates for given world position + * + * @SINCE_1_1.13 + * + * @param[in] position The world position. + * @param[out] viewportX The viewport x position. + * @param[out] viewportY The viewport y position. + * @return true if the position has a screen coordinate + */ + bool WorldToViewport(const Vector3 &position, float& viewportX, float& viewportY) const; + + /* + * @brief Get actor local coordinates for given viewport coordinates + * + * @SINCE_1_1.13 + * + * @param[in] actor The actor describing local coordinate system. + * @param[in] viewportX The viewport x position. + * @param[in] viewportY The viewport y position. + * @param[out] localX The local x position. + * @param[out] localY The local y position. + * @return true if the screen position has a local coordinate + */ + bool ViewportToLocal(Actor actor, float viewportX, float viewportY, float &localX, float &localY) const; + public: // Signals /** * @brief If the refresh rate is REFRESH_ONCE, connect to this signal to be notified when a RenderTask has finished. + * @SINCE_1_0.0 */ RenderTaskSignalType& FinishedSignal(); @@ -413,6 +516,7 @@ public: // Not intended for application developers /** * @brief This constructor is used by Dali New() methods. + * @SINCE_1_0.0 * @param [in] renderTask A pointer to a newly allocated render-task */ explicit DALI_INTERNAL RenderTask( Internal::RenderTask* renderTask );