Add support for global view culling outset ratio setting (#53845)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/53845

Adding a feature flag controlling the outset ratio set on the culling context frame. This feature flag value will add an outset on the width and height calculated by multiplying these with the provided ratio value. This will offset each side of the frame, maintaining the center of the frame at the same location.

This outset ratio helps mitigate async scroll blanking and focus handling on host platforms.

Changelog: [Internal]

Reviewed By: mdvacca

Differential Revision: D82684027

fbshipit-source-id: 3d1aaf680c5896fd4bb992b272b650ab2c097905
This commit is contained in:
Nick Lefever
2025-09-28 15:13:07 -07:00
committed by Facebook GitHub Bot
parent fb09b37646
commit 2f40224faf
21 changed files with 153 additions and 22 deletions
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<6b632ac7553ae149fa42a67efde5acfa>>
* @generated SignedSource<<f707e26d09b6f7962ec97296a1a215b6>>
*/
/**
@@ -468,6 +468,12 @@ public object ReactNativeFeatureFlags {
@JvmStatic
public fun useTurboModules(): Boolean = accessor.useTurboModules()
/**
* Outset the culling context frame with the provided ratio. The culling context frame size will be outset by width * ratio on the left and right, and height * ratio on the top and bottom.
*/
@JvmStatic
public fun viewCullingOutsetRatio(): Double = accessor.viewCullingOutsetRatio()
/**
* Sets a hysteresis window for transition between prerender and hidden modes.
*/
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<c228bdbf6120b4715f49e03c04918a7c>>
* @generated SignedSource<<e7cfc5135c7b3c731324297e92e41e3f>>
*/
/**
@@ -93,6 +93,7 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
private var useShadowNodeStateOnCloneCache: Boolean? = null
private var useTurboModuleInteropCache: Boolean? = null
private var useTurboModulesCache: Boolean? = null
private var viewCullingOutsetRatioCache: Double? = null
private var virtualViewHysteresisRatioCache: Double? = null
private var virtualViewPrerenderRatioCache: Double? = null
@@ -753,6 +754,15 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
return cached
}
override fun viewCullingOutsetRatio(): Double {
var cached = viewCullingOutsetRatioCache
if (cached == null) {
cached = ReactNativeFeatureFlagsCxxInterop.viewCullingOutsetRatio()
viewCullingOutsetRatioCache = cached
}
return cached
}
override fun virtualViewHysteresisRatio(): Double {
var cached = virtualViewHysteresisRatioCache
if (cached == null) {
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<26dce1945df5641ab84cbca9eaf2b10f>>
* @generated SignedSource<<3254fef626b10ef21d8d9ee1bdbb1880>>
*/
/**
@@ -174,6 +174,8 @@ public object ReactNativeFeatureFlagsCxxInterop {
@DoNotStrip @JvmStatic public external fun useTurboModules(): Boolean
@DoNotStrip @JvmStatic public external fun viewCullingOutsetRatio(): Double
@DoNotStrip @JvmStatic public external fun virtualViewHysteresisRatio(): Double
@DoNotStrip @JvmStatic public external fun virtualViewPrerenderRatio(): Double
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<11051ece1b61fd4bf4ca003a3b7fc4f9>>
* @generated SignedSource<<9f7eb1bb5e24fd8ee87accf60209cce3>>
*/
/**
@@ -169,6 +169,8 @@ public open class ReactNativeFeatureFlagsDefaults : ReactNativeFeatureFlagsProvi
override fun useTurboModules(): Boolean = false
override fun viewCullingOutsetRatio(): Double = 0.0
override fun virtualViewHysteresisRatio(): Double = 0.0
override fun virtualViewPrerenderRatio(): Double = 5.0
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<66fa583c37021750123a483ab0ccb030>>
* @generated SignedSource<<9e6e04ca37edd1ad9265b74e251ff4de>>
*/
/**
@@ -97,6 +97,7 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
private var useShadowNodeStateOnCloneCache: Boolean? = null
private var useTurboModuleInteropCache: Boolean? = null
private var useTurboModulesCache: Boolean? = null
private var viewCullingOutsetRatioCache: Double? = null
private var virtualViewHysteresisRatioCache: Double? = null
private var virtualViewPrerenderRatioCache: Double? = null
@@ -830,6 +831,16 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
return cached
}
override fun viewCullingOutsetRatio(): Double {
var cached = viewCullingOutsetRatioCache
if (cached == null) {
cached = currentProvider.viewCullingOutsetRatio()
accessedFeatureFlags.add("viewCullingOutsetRatio")
viewCullingOutsetRatioCache = cached
}
return cached
}
override fun virtualViewHysteresisRatio(): Double {
var cached = virtualViewHysteresisRatioCache
if (cached == null) {
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<f26998daf87c8b90c2ec822c8316b134>>
* @generated SignedSource<<65e895433fc609bd7c2b5d7faa507f46>>
*/
/**
@@ -169,6 +169,8 @@ public interface ReactNativeFeatureFlagsProvider {
@DoNotStrip public fun useTurboModules(): Boolean
@DoNotStrip public fun viewCullingOutsetRatio(): Double
@DoNotStrip public fun virtualViewHysteresisRatio(): Double
@DoNotStrip public fun virtualViewPrerenderRatio(): Double
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<8e1821e9a153a4b725890cb4a7f262ee>>
* @generated SignedSource<<7a0a26494846d6b4881bea01beabb9d6>>
*/
/**
@@ -477,6 +477,12 @@ class ReactNativeFeatureFlagsJavaProvider
return method(javaProvider_);
}
double viewCullingOutsetRatio() override {
static const auto method =
getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jdouble()>("viewCullingOutsetRatio");
return method(javaProvider_);
}
double virtualViewHysteresisRatio() override {
static const auto method =
getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jdouble()>("virtualViewHysteresisRatio");
@@ -858,6 +864,11 @@ bool JReactNativeFeatureFlagsCxxInterop::useTurboModules(
return ReactNativeFeatureFlags::useTurboModules();
}
double JReactNativeFeatureFlagsCxxInterop::viewCullingOutsetRatio(
facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
return ReactNativeFeatureFlags::viewCullingOutsetRatio();
}
double JReactNativeFeatureFlagsCxxInterop::virtualViewHysteresisRatio(
facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
return ReactNativeFeatureFlags::virtualViewHysteresisRatio();
@@ -1118,6 +1129,9 @@ void JReactNativeFeatureFlagsCxxInterop::registerNatives() {
makeNativeMethod(
"useTurboModules",
JReactNativeFeatureFlagsCxxInterop::useTurboModules),
makeNativeMethod(
"viewCullingOutsetRatio",
JReactNativeFeatureFlagsCxxInterop::viewCullingOutsetRatio),
makeNativeMethod(
"virtualViewHysteresisRatio",
JReactNativeFeatureFlagsCxxInterop::virtualViewHysteresisRatio),
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<5be2ec52bda638a1eac837c402149b9f>>
* @generated SignedSource<<ad2e322ef177ced7eb07412552596a5b>>
*/
/**
@@ -249,6 +249,9 @@ class JReactNativeFeatureFlagsCxxInterop
static bool useTurboModules(
facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
static double viewCullingOutsetRatio(
facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
static double virtualViewHysteresisRatio(
facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<e335c5069e7fe7a67f2d754602d2200e>>
* @generated SignedSource<<f01f3d1a08880a7fa9d3490e6bd9c61a>>
*/
/**
@@ -318,6 +318,10 @@ bool ReactNativeFeatureFlags::useTurboModules() {
return getAccessor().useTurboModules();
}
double ReactNativeFeatureFlags::viewCullingOutsetRatio() {
return getAccessor().viewCullingOutsetRatio();
}
double ReactNativeFeatureFlags::virtualViewHysteresisRatio() {
return getAccessor().virtualViewHysteresisRatio();
}
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<bad2aadea64eba29430e9c93c169d621>>
* @generated SignedSource<<559a8be87c24238e70fceded8ac962a0>>
*/
/**
@@ -404,6 +404,11 @@ class ReactNativeFeatureFlags {
*/
RN_EXPORT static bool useTurboModules();
/**
* Outset the culling context frame with the provided ratio. The culling context frame size will be outset by width * ratio on the left and right, and height * ratio on the top and bottom.
*/
RN_EXPORT static double viewCullingOutsetRatio();
/**
* Sets a hysteresis window for transition between prerender and hidden modes.
*/
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<908baa1dbc4608be4b6407ffd670c066>>
* @generated SignedSource<<379732a049a8539a1cde814996ff4791>>
*/
/**
@@ -1343,6 +1343,24 @@ bool ReactNativeFeatureFlagsAccessor::useTurboModules() {
return flagValue.value();
}
double ReactNativeFeatureFlagsAccessor::viewCullingOutsetRatio() {
auto flagValue = viewCullingOutsetRatio_.load();
if (!flagValue.has_value()) {
// This block is not exclusive but it is not necessary.
// If multiple threads try to initialize the feature flag, we would only
// be accessing the provider multiple times but the end state of this
// instance and the returned flag value would be the same.
markFlagAsAccessed(73, "viewCullingOutsetRatio");
flagValue = currentProvider_->viewCullingOutsetRatio();
viewCullingOutsetRatio_ = flagValue;
}
return flagValue.value();
}
double ReactNativeFeatureFlagsAccessor::virtualViewHysteresisRatio() {
auto flagValue = virtualViewHysteresisRatio_.load();
@@ -1352,7 +1370,7 @@ double ReactNativeFeatureFlagsAccessor::virtualViewHysteresisRatio() {
// be accessing the provider multiple times but the end state of this
// instance and the returned flag value would be the same.
markFlagAsAccessed(73, "virtualViewHysteresisRatio");
markFlagAsAccessed(74, "virtualViewHysteresisRatio");
flagValue = currentProvider_->virtualViewHysteresisRatio();
virtualViewHysteresisRatio_ = flagValue;
@@ -1370,7 +1388,7 @@ double ReactNativeFeatureFlagsAccessor::virtualViewPrerenderRatio() {
// be accessing the provider multiple times but the end state of this
// instance and the returned flag value would be the same.
markFlagAsAccessed(74, "virtualViewPrerenderRatio");
markFlagAsAccessed(75, "virtualViewPrerenderRatio");
flagValue = currentProvider_->virtualViewPrerenderRatio();
virtualViewPrerenderRatio_ = flagValue;
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<d4453ed23422fc05e53ac2b5e342b0e8>>
* @generated SignedSource<<ae0e9dbf8605126b358f776226e68130>>
*/
/**
@@ -105,6 +105,7 @@ class ReactNativeFeatureFlagsAccessor {
bool useShadowNodeStateOnClone();
bool useTurboModuleInterop();
bool useTurboModules();
double viewCullingOutsetRatio();
double virtualViewHysteresisRatio();
double virtualViewPrerenderRatio();
@@ -118,7 +119,7 @@ class ReactNativeFeatureFlagsAccessor {
std::unique_ptr<ReactNativeFeatureFlagsProvider> currentProvider_;
bool wasOverridden_;
std::array<std::atomic<const char*>, 75> accessedFeatureFlags_;
std::array<std::atomic<const char*>, 76> accessedFeatureFlags_;
std::atomic<std::optional<bool>> commonTestFlag_;
std::atomic<std::optional<bool>> cdpInteractionMetricsEnabled_;
@@ -193,6 +194,7 @@ class ReactNativeFeatureFlagsAccessor {
std::atomic<std::optional<bool>> useShadowNodeStateOnClone_;
std::atomic<std::optional<bool>> useTurboModuleInterop_;
std::atomic<std::optional<bool>> useTurboModules_;
std::atomic<std::optional<double>> viewCullingOutsetRatio_;
std::atomic<std::optional<double>> virtualViewHysteresisRatio_;
std::atomic<std::optional<double>> virtualViewPrerenderRatio_;
};
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<5e6ee2118acc15edb9da813bb43978f3>>
* @generated SignedSource<<e8eb056e546c41e5863073e460362020>>
*/
/**
@@ -319,6 +319,10 @@ class ReactNativeFeatureFlagsDefaults : public ReactNativeFeatureFlagsProvider {
return false;
}
double viewCullingOutsetRatio() override {
return 0.0;
}
double virtualViewHysteresisRatio() override {
return 0.0;
}
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<edcc579f1ecfd47b8fc480bc1e4e7988>>
* @generated SignedSource<<00b4d80631374e0714c8aa9f65060220>>
*/
/**
@@ -702,6 +702,15 @@ class ReactNativeFeatureFlagsDynamicProvider : public ReactNativeFeatureFlagsDef
return ReactNativeFeatureFlagsDefaults::useTurboModules();
}
double viewCullingOutsetRatio() override {
auto value = values_["viewCullingOutsetRatio"];
if (!value.isNull()) {
return value.getDouble();
}
return ReactNativeFeatureFlagsDefaults::viewCullingOutsetRatio();
}
double virtualViewHysteresisRatio() override {
auto value = values_["virtualViewHysteresisRatio"];
if (!value.isNull()) {
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<4d141c52bc66225656194eeb8786f475>>
* @generated SignedSource<<fde4b531c2b0f19bef7bc69aaf3c5639>>
*/
/**
@@ -98,6 +98,7 @@ class ReactNativeFeatureFlagsProvider {
virtual bool useShadowNodeStateOnClone() = 0;
virtual bool useTurboModuleInterop() = 0;
virtual bool useTurboModules() = 0;
virtual double viewCullingOutsetRatio() = 0;
virtual double virtualViewHysteresisRatio() = 0;
virtual double virtualViewPrerenderRatio() = 0;
};
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<faa71f6cfef7a803bb034507eabd264e>>
* @generated SignedSource<<27c7bc7a528da06ffe2bcea48211f6bd>>
*/
/**
@@ -409,6 +409,11 @@ bool NativeReactNativeFeatureFlags::useTurboModules(
return ReactNativeFeatureFlags::useTurboModules();
}
double NativeReactNativeFeatureFlags::viewCullingOutsetRatio(
jsi::Runtime& /*runtime*/) {
return ReactNativeFeatureFlags::viewCullingOutsetRatio();
}
double NativeReactNativeFeatureFlags::virtualViewHysteresisRatio(
jsi::Runtime& /*runtime*/) {
return ReactNativeFeatureFlags::virtualViewHysteresisRatio();
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<2dcd8b3add6f1fdc1bf378714deb41d7>>
* @generated SignedSource<<39140c882a6faa0403d3a59806c6bea5>>
*/
/**
@@ -182,6 +182,8 @@ class NativeReactNativeFeatureFlags
bool useTurboModules(jsi::Runtime& runtime);
double viewCullingOutsetRatio(jsi::Runtime& runtime);
double virtualViewHysteresisRatio(jsi::Runtime& runtime);
double virtualViewPrerenderRatio(jsi::Runtime& runtime);
@@ -32,6 +32,20 @@ CullingContext CullingContext::adjustCullingContextIfNeeded(
/* includeTransform */ true);
cullingContext.frame.size =
scrollViewShadowNode->getLayoutMetrics().frame.size;
// Enlarge the frame if an outset ratio is defined
auto outsetRatio = ReactNativeFeatureFlags::viewCullingOutsetRatio();
if (outsetRatio > 0) {
auto xOutset = static_cast<float>(
floor(cullingContext.frame.size.width * outsetRatio));
auto yOutset = static_cast<float>(
floor(cullingContext.frame.size.height * outsetRatio));
cullingContext.frame.origin.x -= xOutset;
cullingContext.frame.origin.y -= yOutset;
cullingContext.frame.size.width += 2.0f * xOutset;
cullingContext.frame.size.height += 2.0f * yOutset;
}
cullingContext.transform = Transform::Identity();
if (layoutMetrics.layoutDirection == LayoutDirection::RightToLeft) {
@@ -825,6 +825,17 @@ const definitions: FeatureFlagDefinitions = {
},
ossReleaseStage: 'canary',
},
viewCullingOutsetRatio: {
defaultValue: 0,
metadata: {
dateAdded: '2025-09-18',
description:
'Outset the culling context frame with the provided ratio. The culling context frame size will be outset by width * ratio on the left and right, and height * ratio on the top and bottom.',
expectedReleaseValue: 0,
purpose: 'experimentation',
},
ossReleaseStage: 'none',
},
virtualViewHysteresisRatio: {
defaultValue: 0,
metadata: {
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<44c491f4078e75b8b77ee346ac802a70>>
* @generated SignedSource<<cddccaa2570aa27af142d90430a14044>>
* @flow strict
* @noformat
*/
@@ -123,6 +123,7 @@ export type ReactNativeFeatureFlags = $ReadOnly<{
useShadowNodeStateOnClone: Getter<boolean>,
useTurboModuleInterop: Getter<boolean>,
useTurboModules: Getter<boolean>,
viewCullingOutsetRatio: Getter<number>,
virtualViewHysteresisRatio: Getter<number>,
virtualViewPrerenderRatio: Getter<number>,
}>;
@@ -498,6 +499,10 @@ export const useTurboModuleInterop: Getter<boolean> = createNativeFlagGetter('us
* When enabled, NativeModules will be executed by using the TurboModule system
*/
export const useTurboModules: Getter<boolean> = createNativeFlagGetter('useTurboModules', false);
/**
* Outset the culling context frame with the provided ratio. The culling context frame size will be outset by width * ratio on the left and right, and height * ratio on the top and bottom.
*/
export const viewCullingOutsetRatio: Getter<number> = createNativeFlagGetter('viewCullingOutsetRatio', 0);
/**
* Sets a hysteresis window for transition between prerender and hidden modes.
*/
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<18ae10cff4e5611d4774252917f57c13>>
* @generated SignedSource<<765a2f99602c00c38047e25ce805af86>>
* @flow strict
* @noformat
*/
@@ -98,6 +98,7 @@ export interface Spec extends TurboModule {
+useShadowNodeStateOnClone?: () => boolean;
+useTurboModuleInterop?: () => boolean;
+useTurboModules?: () => boolean;
+viewCullingOutsetRatio?: () => number;
+virtualViewHysteresisRatio?: () => number;
+virtualViewPrerenderRatio?: () => number;
}