DEV/flutter_flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2026-02-20 02:29:02 +08:00
Code Issues Packages Projects Releases Wiki Activity
flutter_flutter/shell/platform/embedder/embedder.h
Chinmay Garde c5329ef5c4
Allow embedders to schedule a callback on all engine managed threads. (#15980) 
`FlutterEnginePostCallbackOnAllNativeThreads` schedule a callback to be run on
all engine managed threads. The engine will attempt to service this callback the
next time the message loops for each managed thread is idle. Since the engine
manages the entire lifecycle of multiple threads, there is no opportunity for
the embedders to finely tune the priorities of threads directly, or, perform
other thread specific configuration (for example, setting thread names for
tracing). This callback gives embedders a chance to affect such tuning.

Fixes flutter/flutter#49551
Fixes b/143774406
Fixes b/148278215
Fixes b/148278931
2020-01-27 13:49:39 -08:00

1739 lines
78 KiB
C
Raw Blame History

// 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>
#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,
} 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,
} 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 */);
typedef struct {
/// The size of this struct. Must be sizeof(FlutterOpenGLRendererConfig).
size_t struct_size;
BoolCallback make_current;
BoolCallback clear_current;
BoolCallback present;
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;
} FlutterOpenGLRendererConfig;
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;
};
} 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;
} 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,
} 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;
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 */);
typedef struct {
double left;
double top;
double right;
double bottom;
} FlutterRect;
typedef struct {
double x;
double y;
} FlutterPoint;
typedef struct {
double width;
double height;
} FlutterSize;
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;
/// 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
/// zero 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 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,
/// Indicates that the Flutter application requested that the platform view be
/// transformed before composition.
kFlutterPlatformViewMutationTypeTransformation,
} FlutterPlatformViewMutationType;
typedef struct {
/// The type of the mutation described by the subsequent union.
FlutterPlatformViewMutationType type;
union {
double opacity;
FlutterRect clip_rect;
FlutterRoundedRect clip_rounded_rect;
FlutterTransformation transformation;
};
} FlutterPlatformViewMutation;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterPlatformView).
size_t struct_size;
/// The identifier of this platform view. This identifier is specified by the
/// application when a platform view is added to the scene via the
/// `SceneBuilder.addPlatformView` call.
FlutterPlatformViewIdentifier identifier;
/// The number of mutations to be applied to the platform view by the embedder
/// before on-screen composition.
size_t mutations_count;
/// The mutations to be applied by this platform view before it is composited
/// on-screen. The Flutter application may transform the platform view but
/// these transformations cannot be affected by the Flutter compositor because
/// it does not render platform views. Since the embedder is responsible for
/// composition of these views, it is also the embedder's responsibility to
/// affect the appropriate transformation.
///
/// The mutations must be applied in order. The mutations done in the
/// collection don't take into account the device pixel ratio or the root
/// surface transformation. If these exist, the first mutation in the list
/// will be a transformation mutation to make sure subsequent mutations are in
/// the correct coordinate space.
const FlutterPlatformViewMutation** mutations;
} FlutterPlatformView;
typedef enum {
/// Specifies an OpenGL backing store. Can either be an OpenGL texture or
/// framebuffer.
kFlutterBackingStoreTypeOpenGL,
/// Specified an software allocation for Flutter to render into using the CPU.
kFlutterBackingStoreTypeSoftware,
} FlutterBackingStoreType;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterBackingStore).
size_t struct_size;
/// A baton that is not interpreted by the engine in any way. The embedder may
/// use this to associate resources that are tied to the lifecycle of the
/// `FlutterBackingStore`.
void* user_data;
/// Specifies the type of backing store.
FlutterBackingStoreType type;
/// Indicates if this backing store was updated since the last time it was
/// associated with a presented layer.
bool did_update;
union {
/// The description of the OpenGL backing store.
FlutterOpenGLBackingStore open_gl;
/// The description of the software backing store.
FlutterSoftwareBackingStore software;
};
} FlutterBackingStore;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterBackingStoreConfig).
size_t struct_size;
/// The size of the render target the engine expects to render into.
FlutterSize size;
} FlutterBackingStoreConfig;
typedef enum {
/// Indicates that the contents of this layer are rendered by Flutter into a
/// backing store.
kFlutterLayerContentTypeBackingStore,
/// Indicates that the contents of this layer are determined by the embedder.
kFlutterLayerContentTypePlatformView,
} FlutterLayerContentType;
typedef struct {
/// This size of this struct. Must be sizeof(FlutterLayer).
size_t struct_size;
/// Each layer displays contents in one way or another. The type indicates
/// whether those contents are specified by Flutter or the embedder.
FlutterLayerContentType type;
union {
/// Indicates that the contents of this layer are rendered by Flutter into a
/// backing store.
const FlutterBackingStore* backing_store;
/// Indicates that the contents of this layer are determined by the
/// embedder.
const FlutterPlatformView* platform_view;
};
/// The offset of this layer (in physical pixels) relative to the top left of
/// the root surface used by the engine.
FlutterPoint offset;
/// The size of the layer (in physical pixels).
FlutterSize size;
} FlutterLayer;
typedef bool (*FlutterBackingStoreCreateCallback)(
const FlutterBackingStoreConfig* config,
FlutterBackingStore* backing_store_out,
void* user_data);
typedef bool (*FlutterBackingStoreCollectCallback)(
const FlutterBackingStore* renderer,
void* user_data);
typedef bool (*FlutterLayersPresentCallback)(const FlutterLayer** layers,
size_t layers_count,
void* user_data);
typedef struct {
/// This size of this struct. Must be sizeof(FlutterCompositor).
size_t struct_size;
/// A baton that in not interpreted by the engine in any way. If it passed
/// back to the embedder in `FlutterCompositor.create_backing_store_callback`,
/// `FlutterCompositor.collect_backing_store_callback` and
/// `FlutterCompositor.present_layers_callback`
void* user_data;
/// A callback invoked by the engine to obtain a backing store for a specific
/// `FlutterLayer`.
///
/// On ABI stability: Callers must take care to restrict access within
/// `FlutterBackingStore::struct_size` when specifying a new backing store to
/// the engine. This only matters if the embedder expects to be used with
/// engines older than the version whose headers it used during compilation.
FlutterBackingStoreCreateCallback create_backing_store_callback;
/// A callback invoked by the engine to release the backing store. The
/// embedder may collect any resources associated with the backing store.
FlutterBackingStoreCollectCallback collect_backing_store_callback;
/// Callback invoked by the engine to composite the contents of each layer
/// onto the screen.
FlutterLayersPresentCallback present_layers_callback;
} FlutterCompositor;
typedef struct {
/// This size of this struct. Must be sizeof(FlutterLocale).
size_t struct_size;
/// The language code of the locale. For example, "en". This is a required
/// field. The string must be null terminated. It may be collected after the
/// call to `FlutterEngineUpdateLocales`.
const char* language_code;
/// The country code of the locale. For example, "US". This is a an optional
/// field. The string must be null terminated if present. It may be collected
/// after the call to `FlutterEngineUpdateLocales`. If not present, a
/// `nullptr` may be specified.
const char* country_code;
/// The script code of the locale. This is a an optional field. The string
/// must be null terminated if present. It may be collected after the call to
/// `FlutterEngineUpdateLocales`. If not present, a `nullptr` may be
/// specified.
const char* script_code;
/// The variant code of the locale. This is a an optional field. The string
/// must be null terminated if present. It may be collected after the call to
/// `FlutterEngineUpdateLocales`. If not present, a `nullptr` may be
/// specified.
const char* variant_code;
} FlutterLocale;
typedef int64_t FlutterEngineDartPort;
typedef enum {
kFlutterEngineDartObjectTypeNull,
kFlutterEngineDartObjectTypeBool,
kFlutterEngineDartObjectTypeInt32,
kFlutterEngineDartObjectTypeInt64,
kFlutterEngineDartObjectTypeDouble,
kFlutterEngineDartObjectTypeString,
/// The object will be made available to Dart code as an instance of
/// Uint8List.
kFlutterEngineDartObjectTypeBuffer,
} FlutterEngineDartObjectType;
typedef struct {
/// The size of this struct. Must be sizeof(FlutterEngineDartBuffer).
size_t struct_size;
/// An opaque baton passed back to the embedder when the
/// buffer_collect_callback is invoked. The engine does not interpret this
/// field in any way.
void* user_data;
/// This is an optional field.
///
/// When specified, the engine will assume that the buffer is owned by the
/// embedder. When the data is no longer needed by any isolate, this callback
/// will be made on an internal engine managed thread. The embedder is free to
/// collect the buffer here. When this field is specified, it is the embedders
/// responsibility to keep the buffer alive and not modify it till this
/// callback is invoked by the engine. The user data specified in the callback
/// is the value of `user_data` field in this struct.
///
/// When NOT specified, the VM creates an internal copy of the buffer. The
/// caller is free to modify the buffer as necessary or collect it immediately
/// after the call to `FlutterEnginePostDartObject`.
///
/// @attention The buffer_collect_callback is will only be invoked by the
/// engine when the `FlutterEnginePostDartObject` method
/// returns kSuccess. In case of non-successful calls to this
/// method, it is the embedders responsibility to collect the
/// buffer.
VoidCallback buffer_collect_callback;
/// A pointer to the bytes of the buffer. When the buffer is owned by the
/// embedder (by specifying the `buffer_collect_callback`), Dart code may
/// modify that embedder owned buffer. For this reason, it is important that
/// this buffer not have page protections that restrict writing to this
/// buffer.
uint8_t* buffer;
/// The size of the buffer.
size_t buffer_size;
} FlutterEngineDartBuffer;
/// This struct specifies the native representation of a Dart object that can be
/// sent via a send port to any isolate in the VM that has the corresponding
/// receive port.
///
/// All fields in this struct are copied out in the call to
/// `FlutterEnginePostDartObject` and the caller is free to reuse or collect
/// this struct after that call.
typedef struct {
FlutterEngineDartObjectType type;
union {
bool bool_value;
int32_t int32_value;
int64_t int64_value;
double double_value;
/// A null terminated string. This string will be copied by the VM in the
/// call to `FlutterEnginePostDartObject` and must be collected by the
/// embedder after that call is made.
const char* string_value;
const FlutterEngineDartBuffer* buffer_value;
};
} FlutterEngineDartObject;
/// This enum allows embedders to determine the type of the engine thread in the
/// FlutterNativeThreadCallback. Based on the thread type, the embedder may be
/// able to tweak the thread priorities for optimum performance.
typedef enum {
/// The Flutter Engine considers the thread on which the FlutterEngineRun call
/// is made to be the platform thread. There is only one such thread per
/// engine instance.
kFlutterNativeThreadTypePlatform,
/// This is the thread the Flutter Engine uses to execute rendering commands
/// based on the selected client rendering API. There is only one such thread
/// per engine instance.
kFlutterNativeThreadTypeRender,
/// This is a dedicated thread on which the root Dart isolate is serviced.
/// There is only one such thread per engine instance.
kFlutterNativeThreadTypeUI,
/// Multiple threads are used by the Flutter engine to perform long running
/// background tasks.
kFlutterNativeThreadTypeWorker,
} FlutterNativeThreadType;
/// A callback made by the engine in response to
/// `FlutterEnginePostCallbackOnAllNativeThreads` on all internal thread.
typedef void (*FlutterNativeThreadCallback)(FlutterNativeThreadType type,
void* user_data);
typedef struct {
/// The size of this struct. Must be sizeof(FlutterProjectArgs).
size_t struct_size;
/// The path to the Flutter assets directory containing project assets. The
/// string can be collected after the call to `FlutterEngineRun` returns. The
/// string must be NULL terminated.
const char* assets_path;
/// The path to the Dart file containing the `main` entry point.
/// The string can be collected after the call to `FlutterEngineRun` returns.
/// The string must be NULL terminated.
///
/// @deprecated As of Dart 2, running from Dart source is no longer
/// supported. Dart code should now be compiled to kernel form
/// and will be loaded by from `kernel_blob.bin` in the assets
/// directory. This struct member is retained for ABI
/// stability.
const char* main_path__unused__;
/// The path to the `.packages` file for the project. The string can be
/// collected after the call to `FlutterEngineRun` returns. The string must be
/// NULL terminated.
///
/// @deprecated As of Dart 2, running from Dart source is no longer
/// supported. Dart code should now be compiled to kernel form
/// and will be loaded by from `kernel_blob.bin` in the assets
/// directory. This struct member is retained for ABI
/// stability.
const char* packages_path__unused__;
/// The path to the `icudtl.dat` file for the project. The string can be
/// collected after the call to `FlutterEngineRun` returns. The string must
/// be NULL terminated.
const char* icu_data_path;
/// The command line argument count used to initialize the project.
int command_line_argc;
/// The command line arguments used to initialize the project. The strings can
/// be collected after the call to `FlutterEngineRun` returns. The strings
/// must be `NULL` terminated.
///
/// @attention The first item in the command line (if specified at all) is
/// interpreted as the executable name. So if an engine flag
/// needs to be passed into the same, it needs to not be the
/// very first item in the list.
///
/// The set of engine flags are only meant to control
/// unstable features in the engine. Deployed applications should not pass any
/// command line arguments at all as they may affect engine stability at
/// runtime in the presence of un-sanitized input. The list of currently
/// recognized engine flags and their descriptions can be retrieved from the
/// `switches.h` engine source file.
const char* const* command_line_argv;
/// The callback invoked by the engine in order to give the embedder the
/// chance to respond to platform messages from the Dart application. The
/// callback will be invoked on the thread on which the `FlutterEngineRun`
/// call is made.
FlutterPlatformMessageCallback platform_message_callback;
/// The VM snapshot data buffer used in AOT operation. This buffer must be
/// mapped in as read-only. For more information refer to the documentation on
/// the Wiki at
/// https://github.com/flutter/flutter/wiki/Flutter-engine-operation-in-AOT-Mode
const uint8_t* vm_snapshot_data;
/// The size of the VM snapshot data buffer. If vm_snapshot_data is a symbol
/// reference, 0 may be passed here.
size_t vm_snapshot_data_size;
/// The VM snapshot instructions buffer used in AOT operation. This buffer
/// must be mapped in as read-execute. For more information refer to the
/// documentation on the Wiki at
/// https://github.com/flutter/flutter/wiki/Flutter-engine-operation-in-AOT-Mode
const uint8_t* vm_snapshot_instructions;
/// The size of the VM snapshot instructions buffer. If
/// vm_snapshot_instructions is a symbol reference, 0 may be passed here.
size_t vm_snapshot_instructions_size;
/// The isolate snapshot data buffer used in AOT operation. This buffer must
/// be mapped in as read-only. For more information refer to the documentation
/// on the Wiki at
/// https://github.com/flutter/flutter/wiki/Flutter-engine-operation-in-AOT-Mode
const uint8_t* isolate_snapshot_data;
/// The size of the isolate snapshot data buffer. If isolate_snapshot_data is
/// a symbol reference, 0 may be passed here.
size_t isolate_snapshot_data_size;
/// The isolate snapshot instructions buffer used in AOT operation. This
/// buffer must be mapped in as read-execute. For more information refer to
/// the documentation on the Wiki at
/// https://github.com/flutter/flutter/wiki/Flutter-engine-operation-in-AOT-Mode
const uint8_t* isolate_snapshot_instructions;
/// The size of the isolate snapshot instructions buffer. If
/// isolate_snapshot_instructions is a symbol reference, 0 may be passed here.
size_t isolate_snapshot_instructions_size;
/// The callback invoked by the engine in root isolate scope. Called
/// immediately after the root isolate has been created and marked runnable.
VoidCallback root_isolate_create_callback;
/// The callback invoked by the engine in order to give the embedder the
/// chance to respond to semantics node updates from the Dart application.
/// Semantics node updates are sent in batches terminated by a 'batch end'
/// callback that is passed a sentinel `FlutterSemanticsNode` whose `id` field
/// has the value `kFlutterSemanticsNodeIdBatchEnd`.
///
/// The callback will be invoked on the thread on which the `FlutterEngineRun`
/// call is made.
FlutterUpdateSemanticsNodeCallback update_semantics_node_callback;
/// The callback invoked by the engine in order to give the embedder the
/// chance to respond to updates to semantics custom actions from the Dart
/// application. Custom action updates are sent in batches terminated by a
/// 'batch end' callback that is passed a sentinel
/// `FlutterSemanticsCustomAction` whose `id` field has the value
/// `kFlutterSemanticsCustomActionIdBatchEnd`.
///
/// The callback will be invoked on the thread on which the `FlutterEngineRun`
/// call is made.
FlutterUpdateSemanticsCustomActionCallback
update_semantics_custom_action_callback;
/// Path to a directory used to store data that is cached across runs of a
/// Flutter application (such as compiled shader programs used by Skia).
/// This is optional. The string must be NULL terminated.
///
// This is different from the cache-path-dir argument defined in switches.h,
// which is used in `flutter::Settings` as `temp_directory_path`.
const char* persistent_cache_path;
/// If true, the engine would only read the existing cache, but not write new
/// ones.
bool is_persistent_cache_read_only;
/// A callback that gets invoked by the engine when it attempts to wait for a
/// platform vsync event. The engine will give the platform a baton that needs
/// to be returned back to the engine via `FlutterEngineOnVsync`. All batons
/// must be retured to the engine before initializing a
/// `FlutterEngineShutdown`. Not doing the same will result in a memory leak.
/// While the call to `FlutterEngineOnVsync` must occur on the thread that
/// made the call to `FlutterEngineRun`, the engine will make this callback on
/// an internal engine-managed thread. If the components accessed on the
/// embedder are not thread safe, the appropriate re-threading must be done.
VsyncCallback vsync_callback;
/// The name of a custom Dart entrypoint. This is optional and specifying a
/// null or empty entrypoint makes the engine look for a method named "main"
/// in the root library of the application.
///
/// Care must be taken to ensure that the custom entrypoint is not tree-shaken
/// away. Usually, this is done using the `@pragma('vm:entry-point')`
/// decoration.
const char* custom_dart_entrypoint;
/// Typically the Flutter engine create and manages its internal threads. This
/// optional argument allows for the specification of task runner interfaces
/// to event loops managed by the embedder on threads it creates.
const FlutterCustomTaskRunners* custom_task_runners;
/// All `FlutterEngine` instances in the process share the same Dart VM. When
/// the first engine is launched, it starts the Dart VM as well. It used to be
/// the case that it was not possible to shutdown the Dart VM cleanly and
/// start it back up in the process in a safe manner. This issue has since
/// been patched. Unfortunately, applications already began to make use of the
/// fact that shutting down the Flutter engine instance left a running VM in
/// the process. Since a Flutter engine could be launched on any thread,
/// applications would "warm up" the VM on another thread by launching
/// an engine with no isolates and then shutting it down immediately. The main
/// Flutter application could then be started on the main thread without
/// having to incur the Dart VM startup costs at that time. With the new
/// behavior, this "optimization" immediately becomes massive performance
/// pessimization as the VM would be started up in the "warm up" phase, shut
/// down there and then started again on the main thread. Changing this
/// behavior was deemed to be an unacceptable breaking change. Embedders that
/// wish to shutdown the Dart VM when the last engine is terminated in the
/// process should opt into this behavior by setting this flag to true.
bool shutdown_dart_vm_when_done;
/// Typically, Flutter renders the layer hierarchy into a single root surface.
/// However, when embedders need to interleave their own contents within the
/// Flutter layer hierarchy, their applications can push platform views within
/// the Flutter scene. This is done using the `SceneBuilder.addPlatformView`
/// call. When this happens, the Flutter rasterizer divides the effective view
/// hierarchy into multiple layers. Each layer gets its own backing store and
/// Flutter renders into the same. Once the layers contents have been
/// fulfilled, the embedder is asked to composite these layers on-screen. At
/// this point, it can interleave its own contents within the effective
/// hierarchy. The interface for the specification of these layer backing
/// stores and the hooks to listen for the composition of layers on-screen can
/// be controlled using this field. This field is completely optional. In its
/// absence, platforms views in the scene are ignored and Flutter renders to
/// the root surface as normal.
const FlutterCompositor* compositor;
/// Max size of the old gen heap for the Dart VM in MB, or 0 for unlimited, -1
/// for default value.
///
/// See also:
/// https://github.com/dart-lang/sdk/blob/ca64509108b3e7219c50d6c52877c85ab6a35ff2/runtime/vm/flag_list.h#L150
int64_t dart_old_gen_heap_size;
} FlutterProjectArgs;
//------------------------------------------------------------------------------
/// @brief Initialize and run a Flutter engine instance and return a handle
/// to it. This is a convenience method for the pair of calls to
/// `FlutterEngineInitialize` and `FlutterEngineRunInitialized`.
///
/// @note This method of running a Flutter engine works well except in
/// cases where the embedder specifies custom task runners via
/// `FlutterProjectArgs::custom_task_runners`. In such cases, the
/// engine may need the embedder to post tasks back to it before
/// `FlutterEngineRun` has returned. Embedders can only post tasks
/// to the engine if they have a handle to the engine. In such
/// cases, embedders are advised to get the engine handle via the
/// `FlutterInitializeCall`. Then they can call
/// `FlutterEngineRunInitialized` knowing that they will be able to
/// service custom tasks on other threads with the engine handle.
///
/// @param[in] version The Flutter embedder API version. Must be
/// FLUTTER_ENGINE_VERSION.
/// @param[in] config The renderer configuration.
/// @param[in] args The Flutter project arguments.
/// @param user_data A user data baton passed back to embedders in
/// callbacks.
/// @param[out] engine_out The engine handle on successful engine creation.
///
/// @return The result of the call to run the Flutter engine.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineRun(size_t version,
const FlutterRendererConfig* config,
const FlutterProjectArgs* args,
void* user_data,
FLUTTER_API_SYMBOL(FlutterEngine) *
engine_out);
//------------------------------------------------------------------------------
/// @brief Shuts down a Flutter engine instance. The engine handle is no
/// longer valid for any calls in the embedder API after this point.
/// Making additional calls with this handle is undefined behavior.
///
/// @note This de-initializes the Flutter engine instance (via an implicit
/// call to `FlutterEngineDeinitialize`) if necessary.
///
/// @param[in] engine The Flutter engine instance to collect.
///
/// @return The result of the call to shutdown the Flutter engine instance.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineShutdown(FLUTTER_API_SYMBOL(FlutterEngine)
engine);
//------------------------------------------------------------------------------
/// @brief Initialize a Flutter engine instance. This does not run the
/// Flutter application code till the `FlutterEngineRunInitialized`
/// call is made. Besides Flutter application code, no tasks are
/// scheduled on embedder managed task runners either. This allows
/// embedders providing custom task runners to the Flutter engine to
/// obtain a handle to the Flutter engine before the engine can post
/// tasks on these task runners.
///
/// @param[in] version The Flutter embedder API version. Must be
/// FLUTTER_ENGINE_VERSION.
/// @param[in] config The renderer configuration.
/// @param[in] args The Flutter project arguments.
/// @param user_data A user data baton passed back to embedders in
/// callbacks.
/// @param[out] engine_out The engine handle on successful engine creation.
///
/// @return The result of the call to initialize the Flutter engine.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineInitialize(size_t version,
const FlutterRendererConfig* config,
const FlutterProjectArgs* args,
void* user_data,
FLUTTER_API_SYMBOL(FlutterEngine) *
engine_out);
//------------------------------------------------------------------------------
/// @brief Stops running the Flutter engine instance. After this call, the
/// embedder is also guaranteed that no more calls to post tasks
/// onto custom task runners specified by the embedder are made. The
/// Flutter engine handle still needs to be collected via a call to
/// `FlutterEngineShutdown`.
///
/// @param[in] engine The running engine instance to de-initialize.
///
/// @return The result of the call to de-initialize the Flutter engine.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineDeinitialize(FLUTTER_API_SYMBOL(FlutterEngine)
engine);
//------------------------------------------------------------------------------
/// @brief Runs an initialized engine instance. An engine can be
/// initialized via `FlutterEngineInitialize`. An initialized
/// instance can only be run once. During and after this call,
/// custom task runners supplied by the embedder are expected to
/// start servicing tasks.
///
/// @param[in] engine An initialized engine instance that has not previously
/// been run.
///
/// @return The result of the call to run the initialized Flutter
/// engine instance.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineRunInitialized(
FLUTTER_API_SYMBOL(FlutterEngine) engine);
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineSendWindowMetricsEvent(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
const FlutterWindowMetricsEvent* event);
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineSendPointerEvent(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
const FlutterPointerEvent* events,
size_t events_count);
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineSendPlatformMessage(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
const FlutterPlatformMessage* message);
//------------------------------------------------------------------------------
/// @brief Creates a platform message response handle that allows the
/// embedder to set a native callback for a response to a message.
/// This handle may be set on the `response_handle` field of any
/// `FlutterPlatformMessage` sent to the engine.
///
/// The handle must be collected via a call to
/// `FlutterPlatformMessageReleaseResponseHandle`. This may be done
/// immediately after a call to `FlutterEngineSendPlatformMessage`
/// with a platform message whose response handle contains the handle
/// created using this call. In case a handle is created but never
/// sent in a message, the release call must still be made. Not
/// calling release on the handle results in a small memory leak.
///
/// The user data baton passed to the data callback is the one
/// specified in this call as the third argument.
///
/// @see FlutterPlatformMessageReleaseResponseHandle()
///
/// @param[in] engine A running engine instance.
/// @param[in] data_callback The callback invoked by the engine when the
/// Flutter application send a response on the
/// handle.
/// @param[in] user_data The user data associated with the data callback.
/// @param[out] response_out The response handle created when this call is
/// successful.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterPlatformMessageCreateResponseHandle(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
FlutterDataCallback data_callback,
void* user_data,
FlutterPlatformMessageResponseHandle** response_out);
//------------------------------------------------------------------------------
/// @brief Collects the handle created using
/// `FlutterPlatformMessageCreateResponseHandle`.
///
/// @see FlutterPlatformMessageCreateResponseHandle()
///
/// @param[in] engine A running engine instance.
/// @param[in] response The platform message response handle to collect.
/// These handles are created using
/// `FlutterPlatformMessageCreateResponseHandle()`.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterPlatformMessageReleaseResponseHandle(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
FlutterPlatformMessageResponseHandle* response);
//------------------------------------------------------------------------------
/// @brief Send a response from the native side to a platform message from
/// the Dart Flutter application.
///
/// @param[in] engine The running engine instance.
/// @param[in] handle The platform message response handle.
/// @param[in] data The data to associate with the platform message
/// response.
/// @param[in] data_length The length of the platform message response data.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineSendPlatformMessageResponse(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
const FlutterPlatformMessageResponseHandle* handle,
const uint8_t* data,
size_t data_length);
//------------------------------------------------------------------------------
/// @brief This API is only meant to be used by platforms that need to
/// flush tasks on a message loop not controlled by the Flutter
/// engine.
///
/// @deprecated This API will be deprecated and is not part of the stable API.
/// Please use the custom task runners API by setting an
/// appropriate `FlutterProjectArgs::custom_task_runners`
/// interface. This will yield better performance and the
/// interface is stable.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult __FlutterEngineFlushPendingTasksNow();
//------------------------------------------------------------------------------
/// @brief Register an external texture with a unique (per engine)
/// identifier. Only rendering backends that support external
/// textures accept external texture registrations. After the
/// external texture is registered, the application can mark that a
/// frame is available by calling
/// `FlutterEngineMarkExternalTextureFrameAvailable`.
///
/// @see FlutterEngineUnregisterExternalTexture()
/// @see FlutterEngineMarkExternalTextureFrameAvailable()
///
/// @param[in] engine A running engine instance.
/// @param[in] texture_identifier The identifier of the texture to register
/// with the engine. The embedder may supply new
/// frames to this texture using the same
/// identifier.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineRegisterExternalTexture(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
int64_t texture_identifier);
//------------------------------------------------------------------------------
/// @brief Unregister a previous texture registration.
///
/// @see FlutterEngineRegisterExternalTexture()
/// @see FlutterEngineMarkExternalTextureFrameAvailable()
///
/// @param[in] engine A running engine instance.
/// @param[in] texture_identifier The identifier of the texture for which new
/// frame will not be available.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineUnregisterExternalTexture(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
int64_t texture_identifier);
//------------------------------------------------------------------------------
/// @brief Mark that a new texture frame is available for a given texture
/// identifier.
///
/// @see FlutterEngineRegisterExternalTexture()
/// @see FlutterEngineUnregisterExternalTexture()
///
/// @param[in] engine A running engine instance.
/// @param[in] texture_identifier The identifier of the texture whose frame
/// has been updated.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineMarkExternalTextureFrameAvailable(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
int64_t texture_identifier);
//------------------------------------------------------------------------------
/// @brief Enable or disable accessibility semantics.
///
/// @param[in] engine A running engine instance.
/// @param[in] enabled When enabled, changes to the semantic contents of the
/// window are sent via the
/// `FlutterUpdateSemanticsNodeCallback` registered to
/// `update_semantics_node_callback` in
/// `FlutterProjectArgs`.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineUpdateSemanticsEnabled(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
bool enabled);
//------------------------------------------------------------------------------
/// @brief Sets additional accessibility features.
///
/// @param[in] engine A running engine instance
/// @param[in] features The accessibility features to set.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineUpdateAccessibilityFeatures(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
FlutterAccessibilityFeature features);
//------------------------------------------------------------------------------
/// @brief Dispatch a semantics action to the specified semantics node.
///
/// @param[in] engine A running engine instance.
/// @param[in] identifier The semantics action identifier.
/// @param[in] action The semantics action.
/// @param[in] data Data associated with the action.
/// @param[in] data_length The data length.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineDispatchSemanticsAction(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
uint64_t id,
FlutterSemanticsAction action,
const uint8_t* data,
size_t data_length);
//------------------------------------------------------------------------------
/// @brief Notify the engine that a vsync event occurred. A baton passed to
/// the platform via the vsync callback must be returned. This call
/// must be made on the thread on which the call to
/// `FlutterEngineRun` was made.
///
/// @see FlutterEngineGetCurrentTime()
///
/// @attention That frame timepoints are in nanoseconds.
///
/// @attention The system monotonic clock is used as the timebase.
///
/// @param[in] engine. A running engine instance.
/// @param[in] baton The baton supplied by the engine.
/// @param[in] frame_start_time_nanos The point at which the vsync event
/// occurred or will occur. If the time
/// point is in the future, the engine will
/// wait till that point to begin its frame
/// workload.
/// @param[in] frame_target_time_nanos The point at which the embedder
/// anticipates the next vsync to occur.
/// This is a hint the engine uses to
/// schedule Dart VM garbage collection in
/// periods in which the various threads
/// are most likely to be idle. For
/// example, for a 60Hz display, embedders
/// should add 16.6 * 1e6 to the frame time
/// field.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineOnVsync(FLUTTER_API_SYMBOL(FlutterEngine)
engine,
intptr_t baton,
uint64_t frame_start_time_nanos,
uint64_t frame_target_time_nanos);
//------------------------------------------------------------------------------
/// @brief Reloads the system fonts in engine.
///
/// @param[in] engine. A running engine instance.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineReloadSystemFonts(
FLUTTER_API_SYMBOL(FlutterEngine) engine);
//------------------------------------------------------------------------------
/// @brief A profiling utility. Logs a trace duration begin event to the
/// timeline. If the timeline is unavailable or disabled, this has
/// no effect. Must be balanced with an duration end event (via
/// `FlutterEngineTraceEventDurationEnd`) with the same name on the
/// same thread. Can be called on any thread. Strings passed into
/// the function will NOT be copied when added to the timeline. Only
/// string literals may be passed in.
///
/// @param[in] name The name of the trace event.
///
FLUTTER_EXPORT
void FlutterEngineTraceEventDurationBegin(const char* name);
//-----------------------------------------------------------------------------
/// @brief A profiling utility. Logs a trace duration end event to the
/// timeline. If the timeline is unavailable or disabled, this has
/// no effect. This call must be preceded by a trace duration begin
/// call (via `FlutterEngineTraceEventDurationBegin`) with the same
/// name on the same thread. Can be called on any thread. Strings
/// passed into the function will NOT be copied when added to the
/// timeline. Only string literals may be passed in.
///
/// @param[in] name The name of the trace event.
///
FLUTTER_EXPORT
void FlutterEngineTraceEventDurationEnd(const char* name);
//-----------------------------------------------------------------------------
/// @brief A profiling utility. Logs a trace duration instant event to the
/// timeline. If the timeline is unavailable or disabled, this has
/// no effect. Can be called on any thread. Strings passed into the
/// function will NOT be copied when added to the timeline. Only
/// string literals may be passed in.
///
/// @param[in] name The name of the trace event.
///
FLUTTER_EXPORT
void FlutterEngineTraceEventInstant(const char* name);
//------------------------------------------------------------------------------
/// @brief Posts a task onto the Flutter render thread. Typically, this may
/// be called from any thread as long as a `FlutterEngineShutdown`
/// on the specific engine has not already been initiated.
///
/// @param[in] engine A running engine instance.
/// @param[in] callback The callback to execute on the render thread.
/// @param callback_data The callback context.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEnginePostRenderThreadTask(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
VoidCallback callback,
void* callback_data);
//------------------------------------------------------------------------------
/// @brief Get the current time in nanoseconds from the clock used by the
/// flutter engine. This is the system monotonic clock.
///
/// @return The current time in nanoseconds.
///
FLUTTER_EXPORT
uint64_t FlutterEngineGetCurrentTime();
//------------------------------------------------------------------------------
/// @brief Inform the engine to run the specified task. This task has been
/// given to the engine via the
/// `FlutterTaskRunnerDescription.post_task_callback`. This call
/// must only be made at the target time specified in that callback.
/// Running the task before that time is undefined behavior.
///
/// @param[in] engine A running engine instance.
/// @param[in] task the task handle.
///
/// @return The result of the call.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineRunTask(FLUTTER_API_SYMBOL(FlutterEngine)
engine,
const FlutterTask* task);
//------------------------------------------------------------------------------
/// @brief Notify a running engine instance that the locale has been
/// updated. The preferred locale must be the first item in the list
/// of locales supplied. The other entries will be used as a
/// fallback.
///
/// @param[in] engine A running engine instance.
/// @param[in] locales The updated locales in the order of preference.
/// @param[in] locales_count The count of locales supplied.
///
/// @return Whether the locale updates were applied.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineUpdateLocales(FLUTTER_API_SYMBOL(FlutterEngine)
engine,
const FlutterLocale** locales,
size_t locales_count);
//------------------------------------------------------------------------------
/// @brief Returns if the Flutter engine instance will run AOT compiled
/// Dart code. This call has no threading restrictions.
///
/// For embedder code that is configured for both AOT and JIT mode
/// Dart execution based on the Flutter engine being linked to, this
/// runtime check may be used to appropriately configure the
/// `FlutterProjectArgs`. In JIT mode execution, the kernel
/// snapshots must be present in the Flutter assets directory
/// specified in the `FlutterProjectArgs`. For AOT execution, the
/// fields `vm_snapshot_data`, `vm_snapshot_instructions`,
/// `isolate_snapshot_data` and `isolate_snapshot_instructions`
/// (along with their size fields) must be specified in
/// `FlutterProjectArgs`.
///
/// @return True, if AOT Dart code is run. JIT otherwise.
///
FLUTTER_EXPORT
bool FlutterEngineRunsAOTCompiledDartCode(void);
//------------------------------------------------------------------------------
/// @brief Posts a Dart object to specified send port. The corresponding
/// receive port for send port can be in any isolate running in the
/// VM. This isolate can also be the root isolate for an
/// unrelated engine. The engine parameter is necessary only to
/// ensure the call is not made when no engine (and hence no VM) is
/// running.
///
/// Unlike the platform messages mechanism, there are no threading
/// restrictions when using this API. Message can be posted on any
/// thread and they will be made available to isolate on which the
/// corresponding send port is listening.
///
/// However, it is the embedders responsibility to ensure that the
/// call is not made during an ongoing call the
/// `FlutterEngineDeinitialize` or `FlutterEngineShutdown` on
/// another thread.
///
/// @param[in] engine A running engine instance.
/// @param[in] port The send port to send the object to.
/// @param[in] object The object to send to the isolate with the
/// corresponding receive port.
///
/// @return If the message was posted to the send port.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEnginePostDartObject(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
FlutterEngineDartPort port,
const FlutterEngineDartObject* object);
//------------------------------------------------------------------------------
/// @brief Posts a low memory notification to a running engine instance.
/// The engine will do its best to release non-critical resources in
/// response. It is not guaranteed that the resource would have been
/// collected by the time this call returns however. The
/// notification is posted to engine subsystems that may be
/// operating on other threads.
///
/// Flutter applications can respond to these notifications by
/// setting `WidgetsBindingObserver.didHaveMemoryPressure`
/// observers.
///
/// @param[in] engine A running engine instance.
///
/// @return If the low memory notification was sent to the running engine
/// instance.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEngineNotifyLowMemoryWarning(
FLUTTER_API_SYMBOL(FlutterEngine) engine);
//------------------------------------------------------------------------------
/// @brief Schedule a callback to be run on all engine managed threads.
/// The engine will attempt to service this callback the next time
/// the message loop for each managed thread is idle. Since the
/// engine manages the entire lifecycle of multiple threads, there
/// is no opportunity for the embedders to finely tune the
/// priorities of threads directly, or, perform other thread
/// specific configuration (for example, setting thread names for
/// tracing). This callback gives embedders a chance to affect such
/// tuning.
///
/// @attention This call is expensive and must be made as few times as
/// possible. The callback must also return immediately as not doing
/// so may risk performance issues (especially for callbacks of type
/// kFlutterNativeThreadTypeUI and kFlutterNativeThreadTypeRender).
///
/// @attention Some callbacks (especially the ones of type
/// kFlutterNativeThreadTypeWorker) may be called after the
/// FlutterEngine instance has shut down. Embedders must be careful
/// in handling the lifecycle of objects associated with the user
/// data baton.
///
/// @attention In case there are multiple running Flutter engine instances,
/// their workers are shared.
///
/// @param[in] engine A running engine instance.
/// @param[in] callback The callback that will get called multiple times on
/// each engine managed thread.
/// @param[in] user_data A baton passed by the engine to the callback. This
/// baton is not interpreted by the engine in any way.
///
/// @return Returns if the callback was successfully posted to all threads.
///
FLUTTER_EXPORT
FlutterEngineResult FlutterEnginePostCallbackOnAllNativeThreads(
FLUTTER_API_SYMBOL(FlutterEngine) engine,
FlutterNativeThreadCallback callback,
void* user_data);
#if defined(__cplusplus)
} // extern "C"
#endif
#endif // FLUTTER_EMBEDDER_H_
Reference in New Issue View Git Blame Copy Permalink