chore: Capture intended values with scrollIndex and scrollPercent (#13084) 9ebf0f88df Setting scrollIndex/scrollPercent converts immediately to scrollOffset using live layout bounds, so a set while the layout couldn't answer (display hidden, pre-layout, no items yet) converted against zeroed bounds and destroyed the value — and two-way binds then pushed the recomputed garbage back into the view model. Sets are now recorded as a per-axis intent tagged with their space and resolved eagerly; when layout can't answer, the intent is held and retried in constrain(), reading back verbatim until it resolves, then discarded (one-shot, RecyclerView-style pending scroll). User interaction drops held intents. Implemented in both rive_core and the C++ runtime; no serialization changes. Behavior changes (web scrollTo semantics): Out-of-range indices clamp to the ends instead of snapping to the start. Resolved offsets clamp to the scrollable range — also removes per-frame relayout churn from overshooting sets (hence the component_list_child_origin silver rebaseline; rendering is identical). C++ 2-D index sets write both axes, matching the editor. Co-authored-by: Philip Chung <philterdesign@gmail.com>
diff --git a/.rive_head b/.rive_head index 2b4e3f6..a484a67 100644 --- a/.rive_head +++ b/.rive_head
@@ -1 +1 @@ -d24376c1d692b4687141dbcff2bc4b84f3de8c66 +9ebf0f88df7a292be01f95fcf6e3ccf0abe07954
diff --git a/include/rive/constraints/scrolling/scroll_constraint.hpp b/include/rive/constraints/scrolling/scroll_constraint.hpp index b76c7e8..9d2b788 100644 --- a/include/rive/constraints/scrolling/scroll_constraint.hpp +++ b/include/rive/constraints/scrolling/scroll_constraint.hpp
@@ -19,6 +19,20 @@ public LayoutConstraint { private: + // Coordinate space a scroll write was expressed in. + enum class ScrollSpace : uint8_t + { + none, + percent, + index, + }; + // A percent/index write awaiting conversion to an offset. + struct ScrollAxisIntent + { + ScrollSpace space = ScrollSpace::none; + float value = 0; + }; + ScrollPhysics* m_physics; ScrollVirtualizer* m_virtualizer = nullptr; std::vector<LayoutNodeProvider*> m_layoutChildren; @@ -37,13 +51,32 @@ bool m_isScrollBarDragging = false; bool m_hasListChildren = false; + // Unresolved writes per axis; held until layout can convert. + ScrollAxisIntent m_intentX; + ScrollAxisIntent m_intentY; + AABB boundsForFlatIndex(size_t index); - Vec2D positionAtIndex(float index); + /// Returns false when layout can't resolve the index yet; out-of-range + /// indices clamp to the ends. + bool positionAtIndex(float index, Vec2D& outPosition); float indexAtPosition(Vec2D pos); float maxOffsetXForPercent(); float maxOffsetYForPercent(); bool isBoundsCollapsed(AABB bounds); std::vector<Vec2D> collectSnapPoints(); + bool scrollLayoutResolvable(bool isX); + float clampResolvedOffset(float value, bool isX); + bool resolveIntent(const ScrollAxisIntent& intent, + bool isX, + float& outOffset); + void setIntentX(ScrollAxisIntent intent); + void setIntentY(ScrollAxisIntent intent); + void resolveScrollIntents(); + void clearScrollIntents() + { + m_intentX.space = ScrollSpace::none; + m_intentY.space = ScrollSpace::none; + } public: ~ScrollConstraint(); @@ -121,6 +154,8 @@ { if (!m_isScrollBarDragging && value) { + // User interaction supersedes held intents. + clearScrollIntents(); // Prime the snapshot so the first advance comparison is // meaningful (otherwise a stale value falsely flags motion). m_lastFrameOffsetX = scrollOffsetX();
diff --git a/src/constraints/scrolling/scroll_constraint.cpp b/src/constraints/scrolling/scroll_constraint.cpp index 0662643..038e97b 100644 --- a/src/constraints/scrolling/scroll_constraint.cpp +++ b/src/constraints/scrolling/scroll_constraint.cpp
@@ -193,6 +193,7 @@ void ScrollConstraint::constrain(TransformComponent* component) { + resolveScrollIntents(); m_scrollTransform = Mat2D::fromTranslate(constrainsHorizontal() ? clampedOffsetX() : 0, constrainsVertical() ? clampedOffsetY() : 0); @@ -411,6 +412,8 @@ void ScrollConstraint::initPhysics() { m_isDragging = true; + // User interaction supersedes held intents. + clearScrollIntents(); m_lastFrameOffsetX = scrollOffsetX(); m_lastFrameOffsetY = scrollOffsetY(); if (m_physics != nullptr) @@ -463,16 +466,30 @@ float ScrollConstraint::scrollPercentX() { + if (m_intentX.space == ScrollSpace::percent) + { + return m_intentX.value; + } return maxOffsetX() != 0 ? scrollOffsetX() / maxOffsetXForPercent() : 0; } float ScrollConstraint::scrollPercentY() { + if (m_intentY.space == ScrollSpace::percent) + { + return m_intentY.value; + } return maxOffsetY() != 0 ? scrollOffsetY() / maxOffsetYForPercent() : 0; } float ScrollConstraint::scrollIndex() { + const ScrollAxisIntent& intent = + constrainsHorizontal() ? m_intentX : m_intentY; + if (intent.space == ScrollSpace::index) + { + return intent.value; + } return indexAtPosition(Vec2D(scrollOffsetX(), scrollOffsetY())); } @@ -483,8 +500,7 @@ return; } stopPhysics(); - float to = value * maxOffsetXForPercent(); - scrollOffsetX(to); + setIntentX({ScrollSpace::percent, value}); } void ScrollConstraint::setScrollPercentY(float value) @@ -494,8 +510,7 @@ return; } stopPhysics(); - float to = value * maxOffsetYForPercent(); - scrollOffsetY(to); + setIntentY({ScrollSpace::percent, value}); } void ScrollConstraint::setScrollIndex(float value) @@ -505,37 +520,165 @@ return; } stopPhysics(); - Vec2D to = positionAtIndex(value); if (constrainsHorizontal()) { - scrollOffsetX(to.x); + setIntentX({ScrollSpace::index, value}); } - else if (constrainsVertical()) + if (constrainsVertical()) { - scrollOffsetY(to.y); + setIntentY({ScrollSpace::index, value}); } } -Vec2D ScrollConstraint::positionAtIndex(float index) +// False while hidden or before the first layout pass on the given axis. +bool ScrollConstraint::scrollLayoutResolvable(bool isX) { - if (!std::isfinite(index)) + auto vp = viewport(); + if (vp == nullptr) { - return Vec2D(); + return false; + } + return isX ? vp->layoutWidth() > 0 : vp->layoutHeight() > 0; +} + +// Resolved offsets clamp to the scrollable range. +float ScrollConstraint::clampResolvedOffset(float value, bool isX) +{ + if (infinite()) + { + return value; + } + return math::clamp(value, isX ? maxOffsetX() : maxOffsetY(), 0.0f); +} + +// Convert an intent to an offset; false if layout can't resolve yet. +bool ScrollConstraint::resolveIntent(const ScrollAxisIntent& intent, + bool isX, + float& outOffset) +{ + // Non-finite indices resolve to the origin without needing layout. + if (intent.space == ScrollSpace::index && + (std::isnan(intent.value) || + (infinite() && !std::isfinite(intent.value)))) + { + outOffset = 0; + return true; + } + // Gate both spaces: virtualized lists compute item bounds from authored + // sizes, which resolve even while the viewport layout is collapsed. + if (!scrollLayoutResolvable(isX)) + { + return false; + } + switch (intent.space) + { + case ScrollSpace::percent: + { + float contentSize = isX ? contentWidth() : contentHeight(); + if (contentSize <= 0) + { + // No measured content — can't resolve. + return false; + } + float maxForPercent = + isX ? maxOffsetXForPercent() : maxOffsetYForPercent(); + outOffset = clampResolvedOffset(intent.value * maxForPercent, isX); + return true; + } + case ScrollSpace::index: + { + Vec2D to; + if (!positionAtIndex(intent.value, to)) + { + return false; + } + outOffset = clampResolvedOffset(isX ? to.x : to.y, isX); + return true; + } + case ScrollSpace::none: + break; + } + return false; +} + +// Resolve eagerly; unresolved intents are held and retried in constrain(). +void ScrollConstraint::setIntentX(ScrollAxisIntent intent) +{ + float resolved; + if (!resolveIntent(intent, true, resolved)) + { + m_intentX = intent; + return; + } + m_intentX.space = ScrollSpace::none; + scrollOffsetX(resolved); +} + +void ScrollConstraint::setIntentY(ScrollAxisIntent intent) +{ + float resolved; + if (!resolveIntent(intent, false, resolved)) + { + m_intentY = intent; + return; + } + m_intentY.space = ScrollSpace::none; + scrollOffsetY(resolved); +} + +// Retry held intents; called from constrain() where layout is fresh. +void ScrollConstraint::resolveScrollIntents() +{ + if (m_intentX.space != ScrollSpace::none) + { + setIntentX(m_intentX); + } + if (m_intentY.space != ScrollSpace::none) + { + setIntentY(m_intentY); + } +} + +bool ScrollConstraint::positionAtIndex(float index, Vec2D& outPosition) +{ + if (std::isnan(index) || (infinite() && !std::isfinite(index))) + { + outPosition = Vec2D(); + return true; } auto count = scrollItemCount(); if (content() == nullptr || count == 0) { - return Vec2D(); + return false; } Vec2D contentGap = gap(); - float normalizedIndex = infinite() ? std::fmod(index, (float)count) : index; + float normalizedIndex; + if (infinite()) + { + normalizedIndex = std::fmod(index, (float)count); + if (normalizedIndex < 0) + { + normalizedIndex += (float)count; + } + } + else + { + normalizedIndex = std::max(index, 0.0f); + // Past the last item: target the far end (clamps to max scroll). + if (normalizedIndex >= (float)count) + { + if (contentWidth() <= 0 && contentHeight() <= 0) + { + // No measured content — can't resolve. + return false; + } + outPosition = Vec2D(-contentWidth(), -contentHeight()); + return true; + } + } float floorIndex = std::floor(normalizedIndex); float mod = normalizedIndex - floorIndex; uint32_t targetIndex = (uint32_t)floorIndex; - if (targetIndex >= (uint32_t)count) - { - return Vec2D(); - } // No list children: O(1) direct index into scrollChildren. if (!m_hasListChildren) @@ -544,9 +687,10 @@ auto bounds = boundsForFlatIndex(targetIndex); if (!isBoundsCollapsed(bounds)) { - return Vec2D(-bounds.left() - (bounds.width() + contentGap.x) * mod, - -bounds.top() - - (bounds.height() + contentGap.y) * mod); + outPosition = + Vec2D(-bounds.left() - (bounds.width() + contentGap.x) * mod, + -bounds.top() - (bounds.height() + contentGap.y) * mod); + return true; } // Target is collapsed — walk forward to next visible item. for (uint32_t k = targetIndex + 1; k < (uint32_t)count; k++) @@ -554,7 +698,8 @@ auto b = boundsForFlatIndex(k); if (!isBoundsCollapsed(b)) { - return Vec2D(-b.left(), -b.top()); + outPosition = Vec2D(-b.left(), -b.top()); + return true; } } if (infinite()) @@ -565,7 +710,8 @@ auto b = boundsForFlatIndex(k); if (!isBoundsCollapsed(b)) { - return Vec2D(-b.left(), -b.top()); + outPosition = Vec2D(-b.left(), -b.top()); + return true; } } } @@ -577,11 +723,13 @@ auto b = boundsForFlatIndex(k); if (!isBoundsCollapsed(b)) { - return Vec2D(-b.left(), -b.top()); + outPosition = Vec2D(-b.left(), -b.top()); + return true; } } } - return Vec2D(); + // Nothing visible — can't resolve. + return false; } // Has list children: single-pass through nested child→node structure. @@ -618,23 +766,25 @@ reachedTarget = true; if (!isBoundsCollapsed(bounds)) { - return Vec2D( + outPosition = Vec2D( -bounds.left() - (bounds.width() + contentGap.x) * mod, -bounds.top() - (bounds.height() + contentGap.y) * mod); + return true; } continue; } // Past target: return first visible item found. if (!isBoundsCollapsed(bounds)) { - return Vec2D(-bounds.left(), -bounds.top()); + outPosition = Vec2D(-bounds.left(), -bounds.top()); + return true; } } } if (!reachedTarget) { - return Vec2D(); + return false; } // No visible item after target. @@ -653,12 +803,14 @@ { if (flatIndex >= targetIndex) { - return Vec2D(); + // Nothing visible — can't resolve. + return false; } auto bounds = child->layoutBoundsForNode(j); if (!isBoundsCollapsed(bounds)) { - return Vec2D(-bounds.left(), -bounds.top()); + outPosition = Vec2D(-bounds.left(), -bounds.top()); + return true; } } } @@ -666,10 +818,12 @@ else if (hasVisibleBeforeTarget) { // End of list: fall back to last visible item before target. - return lastVisibleBeforeTarget; + outPosition = lastVisibleBeforeTarget; + return true; } - return Vec2D(); + // Nothing visible — can't resolve. + return false; } float ScrollConstraint::indexAtPosition(Vec2D pos) @@ -830,6 +984,8 @@ void ScrollConstraint::scrollToPosition(float targetX, float targetY) { + // Direct offset writes supersede held intents. + clearScrollIntents(); if (m_physics == nullptr) { // No physics, just set offset directly
diff --git a/tests/unit_tests/assets/scroll_intent.riv b/tests/unit_tests/assets/scroll_intent.riv new file mode 100644 index 0000000..96e12cf --- /dev/null +++ b/tests/unit_tests/assets/scroll_intent.riv Binary files differ
diff --git a/tests/unit_tests/runtime/layout_scroll_test.cpp b/tests/unit_tests/runtime/layout_scroll_test.cpp index dd680d1..02f1097 100644 --- a/tests/unit_tests/runtime/layout_scroll_test.cpp +++ b/tests/unit_tests/runtime/layout_scroll_test.cpp
@@ -6,6 +6,7 @@ #include "rive/shapes/rectangle.hpp" #include "rive/text/text.hpp" #include "rive/viewmodel/viewmodel_instance_enum.hpp" +#include "rive/viewmodel/viewmodel_instance_number.hpp" #include "utils/no_op_factory.hpp" #include "utils/serializing_factory.hpp" #include "rive_file_reader.hpp" @@ -653,6 +654,112 @@ rive::File::deterministicMode = false; } +TEST_CASE("ScrollConstraint index intent across hidden layout", "[silver]") +{ + rive::File::deterministicMode = true; + + rive::SerializingFactory silver; + auto file = ReadRiveFile("assets/scroll_intent.riv", &silver); + + auto artboard = file->artboard()->instance(); + REQUIRE(artboard != nullptr); + silver.frameSize(artboard->width(), artboard->height()); + + auto vmi = file->createDefaultViewModelInstance(artboard.get()); + REQUIRE(vmi != nullptr); + artboard->bindViewModelInstance(vmi); + + auto smi = artboard->defaultStateMachine(); + REQUIRE(smi != nullptr); + + auto display = + vmi->propertyValue("display")->as<rive::ViewModelInstanceEnum>(); + auto scrollIndex = + vmi->propertyValue("scrollIndex")->as<rive::ViewModelInstanceNumber>(); + + auto scrolls = artboard->find<rive::ScrollConstraint>(); + REQUIRE_FALSE(scrolls.empty()); + auto scroll = scrolls[0]; + // LayoutComponent re-declares isCollapsed as protected; read it through + // the public Component interface. + rive::Component* content = scroll->content(); + auto offset = [&]() { + return scroll->constrainsVertical() ? scroll->scrollOffsetY() + : scroll->scrollOffsetX(); + }; + + auto renderer = silver.makeRenderer(); + float dt = 1.0f / 60.0f; + + smi->advanceAndApply(0.0f); + artboard->draw(renderer.get()); + + for (int frame = 0; frame < 35; frame++) + { + // Visible: an index set applies immediately. + if (frame == 5) + { + scrollIndex->propertyValue(2.0f); + } + if (frame == 6) + { + REQUIRE(offset() < 0); + } + // Hide the scrolling layout. + if (frame == 10) + { + display->value(1); + } + if (frame == 11) + { + REQUIRE(content->isCollapsed()); + } + // Hidden: the set is held and reads back verbatim. + if (frame == 15) + { + scrollIndex->propertyValue(4.0f); + } + if (frame == 16) + { + REQUIRE(scroll->scrollIndex() == 4.0f); + } + // Show again: the held index resolves against fresh layout. + if (frame == 20) + { + display->value(0); + } + if (frame == 21) + { + REQUIRE_FALSE(content->isCollapsed()); + REQUIRE(offset() < 0); + } + // Visible: out-of-range clamps to the end of the scroll range. + if (frame == 25) + { + scrollIndex->propertyValue(100.0f); + } + if (frame == 26) + { + REQUIRE(offset() == (scroll->constrainsVertical() + ? scroll->maxOffsetY() + : scroll->maxOffsetX())); + } + // Back to the start. + if (frame == 30) + { + scrollIndex->propertyValue(0.0f); + } + silver.addFrame(); + smi->advanceAndApply(dt); + artboard->draw(renderer.get()); + } + REQUIRE(offset() == 0); + + CHECK(silver.matches("scroll_intent")); + + rive::File::deterministicMode = false; +} + // ========================================================================= // Velocity-tracking tests for ScrollConstraint. // @@ -936,4 +1043,62 @@ CHECK_FALSE(scroll->physics()->isRunning()); rive::File::deterministicMode = false; +} + +TEST_CASE("ScrollConstraint index set before layout resolves on advance", + "[layoutscroll]") +{ + auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv"); + + auto artboard = file->artboard(); + auto scroll = artboard->find<rive::ScrollConstraint>()[0]; + + // Layout hasn't run; the index is held and reads back verbatim. + scroll->setScrollIndex(2); + REQUIRE(scroll->scrollIndex() == 2); + REQUIRE(scroll->offsetY() == 0); + + // First advance runs layout; the intent resolves. + artboard->advance(0.0f); + REQUIRE(scroll->offsetY() == -220.0f); + REQUIRE(scroll->scrollIndex() == 2); +} + +TEST_CASE("ScrollConstraint percent set before layout resolves on advance", + "[layoutscroll]") +{ + auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv"); + + auto artboard = file->artboard(); + auto scroll = artboard->find<rive::ScrollConstraint>()[0]; + + // Layout hasn't run; the percent is held and reads back verbatim. + scroll->setScrollPercentY(0.5f); + REQUIRE(scroll->scrollPercentY() == 0.5f); + REQUIRE(scroll->offsetY() == 0); + + // First advance runs layout; the intent resolves. + artboard->advance(0.0f); + REQUIRE(scroll->offsetY() == -305.0f); + REQUIRE(scroll->scrollPercentY() == 0.5f); +} + +TEST_CASE("ScrollConstraint out-of-range index clamps to the ends", + "[layoutscroll]") +{ + auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv"); + + auto artboard = file->artboard(); + auto scroll = artboard->find<rive::ScrollConstraint>()[0]; + artboard->advance(0.0f); + + // Past the end: clamps to max scroll; readback reports the actual index. + scroll->setScrollIndex(99); + REQUIRE(scroll->offsetY() == -610.0f); + REQUIRE(scroll->scrollIndex() == Approx(5.54545f)); + + // Before the start: clamps to zero. + scroll->setScrollIndex(-5); + REQUIRE(scroll->offsetY() == 0.0f); + REQUIRE(scroll->scrollIndex() == 0); } \ No newline at end of file
diff --git a/tests/unit_tests/silvers/component_list_child_origin.sriv b/tests/unit_tests/silvers/component_list_child_origin.sriv index 0f344ea..1f09995 100644 --- a/tests/unit_tests/silvers/component_list_child_origin.sriv +++ b/tests/unit_tests/silvers/component_list_child_origin.sriv Binary files differ
diff --git a/tests/unit_tests/silvers/scroll_intent.sriv b/tests/unit_tests/silvers/scroll_intent.sriv new file mode 100644 index 0000000..3e8a652 --- /dev/null +++ b/tests/unit_tests/silvers/scroll_intent.sriv Binary files differ