1 #ifndef DALI_TOOLKIT_GL_VIEW_H
2 #define DALI_TOOLKIT_GL_VIEW_H
4 * Copyright (c) 2024 Samsung Electronics Co., Ltd.
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
21 #include <dali/public-api/common/vector-wrapper.h>
22 #include <dali/public-api/rendering/texture.h>
25 #include <dali-toolkit/public-api/controls/control.h>
31 namespace Internal DALI_INTERNAL
37 * @brief GlView is a class for rendering with GL
39 * GlView allows drawing with OpenGL.
40 * GlView creates a GL context, a GL surface and a render thread.
41 * The render thread invokes user's callbacks.
45 class DALI_TOOLKIT_API GlView : public Dali::Toolkit::Control
49 * @brief Implementation backend mode
53 enum class BackendMode
56 * DIRECT_RENDERING mode executes GL code within DALi graphics
57 * pipeline but creates isolated context hence it doesn't alter any
58 * DALi rendering state. When Renderer is about to be drawn, the callback
59 * will be executed and the custom code "injected" into the pipeline.
60 * This allows rendering directly to the surface rather than offscreen.
67 * DIRECT_RENDERING_THREADED mode executes GL code on separate thread
68 * and then blits the result within DALi graphics commands stream.
69 * The mode is logically compatible with the EGL_IMAGE_OFFSCREEN_RENDERING.
73 DIRECT_RENDERING_THREADED,
76 * EGL_IMAGE_OFFSCREEN_RENDERING mode executes GL code in own thread
77 * and renders to the offscreen NativeImage (EGL) buffer. This backend
78 * will render in parallel but has higher memory footprint and may suffer
79 * performance issues due to using EGL image.
83 EGL_IMAGE_OFFSCREEN_RENDERING,
86 * UNSAFE_DIRECT_RENDERING mode executes GL code within DALi graphics
87 * pipeline WITHOUT isolating the GL context so should be used with caution!
88 * The custom rendering code is executed within current window context and
89 * may alter the GL state. This mode is considered unsafe and should be used
90 * only when drawing on main GL context is necessary!
92 * When Renderer is about to be drawn, the callback
93 * will be executed and the custom code "injected" into the pipeline.
94 * This allows rendering directly to the surface rather than offscreen.
98 UNSAFE_DIRECT_RENDERING,
101 * The default mode is set to EGL_IMAGE_OFFSCREEN_RENDERING for backwards
106 DEFAULT = EGL_IMAGE_OFFSCREEN_RENDERING
110 * @brief Enumeration for rendering mode
112 * This Enumeration is used to choose the rendering mode.
113 * It has two options.
114 * One of them is continuous mode. It is rendered continuously.
115 * The other is on demand mode. It is rendered by application.
119 enum class RenderingMode
121 CONTINUOUS, ///< continuous mode
122 ON_DEMAND ///< on demand by application
126 * @brief Enumeration for Graphics API version
128 * This Enumeration is used to set a GLES version for EGL configuration.
132 enum class GraphicsApiVersion
134 GLES_VERSION_2_0 = 0, ///< GLES version 2.0
135 GLES_VERSION_3_0, ///< GLES version 3.0
139 * @brief Enumeration for color buffer format
141 * This Enumeration is used to set a color buffer format of GlView
145 enum class ColorFormat
147 RGB888, ///< 8 red bits, 8 green bits, 8 blue bits
148 RGBA8888 ///< 8 red bits, 8 green bits, 8 blue bits, alpha 8 bits
152 * @brief Creates a GlView control.
154 * @note This function always creates the GlView with NativeImage backend.
156 * @param[in] colorFormat the format of the color buffer.
157 * @return A handle to a GlView control
161 static GlView New(ColorFormat colorFormat);
164 * @brief Creates a GlView control.
166 * The new GlView will be created with specified backend.
167 * The colorFormat is ignored for DIRECT_RENDERING backend.
169 * @param[in] colorFormat the format of the color buffer.
170 * @param[in] backendMode the backend used by the GlView
171 * @return A handle to a GlView control
175 static GlView New(BackendMode backendMode, ColorFormat colorFormat);
178 * @brief Creates an uninitialized GlView.
187 * This is non-virtual since derived Handle types must not contain data or virtual methods.
194 * @brief Copy constructor.
196 * @param[in] GlView GlView to copy. The copied GlView will point at the same implementation
200 GlView(const GlView& GlView);
203 * @brief Move constructor
205 * @param[in] rhs A reference to the moved handle
209 GlView(GlView&& rhs) noexcept;
212 * @brief Assignment operator.
214 * @param[in] GlView The GlView to assign from
215 * @return A reference to this
219 GlView& operator=(const GlView& GlView);
222 * @brief Move assignment
224 * @param[in] rhs A reference to the moved handle
225 * @return A reference to this
229 GlView& operator=(GlView&& rhs) noexcept;
232 * @brief Downcasts a handle to GlView handle.
234 * If handle points to a GlView, the downcast produces valid handle.
235 * If not, the returned handle is left uninitialized.
237 * @param[in] handle Handle to an object
238 * @return Handle to a GlView or an uninitialized handle
242 static GlView DownCast(BaseHandle handle);
245 * @brief Registers GL callback functions for GlView.
247 * @param[in] initCallback the callback function to create GL resources.
248 * @param[in] renderFrameCallback the callback function to render for the frame.
249 * @param[in] terminateCallback the callback function to clean-up GL resources.
251 * A initCallback of the following type have to be used:
253 * void intializeGL();
255 * This callback will be called before renderFrame callback is called once.
257 * A renderFrameCallback of the following type have to be used:
259 * int renderFrameGL();
261 * If the return value of this callback is not 0, the eglSwapBuffers() will be called.
263 * A terminateCallback of the following type have to be used:
265 * void terminateGL();
267 * This callback is called when GlView is deleted.
269 * @note Ownership of the callbacks is passed onto this class.
270 * <b>You can't call Dali APIs in your callbacks because it is invoked in GlView's own render thread.</b>
271 * And this must be called before adding GlView to the scene.
275 void RegisterGlCallbacks(CallbackBase* initCallback, CallbackBase* renderFrameCallback, CallbackBase* terminateCallback);
278 * @brief Sets the ResizeCallback of the GlView.
279 * When GlView is resized, ResizeCallback would be invoked.
280 * You can get the resized width and height of the GlView.
282 * @param[in] resizeCallback The ResizeCallback function
284 * A resizeCallback of the following type have to be used:
286 * void resizeCallback(int width, int height);
289 * @note Ownership of the callback is passed onto this class.
290 * <b>You can't call Dali APIs in your callback because it is invoked in GlView's own render thread.</b>
291 * And this must be called before adding GlView to the scene.
295 void SetResizeCallback(CallbackBase* resizeCallback);
298 * @brief Sets the rendering mode.
300 * @param[in] mode the rendering mode for GlView
302 * @note The default Rendering mode is CONTINUOUS.
303 * If ON_DEMAND mode is set, it is rendered by RenderOnce()
307 void SetRenderingMode(RenderingMode mode);
310 * @brief Gets the rendering mode.
314 [[nodiscard]] RenderingMode GetRenderingMode() const;
317 * @brief Gets the backend mode.
321 [[nodiscard]] BackendMode GetBackendMode() const;
324 * @brief Sets egl configuration for GlView
326 * @param[in] depth the flag of depth buffer. If the value is true, 24bit depth buffer is enabled.
327 * @param[in] stencil the flag of stencil. If the value is true, 8bit stencil buffer is enabled.
328 * @param[in] msaa the expected sampling number per pixel.
329 * @param[in] version the graphics API version
330 * @return True if the config exists, false otherwise.
334 bool SetGraphicsConfig(bool depth, bool stencil, int msaa, GraphicsApiVersion version);
337 * @brief Renders once more even if GL render functions are not added to idler.
338 * @note Will not work if the window is hidden or GL render functions are added to idler
345 * @brief Binds DALi textures to the callback
347 * The textures that are bound to the callback will be passed upon
348 * callback execution providing native handles (like GL name) so they
349 * can be used alongside with custom GL code.
351 * Binding texture does not affect lifecycle and it's up to the client-side
352 * to make sure the resource is alive when used inside the callback.
354 * @param[in] textures List of DALi textures to be bound to the callback
356 * @note It only supported only in the GlView::BackendMode::DIRECT_RENDERING.
360 void BindTextureResources(std::vector<Dali::Texture> textures);
362 public: // Not intended for application developers
365 * @brief Creates a handle using the Toolkit::Internal implementation.
366 * @param[in] implementation The GlView implementation
370 DALI_INTERNAL GlView(Internal::GlViewImpl& implementation);
373 * @brief Allows the creation of this GlView from an Internal::CustomActor pointer.
374 * @param[in] internal A pointer to the internal CustomActor
378 DALI_INTERNAL GlView(Dali::Internal::CustomActor* internal);
382 } // namespace Toolkit
386 #endif // DALI_TOOLKIT_GL_VIEW_H