diff --git a/docs/building/application-descriptor-files/elements/android.md b/docs/building/application-descriptor-files/elements/android.md index 401ae4214..6ce6e63a2 100644 --- a/docs/building/application-descriptor-files/elements/android.md +++ b/docs/building/application-descriptor-files/elements/android.md @@ -349,3 +349,26 @@ For example: ``` + + +### `asyncStartup` + +Available: 51.3.1.1 + +An asynchronous startup mechanism for the Android AIR runtime was introduced in version 51.2.2.4 to address a slow start-up metric from the "Android Vitals" dashboard. However, +this appears to have had a side-effect for some applications that need the bootstrap mechanism to be completed within the "onCreate" Android activity call. This setting has +been added so that the default behaviour (`true`) can be overridden to turn off the asynchronous elements of the Android bootstrapping. + +As well as removing the deliberate delay intended to improve the start-up metric, this also means that the application does not wait in case the Adobe Scout settings have not +yet been retrieved from the helper service (when configured by the Adobe Scout mobile helper application). This could mean that Scout connectivity is not consistent; a mechanism +to address this should be added into a later 51.3 release. + + +### `useCamera2` + +Available: 51.3.1.1 + +An update was made in the Android runtime classes to use the `android.hardware.camera2` package when an AIR application requests a `flash.media.Camera` object. This has been +introduced in 51.3 but has been made optional, because an issue in the supported formats provided by Android means that the frame retrieval may not be efficient, resulting in +performance issues or a low frame rate. To enable the use of `camera2`, this setting will need to be set to `true`. + diff --git a/docs/building/application-descriptor-files/elements/application.md b/docs/building/application-descriptor-files/elements/application.md index 3abb015a5..32d9c121b 100644 --- a/docs/building/application-descriptor-files/elements/application.md +++ b/docs/building/application-descriptor-files/elements/application.md @@ -469,6 +469,7 @@ The `application` element can also contain other elements that are described fur - [`android`](android.md) - [`macOS`](macOS.md) - [`windows`](windows.md) +- [`systemConfig`](systemConfig.md) ## Localisation diff --git a/docs/building/application-descriptor-files/elements/systemConfig.md b/docs/building/application-descriptor-files/elements/systemConfig.md new file mode 100644 index 000000000..221588e2b --- /dev/null +++ b/docs/building/application-descriptor-files/elements/systemConfig.md @@ -0,0 +1,61 @@ +--- +title: systemConfig +sidebar_position: 9 +--- + +The `systemConfig` element provides access to a number of generic settings that can adjust the underlying behaviour of the ActionScript virtual machine within the AIR runtime. +The VM is based upon the open source `avmplus` component, available at https://github.com/adobe/avmplus/tree/master, and the below descriptions might refer to this and to code +or documentation associated with it such as the [GC Policy](https://github.com/adobe/avmplus/blob/master/doc/mmgc/policy.txt). + +All of the elements are optional with the default values mentioned in the descriptions. + + +## Elements + +### `stackOverflowChecks` + +Available: 51.3.1.1 + +Determines whether or not the JIT compiler generates checks for stack overflows when entering an AS3 function. Normally/historically these checks are made to ensure that +the application does not use too much stack space and allows an application to receive and handle a `StackOverflowError` to avoid the application aborting. However, this can +come at a cost for JIT-compiled methods and is not generally such an issue for a lot of AIR applications, so it is now possible to avoid these checks from being injected. + +Possible values for this setting are: +- `always` (default behaviour) where the checks are always injected, to match previous behaviour. +- `never` where the JIT will not inject any checks which may improve performance and reduce code memory usage +- `debugOnly` where checks will be injected only for a SWF that has debug information within it (i.e. compiled with the `-debug` mxmlc flag) + + +### `gcCollectionThreshold` + +Available: 51.3.1.1 + +This parameter can be used to adjust the Garbage Collection mechanism within the AIR runtime. The collection threshold is the amount of memory that the runtime aims to +use up before it then collects some via the internal GC mark-and-sweep method. A higher value uses more memory but can reduce the time spent in GC. + +The value is given as a number of 4kb blocks, with the internal default now set at 5120 blocks which is equivalent to 20MB (5120x4x1024). + +Adding a value here will result in a call to [`GCPolicyManager::setLowerLimitCollectionThreshold()`](https://github.com/adobe/avmplus/blob/858d034a3bd3a54d9b70909386435cf4aec81d21/MMgc/GCPolicyManager.cpp#L384). + + +### `gcEfficiency` + +Available: 51.3.1.1 + +The efficiency coefficient is the intended ratio of GC work to program work, referenced as `G` in the [GC Policy document](https://github.com/adobe/avmplus/blob/858d034a3bd3a54d9b70909386435cf4aec81d21/doc/mmgc/policy.txt#L35). This value must be at least 0.01 and less than 1, with a default value of 0.25. Adjusting this value may limit the number/length of pauses that happen +due to GC activity but this may result in other side-effects such as an increase in the amount of memory consumed by the application. + +Adding a value here will result in a change of the [`GCPolicyManager::G`](https://github.com/adobe/avmplus/blob/858d034a3bd3a54d9b70909386435cf4aec81d21/MMgc/GCPolicyManager.h#L573) variable. + + +### `gcMarkingTime` + +Available: 51.3.1.1 + +This value is the intended maximum time slice spent doing incremental marking i.e. where activity is paused but for only a small period. +This is different from the collection time which is the more noticeable delay when the GC has finished marking and has a “stop-the-world” period to free +up the unused objects. In the [GC Policy document](https://github.com/adobe/avmplus/blob/858d034a3bd3a54d9b70909386435cf4aec81d21/doc/mmgc/policy.txt#L32) +this value is referred to as `P`. It is given here in milliseconds, with a default of 5. + +Adding a value here will result in a change of the [`GCPolicyManager::P`](https://github.com/adobe/avmplus/blob/858d034a3bd3a54d9b70909386435cf4aec81d21/MMgc/GCPolicyManager.h#L555) variable. + diff --git a/docs/building/application-descriptor-files/elements/windows.md b/docs/building/application-descriptor-files/elements/windows.md index 17a54a368..478b7eb76 100644 --- a/docs/building/application-descriptor-files/elements/windows.md +++ b/docs/building/application-descriptor-files/elements/windows.md @@ -39,4 +39,28 @@ This setting can be used to retrieve the full Windows clipboard entry for HTML s To ensure the full clipboard contents are retrieved for HTML strings, set the value to `true`. +### `localAppData` + +(optional) + +Available: 51.3.1.1 + +This setting determines where the application's local storage folder is located (i.e. `File.applicationStorageDirectory`). Normally this is under the standard "AppData" folder +on Windows, as determined by the `%APPDATA%` environment variable, which is under a "Roaming" folder. If this setting is configured as `true` then the "Local" folder will be used +instead, i.e. the application storage directory will be a subfolder of the path given by the `%LOCALAPPDATA%` environment variable. + + +### `useDirectDrawFonts` + +(optional) + +Available: 51.3.1.1 + +Font rendering for FTE-based text lines was updated in AIR SDK 51.2 to use DirectDraw/DirectWrite, which allowed for colored emoji characters to be suported. However, some +computer systems display some poor behaviour (memory leaks and system hangs) when this is used, so this setting has been introduced as a mechanism by which developers can turn +off the use of the DirectX graphics system for font rendering (switching back to the earlier GDI-based font support). The default value is `true` so that existing behaviour will +not change if the value is omitted. + +Note that the DirectDraw font rendering is carried out in a different library (DDrawFontSupport.dll) due to dependencies on Windows versions/APIs, and if the setting here had +been set to `false`, this library will not be packaged up when creating an application bundle on Windows.