1# Creating and Using a Virtual Screen (ArkTS) (for System Applications Only)
2
3## When to Use
4
5A virtual screen serves as a conceptual representation in the system. It allows an application to create a virtual screen without depending on a physical screen. It provides a rendering target through the surface, allowing applications to render content such as images and videos onto the virtual screen.
6
7## Available APIs
8
9The following lists the common APIs available for the virtual screen. For details about the APIs, see [@ohos.screen (Screen) (System API)](../reference/apis-arkui/js-apis-screen-sys.md).
10
11| API                                                      | Description                                        |
12| ------------------------------------------------------------ | -------------------------------------------- |
13| createVirtualScreen(options:VirtualScreenOption): Promise<Screen> | Creates a virtual screen. This API uses a promise to return the result.         |
14| setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> | Sets the surface for a virtual screen. This API uses a promise to return the result.|
15| makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> | Sets screen mirroring. This API uses a promise to return the result. |
16| stopMirror(mirrorScreen:Array<number>): Promise<void> | Stops screen mirroring. This API uses a promise to return the result.   |
17| destroyVirtualScreen(screenId:number): Promise<void>   | Destroys a virtual screen. This API uses a promise to return the result.         |
18
19## How to Develop
20
211. Create a virtual screen.
22
23   - Define the parameters used for creating the virtual screen.
24
25   - Call **createVirtualScreen()** to create the virtual screen.
26
27   The ohos.permission.CAPTURE_SCREEN permission is required for calling **createVirtualScreen()**. For details, see [Requesting Restricted Permissions](../security/AccessToken/declare-permissions-in-acl.md).
28
292. Bind the surface ID of the rendering target to the virtual screen.
30
31   To enable the virtual screen to accurately present the intended content, bind the surface ID of the rendering target to the virtual screen. The operations are as follows:
32
33   - Call **getXComponentSurfaceId()** to obtain the surface ID. As a unique identifier, the surface ID carries important data related to the screen's image properties. It facilitates the acquisition and adjustable configuration of the image properties such as resolution and pixel format.
34
35   - Call **setVirtualScreenSurface()** to associate the obtained surface ID with the virtual screen, ensuring that the virtual screen can properly receive and process the associated image data.
36
373. Call **makeMirror()** to create a mirror of the physical screen and project it onto the virtual screen.
38
39   After the virtual screen is created, the application can call **makeMirror()** to start mirroring of the physical screen based on service requirements. This API duplicates the content currently displayed on the physical screen and projects it onto the virtual screen created earlier, facilitating real-time synchronized viewing between the two screens.
40
414. Stop mirroring.
42
43   If synchronized mirroring between the physical and virtual screens is no longer needed, call **stopMirror()** to stop mirroring. This operation terminates the mirroring from the physical screen to the virtual screen, restoring the virtual screen to an autonomous state.
44
455. Destroy the virtual screen.
46
47   Upon completion of the service process and when the virtual screen is no longer needed, release the related resources in a timely manner to prevent memory leaks and unnecessary consumption of system resources. You can call **destroyVirtualScreen()** to destroy the virtual screen securely and effectively, thereby releasing the system resources occupied by the virtual screen.
48
49```ts
50import { BusinessError } from '@kit.BasicServicesKit';
51import { screen } from '@kit.ArkUI';
52
53@Entry
54@Component
55struct VirtualScreen {
56  xComponentController: XComponentController = new XComponentController();
57
58  build() {
59    RelativeContainer() {
60      Column() {
61        XComponent({
62          type: XComponentType.SURFACE,
63          controller: this.xComponentController
64        })
65      }
66      Button('Virtual screen')
67        .onClick(() => {
68          // screenVirtualScreen is used to store the created virtual screen object.
69          let screenVirtualScreen: screen.Screen | null = null;
70          class VirtualScreenOption {
71            name: string = '';
72            width: number = 0;
73            height: number = 0;
74            density: number = 0;
75            surfaceId: string = '';
76          }
77          // option defines the parameters required for creating the virtual screen.
78          let option: VirtualScreenOption = {
79            name: 'screen01',
80            width: 1080,
81            height: 2340,
82            density: 2,
83            surfaceId: ''
84          };
85          // Create a virtual screen.
86          screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => {
87            const errCode: number = err.code;
88            if (errCode) {
89              console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`);
90              return;
91            }
92            screenVirtualScreen = data;
93            console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
94            // Obtain the surface ID.
95            let surfaceId = this.xComponentController.getXComponentSurfaceId();
96            screen.setVirtualScreenSurface(screenVirtualScreen.id, surfaceId, (err: BusinessError) => {
97              const errCode: number = err.code;
98              if (errCode) {
99                console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`);
100                return;
101              }
102              console.info('Succeeded in setting the surface for the virtual screen.');
103            });
104            let mirrorScreenIds: Array<number> = [screenVirtualScreen.id];
105            // Obtain all screens.
106            screen.getAllScreens((err: BusinessError, data: Array<screen.Screen>) => {
107              const errCode: number = err.code;
108              if (errCode) {
109                console.error(`Failed to get all screens. Code:${err.code},message is ${err.message}`);
110                return;
111              }
112              // Call makeMirror to create a mirror for the physical screen and project it to the virtual screen.
113              let mainScreenId = data.find(item => item.sourceMode === 0)?.id;
114              screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: number) => {
115                const errCode: number = err.code;
116                if (errCode) {
117                  console.error(`Failed to set screen mirroring. Code:${err.code},message is ${err.message}`);
118                  return;
119                }
120                console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data));
121              });
122              // Stop mirroring.
123              screen.stopMirror(mirrorScreenIds, (err: BusinessError) => {
124                const errCode: number = err.code;
125                if (errCode) {
126                  console.error(`Failed to stop mirror screens. Code:${err.code},message is ${err.message}`);
127                  return;
128                }
129                console.info('Succeeded in stopping mirror screens.');
130              });
131              // Destroy the virtual screen.
132              screen.destroyVirtualScreen(mirrorScreenIds[0], (err: BusinessError) => {
133                const errCode: number = err.code;
134                if (errCode) {
135                  console.error(`Failed to destroy the virtual screen. Code:${err.code},message is ${err.message}`);
136                  return;
137                }
138                console.info('Succeeded in destroying the virtual screen.');
139              });
140            });
141          });
142        })
143    }
144    .height('100%')
145    .width('100%')
146  }
147}
148```
149