1# Scene
2The Scene module is the basic module of ArkGraphics 3D and provides common data types such as **SceneResourceParamters** and **SceneNodeParamters**. It also provides basic methods such as glTF model loading, scene creation, and resource creation.
3
4> **NOTE**
5>
6> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
7
8## Modules to Import
9```ts
10import { SceneResourceParameters, SceneNodeParameters, SceneResourceFactory, Scene } from '@kit.ArkGraphics3D';
11```
12
13## SceneResourceParameters
14Describes the scene resource parameters, which are **name** and **uri**. The parameters describe the name of the scene resource and the path of the resource file required in the 3D scene.
15
16**System capability**: SystemCapability.ArkUi.Graphics3D
17| Name| Type| Read Only| Optional| Description|
18| ---- | ---- | ---- | ---- | ---- |
19| name | string | No| No| Name of the scene resource. It is customizable.|
20| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | No| Yes| Path of the resource file required in the 3D scene. The default value is undefined.|
21
22**Example**
23```ts
24import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
25  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
26
27function createShaderPromise() : Promise<Shader> {
28  return new Promise(() => {
29    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
30    scene.then(async (result: Scene) => {
31      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
32
33      // Create a variable of the SceneResourceParameters type and use it to create a shader.
34      let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource",
35        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") };
36      let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter);
37      return shader;
38    });
39  });
40}
41```
42
43## SceneNodeParameters
44Describes the scene node parameters, which are used to provide the name and path in the scene node tree.
45
46**System capability**: SystemCapability.ArkUi.Graphics3D
47| Name| Type| Read Only| Optional| Description|
48| ---- | ---- | ---- | ---- | ---- |
49| name | string | No| No| Name of the scene node. It is customizable.
50| path | string | No| Yes| Path in the scene node tree. It specifies the position of the created camera, light, or node in the scene node tree. Each layer is separated by a slash (/). If no path is provided, the node is set as a child node of the root node. The default value is undefined.|
51
52**Example**
53```ts
54import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
55  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
56
57function createNodePromise() : Promise<Node> {
58  return new Promise(() => {
59    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
60    scene.then(async (result: Scene) => {
61      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
62
63      // Create a variable of the SceneNodeParameters type and use it to create a node.
64      let sceneNodeParameter: SceneNodeParameters = { name: "empty_node",
65        path:"/rootNode_/empty_node" };
66      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
67      return node;
68    });
69  });
70}
71```
72## SceneResourceFactory
73Provides APIs to create camera, light, and other resources required in the 3D scene.
74
75### createCamera
76createCamera(params: SceneNodeParameters): Promise\<Camera>
77
78Creates a camera based on scene node parameters. This API uses a promise to return the result.
79
80**System capability**: SystemCapability.ArkUi.Graphics3D
81
82**Parameters**
83| Name| Type| Mandatory| Description|
84| ---- | ---- | ---- | ---- |
85| params | [SceneNodeParameters](#scenenodeparameters) | Yes| Scene node parameters.|
86
87**Return value**
88| Type| Description|
89| ---- | ---- |
90| Promise\<[Camera](js-apis-inner-scene-nodes.md#camera)> | Promise used to return the **Camera** object created.|
91
92**Example**
93```ts
94import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
95  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
96
97function createCameraPromise() : Promise<Camera> {
98  return new Promise(() => {
99    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
100    scene.then(async (result: Scene) => {
101      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
102      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
103      // Create a camera.
104      let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter);
105      return camera;
106    });
107  });
108}
109```
110
111### createLight
112createLight(params: SceneNodeParameters, lightType: LightType): Promise\<Light>
113
114Creates a light based on the scene node parameters and light type. This API uses a promise to return the result.
115
116**System capability**: SystemCapability.ArkUi.Graphics3D
117
118**Parameters**
119| Name| Type| Mandatory| Description|
120| ---- | ---- | ---- | ---- |
121| params | [SceneNodeParameters](#scenenodeparameters) | Yes| Scene node parameters.|
122| lightType | [LightType](js-apis-inner-scene-nodes.md#lighttype) | Yes| Light type.|
123
124**Return value**
125| Type| Description|
126| ---- | ---- |
127| Promise\<[Light](js-apis-inner-scene-nodes.md#light)> | Promise used to return the **Light** object created.|
128
129**Example**
130```ts
131import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
132  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
133
134function createLightPromise() : Promise<Light> {
135  return new Promise(() => {
136    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
137    scene.then(async (result: Scene) => {
138      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
139      let sceneLightParameter: SceneNodeParameters = { name: "light" };
140      // Create directional light.
141      let light: Promise<Light> = sceneFactory.createLight(sceneLightParameter, LightType.DIRECTIONAL);
142      return light;
143    });
144  });
145}
146```
147
148### createNode
149createNode(params: SceneNodeParameters): Promise\<Node>
150
151Creates a node. This API uses a promise to return the result.
152
153**System capability**: SystemCapability.ArkUi.Graphics3D
154
155**Parameters**
156| Name| Type| Mandatory| Description|
157| ---- | ---- | ---- | ---- |
158| params | [SceneNodeParameters](#scenenodeparameters) | Yes| Scene node parameters.|
159
160**Return value**
161| Type| Description|
162| ---- | ---- |
163| Promise\<[Node](js-apis-inner-scene-nodes.md#node)> | Promise used to return the **Node** object.|
164
165**Example**
166```ts
167import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
168  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
169
170function createNodePromise() : Promise<Node> {
171  return new Promise(() => {
172    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
173    scene.then(async (result: Scene) => {
174      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
175      let sceneNodeParameter: SceneNodeParameters = { name: "empty_node",
176        path:"/rootNode_/empty_node" };
177      // Create a node.
178      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
179      return node;
180    });
181  });
182}
183```
184
185### createMaterial
186createMaterial(params: SceneResourceParameters, materialType: MaterialType): Promise\<Material>
187
188Creates a material based on the scene resource parameters and material type. This API uses a promise to return the result.
189
190**System capability**: SystemCapability.ArkUi.Graphics3D
191
192**Parameters**
193| Name| Type| Mandatory| Description|
194| ---- | ---- | ---- | ---- |
195| params | [SceneResourceParameters](#sceneresourceparameters) | Yes| Scene resource parameters.|
196| materialType | [MaterialType](js-apis-inner-scene-resources.md#materialtype) | Yes| Material type.|
197
198**Return value**
199| Type| Description|
200| ---- | ---- |
201| Promise\<[Material](js-apis-inner-scene-resources.md#material)> | Promise used to return the **Material** object.|
202
203**Example**
204```ts
205import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
206  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
207
208function createMaterialPromise() : Promise<Material> {
209  return new Promise(() => {
210    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
211    scene.then(async (result: Scene) => {
212      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
213      let sceneMaterialParameter: SceneResourceParameters = { name: "material" };
214      // Create a material.
215      let material: Promise<Material> = sceneFactory.createMaterial(sceneMaterialParameter, MaterialType.SHADER);
216      return material;
217    });
218  });
219}
220```
221
222### createShader
223createShader(params: SceneResourceParameters): Promise\<Shader>
224
225Creates a shader based on the scene resource parameters. This API uses a promise to return the result.
226
227**System capability**: SystemCapability.ArkUi.Graphics3D
228
229**Parameters**
230| Name| Type| Mandatory| Description|
231| ---- | ---- | ---- | ---- |
232| params | [SceneResourceParameters](#sceneresourceparameters) | Yes| Scene resource parameters.|
233
234**Return value**
235| Type| Description|
236| ---- | ---- |
237| Promise\<[Shader](js-apis-inner-scene-resources.md#shader)> | Promise used to return the **Shader** object created.|
238
239**Example**
240```ts
241import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
242  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
243
244function createShaderPromise() : Promise<Shader> {
245  return new Promise(() => {
246    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
247    scene.then(async (result: Scene) => {
248      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
249      let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource",
250        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") };
251      // Create a shader.
252      let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter);
253      return shader;
254    });
255  });
256}
257```
258
259
260### createImage
261createImage(params: SceneResourceParameters): Promise\<Image>
262
263Creates an image. This API uses a promise to return the result.
264
265**System capability**: SystemCapability.ArkUi.Graphics3D
266
267**Parameters**
268| Name| Type| Mandatory| Description|
269| ---- | ---- | ---- | ---- |
270| params | [SceneResourceParameters](#sceneresourceparameters) | Yes| Scene resource parameters.|
271
272**Return value**
273| Type| Description|
274| ---- | ---- |
275| Promise\<[Image](js-apis-inner-scene-resources.md#image)> | Promise used to return the **Image** object created.|
276
277**Example**
278```ts
279import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
280  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
281
282function createImagePromise() : Promise<Image> {
283  return new Promise(() => {
284    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
285    scene.then(async (result: Scene) => {
286      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
287      let sceneImageParameter: SceneResourceParameters = { name: "image", uri: $rawfile("bricks.jpg") };
288      // Create an image.
289      let image: Promise<Image> = sceneFactory.createImage(sceneImageParameter);
290      return image;
291    });
292  });
293}
294```
295
296### createEnvironment
297createEnvironment(params: SceneResourceParameters): Promise\<Environment>
298
299Creates an environment based on the scene resource parameters. This API uses a promise to return the result.
300
301**System capability**: SystemCapability.ArkUi.Graphics3D
302
303**Parameters**
304| Name| Type| Mandatory| Description|
305| ---- | ---- | ---- | ---- |
306| params | [SceneResourceParameters](#sceneresourceparameters) | Yes| Scene resource parameters.|
307
308**Return value**
309| Type| Description|
310| ---- | ---- |
311| Promise\<[Environment](js-apis-inner-scene-resources.md#environment)> | Promise used to return the **Environment** object created.|
312
313**Example**
314```ts
315import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
316  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
317
318function createEnvironmentPromise() : Promise<Environment> {
319  return new Promise(() => {
320    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
321    scene.then(async (result: Scene) => {
322      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
323      let sceneEnvironmentParameter: SceneResourceParameters = { name: "env", uri: $rawfile("bricks.ktx") };
324      // Create an environment.
325      let env: Promise<Environment> = sceneFactory.createEnvironment(sceneEnvironmentParameter);
326      return env;
327    });
328  });
329}
330```
331
332## Scene
333Used to set a scene.
334
335### Properties
336
337**System capability**: SystemCapability.ArkUi.Graphics3D
338
339| Name| Type| Read Only| Optional| Description|
340| ---- | ---- | ---- | ---- | ---- |
341| environment | [Environment](js-apis-inner-scene-resources.md#environment) | No| No| Environment object.|
342| animations | [Animation](js-apis-inner-scene-resources.md#animation)[] | Yes| No| Animation array used to hold the animation objects in the 3D scene.|
343| root | [Node](js-apis-inner-scene-nodes.md#node) \| null | Yes| No| Root node in the 3D scene tree.|
344
345### load
346static load(uri?: ResourceStr): Promise\<Scene>
347
348Loads a resource by path.
349
350**System capability**: SystemCapability.ArkUi.Graphics3D
351
352**Parameters**
353| Name| Type| Mandatory| Description|
354| ---- | ---- | ---- | ---- |
355| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | No| Path of the model file resource to load. The default value is undefined.|
356
357**Return value**
358| Type| Description|
359| ---- | ---- |
360| Promise\<[Scene](#scene)> | Promise used to return the **Scene** object created.|
361
362**Example**
363```ts
364import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
365  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
366
367function loadModel() : void {
368  // Load the model.
369  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
370  scene.then(async (result: Scene) => {});
371}
372```
373
374### getNodeByPath
375getNodeByPath(path: string, type?: NodeType): Node | null
376
377Obtains a node by path.
378
379**System capability**: SystemCapability.ArkUi.Graphics3D
380
381**Parameters**
382| Name| Type| Mandatory| Description|
383| ---- | ---- | ---- | ---- |
384| path | string | Yes| Path in the scene node tree. Each layer is separated by a slash (/).|
385| type | [NodeType](js-apis-inner-scene-nodes.md#nodetype) | No| Type of the node expected. The default value is null.|
386
387**Return value**
388| Type| Description|
389| ---- | ---- |
390| [Node](js-apis-inner-scene-nodes.md#node) \| null | Returns the **Node** object requested. If no node is found in the specified path or the found node type does not match the expected type, null is returned.|
391
392**Example**
393```ts
394import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
395  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
396
397function getNode() : void {
398  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
399  scene.then(async (result: Scene) => {
400    if (result) {
401         // Search for a node in the specified path.
402        let node : Node | null = result.getNodeByPath("rootNode_");
403    }
404  });
405}
406```
407
408### getResourceFactory
409getResourceFactory(): SceneResourceFactory
410
411Obtains the scene resource factory.
412
413**System capability**: SystemCapability.ArkUi.Graphics3D
414
415**Return value**
416| Type| Description|
417| ---- | ---- |
418| [SceneResourceFactory](js-apis-inner-scene.md#sceneresourcefactory)| Scene resource factory.|
419
420**Example**
421```ts
422import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
423  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
424
425function getFactory() : void {
426  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
427  scene.then(async (result: Scene) => {
428    if (result) {
429         // Obtain a SceneResourceFactory object.
430        let sceneFactory: SceneResourceFactory = result.getResourceFactory();
431    }
432  });
433}
434```
435
436### destroy
437destroy(): void
438
439Destroys this scene and releases all scene resources.
440
441**System capability**: SystemCapability.ArkUi.Graphics3D
442
443**Example**
444```ts
445import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
446  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
447
448function destroy() : void {
449  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
450  scene.then(async (result: Scene) => {
451    if (result) {
452         // Destroy the scene.
453        result.destroy();
454    }
455  });
456}
457```
458