1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.google.android.msdl.domain
18 
19 import android.os.VibrationAttributes
20 import androidx.annotation.FloatRange
21 
22 /**
23  * Properties associated to an interaction that is currently occurring.
24  *
25  * The properties define parameters required to play the data associated with a
26  * [com.google.android.msdl.data.model.MSDLToken]. These can be dynamic, in the sense that they can
27  * be created as an interaction progresses throughout time.
28  *
29  * Each set of properties needs to define [VibrationAttributes] for a haptic effect to play with. If
30  * no properties are provided when playing a token, the effect will play with a default set of
31  * attributes with [VibrationAttributes.USAGE_TOUCH] usage.
32  */
33 interface InteractionProperties {
34 
35     /** [android.os.VibrationAttributes] for haptics in the interaction */
36     val vibrationAttributes: VibrationAttributes
37 
38     /**
39      * Properties for a vibration that changes scale dynamically.
40      *
41      * The scale must be calculated at the time of calling the
42      * [com.google.android.msdl.domain.MSDLPlayer] API to play feedback. Use these properties for
43      * effects where vibration scales depend on temporal variables, such as position and velocity
44      * for slider haptics.
45      *
46      * @param[scale] The scale of the vibration at the time of calling. Must be between 0 and 1.
47      * @param[vibrationUsageId] Id used to create [android.os.VibrationAttributes]
48      */
49     data class DynamicVibrationScale(
50         @FloatRange(from = 0.0, to = 1.0) val scale: Float,
51         override val vibrationAttributes: VibrationAttributes,
52     ) : InteractionProperties
53 }
54