Refactor `DirectionalMotionSpecBuilder.kt` into reusable targets (512af2a1) · Commits · e / os / android_frameworks_libs_systemui

mechanics/src/com/android/mechanics/spec/DirectionalMotionSpecBuilder.kt

+7 −481

Original line number	Diff line number	Diff line
		@@ -16,6 +16,9 @@

		package com.android.mechanics.spec

		import com.android.mechanics.spec.builder.DirectionalBuilderFn
		import com.android.mechanics.spec.builder.DirectionalBuilderImpl
		import com.android.mechanics.spec.builder.SegmentSemanticValuesBuilder
		import com.android.mechanics.spring.SpringParameters

		/**
		@@ -48,8 +51,8 @@ import com.android.mechanics.spring.SpringParameters
		* @param defaultSpring The default [SpringParameters] to use for all breakpoints.
		* @param initialMapping The initial [Mapping] for the first segment (defaults to
		* [Mapping.Identity]).
		* @param init A lambda function that configures the [DirectionalMotionSpecBuilder]. The lambda
		* should return a [CanBeLastSegment] to indicate the end of the spec.
		* @param init A lambda function that configures the spec using the [DirectionalBuilderScope]. The
		* lambda should return a [CanBeLastSegment] to indicate the end of the spec.
		* @param semantics Semantics specified in this spec, including the initial value applied for
		* [initialMapping].
		* @return The constructed [DirectionalMotionSpec].
		@@ -58,9 +61,9 @@ fun buildDirectionalMotionSpec(
		defaultSpring: SpringParameters,
		initialMapping: Mapping = Mapping.Identity,
		semantics: List<SemanticValue<*>> = emptyList(),
		init: DirectionalMotionSpecBuilder.() -> CanBeLastSegment,
		init: DirectionalBuilderFn,
		): DirectionalMotionSpec {
		return DirectionalMotionSpecBuilderImpl(defaultSpring)
		return DirectionalBuilderImpl(defaultSpring)
		.also { it.mappings += initialMapping }
		.also { it.semantics += semantics.map { SegmentSemanticValuesBuilder(it) } }
		.also { it.init() }
		@@ -87,480 +90,3 @@ fun buildDirectionalMotionSpec(
		semantics.map { toSegmentSemanticValues(it) },
		)
		}

		/**
		* Defines the contract for building a [DirectionalMotionSpec].
		*
		* Provides methods to define breakpoints and mappings for the motion specification.
		*/
		interface DirectionalMotionSpecBuilder {
		/** The default [SpringParameters] used for breakpoints. */
		val defaultSpring: SpringParameters

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to
		* linearly interpolate from a starting value ([from]) to the desired target value ([to]).
		*
		* Note: This segment cannot be used as the last segment in the specification, as it requires a
		* subsequent breakpoint to define the target value.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param from The output value at the previous breakpoint, explicitly setting the starting
		* point for the linear mapping.
		* @param to The desired output value at the new breakpoint.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun target(
		breakpoint: Float,
		from: Float,
		to: Float,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		)

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to
		* linearly interpolate from the current output value (optionally with an offset of [delta]) to
		* the desired target value ([to]).
		*
		* Note: This segment cannot be used as the last segment in the specification, as it requires a
		* subsequent breakpoint to define the target value.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param to The desired output value at the new breakpoint.
		* @param delta An optional offset to apply to the calculated starting value. Defaults to 0f.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun targetFromCurrent(
		breakpoint: Float,
		to: Float,
		delta: Float = 0f,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		)

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to
		* linearly interpolate from a starting value ([from]) and then continue with a fractional input
		* ([fraction]).
		*
		* Note: This segment can be used as the last segment in the specification.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param from The output value at the previous breakpoint, explicitly setting the starting
		* point for the linear mapping.
		* @param fraction The fractional multiplier applied to the input difference between
		* breakpoints.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun fractionalInput(
		breakpoint: Float,
		from: Float,
		fraction: Float,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		): CanBeLastSegment

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to
		* linearly interpolate from the current output value (optionally with an offset of [delta]) and
		* then continue with a fractional input ([fraction]).
		*
		* Note: This segment can be used as the last segment in the specification.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param fraction The fractional multiplier applied to the input difference between
		* breakpoints.
		* @param delta An optional offset to apply to the calculated starting value. Defaults to 0f.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun fractionalInputFromCurrent(
		breakpoint: Float,
		fraction: Float,
		delta: Float = 0f,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		): CanBeLastSegment

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to output
		* a constant value ([value]).
		*
		* Note: This segment can be used as the last segment in the specification.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param value The constant output value for this segment.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun constantValue(
		breakpoint: Float,
		value: Float,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		): CanBeLastSegment

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment to output
		* a constant value derived from the current output value (optionally with an offset of
		* [delta]).
		*
		* Note: This segment can be used as the last segment in the specification.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param delta An optional offset to apply to the mapped value to determine the constant value.
		* Defaults to 0f.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		*/
		fun constantValueFromCurrent(
		breakpoint: Float,
		delta: Float = 0f,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		): CanBeLastSegment

		/**
		* Ends the current segment at the [breakpoint] position and defines the next segment using the
		* provided [mapping].
		*
		* Note: This segment can be used as the last segment in the specification.
		*
		* @param breakpoint The breakpoint defining the end of the current segment and the start of the
		* next.
		* @param spring The [SpringParameters] for the transition to this breakpoint. Defaults to
		* [defaultSpring].
		* @param guarantee The animation guarantee for this transition. Defaults to [Guarantee.None].
		* @param key A unique [BreakpointKey] for this breakpoint. Defaults to a newly generated key.
		* @param semantics Updated semantics values to be applied. Must be a subset of the
		* [SemanticKey]s used when first creating this builder.
		* @param mapping The custom [Mapping] to use.
		*/
		fun mapping(
		breakpoint: Float,
		spring: SpringParameters = defaultSpring,
		guarantee: Guarantee = Guarantee.None,
		key: BreakpointKey = BreakpointKey(),
		semantics: List<SemanticValue<*>> = emptyList(),
		mapping: Mapping,
		): CanBeLastSegment
		}

		/** Marker interface to indicate that a segment can be the last one in a [DirectionalMotionSpec]. */
		sealed interface CanBeLastSegment

		private data object CanBeLastSegmentImpl : CanBeLastSegment

		private class SegmentSemanticValuesBuilder<T>(seed: SemanticValue<T>) {
		val key = seed.key
		private val values = mutableListOf(seed.value)

		fun backfill(segmentCount: Int) {
		val lastValue = values.last()
		repeat(segmentCount - values.size) { values.add(lastValue) }
		}

		@Suppress("UNCHECKED_CAST")
		fun <V> append(value: V) {
		values.add(value as T)
		}

		fun build() = SegmentSemanticValues(key, values.toList())
		}

		private class DirectionalMotionSpecBuilderImpl(override val defaultSpring: SpringParameters) :
		DirectionalMotionSpecBuilder {
		private val breakpoints = mutableListOf(Breakpoint.minLimit)
		val semantics = mutableListOf<SegmentSemanticValuesBuilder<*>>()
		val mappings = mutableListOf<Mapping>()
		private var sourceValue: Float = Float.NaN
		private var targetValue: Float = Float.NaN
		private var fractionalMapping: Float = Float.NaN
		private var breakpointPosition: Float = Float.NaN
		private var breakpointKey: BreakpointKey? = null

		private fun applySemantics(toApply: List<SemanticValue<*>>) {
		toApply.forEach { (key, value) ->
		val semanticValuesBuilder =
		checkNotNull(semantics.first { it.key == key }) {
		"semantic key $key not initially registered"
		}

		semanticValuesBuilder.backfill(mappings.size)
		semanticValuesBuilder.append(value)
		}
		}

		override fun target(
		breakpoint: Float,
		from: Float,
		to: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		) {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpToImpl(from, spring, guarantee)
		continueWithTargetValueImpl(to)
		}

		override fun targetFromCurrent(
		breakpoint: Float,
		to: Float,
		delta: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		) {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpByImpl(delta, spring, guarantee)
		continueWithTargetValueImpl(to)
		}

		override fun fractionalInput(
		breakpoint: Float,
		from: Float,
		fraction: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		): CanBeLastSegment {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpToImpl(from, spring, guarantee)
		continueWithFractionalInputImpl(fraction)
		return CanBeLastSegmentImpl
		}

		override fun fractionalInputFromCurrent(
		breakpoint: Float,
		fraction: Float,
		delta: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		): CanBeLastSegment {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpByImpl(delta, spring, guarantee)
		continueWithFractionalInputImpl(fraction)
		return CanBeLastSegmentImpl
		}

		override fun constantValue(
		breakpoint: Float,
		value: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		): CanBeLastSegment {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpToImpl(value, spring, guarantee)
		continueWithConstantValueImpl()
		return CanBeLastSegmentImpl
		}

		override fun constantValueFromCurrent(
		breakpoint: Float,
		delta: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		): CanBeLastSegment {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		jumpByImpl(delta, spring, guarantee)
		continueWithConstantValueImpl()
		return CanBeLastSegmentImpl
		}

		override fun mapping(
		breakpoint: Float,
		spring: SpringParameters,
		guarantee: Guarantee,
		key: BreakpointKey,
		semantics: List<SemanticValue<*>>,
		mapping: Mapping,
		): CanBeLastSegment {
		applySemantics(semantics)
		toBreakpointImpl(breakpoint, key)
		continueWithImpl(mapping, spring, guarantee)
		return CanBeLastSegmentImpl
		}

		fun build(): DirectionalMotionSpec {
		completeImpl()
		val semantics =
		semantics.map { builder ->
		with(builder) {
		backfill(mappings.size)
		build()
		}
		}

		return DirectionalMotionSpec(breakpoints.toList(), mappings.toList(), semantics)
		}

		private fun continueWithTargetValueImpl(target: Float) {
		check(sourceValue.isFinite())

		targetValue = target
		}

		private fun continueWithFractionalInputImpl(fraction: Float) {
		check(sourceValue.isFinite())

		fractionalMapping = fraction
		}

		private fun continueWithConstantValueImpl() {
		check(sourceValue.isFinite())

		mappings.add(Mapping.Fixed(sourceValue))
		sourceValue = Float.NaN
		}

		private fun jumpToImpl(value: Float, spring: SpringParameters, guarantee: Guarantee) {
		check(sourceValue.isNaN())

		doAddBreakpointImpl(spring, guarantee)
		sourceValue = value
		}

		private fun jumpByImpl(delta: Float, spring: SpringParameters, guarantee: Guarantee) {
		check(sourceValue.isNaN())

		val breakpoint = doAddBreakpointImpl(spring, guarantee)
		sourceValue = mappings.last().map(breakpoint.position) + delta
		}

		private fun continueWithImpl(mapping: Mapping, spring: SpringParameters, guarantee: Guarantee) {
		check(sourceValue.isNaN())

		doAddBreakpointImpl(spring, guarantee)
		mappings.add(mapping)
		}

		private fun toBreakpointImpl(atPosition: Float, key: BreakpointKey) {
		check(breakpointPosition.isNaN())
		check(breakpointKey == null)

		if (!targetValue.isNaN() \|\| !fractionalMapping.isNaN()) {
		check(!sourceValue.isNaN())

		val sourcePosition = breakpoints.last().position
		val breakpointDistance = atPosition - sourcePosition
		val mapping =
		if (breakpointDistance == 0f) {
		Mapping.Fixed(sourceValue)
		} else {

		if (fractionalMapping.isNaN()) {
		val delta = targetValue - sourceValue
		fractionalMapping = delta / (atPosition - sourcePosition)
		} else {
		val delta = (atPosition - sourcePosition) * fractionalMapping
		targetValue = sourceValue + delta
		}

		val offset = sourceValue - (sourcePosition * fractionalMapping)
		Mapping.Linear(fractionalMapping, offset)
		}

		mappings.add(mapping)
		targetValue = Float.NaN
		sourceValue = Float.NaN
		fractionalMapping = Float.NaN
		}

		breakpointPosition = atPosition
		breakpointKey = key
		}

		private fun completeImpl() {
		check(targetValue.isNaN()) { "cant specify target value for last segment" }

		if (!fractionalMapping.isNaN()) {
		check(!sourceValue.isNaN())

		val sourcePosition = breakpoints.last().position

		mappings.add(
		Mapping.Linear(
		fractionalMapping,
		sourceValue - (sourcePosition * fractionalMapping),
		)
		)
		}

		breakpoints.add(Breakpoint.maxLimit)
		}

		private fun doAddBreakpointImpl(
		springSpec: SpringParameters,
		guarantee: Guarantee,
		): Breakpoint {
		check(breakpointPosition.isFinite())
		return Breakpoint(checkNotNull(breakpointKey), breakpointPosition, springSpec, guarantee)
		.also {
		breakpoints.add(it)
		breakpointPosition = Float.NaN
		breakpointKey = null
		}
		}
		}

mechanics/src/com/android/mechanics/spec/builder/DirectionalBuilderImpl.kt

0 → 100644

+302 −0

File added.

Preview size limit exceeded, changes collapsed.

mechanics/src/com/android/mechanics/spec/builder/DirectionalBuilderScope.kt

0 → 100644

+235 −0

File added.

Preview size limit exceeded, changes collapsed.

mechanics/tests/src/com/android/mechanics/MotionValueTest.kt

+2 −3

Original line number	Diff line number	Diff line
		@@ -28,9 +28,7 @@ import androidx.compose.ui.test.junit4.createComposeRule
		import androidx.test.ext.junit.runners.AndroidJUnit4
		import com.android.mechanics.spec.Breakpoint
		import com.android.mechanics.spec.BreakpointKey
		import com.android.mechanics.spec.CanBeLastSegment
		import com.android.mechanics.spec.DirectionalMotionSpec
		import com.android.mechanics.spec.DirectionalMotionSpecBuilder
		import com.android.mechanics.spec.Guarantee
		import com.android.mechanics.spec.InputDirection
		import com.android.mechanics.spec.Mapping
		@@ -40,6 +38,7 @@ import com.android.mechanics.spec.SemanticKey
		import com.android.mechanics.spec.SemanticValue
		import com.android.mechanics.spec.buildDirectionalMotionSpec
		import com.android.mechanics.spec.builder
		import com.android.mechanics.spec.builder.DirectionalBuilderFn
		import com.android.mechanics.spec.reverseBuilder
		import com.android.mechanics.spec.with
		import com.android.mechanics.testing.CapturedSemantics
		@@ -766,7 +765,7 @@ class MotionValueTest {
		fun specBuilder(
		initialMapping: Mapping = Mapping.Identity,
		semantics: List<SemanticValue<*>> = emptyList(),
		init: DirectionalMotionSpecBuilder.() -> CanBeLastSegment,
		init: DirectionalBuilderFn,
		): MotionSpec {
		return MotionSpec(
		buildDirectionalMotionSpec(matStandardDefault, initialMapping, semantics, init),

mechanics/tests/src/com/android/mechanics/spec/MotionSpecTest.kt

+0 −3

Original line number	Diff line number	Diff line
		@@ -17,9 +17,6 @@
		package com.android.mechanics.spec

		import androidx.test.ext.junit.runners.AndroidJUnit4
		import com.android.mechanics.spec.DirectionalMotionSpecBuilderTest.Companion.S1
		import com.android.mechanics.spec.DirectionalMotionSpecBuilderTest.Companion.S2
		import com.android.mechanics.spec.DirectionalMotionSpecBuilderTest.Companion.Spring
		import com.android.mechanics.spring.SpringParameters
		import com.android.mechanics.testing.BreakpointSubject.Companion.assertThat
		import com.google.common.truth.Truth.assertThat