/
embedder.h
2420 lines (2260 loc) · 107 KB
/
embedder.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef FLUTTER_EMBEDDER_H_
#define FLUTTER_EMBEDDER_H_
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
// This file defines an Application Binary Interface (ABI), which requires more
// stability than regular code to remain functional for exchanging messages
// between different versions of the embedding and the engine, to allow for both
// forward and backward compatibility.
//
// Specifically,
// - The order, type, and size of the struct members below must remain the same,
// and members should not be removed.
// - New structures that are part of the ABI must be defined with "size_t
// struct_size;" as their first member, which should be initialized using
// "sizeof(Type)".
// - Enum values must not change or be removed.
// - Enum members without explicit values must not be reordered.
// - Function signatures (names, argument counts, argument order, and argument
// type) cannot change.
// - The core behavior of existing functions cannot change.
//
// These changes are allowed:
// - Adding new struct members at the end of a structure.
// - Adding new enum members with a new value.
// - Renaming a struct member as long as its type, size, and intent remain the
// same.
// - Renaming an enum member as long as its value and intent remains the same.
//
// It is expected that struct members and implicitly-valued enums will not
// always be declared in an order that is optimal for the reader, since members
// will be added over time, and they can't be reordered.
//
// Existing functions should continue to appear from the caller's point of view
// to operate as they did when they were first introduced, so introduce a new
// function instead of modifying the core behavior of a function (and continue
// to support the existing function with the previous behavior).
#if defined(__cplusplus)
extern "C" {
#endif
#ifndef FLUTTER_EXPORT
#define FLUTTER_EXPORT
#endif // FLUTTER_EXPORT
#ifdef FLUTTER_API_SYMBOL_PREFIX
#define FLUTTER_EMBEDDING_CONCAT(a, b) a##b
#define FLUTTER_EMBEDDING_ADD_PREFIX(symbol, prefix) \
FLUTTER_EMBEDDING_CONCAT(prefix, symbol)
#define FLUTTER_API_SYMBOL(symbol) \
FLUTTER_EMBEDDING_ADD_PREFIX(symbol, FLUTTER_API_SYMBOL_PREFIX)
#else
#define FLUTTER_API_SYMBOL(symbol) symbol
#endif
#define FLUTTER_ENGINE_VERSION 1
typedef enum {
kSuccess = 0,
kInvalidLibraryVersion,
kInvalidArguments,
kInternalInconsistency,
} FlutterEngineResult;
typedef enum {
kOpenGL,
kSoftware,
/// Metal is only supported on Darwin platforms (macOS / iOS).
/// iOS version >= 10.0 (device), 13.0 (simulator)
/// macOS version >= 10.14
kMetal,
} FlutterRendererType;
/// Additional accessibility features that may be enabled by the platform.
/// Must match the `AccessibilityFeatures` enum in window.dart.
typedef enum {
/// Indicate there is a running accessibility service which is changing the
/// interaction model of the device.
kFlutterAccessibilityFeatureAccessibleNavigation = 1 << 0,
/// Indicate the platform is inverting the colors of the application.
kFlutterAccessibilityFeatureInvertColors = 1 << 1,
/// Request that animations be disabled or simplified.
kFlutterAccessibilityFeatureDisableAnimations = 1 << 2,
/// Request that text be rendered at a bold font weight.
kFlutterAccessibilityFeatureBoldText = 1 << 3,
/// Request that certain animations be simplified and parallax effects
// removed.
kFlutterAccessibilityFeatureReduceMotion = 1 << 4,
} FlutterAccessibilityFeature;
/// The set of possible actions that can be conveyed to a semantics node.
///
/// Must match the `SemanticsAction` enum in semantics.dart.
typedef enum {
/// The equivalent of a user briefly tapping the screen with the finger
/// without moving it.
kFlutterSemanticsActionTap = 1 << 0,
/// The equivalent of a user pressing and holding the screen with the finger
/// for a few seconds without moving it.
kFlutterSemanticsActionLongPress = 1 << 1,
/// The equivalent of a user moving their finger across the screen from right
/// to left.
kFlutterSemanticsActionScrollLeft = 1 << 2,
/// The equivalent of a user moving their finger across the screen from left
/// to
/// right.
kFlutterSemanticsActionScrollRight = 1 << 3,
/// The equivalent of a user moving their finger across the screen from bottom
/// to top.
kFlutterSemanticsActionScrollUp = 1 << 4,
/// The equivalent of a user moving their finger across the screen from top to
/// bottom.
kFlutterSemanticsActionScrollDown = 1 << 5,
/// Increase the value represented by the semantics node.
kFlutterSemanticsActionIncrease = 1 << 6,
/// Decrease the value represented by the semantics node.
kFlutterSemanticsActionDecrease = 1 << 7,
/// A request to fully show the semantics node on screen.
kFlutterSemanticsActionShowOnScreen = 1 << 8,
/// Move the cursor forward by one character.
kFlutterSemanticsActionMoveCursorForwardByCharacter = 1 << 9,
/// Move the cursor backward by one character.
kFlutterSemanticsActionMoveCursorBackwardByCharacter = 1 << 10,
/// Set the text selection to the given range.
kFlutterSemanticsActionSetSelection = 1 << 11,
/// Copy the current selection to the clipboard.
kFlutterSemanticsActionCopy = 1 << 12,
/// Cut the current selection and place it in the clipboard.
kFlutterSemanticsActionCut = 1 << 13,
/// Paste the current content of the clipboard.
kFlutterSemanticsActionPaste = 1 << 14,
/// Indicate that the node has gained accessibility focus.
kFlutterSemanticsActionDidGainAccessibilityFocus = 1 << 15,
/// Indicate that the node has lost accessibility focus.
kFlutterSemanticsActionDidLoseAccessibilityFocus = 1 << 16,
/// Indicate that the user has invoked a custom accessibility action.
kFlutterSemanticsActionCustomAction = 1 << 17,
/// A request that the node should be dismissed.
kFlutterSemanticsActionDismiss = 1 << 18,
/// Move the cursor forward by one word.
kFlutterSemanticsActionMoveCursorForwardByWord = 1 << 19,
/// Move the cursor backward by one word.
kFlutterSemanticsActionMoveCursorBackwardByWord = 1 << 20,
} FlutterSemanticsAction;
/// The set of properties that may be associated with a semantics node.
///
/// Must match the `SemanticsFlag` enum in semantics.dart.
typedef enum {
/// The semantics node has the quality of either being "checked" or
/// "unchecked".
kFlutterSemanticsFlagHasCheckedState = 1 << 0,
/// Whether a semantics node is checked.
kFlutterSemanticsFlagIsChecked = 1 << 1,
/// Whether a semantics node is selected.
kFlutterSemanticsFlagIsSelected = 1 << 2,
/// Whether the semantic node represents a button.
kFlutterSemanticsFlagIsButton = 1 << 3,
/// Whether the semantic node represents a text field.
kFlutterSemanticsFlagIsTextField = 1 << 4,
/// Whether the semantic node currently holds the user's focus.
kFlutterSemanticsFlagIsFocused = 1 << 5,
/// The semantics node has the quality of either being "enabled" or
/// "disabled".
kFlutterSemanticsFlagHasEnabledState = 1 << 6,
/// Whether a semantic node that hasEnabledState is currently enabled.
kFlutterSemanticsFlagIsEnabled = 1 << 7,
/// Whether a semantic node is in a mutually exclusive group.
kFlutterSemanticsFlagIsInMutuallyExclusiveGroup = 1 << 8,
/// Whether a semantic node is a header that divides content into sections.
kFlutterSemanticsFlagIsHeader = 1 << 9,
/// Whether the value of the semantics node is obscured.
kFlutterSemanticsFlagIsObscured = 1 << 10,
/// Whether the semantics node is the root of a subtree for which a route name
/// should be announced.
kFlutterSemanticsFlagScopesRoute = 1 << 11,
/// Whether the semantics node label is the name of a visually distinct route.
kFlutterSemanticsFlagNamesRoute = 1 << 12,
/// Whether the semantics node is considered hidden.
kFlutterSemanticsFlagIsHidden = 1 << 13,
/// Whether the semantics node represents an image.
kFlutterSemanticsFlagIsImage = 1 << 14,
/// Whether the semantics node is a live region.
kFlutterSemanticsFlagIsLiveRegion = 1 << 15,
/// The semantics node has the quality of either being "on" or "off".
kFlutterSemanticsFlagHasToggledState = 1 << 16,
/// If true, the semantics node is "on". If false, the semantics node is
/// "off".
kFlutterSemanticsFlagIsToggled = 1 << 17,
/// Whether the platform can scroll the semantics node when the user attempts
/// to move the accessibility focus to an offscreen child.
///
/// For example, a `ListView` widget has implicit scrolling so that users can
/// easily move the accessibility focus to the next set of children. A
/// `PageView` widget does not have implicit scrolling, so that users don't
/// navigate to the next page when reaching the end of the current one.
kFlutterSemanticsFlagHasImplicitScrolling = 1 << 18,
/// Whether the semantic node is read only.
///
/// Only applicable when kFlutterSemanticsFlagIsTextField flag is on.
kFlutterSemanticsFlagIsReadOnly = 1 << 20,
/// Whether the semantic node can hold the user's focus.
kFlutterSemanticsFlagIsFocusable = 1 << 21,
/// Whether the semantics node represents a link.
kFlutterSemanticsFlagIsLink = 1 << 22,
/// Whether the semantics node represents a slider.
kFlutterSemanticsFlagIsSlider = 1 << 23,
/// Whether the semantics node represents a keyboard key.
kFlutterSemanticsFlagIsKeyboardKey = 1 << 24,
} FlutterSemanticsFlag;
typedef enum {
/// Text has unknown text direction.
kFlutterTextDirectionUnknown = 0,
/// Text is read from right to left.
kFlutterTextDirectionRTL = 1,
/// Text is read from left to right.
kFlutterTextDirectionLTR = 2,
} FlutterTextDirection;
typedef struct _FlutterEngine* FLUTTER_API_SYMBOL(FlutterEngine);
typedef struct {
/// horizontal scale factor
double scaleX;
/// horizontal skew factor
double skewX;
/// horizontal translation
double transX;
/// vertical skew factor
double skewY;
/// vertical scale factor
double scaleY;
/// vertical translation
double transY;
/// input x-axis perspective factor
double pers0;
/// input y-axis perspective factor
double pers1;
/// perspective scale factor
double pers2;
} FlutterTransformation;
typedef void (*VoidCallback)(void* /* user data */);
typedef enum {
/// Specifies an OpenGL texture target type. Textures are specified using
/// the FlutterOpenGLTexture struct.
kFlutterOpenGLTargetTypeTexture,
/// Specifies an OpenGL frame-buffer target type. Framebuffers are specified
/// using the FlutterOpenGLFramebuffer struct.
kFlutterOpenGLTargetTypeFramebuffer,
} FlutterOpenGLTargetType;
typedef struct {
/// Target texture of the active texture unit (example GL_TEXTURE_2D or
/// GL_TEXTURE_RECTANGLE).
uint32_t target;
/// The name of the texture.
uint32_t name;
/// The texture format (example GL_RGBA8).
uint32_t format;
/// User data to be returned on the invocation of the destruction callback.
void* user_data;
/// Callback invoked (on an engine managed thread) that asks the embedder to
/// collect the texture.
VoidCallback destruction_callback;
/// Optional parameters for texture height/width, default is 0, non-zero means
/// the texture has the specified width/height. Usually, when the texture type
/// is GL_TEXTURE_RECTANGLE, we need to specify the texture width/height to
/// tell the embedder to scale when rendering.
/// Width of the texture.
size_t width;
/// Height of the texture.
size_t height;
} FlutterOpenGLTexture;
typedef struct {
/// The target of the color attachment of the frame-buffer. For example,
/// GL_TEXTURE_2D or GL_RENDERBUFFER. In case of ambiguity when dealing with
/// Window bound frame-buffers, 0 may be used.
uint32_t target;
/// The name of the framebuffer.
uint32_t name;
/// User data to be returned on the invocation of the destruction callback.
void* user_data;
/// Callback invoked (on an engine managed thread) that asks the embedder to
/// collect the framebuffer.
VoidCallback destruction_callback;
} FlutterOpenGLFramebuffer;
typedef bool (*BoolCallback)(void* /* user data */);
typedef FlutterTransformation (*TransformationCallback)(void* /* user data */);
typedef uint32_t (*UIntCallback)(void* /* user data */);
typedef bool (*SoftwareSurfacePresentCallback)(void* /* user data */,
const void* /* allocation */,
size_t /* row bytes */,
size_t /* height */);
typedef void* (*ProcResolver)(void* /* user data */, const char* /* name */);
typedef bool (*TextureFrameCallback)(void* /* user data */,
int64_t /* texture identifier */,
size_t /* width */,
size_t /* height */,
FlutterOpenGLTexture* /* texture out */);
typedef void (*VsyncCallback)(void* /* user data */, intptr_t /* baton */);
/// A structure to represent the width and height.
typedef struct {
double width;
double height;
} FlutterSize;
/// A structure to represent the width and height.
///
/// See: \ref FlutterSize when the value are not integers.
typedef struct {
uint32_t width;
uint32_t height;
} FlutterUIntSize;
/// A structure to represent a rectangle.
typedef struct {
double left;
double top;
double right;
double bottom;
} FlutterRect;
/// A structure to represent a 2D point.
typedef struct {
double x;
double y;
} FlutterPoint;
/// A structure to represent a rounded rectangle.
typedef struct {
FlutterRect rect;
FlutterSize upper_left_corner_radius;
FlutterSize upper_right_corner_radius;
FlutterSize lower_right_corner_radius;
FlutterSize lower_left_corner_radius;
} FlutterRoundedRect;
/// This information is passed to the embedder when requesting a frame buffer
/// object.
///
/// See: \ref FlutterOpenGLRendererConfig.fbo_with_frame_info_callback.
typedef struct {
/// The size of this struct. Must be sizeof(FlutterFrameInfo).
size_t struct_size;
/// The size of the surface that will be backed by the fbo.
FlutterUIntSize size;
} FlutterFrameInfo;
/// Callback for when a frame buffer object is requested.
typedef uint32_t (*UIntFrameInfoCallback)(
void* /* user data */,
const FlutterFrameInfo* /* frame info */);
/// This information is passed to the embedder when a surface is presented.
///
/// See: \ref FlutterOpenGLRendererConfig.present_with_info.
typedef struct {
/// The size of this struct. Must be sizeof(FlutterFrameInfo).
size_t struct_size;
/// Id of the fbo backing the surface that was presented.
uint32_t fbo_id;
} FlutterPresentInfo;
/// Callback for when a surface is presented.
typedef bool (*BoolPresentInfoCallback)(
void* /* user data */,
const FlutterPresentInfo* /* present info */);
typedef struct {
/// The size of this struct. Must be sizeof(FlutterOpenGLRendererConfig).
size_t struct_size;
BoolCallback make_current;
BoolCallback clear_current;
/// Specifying one (and only one) of `present` or `present_with_info` is
/// required. Specifying both is an error and engine initialization will be
/// terminated. The return value indicates success of the present call.
BoolCallback present;
/// Specifying one (and only one) of the `fbo_callback` or
/// `fbo_with_frame_info_callback` is required. Specifying both is an error
/// and engine intialization will be terminated. The return value indicates
/// the id of the frame buffer object that flutter will obtain the gl surface
/// from.
UIntCallback fbo_callback;
/// This is an optional callback. Flutter will ask the emebdder to create a GL
/// context current on a background thread. If the embedder is able to do so,
/// Flutter will assume that this context is in the same sharegroup as the
/// main rendering context and use this context for asynchronous texture
/// uploads. Though optional, it is recommended that all embedders set this
/// callback as it will lead to better performance in texture handling.
BoolCallback make_resource_current;
/// By default, the renderer config assumes that the FBO does not change for
/// the duration of the engine run. If this argument is true, the
/// engine will ask the embedder for an updated FBO target (via an
/// fbo_callback invocation) after a present call.
bool fbo_reset_after_present;
/// The transformation to apply to the render target before any rendering
/// operations. This callback is optional.
/// @attention When using a custom compositor, the layer offset and sizes
/// will be affected by this transformation. It will be
/// embedder responsibility to render contents at the
/// transformed offset and size. This is useful for embedders
/// that want to render transformed contents directly into
/// hardware overlay planes without having to apply extra
/// transformations to layer contents (which may necessitate
/// an expensive off-screen render pass).
TransformationCallback surface_transformation;
ProcResolver gl_proc_resolver;
/// When the embedder specifies that a texture has a frame available, the
/// engine will call this method (on an internal engine managed thread) so
/// that external texture details can be supplied to the engine for subsequent
/// composition.
TextureFrameCallback gl_external_texture_frame_callback;
/// Specifying one (and only one) of the `fbo_callback` or
/// `fbo_with_frame_info_callback` is required. Specifying both is an error
/// and engine intialization will be terminated. The return value indicates
/// the id of the frame buffer object (fbo) that flutter will obtain the gl
/// surface from. When using this variant, the embedder is passed a
/// `FlutterFrameInfo` struct that indicates the properties of the surface
/// that flutter will acquire from the returned fbo.
UIntFrameInfoCallback fbo_with_frame_info_callback;
/// Specifying one (and only one) of `present` or `present_with_info` is
/// required. Specifying both is an error and engine initialization will be
/// terminated. When using this variant, the embedder is passed a
/// `FlutterPresentInfo` struct that the embedder can use to release any
/// resources. The return value indicates success of the present call.
BoolPresentInfoCallback present_with_info;
} FlutterOpenGLRendererConfig;
/// Alias for id<MTLDevice>.
typedef const void* FlutterMetalDeviceHandle;
/// Alias for id<MTLCommandQueue>.
typedef const void* FlutterMetalCommandQueueHandle;
/// Alias for id<MTLTexture>.
typedef const void* FlutterMetalTextureHandle;
/// Pixel format for the external texture.
typedef enum {
kYUVA,
kRGBA,
} FlutterMetalExternalTexturePixelFormat;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterMetalExternalTexture).
size_t struct_size;
/// Height of the texture.
size_t width;
/// Height of the texture.
size_t height;
/// The pixel format type of the external.
FlutterMetalExternalTexturePixelFormat pixel_format;
/// Represents the size of the `textures` array.
size_t num_textures;
/// Supported textures are YUVA and RGBA, in case of YUVA we expect 2 texture
/// handles to be provided by the embedder, Y first and UV next. In case of
/// RGBA only one should be passed.
/// These are individually aliases for id<MTLTexture>. These textures are
/// retained by the engine for the period of the composition. Once these
/// textures have been unregistered via the
/// `FlutterEngineUnregisterExternalTexture`, the embedder has to release
/// these textures.
FlutterMetalTextureHandle* textures;
} FlutterMetalExternalTexture;
/// Callback to provide an external texture for a given texture_id.
/// See: external_texture_frame_callback.
typedef bool (*FlutterMetalTextureFrameCallback)(
void* /* user data */,
int64_t /* texture identifier */,
size_t /* width */,
size_t /* height */,
FlutterMetalExternalTexture* /* texture out */);
typedef struct {
/// The size of this struct. Must be sizeof(FlutterMetalTexture).
size_t struct_size;
/// Embedder provided unique identifier to the texture buffer. Given that the
/// `texture` handle is passed to the engine to render to, the texture buffer
/// is itseld owned by the embedder. This `texture_id` is then also given to
/// the embedder in the present callback.
int64_t texture_id;
/// Handle to the MTLTexture that is owned by the embedder. Engine will render
/// the frame into this texture.
FlutterMetalTextureHandle texture;
/// A baton that is not interpreted by the engine in any way. It will be given
/// back to the embedder in the destruction callback below. Embedder resources
/// may be associated with this baton.
void* user_data;
/// The callback invoked by the engine when it no longer needs this backing
/// store.
VoidCallback destruction_callback;
} FlutterMetalTexture;
/// Callback for when a metal texture is requested.
typedef FlutterMetalTexture (*FlutterMetalTextureCallback)(
void* /* user data */,
const FlutterFrameInfo* /* frame info */);
/// Callback for when a metal texture is presented. The texture_id here
/// corresponds to the texture_id provided by the embedder in the
/// `FlutterMetalTextureCallback` callback.
typedef bool (*FlutterMetalPresentCallback)(
void* /* user data */,
const FlutterMetalTexture* /* texture */);
typedef struct {
/// The size of this struct. Must be sizeof(FlutterMetalRendererConfig).
size_t struct_size;
/// Alias for id<MTLDevice>.
FlutterMetalDeviceHandle device;
/// Alias for id<MTLCommandQueue>.
FlutterMetalCommandQueueHandle present_command_queue;
/// The callback that gets invoked when the engine requests the embedder for a
/// texture to render to.
FlutterMetalTextureCallback get_next_drawable_callback;
/// The callback presented to the embedder to present a fully populated metal
/// texture to the user.
FlutterMetalPresentCallback present_drawable_callback;
/// When the embedder specifies that a texture has a frame available, the
/// engine will call this method (on an internal engine managed thread) so
/// that external texture details can be supplied to the engine for subsequent
/// composition.
FlutterMetalTextureFrameCallback external_texture_frame_callback;
} FlutterMetalRendererConfig;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterSoftwareRendererConfig).
size_t struct_size;
/// The callback presented to the embedder to present a fully populated buffer
/// to the user. The pixel format of the buffer is the native 32-bit RGBA
/// format. The buffer is owned by the Flutter engine and must be copied in
/// this callback if needed.
SoftwareSurfacePresentCallback surface_present_callback;
} FlutterSoftwareRendererConfig;
typedef struct {
FlutterRendererType type;
union {
FlutterOpenGLRendererConfig open_gl;
FlutterSoftwareRendererConfig software;
FlutterMetalRendererConfig metal;
};
} FlutterRendererConfig;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterWindowMetricsEvent).
size_t struct_size;
/// Physical width of the window.
size_t width;
/// Physical height of the window.
size_t height;
/// Scale factor for the physical screen.
double pixel_ratio;
/// Horizontal physical location of the left side of the window on the screen.
size_t left;
/// Vertical physical location of the top of the window on the screen.
size_t top;
/// Top inset of window.
double physical_view_inset_top;
/// Right inset of window.
double physical_view_inset_right;
/// Bottom inset of window.
double physical_view_inset_bottom;
/// Left inset of window.
double physical_view_inset_left;
} FlutterWindowMetricsEvent;
/// The phase of the pointer event.
typedef enum {
kCancel,
/// The pointer, which must have been down (see kDown), is now up.
///
/// For touch, this means that the pointer is no longer in contact with the
/// screen. For a mouse, it means the last button was released. Note that if
/// any other buttons are still pressed when one button is released, that
/// should be sent as a kMove rather than a kUp.
kUp,
/// The pointer, which must have been been up, is now down.
///
/// For touch, this means that the pointer has come into contact with the
/// screen. For a mouse, it means a button is now pressed. Note that if any
/// other buttons are already pressed when a new button is pressed, that
/// should be sent as a kMove rather than a kDown.
kDown,
/// The pointer moved while down.
///
/// This is also used for changes in button state that don't cause a kDown or
/// kUp, such as releasing one of two pressed buttons.
kMove,
/// The pointer is now sending input to Flutter. For instance, a mouse has
/// entered the area where the Flutter content is displayed.
///
/// A pointer should always be added before sending any other events.
kAdd,
/// The pointer is no longer sending input to Flutter. For instance, a mouse
/// has left the area where the Flutter content is displayed.
///
/// A removed pointer should no longer send events until sending a new kAdd.
kRemove,
/// The pointer moved while up.
kHover,
} FlutterPointerPhase;
/// The device type that created a pointer event.
typedef enum {
kFlutterPointerDeviceKindMouse = 1,
kFlutterPointerDeviceKindTouch,
kFlutterPointerDeviceKindStylus,
} FlutterPointerDeviceKind;
/// Flags for the `buttons` field of `FlutterPointerEvent` when `device_kind`
/// is `kFlutterPointerDeviceKindMouse`.
typedef enum {
kFlutterPointerButtonMousePrimary = 1 << 0,
kFlutterPointerButtonMouseSecondary = 1 << 1,
kFlutterPointerButtonMouseMiddle = 1 << 2,
kFlutterPointerButtonMouseBack = 1 << 3,
kFlutterPointerButtonMouseForward = 1 << 4,
/// If a mouse has more than five buttons, send higher bit shifted values
/// corresponding to the button number: 1 << 5 for the 6th, etc.
} FlutterPointerMouseButtons;
/// The type of a pointer signal.
typedef enum {
kFlutterPointerSignalKindNone,
kFlutterPointerSignalKindScroll,
} FlutterPointerSignalKind;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterPointerEvent).
size_t struct_size;
FlutterPointerPhase phase;
/// The timestamp at which the pointer event was generated. The timestamp
/// should be specified in microseconds and the clock should be the same as
/// that used by `FlutterEngineGetCurrentTime`.
size_t timestamp;
/// The x coordinate of the pointer event in physical pixels.
double x;
/// The y coordinate of the pointer event in physical pixels.
double y;
/// An optional device identifier. If this is not specified, it is assumed
/// that the embedder has no multi-touch capability.
int32_t device;
FlutterPointerSignalKind signal_kind;
/// The x offset of the scroll in physical pixels.
double scroll_delta_x;
/// The y offset of the scroll in physical pixels.
double scroll_delta_y;
/// The type of the device generating this event.
/// Backwards compatibility note: If this is not set, the device will be
/// treated as a mouse, with the primary button set for `kDown` and `kMove`.
/// If set explicitly to `kFlutterPointerDeviceKindMouse`, you must set the
/// correct buttons.
FlutterPointerDeviceKind device_kind;
/// The buttons currently pressed, if any.
int64_t buttons;
} FlutterPointerEvent;
typedef enum {
kFlutterKeyEventTypeUp = 1,
kFlutterKeyEventTypeDown,
kFlutterKeyEventTypeRepeat,
} FlutterKeyEventType;
/// A structure to represent a key event.
///
/// Sending `FlutterKeyEvent` via `FlutterEngineSendKeyEvent` results in a
/// corresponding `FlutterKeyEvent` to be dispatched in the framework. It is
/// embedder's responsibility to ensure the regularity of sent events, since the
/// framework only performs simple one-to-one mapping. The events must conform
/// the following rules:
///
/// * Each key press sequence shall consist of one key down event (`kind` being
/// `kFlutterKeyEventTypeDown`), zero or more repeat events, and one key up
/// event, representing a physical key button being pressed, held, and
/// released.
/// * All events throughout a key press sequence shall have the same `physical`
/// and `logical`. Having different `character`s is allowed.
///
/// A `FlutterKeyEvent` with `physical` 0 and `logical` 0 is an empty event.
/// This is the only case either `physical` or `logical` can be 0. An empty
/// event must be sent if a key message should be converted to no
/// `FlutterKeyEvent`s, for example, when a key down message is received for a
/// key that has already been pressed according to the record. This is to ensure
/// some `FlutterKeyEvent` arrives at the framework before raw key message.
/// See https://github.com/flutter/flutter/issues/87230.
typedef struct {
/// The size of this struct. Must be sizeof(FlutterKeyEvent).
size_t struct_size;
/// The timestamp at which the key event was generated. The timestamp should
/// be specified in microseconds and the clock should be the same as that used
/// by `FlutterEngineGetCurrentTime`.
double timestamp;
/// The event kind.
FlutterKeyEventType type;
/// The USB HID code for the physical key of the event.
///
/// For the full definition and list of pre-defined physical keys, see
/// `PhysicalKeyboardKey` from the framework.
///
/// The only case that `physical` might be 0 is when this is an empty event.
/// See `FlutterKeyEvent` for introduction.
uint64_t physical;
/// The key ID for the logical key of this event.
///
/// For the full definition and a list of pre-defined logical keys, see
/// `LogicalKeyboardKey` from the framework.
///
/// The only case that `logical` might be 0 is when this is an empty event.
/// See `FlutterKeyEvent` for introduction.
uint64_t logical;
/// Null-terminated character input from the event. Can be null. Ignored for
/// up events.
const char* character;
/// True if this event does not correspond to a native event.
///
/// The embedder is likely to skip events and/or construct new events that do
/// not correspond to any native events in order to conform the regularity
/// of events (as documented in `FlutterKeyEvent`). An example is when a key
/// up is missed due to loss of window focus, on a platform that provides
/// query to key pressing status, the embedder might realize that the key has
/// been released at the next key event, and should construct a synthesized up
/// event immediately before the actual event.
///
/// An event being synthesized means that the `timestamp` might greatly
/// deviate from the actual time when the event occurs physically.
bool synthesized;
} FlutterKeyEvent;
typedef void (*FlutterKeyEventCallback)(bool /* handled */,
void* /* user_data */);
struct _FlutterPlatformMessageResponseHandle;
typedef struct _FlutterPlatformMessageResponseHandle
FlutterPlatformMessageResponseHandle;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterPlatformMessage).
size_t struct_size;
const char* channel;
const uint8_t* message;
size_t message_size;
/// The response handle on which to invoke
/// `FlutterEngineSendPlatformMessageResponse` when the response is ready.
/// `FlutterEngineSendPlatformMessageResponse` must be called for all messages
/// received by the embedder. Failure to call
/// `FlutterEngineSendPlatformMessageResponse` will cause a memory leak. It is
/// not safe to send multiple responses on a single response object.
const FlutterPlatformMessageResponseHandle* response_handle;
} FlutterPlatformMessage;
typedef void (*FlutterPlatformMessageCallback)(
const FlutterPlatformMessage* /* message*/,
void* /* user data */);
typedef void (*FlutterDataCallback)(const uint8_t* /* data */,
size_t /* size */,
void* /* user data */);
/// The identifier of the platform view. This identifier is specified by the
/// application when a platform view is added to the scene via the
/// `SceneBuilder.addPlatformView` call.
typedef int64_t FlutterPlatformViewIdentifier;
/// `FlutterSemanticsNode` ID used as a sentinel to signal the end of a batch of
/// semantics node updates.
FLUTTER_EXPORT
extern const int32_t kFlutterSemanticsNodeIdBatchEnd;
/// A node that represents some semantic data.
///
/// The semantics tree is maintained during the semantics phase of the pipeline
/// (i.e., during PipelineOwner.flushSemantics), which happens after
/// compositing. Updates are then pushed to embedders via the registered
/// `FlutterUpdateSemanticsNodeCallback`.
typedef struct {
/// The size of this struct. Must be sizeof(FlutterSemanticsNode).
size_t struct_size;
/// The unique identifier for this node.
int32_t id;
/// The set of semantics flags associated with this node.
FlutterSemanticsFlag flags;
/// The set of semantics actions applicable to this node.
FlutterSemanticsAction actions;
/// The position at which the text selection originates.
int32_t text_selection_base;
/// The position at which the text selection terminates.
int32_t text_selection_extent;
/// The total number of scrollable children that contribute to semantics.
int32_t scroll_child_count;
/// The index of the first visible semantic child of a scroll node.
int32_t scroll_index;
/// The current scrolling position in logical pixels if the node is
/// scrollable.
double scroll_position;
/// The maximum in-range value for `scrollPosition` if the node is scrollable.
double scroll_extent_max;
/// The minimum in-range value for `scrollPosition` if the node is scrollable.
double scroll_extent_min;
/// The elevation along the z-axis at which the rect of this semantics node is
/// located above its parent.
double elevation;
/// Describes how much space the semantics node takes up along the z-axis.
double thickness;
/// A textual description of the node.
const char* label;
/// A brief description of the result of performing an action on the node.
const char* hint;
/// A textual description of the current value of the node.
const char* value;
/// A value that `value` will have after a kFlutterSemanticsActionIncrease`
/// action has been performed.
const char* increased_value;
/// A value that `value` will have after a kFlutterSemanticsActionDecrease`
/// action has been performed.
const char* decreased_value;
/// The reading direction for `label`, `value`, `hint`, `increasedValue`, and
/// `decreasedValue`.
FlutterTextDirection text_direction;
/// The bounding box for this node in its coordinate system.
FlutterRect rect;
/// The transform from this node's coordinate system to its parent's
/// coordinate system.
FlutterTransformation transform;
/// The number of children this node has.
size_t child_count;
/// Array of child node IDs in traversal order. Has length `child_count`.
const int32_t* children_in_traversal_order;
/// Array of child node IDs in hit test order. Has length `child_count`.
const int32_t* children_in_hit_test_order;
/// The number of custom accessibility action associated with this node.
size_t custom_accessibility_actions_count;
/// Array of `FlutterSemanticsCustomAction` IDs associated with this node.
/// Has length `custom_accessibility_actions_count`.
const int32_t* custom_accessibility_actions;
/// Identifier of the platform view associated with this semantics node, or
/// -1 if none.
FlutterPlatformViewIdentifier platform_view_id;
} FlutterSemanticsNode;
/// `FlutterSemanticsCustomAction` ID used as a sentinel to signal the end of a
/// batch of semantics custom action updates.
FLUTTER_EXPORT
extern const int32_t kFlutterSemanticsCustomActionIdBatchEnd;
/// A custom semantics action, or action override.
///
/// Custom actions can be registered by applications in order to provide
/// semantic actions other than the standard actions available through the
/// `FlutterSemanticsAction` enum.
///
/// Action overrides are custom actions that the application developer requests
/// to be used in place of the standard actions in the `FlutterSemanticsAction`
/// enum.
typedef struct {
/// The size of the struct. Must be sizeof(FlutterSemanticsCustomAction).
size_t struct_size;
/// The unique custom action or action override ID.
int32_t id;
/// For overridden standard actions, corresponds to the
/// `FlutterSemanticsAction` to override.
FlutterSemanticsAction override_action;
/// The user-readable name of this custom semantics action.
const char* label;
/// The hint description of this custom semantics action.
const char* hint;
} FlutterSemanticsCustomAction;
typedef void (*FlutterUpdateSemanticsNodeCallback)(
const FlutterSemanticsNode* /* semantics node */,
void* /* user data */);
typedef void (*FlutterUpdateSemanticsCustomActionCallback)(
const FlutterSemanticsCustomAction* /* semantics custom action */,
void* /* user data */);
typedef struct _FlutterTaskRunner* FlutterTaskRunner;
typedef struct {
FlutterTaskRunner runner;
uint64_t task;
} FlutterTask;
typedef void (*FlutterTaskRunnerPostTaskCallback)(
FlutterTask /* task */,
uint64_t /* target time nanos */,
void* /* user data */);
/// An interface used by the Flutter engine to execute tasks at the target time
/// on a specified thread. There should be a 1-1 relationship between a thread
/// and a task runner. It is undefined behavior to run a task on a thread that
/// is not associated with its task runner.
typedef struct {
/// The size of this struct. Must be sizeof(FlutterTaskRunnerDescription).
size_t struct_size;
void* user_data;
/// May be called from any thread. Should return true if tasks posted on the
/// calling thread will be run on that same thread.
///
/// @attention This field is required.
BoolCallback runs_task_on_current_thread_callback;
/// May be called from any thread. The given task should be executed by the
/// embedder on the thread associated with that task runner by calling
/// `FlutterEngineRunTask` at the given target time. The system monotonic
/// clock should be used for the target time. The target time is the absolute
/// time from epoch (NOT a delta) at which the task must be returned back to
/// the engine on the correct thread. If the embedder needs to calculate a
/// delta, `FlutterEngineGetCurrentTime` may be called and the difference used
/// as the delta.
///
/// @attention This field is required.
FlutterTaskRunnerPostTaskCallback post_task_callback;
/// A unique identifier for the task runner. If multiple task runners service
/// tasks on the same thread, their identifiers must match.
size_t identifier;
} FlutterTaskRunnerDescription;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterCustomTaskRunners).
size_t struct_size;
/// Specify the task runner for the thread on which the `FlutterEngineRun`
/// call is made. The same task runner description can be specified for both
/// the render and platform task runners. This makes the Flutter engine use
/// the same thread for both task runners.
const FlutterTaskRunnerDescription* platform_task_runner;
/// Specify the task runner for the thread on which the render tasks will be
/// run. The same task runner description can be specified for both the render
/// and platform task runners. This makes the Flutter engine use the same
/// thread for both task runners.
const FlutterTaskRunnerDescription* render_task_runner;
} FlutterCustomTaskRunners;
typedef struct {
/// The type of the OpenGL backing store. Currently, it can either be a
/// texture or a framebuffer.
FlutterOpenGLTargetType type;
union {
/// A texture for Flutter to render into.
FlutterOpenGLTexture texture;
/// A framebuffer for Flutter to render into. The embedder must ensure that
/// the framebuffer is complete.
FlutterOpenGLFramebuffer framebuffer;
};
} FlutterOpenGLBackingStore;
typedef struct {
/// A pointer to the raw bytes of the allocation described by this software
/// backing store.
const void* allocation;
/// The number of bytes in a single row of the allocation.
size_t row_bytes;
/// The number of rows in the allocation.
size_t height;
/// A baton that is not interpreted by the engine in any way. It will be given
/// back to the embedder in the destruction callback below. Embedder resources
/// may be associated with this baton.
void* user_data;
/// The callback invoked by the engine when it no longer needs this backing
/// store.
VoidCallback destruction_callback;
} FlutterSoftwareBackingStore;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterMetalBackingStore).
size_t struct_size;
union {
// A Metal texture for Flutter to render into. Ownership is not transferred
// to Flutter; the texture is CFRetained on successfully being passed in and
// CFReleased when no longer used.
FlutterMetalTexture texture;
};
} FlutterMetalBackingStore;
typedef enum {
/// Indicates that the Flutter application requested that an opacity be
/// applied to the platform view.
kFlutterPlatformViewMutationTypeOpacity,
/// Indicates that the Flutter application requested that the platform view be
/// clipped using a rectangle.
kFlutterPlatformViewMutationTypeClipRect,
/// Indicates that the Flutter application requested that the platform view be
/// clipped using a rounded rectangle.
kFlutterPlatformViewMutationTypeClipRoundedRect,