Flutter Engine
fl_engine_private.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
6 #define FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
7 
8 #include <glib-object.h>
9 
10 #include "flutter/shell/platform/embedder/embedder.h"
11 #include "flutter/shell/platform/linux/fl_renderer.h"
12 #include "flutter/shell/platform/linux/fl_task_runner.h"
13 #include "flutter/shell/platform/linux/public/flutter_linux/fl_dart_project.h"
14 #include "flutter/shell/platform/linux/public/flutter_linux/fl_engine.h"
15 
16 G_BEGIN_DECLS
17 
18 /**
19  * FlEngineError:
20  * Errors for #FlEngine objects to set on failures.
21  */
22 
23 typedef enum {
26 
27 GQuark fl_engine_error_quark(void) G_GNUC_CONST;
28 
29 /**
30  * FlEnginePlatformMessageHandler:
31  * @engine: an #FlEngine.
32  * @channel: channel message received on.
33  * @message: message content received from Dart.
34  * @response_handle: a handle to respond to the message with.
35  * @user_data: (closure): data provided when registering this handler.
36  *
37  * Function called when platform messages are received.
38  *
39  * Returns: %TRUE if message has been accepted.
40  */
41 typedef gboolean (*FlEnginePlatformMessageHandler)(
42  FlEngine* engine,
43  const gchar* channel,
44  GBytes* message,
45  const FlutterPlatformMessageResponseHandle* response_handle,
46  gpointer user_data);
47 
48 /**
49  * FlEngineUpdateSemanticsNodeHandler:
50  * @engine: an #FlEngine.
51  * @node: semantic node information.
52  * @user_data: (closure): data provided when registering this handler.
53  *
54  * Function called when semantics node updates are received.
55  */
57  FlEngine* engine,
59  gpointer user_data);
60 
61 /**
62  * FlEngineOnPreEngineRestartHandler:
63  * @engine: an #FlEngine.
64  * @user_data: semantic node information.
65  *
66  * @user_data: (closure): data provided when registering this handler.
67  */
68 typedef void (*FlEngineOnPreEngineRestartHandler)(FlEngine* engine,
69  gpointer user_data);
70 
71 /**
72  * fl_engine_new:
73  * @project: an #FlDartProject.
74  * @renderer: an #FlRenderer.
75  *
76  * Creates new Flutter engine.
77  *
78  * Returns: a new #FlEngine.
79  */
80 FlEngine* fl_engine_new(FlDartProject* project, FlRenderer* renderer);
81 
82 /**
83  * fl_engine_get_embedder_api:
84  * @engine: an #FlEngine.
85  *
86  * Gets the embedder API proc table, allowing modificiations for unit testing.
87  *
88  * Returns: a mutable pointer to the embedder API proc table.
89  */
91 
92 /**
93  * fl_engine_set_platform_message_handler:
94  * @engine: an #FlEngine.
95  * @handler: function to call when a platform message is received.
96  * @user_data: (closure): user data to pass to @handler.
97  * @destroy_notify: (allow-none): a function which gets called to free
98  * @user_data, or %NULL.
99  *
100  * Registers the function called when a platform message is received. Call
101  * fl_engine_send_platform_message_response() with the response to this message.
102  * Ownership of #FlutterPlatformMessageResponseHandle is
103  * transferred to the caller, and the message must be responded to to avoid
104  * memory leaks.
105  */
107  FlEngine* engine,
109  gpointer user_data,
110  GDestroyNotify destroy_notify);
111 
112 /**
113  * fl_engine_set_update_semantics_node_handler:
114  * @engine: an #FlEngine.
115  * @handler: function to call when a semantics node update is received.
116  * @user_data: (closure): user data to pass to @handler.
117  * @destroy_notify: (allow-none): a function which gets called to free
118  * @user_data, or %NULL.
119  *
120  * Registers the function called when a semantics node update is reveived.
121  */
123  FlEngine* engine,
125  gpointer user_data,
126  GDestroyNotify destroy_notify);
127 
128 /**
129  * fl_engine_set_on_pre_engine_restart_handler:
130  * @engine: an #FlEngine.
131  * @handler: function to call when the engine is restarted.
132  * @user_data: (closure): user data to pass to @handler.
133  * @destroy_notify: (allow-none): a function which gets called to free
134  * @user_data, or %NULL.
135  *
136  * Registers the function called when the engine is restarted.
137  */
139  FlEngine* engine,
141  gpointer user_data,
142  GDestroyNotify destroy_notify);
143 
144 /**
145  * fl_engine_start:
146  * @engine: an #FlEngine.
147  * @error: (allow-none): #GError location to store the error occurring, or %NULL
148  * to ignore.
149  *
150  * Starts the Flutter engine.
151  *
152  * Returns: %TRUE on success.
153  */
154 gboolean fl_engine_start(FlEngine* engine, GError** error);
155 
156 /**
157  * fl_engine_send_window_metrics_event:
158  * @engine: an #FlEngine.
159  * @width: width of the window in pixels.
160  * @height: height of the window in pixels.
161  * @pixel_ratio: scale factor for window.
162  *
163  * Sends a window metrics event to the engine.
164  */
166  size_t width,
167  size_t height,
168  double pixel_ratio);
169 
170 /**
171  * fl_engine_send_mouse_pointer_event:
172  * @engine: an #FlEngine.
173  * @phase: mouse phase.
174  * @timestamp: time when event occurred in microseconds.
175  * @x: x location of mouse cursor.
176  * @y: y location of mouse cursor.
177  * @scroll_delta_x: x offset of scroll.
178  * @scroll_delta_y: y offset of scroll.
179  * @buttons: buttons that are pressed.
180  *
181  * Sends a mouse pointer event to the engine.
182  */
184  FlutterPointerPhase phase,
185  size_t timestamp,
186  double x,
187  double y,
188  double scroll_delta_x,
189  double scroll_delta_y,
190  int64_t buttons);
191 
192 /**
193  * fl_engine_send_key_event:
194  */
195 void fl_engine_send_key_event(FlEngine* engine,
196  const FlutterKeyEvent* event,
198  void* user_data);
199 
200 /**
201  * fl_engine_dispatch_semantics_action:
202  * @engine: an #FlEngine.
203  * @id: the semantics action identifier.
204  * @action: the action being dispatched.
205  * @data: (allow-none): data associated with the action.
206  */
208  uint64_t id,
210  GBytes* data);
211 
212 /**
213  * fl_engine_send_platform_message_response:
214  * @engine: an #FlEngine.
215  * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
216  * @response: (allow-none): response to send or %NULL for an empty response.
217  * @error: (allow-none): #GError location to store the error occurring, or %NULL
218  * to ignore.
219  *
220  * Responds to a platform message.
221  *
222  * Returns: %TRUE on success.
223  */
225  FlEngine* engine,
227  GBytes* response,
228  GError** error);
229 
230 /**
231  * fl_engine_send_platform_message:
232  * @engine: an #FlEngine.
233  * @channel: channel to send to.
234  * @message: (allow-none): message buffer to send or %NULL for an empty message
235  * @cancellable: (allow-none): a #GCancellable or %NULL.
236  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
237  * satisfied.
238  * @user_data: (closure): user data to pass to @callback.
239  *
240  * Asynchronously sends a platform message.
241  */
243  const gchar* channel,
244  GBytes* message,
245  GCancellable* cancellable,
246  GAsyncReadyCallback callback,
247  gpointer user_data);
248 
249 /**
250  * fl_engine_send_platform_message_finish:
251  * @engine: an #FlEngine.
252  * @result: a #GAsyncResult.
253  * @error: (allow-none): #GError location to store the error occurring, or %NULL
254  * to ignore.
255  *
256  * Completes request started with fl_engine_send_platform_message().
257  *
258  * Returns: message response on success or %NULL on error.
259  */
261  GAsyncResult* result,
262  GError** error);
263 
264 /**
265  * fl_engine_get_task_runner:
266  * @engine: an #FlEngine.
267  * @result: a #FlTaskRunner.
268  *
269  * Returns: task runner responsible for scheduling Flutter tasks.
270  */
271 FlTaskRunner* fl_engine_get_task_runner(FlEngine* engine);
272 
273 /**
274  * fl_engine_execute_task:
275  * @engine: an #FlEngine.
276  * @task: a #FlutterTask to execute.
277  *
278  * Executes given Flutter task.
279  */
280 void fl_engine_execute_task(FlEngine* engine, FlutterTask* task);
281 
282 /**
283  * fl_engine_mark_texture_frame_available:
284  * @engine: an #FlEngine.
285  * @texture_id: the identifier of the texture whose frame has been updated.
286  *
287  * Tells the Flutter engine that a new texture frame is available for the given
288  * texture.
289  *
290  * Returns: %TRUE on success.
291  */
293  int64_t texture_id);
294 
295 /**
296  * fl_engine_register_external_texture:
297  * @engine: an #FlEngine.
298  * @texture_id: the identifier of the texture that is available.
299  *
300  * Tells the Flutter engine that a new external texture is available.
301  *
302  * Returns: %TRUE on success.
303  */
305  int64_t texture_id);
306 
307 /**
308  * fl_engine_unregister_external_texture:
309  * @engine: an #FlEngine.
310  * @texture_id: the identifier of the texture that is not available anymore.
311  *
312  * Tells the Flutter engine that an existing external texture is not available
313  * anymore.
314  *
315  * Returns: %TRUE on success.
316  */
318  int64_t texture_id);
319 
320 G_END_DECLS
321 
322 #endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_ENGINE_PRIVATE_H_
GBytes * fl_engine_send_platform_message_finish(FlEngine *engine, GAsyncResult *result, GError **error)
Definition: fl_engine.cc:657
const uint8_t uint32_t uint32_t GError ** error
gboolean(* FlEnginePlatformMessageHandler)(FlEngine *engine, const gchar *channel, GBytes *message, const FlutterPlatformMessageResponseHandle *response_handle, gpointer user_data)
void fl_engine_send_window_metrics_event(FlEngine *engine, size_t width, size_t height, double pixel_ratio)
Definition: fl_engine.cc:666
gboolean fl_engine_unregister_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:762
void fl_engine_send_platform_message(FlEngine *engine, const gchar *channel, GBytes *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)
Definition: fl_engine.cc:598
gboolean fl_engine_start(FlEngine *engine, GError **error)
Definition: fl_engine.cc:403
gboolean fl_engine_mark_texture_frame_available(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:748
FlutterPointerPhase
The phase of the pointer event.
Definition: embedder.h:587
Function-pointer-based versions of the APIs above.
Definition: embedder.h:2372
void * user_data
void fl_engine_execute_task(FlEngine *engine, FlutterTask *task)
Definition: fl_engine.cc:780
int64_t texture_id
GAsyncResult * result
void fl_engine_set_on_pre_engine_restart_handler(FlEngine *engine, FlEngineOnPreEngineRestartHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:549
FlKeyEvent FlKeyResponderAsyncCallback callback
gboolean fl_engine_send_platform_message_response(FlEngine *engine, const FlutterPlatformMessageResponseHandle *handle, GBytes *response, GError **error)
Definition: fl_engine.cc:566
gboolean fl_engine_register_external_texture(FlEngine *engine, int64_t texture_id)
Definition: fl_engine.cc:755
FlutterSemanticsAction
Definition: embedder.h:101
FlKeyEvent * event
void fl_engine_send_key_event(FlEngine *engine, const FlutterKeyEvent *event, FlutterKeyEventCallback callback, void *user_data)
Definition: fl_engine.cc:714
const FlutterSemanticsNode * node
Definition: fl_view.cc:83
SemanticsAction action
int32_t width
void fl_engine_set_platform_message_handler(FlEngine *engine, FlEnginePlatformMessageHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:514
FlTaskRunner * fl_engine_get_task_runner(FlEngine *engine)
Definition: fl_engine.cc:775
int32_t height
FlEngineError
FlEngine * fl_engine_new(FlDartProject *project, FlRenderer *renderer)
Definition: fl_engine.cc:388
FlutterEngineProcTable * fl_engine_get_embedder_api(FlEngine *engine)
Definition: fl_engine.cc:510
void(* FlutterKeyEventCallback)(bool, void *)
Definition: embedder.h:748
void fl_engine_dispatch_semantics_action(FlEngine *engine, uint64_t id, FlutterSemanticsAction action, GBytes *data)
Definition: fl_engine.cc:727
void fl_engine_send_mouse_pointer_event(FlEngine *engine, FlutterPointerPhase phase, size_t timestamp, double x, double y, double scroll_delta_x, double scroll_delta_y, int64_t buttons)
Definition: fl_engine.cc:684
void fl_engine_set_update_semantics_node_handler(FlEngine *engine, FlEngineUpdateSemanticsNodeHandler handler, gpointer user_data, GDestroyNotify destroy_notify)
Definition: fl_engine.cc:532
GQuark fl_engine_error_quark(void) G_GNUC_CONST
void(* FlEngineUpdateSemanticsNodeHandler)(FlEngine *engine, const FlutterSemanticsNode *node, gpointer user_data)
void(* FlEngineOnPreEngineRestartHandler)(FlEngine *engine, gpointer user_data)