Flutter Engine
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
 

Detailed Description

Definition at line 1169 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 1363 of file embedder.h.

Referenced by fl_engine_start(), PopulateSnapshotMappingCallbacks(), RunFlutterEngine(), flutter::FlutterWindowsEngine::RunWithEntrypoint(), and flutter::testing::EmbedderConfigBuilder::SetAOTDataElf().

◆ 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 1175 of file embedder.h.

Referenced by fl_engine_start(), FlutterEngineInitialize(), RunFlutterEngine(), flutter::FlutterWindowsEngine::RunWithEntrypoint(), and flutter::testing::EmbedderConfigBuilder::SetAssetsPath().

◆ command_line_argc

int FlutterProjectArgs::command_line_argc

The command line argument count used to initialize the project.

Definition at line 1201 of file embedder.h.

Referenced by fl_engine_start(), flutter::testing::EmbedderConfigBuilder::InitializeEngine(), RunFlutterEngine(), and flutter::FlutterWindowsEngine::RunWithEntrypoint().

◆ 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 1217 of file embedder.h.

Referenced by fl_engine_start(), flutter::testing::EmbedderConfigBuilder::InitializeEngine(), RunFlutterEngine(), and flutter::FlutterWindowsEngine::RunWithEntrypoint().

◆ 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 1348 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetCompositor().

◆ 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 1374 of file embedder.h.

Referenced by FlutterEngineInitialize(), and flutter::testing::EmbedderConfigBuilder::SetLocalizationCallbackHooks().

◆ 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 `('vm:entry-point')` decoration.

Definition at line 1308 of file embedder.h.

Referenced by FlutterEngineInitialize(), flutter::FlutterWindowsEngine::RunWithEntrypoint(), and flutter::testing::EmbedderConfigBuilder::SetDartEntrypoint().

◆ 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 1313 of file embedder.h.

Referenced by fl_engine_start(), FlutterEngineInitialize(), RunFlutterEngine(), flutter::FlutterWindowsEngine::RunWithEntrypoint(), flutter::testing::EmbedderConfigBuilder::SetPlatformTaskRunner(), and flutter::testing::EmbedderConfigBuilder::SetRenderTaskRunner().

◆ dart_entrypoint_argc

int FlutterProjectArgs::dart_entrypoint_argc

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

Definition at line 1378 of file embedder.h.

Referenced by fl_engine_start(), FlutterEngineInitialize(), and flutter::testing::EmbedderConfigBuilder::InitializeEngine().

◆ 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 1386 of file embedder.h.

Referenced by fl_engine_start(), FlutterEngineInitialize(), and flutter::testing::EmbedderConfigBuilder::InitializeEngine().

◆ 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 1355 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 1199 of file embedder.h.

Referenced by fl_engine_start(), RunFlutterEngine(), and flutter::FlutterWindowsEngine::RunWithEntrypoint().

◆ 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 1288 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 1243 of file embedder.h.

Referenced by PopulateSnapshotMappingCallbacks(), and flutter::testing::EmbedderConfigBuilder::SetSnapshots().

◆ 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 1246 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetSnapshots(), and flutter::testing::TEST_F().

◆ 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 1251 of file embedder.h.

Referenced by PopulateSnapshotMappingCallbacks(), and flutter::testing::EmbedderConfigBuilder::SetSnapshots().

◆ 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 1254 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetSnapshots(), and flutter::testing::TEST_F().

◆ 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.

Definition at line 1185 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.

Definition at line 1195 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 1284 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.

Definition at line 1222 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::EmbedderConfigBuilder(), fl_engine_start(), FlutterEngineInitialize(), RunFlutterEngine(), and flutter::FlutterWindowsEngine::RunWithEntrypoint().

◆ 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 1257 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetIsolateCreateCallbackHook().

◆ 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 1332 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::EmbedderConfigBuilder(), and fl_engine_start().

◆ struct_size

size_t FlutterProjectArgs::struct_size

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

Definition at line 1171 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::EmbedderConfigBuilder(), fl_engine_start(), RunFlutterEngine(), and flutter::FlutterWindowsEngine::RunWithEntrypoint().

◆ update_semantics_custom_action_callback

FlutterUpdateSemanticsCustomActionCallback FlutterProjectArgs::update_semantics_custom_action_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.

Definition at line 1277 of file embedder.h.

Referenced by FlutterEngineInitialize(), and flutter::testing::EmbedderConfigBuilder::SetSemanticsCallbackHooks().

◆ update_semantics_node_callback

FlutterUpdateSemanticsNodeCallback FlutterProjectArgs::update_semantics_node_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.

Definition at line 1266 of file embedder.h.

Referenced by FlutterEngineInitialize(), and flutter::testing::EmbedderConfigBuilder::SetSemanticsCallbackHooks().

◆ 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 1227 of file embedder.h.

Referenced by PopulateSnapshotMappingCallbacks(), and flutter::testing::EmbedderConfigBuilder::SetSnapshots().

◆ 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 1230 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetSnapshots(), and flutter::testing::TEST_F().

◆ 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 1235 of file embedder.h.

Referenced by PopulateSnapshotMappingCallbacks(), and flutter::testing::EmbedderConfigBuilder::SetSnapshots().

◆ 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 1238 of file embedder.h.

Referenced by flutter::testing::EmbedderConfigBuilder::SetSnapshots(), and flutter::testing::TEST_F().

◆ 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 1299 of file embedder.h.

Referenced by FlutterEngineInitialize().


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