1# NativeDisplaySoloist
2
3
4## Overview
5
6The NativeDisplaySoloist module provides the native service that control the frame rate in threads other than the UI thread.
7
8**Since**: 12
9
10
11## Summary
12
13
14### Files
15
16| Name| Description|
17| -------- | -------- |
18| [native_display_soloist.h](native__display__soloist_8h.md) | Declares the functions for obtaining and using native display soloist.|
19
20
21### Structs
22
23| Name| Description|
24| -------- | -------- |
25| struct  [DisplaySoloist_ExpectedRateRange](_display_soloist___expected_rate_range.md) | Describes the expected frame rate range.|
26
27
28### Types
29
30| Name| Description|
31| -------- | -------- |
32| typedef struct [OH_DisplaySoloist](#oh_displaysoloist)  [OH_DisplaySoloist](#oh_displaysoloist) | Provides the declaration of an **OH_DisplaySoloist** struct.|
33| typedef void(\* [OH_DisplaySoloist_FrameCallback](#oh_displaysoloist_framecallback)) (long long timestamp, long long targetTimestamp, void \*data) | Defines the pointer to an OH_DisplaySoloist callback function.|
34| typedef struct [DisplaySoloist_ExpectedRateRange](_display_soloist___expected_rate_range.md)  [DisplaySoloist_ExpectedRateRange](#displaysoloist_expectedraterange) | Defines a struct for the expected frame rate range.|
35
36
37### Functions
38
39| Name| Description|
40| -------- | -------- |
41| [OH_DisplaySoloist](#oh_displaysoloist) \* [OH_DisplaySoloist_Create](#oh_displaysoloist_create) (bool useExclusiveThread) | Creates an **OH_DisplaySoloist** instance. A new **OH_DisplaySoloist** instance is created each time this API is called.|
42| int32_t [OH_DisplaySoloist_Destroy](#oh_displaysoloist_destroy) ([OH_DisplaySoloist](#oh_displaysoloist) \*displaySoloist) | Destroys an **OH_DisplaySoloist** object and reclaims the memory occupied.|
43| int32_t [OH_DisplaySoloist_Start](#oh_displaysoloist_start) ([OH_DisplaySoloist](#oh_displaysoloist) \*displaySoloist, [OH_DisplaySoloist_FrameCallback](#oh_displaysoloist_framecallback) callback, void \*data) | Sets a callback function for each frame. The callback function is triggered each time a VSync signal arrives.|
44| int32_t [OH_DisplaySoloist_Stop](#oh_displaysoloist_stop) ([OH_DisplaySoloist](#oh_displaysoloist) \*displaySoloist) | Stops requesting the next VSync signal and triggering the callback function.|
45| int32_t [OH_DisplaySoloist_SetExpectedFrameRateRange](#oh_displaysoloist_setexpectedframeraterange) ([OH_DisplaySoloist](#oh_displaysoloist) \*displaySoloist, [DisplaySoloist_ExpectedRateRange](_display_soloist___expected_rate_range.md) \*range) | Sets the expected frame rate range.|
46
47
48## Type Description
49
50
51### DisplaySoloist_ExpectedRateRange
52
53```
54typedef struct DisplaySoloist_ExpectedRateRange DisplaySoloist_ExpectedRateRange
55```
56
57**Description**
58
59Defines a struct for the expected frame rate range.
60
61**Since**: 12
62
63
64### OH_DisplaySoloist
65
66```
67typedef struct OH_DisplaySoloist OH_DisplaySoloist
68```
69
70**Description**
71
72Provides the declaration of an **OH_DisplaySoloist** struct.
73
74**Since**: 12
75
76
77### OH_DisplaySoloist_FrameCallback
78
79```
80typedef void(* OH_DisplaySoloist_FrameCallback) (long long timestamp, long long targetTimestamp, void *data)
81```
82
83**Description**
84
85Defines the pointer to an OH_DisplaySoloist callback function.
86
87**Since**: 12
88
89**Parameters**
90
91| Name| Description|
92| -------- | -------- |
93| timestamp | VSync timestamp.|
94| targetTimestamp | Expected VSync timestamp of the next frame.|
95| data | User-defined data.|
96
97
98## Function Description
99
100
101### OH_DisplaySoloist_Create()
102
103```
104OH_DisplaySoloist* OH_DisplaySoloist_Create (bool useExclusiveThread)
105```
106
107**Description**
108
109Creates an **OH_DisplaySoloist** instance. A new **OH_DisplaySoloist** instance is created each time this API is called.
110
111**Since**: 12
112
113**Parameters**
114
115| Name| Description|
116| -------- | -------- |
117| useExclusiveThread | Whether the **OH_DisplaySoloist** instance exclusively occupies a thread. The value **true** means that the instance exclusively occupies a thread, and **false** means that the instance shares a thread with others.|
118
119**Returns**
120
121Returns the pointer to the [OH_DisplaySoloist](#oh_displaysoloist) instance created if the operation is successful; returns a null pointer otherwise. The failure cause may be out of memory.
122
123
124### OH_DisplaySoloist_Destroy()
125
126```
127int32_t OH_DisplaySoloist_Destroy (OH_DisplaySoloist* displaySoloist)
128```
129
130**Description**
131
132Destroys an **OH_DisplaySoloist** object and reclaims the memory occupied.
133
134**Since**: 12
135
136**Parameters**
137
138| Name| Description|
139| -------- | -------- |
140| displaySoloist | Pointer to an [OH_DisplaySoloist](#oh_displaysoloist) instance.|
141
142**Returns**
143
144Returns **0** if the operation is successful; returns **-1** otherwise.
145
146
147### OH_DisplaySoloist_SetExpectedFrameRateRange()
148
149```
150int32_t OH_DisplaySoloist_SetExpectedFrameRateRange (OH_DisplaySoloist* displaySoloist, DisplaySoloist_ExpectedRateRange* range )
151```
152
153**Description**
154
155Sets the expected frame rate range.
156
157**Since**: 12
158
159**Parameters**
160
161| Name| Description|
162| -------- | -------- |
163| displaySoloist | Pointer to an [OH_DisplaySoloist](#oh_displaysoloist) instance.|
164| range | Pointer to the expected frame rate range, which is a [DisplaySoloist_ExpectedRateRange](_display_soloist___expected_rate_range.md) instance.|
165
166**Returns**
167
168Returns **0** if the operation is successful; returns **-1** otherwise.
169
170
171### OH_DisplaySoloist_Start()
172
173```
174int32_t OH_DisplaySoloist_Start (OH_DisplaySoloist* displaySoloist, OH_DisplaySoloist_FrameCallback callback, void* data )
175```
176
177**Description**
178
179Sets a callback function for each frame. The callback function is triggered each time a VSync signal arrives.
180
181**Since**: 12
182
183**Parameters**
184
185| Name| Description|
186| -------- | -------- |
187| displaySoloist | Pointer to an [OH_DisplaySoloist](#oh_displaysoloist) instance.|
188| callback | Callback function to be triggered when the next VSync signal arrives.|
189| data | Pointer to the user-defined data struct. The type is void\*.|
190
191**Returns**
192
193Returns **0** if the operation is successful; returns **-1** otherwise.
194
195
196### OH_DisplaySoloist_Stop()
197
198```
199int32_t OH_DisplaySoloist_Stop (OH_DisplaySoloist* displaySoloist)
200```
201
202**Description**
203
204Stops requesting the next VSync signal and triggering the callback function.
205
206**Since**: 12
207
208**Parameters**
209
210| Name| Description|
211| -------- | -------- |
212| displaySoloist | Pointer to an [OH_DisplaySoloist](#oh_displaysoloist) instance.|
213
214**Returns**
215
216Returns **0** if the operation is successful; returns **-1** otherwise.
217