Flutter Engine
The Flutter Engine
Public Attributes | List of all members
FlutterProjectArgs Struct Reference

#include <embedder.h>

Public Attributes

size_t struct_size
 The size of this struct. Must be sizeof(FlutterProjectArgs). More...
 
const char * assets_path
 
const char * main_path__unused__
 
const char * packages_path__unused__
 
const char * icu_data_path
 
int command_line_argc
 The command line argument count used to initialize the project. More...
 
const char *const * command_line_argv
 
FlutterPlatformMessageCallback platform_message_callback
 
const uint8_t * vm_snapshot_data
 
size_t vm_snapshot_data_size
 
const uint8_t * vm_snapshot_instructions
 
size_t vm_snapshot_instructions_size
 
const uint8_t * isolate_snapshot_data
 
size_t isolate_snapshot_data_size
 
const uint8_t * isolate_snapshot_instructions
 
size_t isolate_snapshot_instructions_size
 
VoidCallback root_isolate_create_callback
 
FlutterUpdateSemanticsNodeCallback update_semantics_node_callback
 
FlutterUpdateSemanticsCustomActionCallback update_semantics_custom_action_callback
 
const char * persistent_cache_path
 
bool is_persistent_cache_read_only
 
VsyncCallback vsync_callback
 
const char * custom_dart_entrypoint
 
const FlutterCustomTaskRunnerscustom_task_runners
 
bool shutdown_dart_vm_when_done
 
const FlutterCompositorcompositor
 
int64_t dart_old_gen_heap_size
 
FlutterEngineAOTData aot_data
 
FlutterComputePlatformResolvedLocaleCallback compute_platform_resolved_locale_callback
 
int dart_entrypoint_argc
 
const char *const * dart_entrypoint_argv
 
FlutterLogMessageCallback log_message_callback
 
const char * log_tag
 
OnPreEngineRestartCallback on_pre_engine_restart_callback
 
FlutterUpdateSemanticsCallback update_semantics_callback
 
FlutterUpdateSemanticsCallback2 update_semantics_callback2
 
FlutterChannelUpdateCallback channel_update_callback
 

Detailed Description

Definition at line 2138 of file embedder.h.

Member Data Documentation

◆ aot_data

FlutterEngineAOTData FlutterProjectArgs::aot_data

The AOT data to be used in AOT operation.

Embedders should instantiate and destroy this object via the FlutterEngineCreateAOTData and FlutterEngineCollectAOTData methods.

Embedders can provide either snapshot buffers or aot_data, but not both.

Definition at line 2353 of file embedder.h.

◆ assets_path

const char* FlutterProjectArgs::assets_path

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.

Definition at line 2144 of file embedder.h.

◆ channel_update_callback

FlutterChannelUpdateCallback FlutterProjectArgs::channel_update_callback

The callback invoked by the engine in response to a channel listener being registered on the framework side. The callback is invoked from a task posted to the platform thread.

Definition at line 2436 of file embedder.h.

◆ command_line_argc

int FlutterProjectArgs::command_line_argc

The command line argument count used to initialize the project.

Definition at line 2170 of file embedder.h.

◆ command_line_argv

const char* const* FlutterProjectArgs::command_line_argv

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.

Definition at line 2186 of file embedder.h.

◆ compositor

const FlutterCompositor* FlutterProjectArgs::compositor

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.

Definition at line 2338 of file embedder.h.

◆ compute_platform_resolved_locale_callback

FlutterComputePlatformResolvedLocaleCallback FlutterProjectArgs::compute_platform_resolved_locale_callback

A callback that computes the locale the platform would natively resolve to.

The input parameter is an array of FlutterLocales which represent the locales supported by the app. One of the input supported locales should be selected and returned to best match with the user/device's preferred locale. The implementation should produce a result that as closely matches what the platform would natively resolve to as possible.

Definition at line 2364 of file embedder.h.

◆ custom_dart_entrypoint

const char* FlutterProjectArgs::custom_dart_entrypoint

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.

Definition at line 2298 of file embedder.h.

◆ custom_task_runners

const FlutterCustomTaskRunners* FlutterProjectArgs::custom_task_runners

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.

Definition at line 2303 of file embedder.h.

◆ dart_entrypoint_argc

int FlutterProjectArgs::dart_entrypoint_argc

The command line argument count for arguments passed through to the Dart entrypoint.

Definition at line 2368 of file embedder.h.

◆ dart_entrypoint_argv

const char* const* FlutterProjectArgs::dart_entrypoint_argv

The command line arguments passed through to the Dart entrypoint. The strings must be NULL terminated.

The strings will be copied out and so any strings passed in here can be safely collected after initializing the engine with FlutterProjectArgs.

Definition at line 2376 of file embedder.h.

◆ dart_old_gen_heap_size

int64_t FlutterProjectArgs::dart_old_gen_heap_size

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

Definition at line 2345 of file embedder.h.

◆ icu_data_path

const char* FlutterProjectArgs::icu_data_path

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.

Definition at line 2168 of file embedder.h.

◆ is_persistent_cache_read_only

bool FlutterProjectArgs::is_persistent_cache_read_only

If true, the engine would only read the existing cache, but not write new ones.

Definition at line 2278 of file embedder.h.

◆ isolate_snapshot_data

const uint8_t* FlutterProjectArgs::isolate_snapshot_data

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

Definition at line 2213 of file embedder.h.

◆ isolate_snapshot_data_size

size_t FlutterProjectArgs::isolate_snapshot_data_size

The size of the isolate snapshot data buffer. If isolate_snapshot_data is a symbol reference, 0 may be passed here.

Definition at line 2216 of file embedder.h.

◆ isolate_snapshot_instructions

const uint8_t* FlutterProjectArgs::isolate_snapshot_instructions

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

Definition at line 2221 of file embedder.h.

◆ isolate_snapshot_instructions_size

size_t FlutterProjectArgs::isolate_snapshot_instructions_size

The size of the isolate snapshot instructions buffer. If isolate_snapshot_instructions is a symbol reference, 0 may be passed here.

Definition at line 2224 of file embedder.h.

◆ log_message_callback

FlutterLogMessageCallback FlutterProjectArgs::log_message_callback

Definition at line 2384 of file embedder.h.

◆ log_tag

const char* FlutterProjectArgs::log_tag

Definition at line 2391 of file embedder.h.

◆ main_path__unused__

const char* FlutterProjectArgs::main_path__unused__

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.

Definition at line 2154 of file embedder.h.

◆ on_pre_engine_restart_callback

OnPreEngineRestartCallback FlutterProjectArgs::on_pre_engine_restart_callback

Definition at line 2401 of file embedder.h.

◆ packages_path__unused__

const char* FlutterProjectArgs::packages_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.

Definition at line 2164 of file embedder.h.

◆ persistent_cache_path

const char* FlutterProjectArgs::persistent_cache_path

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.

Definition at line 2274 of file embedder.h.

◆ platform_message_callback

FlutterPlatformMessageCallback FlutterProjectArgs::platform_message_callback

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. The second parameter, user_data, is supplied when FlutterEngineRun or FlutterEngineInitialize is called.

Definition at line 2192 of file embedder.h.

◆ root_isolate_create_callback

VoidCallback FlutterProjectArgs::root_isolate_create_callback

The callback invoked by the engine in root isolate scope. Called immediately after the root isolate has been created and marked runnable.

Definition at line 2227 of file embedder.h.

◆ shutdown_dart_vm_when_done

bool FlutterProjectArgs::shutdown_dart_vm_when_done

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.

Definition at line 2322 of file embedder.h.

◆ struct_size

size_t FlutterProjectArgs::struct_size

The size of this struct. Must be sizeof(FlutterProjectArgs).

Definition at line 2140 of file embedder.h.

◆ update_semantics_callback

FlutterUpdateSemanticsCallback FlutterProjectArgs::update_semantics_callback

The callback invoked by the engine in order to give the embedder the chance to respond to updates to semantics nodes and custom actions from the Dart application.

The callback will be invoked on the thread on which the FlutterEngineRun call is made.

Deprecated:
Use update_semantics_callback2 instead. Only one of update_semantics_node_callback, update_semantics_callback, and update_semantics_callback2 may be provided; the others must be set to null.

This callback is incompatible with multiple views. If this callback is provided, FlutterEngineAddView and FlutterEngineRemoveView should not be used.

Definition at line 2419 of file embedder.h.

◆ update_semantics_callback2

FlutterUpdateSemanticsCallback2 FlutterProjectArgs::update_semantics_callback2

The callback invoked by the engine in order to give the embedder the chance to respond to updates to semantics nodes and custom actions from the Dart application.

The callback will be invoked on the thread on which the FlutterEngineRun call is made.

Only one of update_semantics_node_callback, update_semantics_callback, and update_semantics_callback2 may be provided; the others must be set to null.

Definition at line 2431 of file embedder.h.

◆ update_semantics_custom_action_callback

FlutterUpdateSemanticsCustomActionCallback FlutterProjectArgs::update_semantics_custom_action_callback

The legacy 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.

Deprecated:
Use update_semantics_callback2 instead. Only one of update_semantics_node_callback, update_semantics_callback, and update_semantics_callback2 may be provided; the others should be set to null.

This callback is incompatible with multiple views. If this callback is provided, FlutterEngineAddView and FlutterEngineRemoveView should not be used.

Definition at line 2267 of file embedder.h.

◆ update_semantics_node_callback

FlutterUpdateSemanticsNodeCallback FlutterProjectArgs::update_semantics_node_callback

The legacy 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.

Deprecated:
Use update_semantics_callback2 instead. Only one of update_semantics_node_callback, update_semantics_callback, and update_semantics_callback2 may be provided; the others should be set to null.

This callback is incompatible with multiple views. If this callback is provided, FlutterEngineAddView and FlutterEngineRemoveView should not be used.

Definition at line 2246 of file embedder.h.

◆ vm_snapshot_data

const uint8_t* FlutterProjectArgs::vm_snapshot_data

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

Definition at line 2197 of file embedder.h.

◆ vm_snapshot_data_size

size_t FlutterProjectArgs::vm_snapshot_data_size

The size of the VM snapshot data buffer. If vm_snapshot_data is a symbol reference, 0 may be passed here.

Definition at line 2200 of file embedder.h.

◆ vm_snapshot_instructions

const uint8_t* FlutterProjectArgs::vm_snapshot_instructions

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

Definition at line 2205 of file embedder.h.

◆ vm_snapshot_instructions_size

size_t FlutterProjectArgs::vm_snapshot_instructions_size

The size of the VM snapshot instructions buffer. If vm_snapshot_instructions is a symbol reference, 0 may be passed here.

Definition at line 2208 of file embedder.h.

◆ vsync_callback

VsyncCallback FlutterProjectArgs::vsync_callback

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.

Definition at line 2289 of file embedder.h.


The documentation for this struct was generated from the following file: