[dali_2.3.24] Merge branch 'devel/master'

[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / gl-view / gl-view.h

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 099b00f..13cc2e9 100644 (file)
--- 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 <dali/public-api/common/vector-wrapper.h>
+#include <dali/public-api/rendering/texture.h>
+
 // INTERNAL INCLUDES
 #include <dali-toolkit/public-api/controls/control.h>
 
@@ -41,7 +45,6 @@ class GlViewImpl;
 class DALI_TOOLKIT_API GlView : public Dali::Toolkit::Control
 {
 public:
-
   /**
    * @brief Implementation backend mode
    *
@@ -51,23 +54,54 @@ public:
   {
     /**
      * DIRECT_RENDERING mode executes GL code within DALi graphics
-     * pipeline. When Renderer is about to be drawn, the callback
+     * 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
   };
@@ -172,7 +206,7 @@ public:
    *
    * @SINCE_2_0.45
    */
-  GlView(GlView&& rhs);
+  GlView(GlView&& rhs) noexcept;
 
   /**
    * @brief Assignment operator.
@@ -192,7 +226,7 @@ public:
    *
    * @SINCE_2_0.45
    */
-  GlView& operator=(GlView&& rhs);
+  GlView& operator=(GlView&& rhs) noexcept;
 
   /**
    * @brief Downcasts a handle to GlView handle.
@@ -307,6 +341,24 @@ public:
    */
   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<Dali::Texture> textures);
+
 public: // Not intended for application developers
   /// @cond internal
   /**