1# SceneResource
2The SceneResource module provides basic resource types in 3D graphics.
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 { SceneResourceType, SceneResource, Shader, MaterialType, Material, ShaderMaterial,
11  SubMesh, Mesh, Animation, EnvironmentBackgroundType, Environment, Image } from '@kit.ArkGraphics3D';
12```
13## SceneResourceType
14Enumerates the scene resource types, which are used to classify resources in a scene.
15
16**System capability**: SystemCapability.ArkUi.Graphics3D
17
18| Name| Value| Description|
19| ---- | ---- | ---- |
20| UNKNOWN | 0 | Unknown.|
21| NODE | 1 | Node resource.|
22| ENVIRONMENT | 2 | Environment resource.|
23| MATERIAL | 3 | Material resource.|
24| MESH | 4 | Mesh resource.|
25| ANIMATION | 5 | Animation resource.|
26| SHADER | 6 | Shader resource.|
27| IMAGE | 7 | Image resource.|
28
29## SceneResource
30Describes a resource in a scene.
31
32### Properties
33
34**System capability**: SystemCapability.ArkUi.Graphics3D
35
36| Name| Type| Read Only| Optional| Description|
37| ---- | ---- | ---- | ---- | ---- |
38| name | string | No| No| Name. There is no special format requirement.|
39| resourceType | [SceneResourceType](#sceneresourcetype) | Yes| No| Scene resource type. The default value is undefined.|
40| uri | [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | Yes| Yes| Resource to load. The default value is undefined.|
41
42### destroy
43destroy(): void
44
45Destroys the scene resource and releases all associated resources or references. Once released, the resource can no longer be used or accessed.
46
47**System capability**: SystemCapability.ArkUi.Graphics3D
48
49**Example**
50```ts
51import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
52  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
53
54function destroy() : void {
55  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
56  scene.then(async (result: Scene) => {
57    if (result) {
58      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
59      let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource",
60        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") };
61      let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter);
62      shader.then(async (shaderResult:Shader) => {
63         // Release the resource.
64         shaderResult.destroy();
65      });
66    }
67  });
68}
69```
70
71## Shader
72Shader resource, which inherits from [SceneResource](#sceneresource).
73
74### Properties
75
76**System capability**: SystemCapability.ArkUi.Graphics3D
77
78| Name| Type| Read Only| Optional| Description|
79| ---- | ---- | ---- | ---- | ---- |
80| inputs | Record<string, number \| Vec2 \| Vec3 \| Vec4 \| Image> | Yes| No| Inputs of the shader.|
81
82## MaterialType
83Enumerates the material types in a scene.
84
85**System capability**: SystemCapability.ArkUi.Graphics3D
86
87| Name| Value| Description|
88| ---- | ---- | ---- |
89| SHADER | 1 | Shader-defined.|
90
91## Material
92Material resource, which inherits from [SceneResource](#sceneresource).
93### Properties
94
95**System capability**: SystemCapability.ArkUi.Graphics3D
96
97| Name| Type| Read Only| Optional| Description|
98| ---- | ---- | ---- | ---- | ---- |
99| materialType | [MaterialType](#materialtype) | Yes| No| Material type.|
100
101## ShaderMaterial
102Shader material, which inherits from [Material](#material).
103### Properties
104
105**System capability**: SystemCapability.ArkUi.Graphics3D
106
107| Name| Type| Read Only| Optional| Description|
108| ---- | ---- | ---- | ---- | ---- |
109| colorShader | [Shader](#shader) | No| Yes| Shader. The default value is undefined.|
110
111## SubMesh
112Sub-mesh resource.
113### Properties
114
115**System capability**: SystemCapability.ArkUi.Graphics3D
116
117| Name| Type| Read Only| Optional| Description|
118| ---- | ---- | ---- | ---- | ---- |
119| name | string | No| No| Name. There is no special format requirement.|
120| material | [Material](#material) | No| No| Material.|
121| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | Yes| No| Axis aligned bounding box.|
122
123## Mesh
124Mesh resource, which inherits from [SceneResource](#sceneresource).
125### Properties
126
127**System capability**: SystemCapability.ArkUi.Graphics3D
128
129| Name| Type| Read Only| Optional| Description|
130| ---- | ---- | ---- | ---- | ---- |
131| subMeshes | [SubMesh](#submesh)[] | Yes| No| Array of sub-meshes.|
132| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | Yes| No| Axis aligned bounding box.|
133| materialOverride | [Material](#material) | No| Yes| Material. The default value is undefined.|
134
135## Animation
136Animation resource, which inherits from [SceneResource](#sceneresource).
137### Properties
138
139**System capability**: SystemCapability.ArkUi.Graphics3D
140
141| Name| Type| Read Only| Optional| Description|
142| ---- | ---- | ---- | ---- | ---- |
143| enabled | boolean | No| No| Whether the animation is enabled. The value **true** means that the animation can be played, and **false** means the opposite.|
144| duration | number | Yes| No| Duration of the animation. The value is greater than or equal to 0.|
145| running | boolean | Yes| No| Running status of the animation. The value **true** means that the animation is being played, and **false** means the opposite.|
146| progress | number | Yes| No| Playing progress of the animation. The value range is [0, 1].|
147
148### onFinished
149onFinished(callback: Callback\<void>): void
150
151Called when the animation playback is complete or the **finish** API is called.
152
153**System capability**: SystemCapability.ArkUi.Graphics3D
154
155**Parameters**
156| Name| Type| Mandatory| Description|
157| ---- | ---- | ---- | ---- |
158| callback | Callback\<void> | Yes| Callback function. The return value is null.|
159
160**Example**
161```ts
162import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
163  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
164
165function onFinished() : void {
166  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
167  scene.then(async (result: Scene) => {
168    if (result) {
169      let anim: Animation = result.animations[0];
170      // Register a callback.
171      anim.onFinished(()=>{
172        console.info("onFinished");  
173      });
174    }
175  });
176}
177```
178
179### onStarted
180onStarted(callback: Callback\<void>): void
181
182Called when the animation starts to play. The start operation is triggered by calling **start** or **restart**.
183
184**Parameters**
185| Name| Type| Mandatory| Description|
186| ---- | ---- | ---- | ---- |
187| callback | Callback\<void> | Yes| Callback function. The return value is null.|
188
189**System capability**: SystemCapability.ArkUi.Graphics3D
190
191**Example**
192
193```ts
194import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
195  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
196
197function onStarted() : void {
198  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
199  scene.then(async (result: Scene) => {
200    if (result) {
201      let anim: Animation = result.animations[0];
202      // Register a callback.
203      anim.onStarted(()=>{
204        console.info("onStarted");  
205      });
206    }
207  });
208}
209```
210
211### pause
212pause(): void
213
214Pauses the animation. The animation remains in the current playing progress.
215
216**System capability**: SystemCapability.ArkUi.Graphics3D
217
218**Example**
219```ts
220import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
221  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
222
223function pause() : void {
224  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
225  scene.then(async (result: Scene) => {
226    if (result) {
227      let anim: Animation = result.animations[0];
228      // Pause the animation.
229      anim.pause();
230    }
231  });
232}
233```
234
235### restart
236restart(): void
237
238Plays the animation from the beginning.
239
240**System capability**: SystemCapability.ArkUi.Graphics3D
241
242**Example**
243```ts
244import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
245  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
246
247function restart() : void {
248  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
249  scene.then(async (result: Scene) => {
250    if (result) {
251      let anim: Animation = result.animations[0];
252      // Restart the animation.
253      anim.restart();
254    }
255  });
256}
257```
258
259### seek
260seek(position: number): void
261
262Plays the animation from the specified position.
263
264**System capability**: SystemCapability.ArkUi.Graphics3D
265
266**Parameters**
267| Name| Type| Mandatory| Description|
268| ---- | ---- | ---- | ---- |
269| position | number | Yes| Position from which the animation playback starts. The value range is [0, 1].|
270
271**Example**
272```ts
273import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
274  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
275
276function seek() : void {
277  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
278  scene.then(async (result: Scene) => {
279    if (result) {
280      let anim: Animation = result.animations[0];
281      // Set the animation playback progress to 10%.
282      anim.seek(0.1);
283    }
284  });
285}
286```
287
288### start
289start(): void
290
291Plays the animation based on the current progress.
292
293**System capability**: SystemCapability.ArkUi.Graphics3D
294
295**Example**
296```ts
297import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
298  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
299
300function start() : void {
301  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
302  scene.then(async (result: Scene) => {
303    if (result) {
304      let anim: Animation = result.animations[0];
305      // Start the animation.
306      anim.start();
307    }
308  });
309}
310```
311
312### stop
313stop(): void
314
315Stops playing the animation and sets its progress to **0** (not started).
316
317**System capability**: SystemCapability.ArkUi.Graphics3D
318
319**Example**
320```ts
321import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
322  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
323
324function stop() : void {
325  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
326  scene.then(async (result: Scene) => {
327    if (result) {
328      let anim: Animation = result.animations[0];
329      // Stop playing the animation and set its progress to 0 (not started).
330      anim.stop();
331    }
332  });
333}
334```
335
336### finish
337finish(): void
338
339Finishes the playing of the animation and sets its progress of **1** (finished).
340
341**System capability**: SystemCapability.ArkUi.Graphics3D
342
343```ts
344import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
345  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
346
347function finish() : void {
348  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
349  scene.then(async (result: Scene) => {
350    if (result) {
351      let anim: Animation = result.animations[0];
352      // Finish the playing of the animation and set its progress of **1** (finished).
353      anim.finish();
354    }
355  });
356}
357```
358
359## EnvironmentBackgroundType
360Enumerates the environment background types.
361
362**System capability**: SystemCapability.ArkUi.Graphics3D
363
364| Name| Value| Description|
365| ---- | ---- | ---- |
366| BACKGROUND_NONE | 0 | No background.|
367| BACKGROUND_IMAGE | 1 | Image background.|
368| BACKGROUND_CUBEMAP | 2 | Cubemap background.|
369| BACKGROUND_EQUIRECTANGULAR | 3 | Equirectangular background.|
370
371## Environment
372Environment resource, which inherits from [SceneResource](#sceneresource).
373### Properties
374
375**System capability**: SystemCapability.ArkUi.Graphics3D
376
377| Name| Type| Read Only| Optional| Description|
378| ---- | ---- | ---- | ---- | ---- |
379| backgroundType | [EnvironmentBackgroundType](#environmentbackgroundtype) | No| No| Environment background type.|
380| indirectDiffuseFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Indirect diffuse factor.|
381| indirectSpecularFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Indirect specular factor.|
382| environmentMapFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Environment map factor.|
383| environmentImage | [Image](#image) \| null | No| Yes| Environment image. The default value is undefined.|
384| radianceImage | [Image](#image) \| null | No| Yes| Radiance image. The default value is undefined.|
385| irradianceCoefficients | [Vec3](js-apis-inner-scene-types.md#vec3)[] | No| Yes| Irradiance coefficients. The default value is undefined.|
386
387## Image
388Image resource, which inherits from [SceneResource](#sceneresource).
389### Properties
390
391**System capability**: SystemCapability.ArkUi.Graphics3D
392
393| Name| Type| Read Only| Optional| Description|
394| ---- | ---- | ---- | ---- | ---- |
395| width | number | Yes| No| Image width. The value is greater than 0.|
396| height | number | Yes| No| Image height. The value is greater than 0.|
397