X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fgl-view%2Fgl-view.h;h=13cc2e9840e9a20764b4c0df09c3e8c321c4bf1f;hb=HEAD;hp=57c320126d75414fc051d05bde54b3af321fab76;hpb=3ea3bc2160dead96a69eae4c12175b6bd760a006;p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git diff --git a/dali-toolkit/public-api/controls/gl-view/gl-view.h b/dali-toolkit/public-api/controls/gl-view/gl-view.h index 57c3201..13cc2e9 100644 --- a/dali-toolkit/public-api/controls/gl-view/gl-view.h +++ b/dali-toolkit/public-api/controls/gl-view/gl-view.h @@ -1,7 +1,7 @@ #ifndef DALI_TOOLKIT_GL_VIEW_H #define DALI_TOOLKIT_GL_VIEW_H /* - * Copyright (c) 2021 Samsung Electronics Co., Ltd. + * Copyright (c) 2024 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. @@ -17,6 +17,10 @@ * */ +// EXTERNAL INCLUDES +#include +#include + // INTERNAL INCLUDES #include @@ -26,7 +30,7 @@ namespace Toolkit { namespace Internal DALI_INTERNAL { -class GlView; +class GlViewImpl; } /** @@ -36,17 +40,81 @@ class GlView; * GlView creates a GL context, a GL surface and a render thread. * The render thread invokes user's callbacks. * + * @SINCE_2_0.45 */ class DALI_TOOLKIT_API GlView : public Dali::Toolkit::Control { public: /** + * @brief Implementation backend mode + * + * @SINCE_2_1.18 + */ + enum class BackendMode + { + /** + * DIRECT_RENDERING mode executes GL code within DALi graphics + * pipeline but creates isolated context hence it doesn't alter any + * DALi rendering state. When Renderer is about to be drawn, the callback + * will be executed and the custom code "injected" into the pipeline. + * This allows rendering directly to the surface rather than offscreen. + * + * @SINCE_2_3.12 + */ + DIRECT_RENDERING = 0, + + /** + * DIRECT_RENDERING_THREADED mode executes GL code on separate thread + * and then blits the result within DALi graphics commands stream. + * The mode is logically compatible with the EGL_IMAGE_OFFSCREEN_RENDERING. + * + * @SINCE_2_1.30 + */ + DIRECT_RENDERING_THREADED, + + /** + * EGL_IMAGE_OFFSCREEN_RENDERING mode executes GL code in own thread + * and renders to the offscreen NativeImage (EGL) buffer. This backend + * will render in parallel but has higher memory footprint and may suffer + * performance issues due to using EGL image. + * + * @SINCE_2_1.18 + */ + EGL_IMAGE_OFFSCREEN_RENDERING, + + /** + * UNSAFE_DIRECT_RENDERING mode executes GL code within DALi graphics + * pipeline WITHOUT isolating the GL context so should be used with caution! + * The custom rendering code is executed within current window context and + * may alter the GL state. This mode is considered unsafe and should be used + * only when drawing on main GL context is necessary! + * + * When Renderer is about to be drawn, the callback + * will be executed and the custom code "injected" into the pipeline. + * This allows rendering directly to the surface rather than offscreen. + * + * @SINCE_2_3.12 + */ + UNSAFE_DIRECT_RENDERING, + + /** + * The default mode is set to EGL_IMAGE_OFFSCREEN_RENDERING for backwards + * compatibility. + * + * @SINCE_2_1.18 + */ + DEFAULT = EGL_IMAGE_OFFSCREEN_RENDERING + }; + + /** * @brief Enumeration for rendering mode * * This Enumeration is used to choose the rendering mode. * It has two options. * One of them is continuous mode. It is rendered continuously. * The other is on demand mode. It is rendered by application. + * + * @SINCE_2_0.45 */ enum class RenderingMode { @@ -58,6 +126,8 @@ public: * @brief Enumeration for Graphics API version * * This Enumeration is used to set a GLES version for EGL configuration. + * + * @SINCE_2_0.45 */ enum class GraphicsApiVersion { @@ -69,6 +139,8 @@ public: * @brief Enumeration for color buffer format * * This Enumeration is used to set a color buffer format of GlView + * + * @SINCE_2_0.45 */ enum class ColorFormat { @@ -78,13 +150,34 @@ public: /** * @brief Creates a GlView control. + * + * @note This function always creates the GlView with NativeImage backend. + * * @param[in] colorFormat the format of the color buffer. * @return A handle to a GlView control + * + * @SINCE_2_0.45 */ static GlView New(ColorFormat colorFormat); /** + * @brief Creates a GlView control. + * + * The new GlView will be created with specified backend. + * The colorFormat is ignored for DIRECT_RENDERING backend. + * + * @param[in] colorFormat the format of the color buffer. + * @param[in] backendMode the backend used by the GlView + * @return A handle to a GlView control + * + * @SINCE_2_1.18 + */ + static GlView New(BackendMode backendMode, ColorFormat colorFormat); + + /** * @brief Creates an uninitialized GlView. + * + * @SINCE_2_0.45 */ GlView(); @@ -92,6 +185,8 @@ public: * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * + * @SINCE_2_0.45 */ ~GlView(); @@ -99,6 +194,8 @@ public: * @brief Copy constructor. * * @param[in] GlView GlView to copy. The copied GlView will point at the same implementation + * + * @SINCE_2_0.45 */ GlView(const GlView& GlView); @@ -106,14 +203,18 @@ public: * @brief Move constructor * * @param[in] rhs A reference to the moved handle + * + * @SINCE_2_0.45 */ - GlView(GlView&& rhs); + GlView(GlView&& rhs) noexcept; /** * @brief Assignment operator. * * @param[in] GlView The GlView to assign from * @return A reference to this + * + * @SINCE_2_0.45 */ GlView& operator=(const GlView& GlView); @@ -122,8 +223,10 @@ public: * * @param[in] rhs A reference to the moved handle * @return A reference to this + * + * @SINCE_2_0.45 */ - GlView& operator=(GlView&& rhs); + GlView& operator=(GlView&& rhs) noexcept; /** * @brief Downcasts a handle to GlView handle. @@ -133,6 +236,8 @@ public: * * @param[in] handle Handle to an object * @return Handle to a GlView or an uninitialized handle + * + * @SINCE_2_0.45 */ static GlView DownCast(BaseHandle handle); @@ -164,6 +269,8 @@ public: * @note Ownership of the callbacks is passed onto this class. * You can't call Dali APIs in your callbacks because it is invoked in GlView's own render thread. * And this must be called before adding GlView to the scene. + * + * @SINCE_2_0.45 */ void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback); @@ -182,6 +289,8 @@ public: * @note Ownership of the callback is passed onto this class. * You can't call Dali APIs in your callback because it is invoked in GlView's own render thread. * And this must be called before adding GlView to the scene. + * + * @SINCE_2_0.45 */ void SetResizeCallback(CallbackBase* resizeCallback); @@ -192,13 +301,24 @@ public: * * @note The default Rendering mode is CONTINUOUS. * If ON_DEMAND mode is set, it is rendered by RenderOnce() + * + * @SINCE_2_0.45 */ void SetRenderingMode(RenderingMode mode); /** * @brief Gets the rendering mode. + * + * @SINCE_2_0.45 + */ + [[nodiscard]] RenderingMode GetRenderingMode() const; + + /** + * @brief Gets the backend mode. + * + * @SINCE_2_1.18 */ - RenderingMode GetRenderingMode() const; + [[nodiscard]] BackendMode GetBackendMode() const; /** * @brief Sets egl configuration for GlView @@ -208,26 +328,52 @@ public: * @param[in] msaa the expected sampling number per pixel. * @param[in] version the graphics API version * @return True if the config exists, false otherwise. + * + * @SINCE_2_0.45 */ bool SetGraphicsConfig(bool depth, bool stencil, int msaa, GraphicsApiVersion version); /** * @brief Renders once more even if GL render functions are not added to idler. * @note Will not work if the window is hidden or GL render functions are added to idler + * + * @SINCE_2_0.45 */ void RenderOnce(); + /** + * @brief Binds DALi textures to the callback + * + * The textures that are bound to the callback will be passed upon + * callback execution providing native handles (like GL name) so they + * can be used alongside with custom GL code. + * + * Binding texture does not affect lifecycle and it's up to the client-side + * to make sure the resource is alive when used inside the callback. + * + * @param[in] textures List of DALi textures to be bound to the callback + * + * @note It only supported only in the GlView::BackendMode::DIRECT_RENDERING. + * + * @SINCE_2_2.2 + */ + void BindTextureResources(std::vector textures); + public: // Not intended for application developers /// @cond internal /** * @brief Creates a handle using the Toolkit::Internal implementation. * @param[in] implementation The GlView implementation + * + * @SINCE_2_0.45 */ - DALI_INTERNAL GlView(Internal::GlView& implementation); + DALI_INTERNAL GlView(Internal::GlViewImpl& implementation); /** * @brief Allows the creation of this GlView from an Internal::CustomActor pointer. * @param[in] internal A pointer to the internal CustomActor + * + * @SINCE_2_0.45 */ DALI_INTERNAL GlView(Dali::Internal::CustomActor* internal); /// @endcond