1#  @ohos.graphics.displaySync (Variable Frame Rate)
2The displaySync module allows your application to draw its custom UI content at a specified frame rate.
3
4> **NOTE**
5>
6> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.
7
8
9## Modules to Import
10
11```ts
12import { displaySync } from '@kit.ArkGraphics2D';
13```
14
15## displaySync.create
16create(): DisplaySync
17
18Creates a **DisplaySync** object, through which you can set the frame rate of the custom UI content.
19
20**System capability**: SystemCapability.ArkUI.ArkUI.Full
21
22**Return value**
23
24| Type               | Description                    |
25| ------------------ | ------------------------ |
26| [DisplaySync](#displaysync)  | **DisplaySync** object created.              |
27
28**Example**
29
30```ts
31let backDisplaySync: displaySync.DisplaySync = displaySync.create();
32```
33## IntervalInfo
34
35You can obtain the timestamp information from the event callback, including the timestamp when the current frame arrives and the timestamp when the next frame is expected to arrive.
36
37**System capability**: SystemCapability.ArkUI.ArkUI.Full
38
39| Name            | Type                                     | Read-only| Optional| Description                                      |
40| ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ |
41| timestamp      | number | Yes  | No  | Time when the current frame arrives, in nanoseconds.|
42| targetTimestamp | number| Yes  | No  | Expected arrival time of the next frame, in nanoseconds.|
43
44## DisplaySync
45
46 An object that implements the setting of the frame rate and callback. It provides APIs for you to set the frame rate, register a callback, and start/stop the callback.
47
48 Before calling any of the following APIs, you must use [displaySync.create()](#displaysynccreate) to create a **DisplaySync** instance.
49
50### setExpectedFrameRateRange
51
52setExpectedFrameRateRange(rateRange: ExpectedFrameRateRange) : void
53
54Sets the expected frame rate range.
55
56**System capability**: SystemCapability.ArkUI.ArkUI.Full
57
58**Parameters**
59
60| Name          | Type                                      | Mandatory| Description                         |
61| --------------- | ------------------------------------------ | ---- | -----------------------------|
62| rateRange       | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11)| Yes  | Expected frame rate range.|
63
64**Error codes**
65
66For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
67
68| ID| Error Message|
69| ------- | -------- |
70| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2.Incorrect parameters types. 3. Parameter verification failed. or check ExpectedFrameRateRange if valid.|
71
72**Example**
73
74```ts
75let range : ExpectedFrameRateRange = {
76  expected: 10,
77  min:0,
78  max:120
79};
80
81// Set the expected frame rate range.
82backDisplaySync?.setExpectedFrameRateRange(range)
83```
84
85### on('frame')
86
87on(type: 'frame', callback: Callback\<IntervalInfo\>): void
88
89Subscribes to change events of each frame.
90
91**System capability**: SystemCapability.ArkUI.ArkUI.Full
92
93**Parameters**
94
95| Name          | Type                                      | Mandatory| Description                         |
96| --------------- | ------------------------------------------ | ---- | -----------------------------|
97| type | 'frame'| Yes  | Event type. The value is fixed at **'frame'**.|
98| callback    | Callback<[IntervalInfo](#intervalinfo)>| Yes  | Callback used for subscription.|
99
100
101**Example**
102
103```ts
104let callback = (frameInfo: displaySync.IntervalInfo) => {
105    console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp);
106}
107
108// Subscribe to the event.
109backDisplaySync?.on("frame", callback)
110```
111
112### off('frame')
113
114off(type: 'frame', callback\?: Callback\<IntervalInfo\>): void
115
116Unsubscribes from change events of each frame.
117
118**System capability**: SystemCapability.ArkUI.ArkUI.Full
119
120**Parameters**
121
122| Name          | Type                                      | Mandatory| Description                         |
123| --------------- | ------------------------------------------ | ---- | -----------------------------|
124| type | 'frame'| Yes  | Event type. The value is fixed at **'frame'**.|
125| callback    | Callback<[IntervalInfo](#intervalinfo)>| No  | Callback used for unsubscription. If no value is passed in, all subscriptions to the specified event are canceled.|
126
127
128**Example**
129
130```ts
131let callback = (frameInfo: displaySync.IntervalInfo) => {
132    console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp);
133}
134
135backDisplaySync?.on("frame", callback)
136
137// Unsubscribe from the event.
138backDisplaySync?.off("frame", callback)
139```
140
141### start
142
143start(): void
144
145Starts callback for each frame.
146
147**System capability**: SystemCapability.ArkUI.ArkUI.Full
148
149**Example**
150
151```ts
152let range : ExpectedFrameRateRange = {
153  expected: 10,
154  min:0,
155  max:120
156};
157
158backDisplaySync?.setExpectedFrameRateRange(range)
159
160let callback = (frameInfo: displaySync.IntervalInfo) => {
161    console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp);
162}
163
164backDisplaySync?.on("frame", callback)
165
166// Start callback for each frame.
167backDisplaySync?.start()
168```
169
170> **NOTE**
171>
172> The **start()** API associates a **DisplaySync** object with a UI instance and window. If the start operation is performed on a non-UI page or in an asynchronous callback, the context of the current UI may not be obtained, causing the API call to fail and consequently the subscription function to fail. Therefore, you can use [runScopedTask](../apis-arkui/js-apis-arkui-UIContext.md#runscopedtask) of **UIContext** to specify the UI context for executing the **start()** API.
173
174**Example**
175
176```ts
177import { displaySync } from '@kit.ArkGraphics2D';
178import { UIContext } from '@kit.ArkUI';
179
180// xxx.ets
181@Entry
182@Component
183struct Index {
184  // Create a DisplaySync instance.
185  backDisplaySync: displaySync.DisplaySync = displaySync.create();
186
187  aboutToAppear() {
188    // Obtain a UIContext instance.
189    let uiContext: UIContext = this.getUIContext();
190    // Call start() in the current UI context.
191    uiContext?.runScopedTask(() => {
192      this.backDisplaySync?.start();
193    })
194  }
195
196  build() {
197    // ...
198  }
199}
200
201```
202
203### stop
204
205stop(): void
206
207Stops callback for each frame.
208
209
210**System capability**: SystemCapability.ArkUI.ArkUI.Full
211
212
213**Example**
214
215```ts
216let range : ExpectedFrameRateRange = {
217  expected: 10,
218  min:0,
219  max:120
220};
221
222backDisplaySync?.setExpectedFrameRateRange(range)
223
224let callback = (frameInfo: displaySync.IntervalInfo) => {
225    console.info("DisplaySync", 'TimeStamp:' + frameInfo.timestamp + ' TargetTimeStamp: ' + frameInfo.targetTimestamp);
226}
227
228backDisplaySync?.on("frame", callback)
229
230backDisplaySync?.start()
231
232// ...
233
234// Stop callback for each frame.
235backDisplaySync?.stop()
236```
237