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