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 | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 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```ts
193import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
194  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
195
196function onStarted() : void {
197  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
198  scene.then(async (result: Scene) => {
199    if (result) {
200      let anim: Animation = result.animations[0];
201      // Register a callback.
202      anim.onStarted(()=>{
203        console.info("onStarted");
204      });
205    }
206  });
207}
208```
209
210### pause
211pause(): void
212
213Pauses the animation. The animation remains in the current playing progress.
214
215**System capability**: SystemCapability.ArkUi.Graphics3D
216
217**Example**
218```ts
219import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
220  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
221
222function pause() : void {
223  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
224  scene.then(async (result: Scene) => {
225    if (result) {
226      let anim: Animation = result.animations[0];
227      // Pause the animation.
228      anim.pause();
229    }
230  });
231}
232```
233
234### restart
235restart(): void
236
237Plays the animation from the beginning.
238
239**System capability**: SystemCapability.ArkUi.Graphics3D
240
241**Example**
242```ts
243import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
244  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
245
246function restart() : void {
247  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
248  scene.then(async (result: Scene) => {
249    if (result) {
250      let anim: Animation = result.animations[0];
251      // Restart the animation.
252      anim.restart();
253    }
254  });
255}
256```
257
258### seek
259seek(position: number): void
260
261Plays the animation from the specified position.
262
263**System capability**: SystemCapability.ArkUi.Graphics3D
264
265**Parameters**
266| Name| Type| Mandatory| Description|
267| ---- | ---- | ---- | ---- |
268| position | number | Yes| Position from which the animation playback starts. The value range is [0, 1].|
269
270**Example**
271```ts
272import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
273  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
274
275function seek() : void {
276  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
277  scene.then(async (result: Scene) => {
278    if (result) {
279      let anim: Animation = result.animations[0];
280      // Set the animation playback progress to 10%.
281      anim.seek(0.1);
282    }
283  });
284}
285```
286
287### start
288start(): void
289
290Plays the animation based on the current progress.
291
292**System capability**: SystemCapability.ArkUi.Graphics3D
293
294**Example**
295```ts
296import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
297  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
298
299function start() : void {
300  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
301  scene.then(async (result: Scene) => {
302    if (result) {
303      let anim: Animation = result.animations[0];
304      // Start the animation.
305      anim.start();
306    }
307  });
308}
309```
310
311### stop
312stop(): void
313
314Stops playing the animation and sets its progress to **0** (not started).
315
316**System capability**: SystemCapability.ArkUi.Graphics3D
317
318**Example**
319```ts
320import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
321  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
322
323function stop() : void {
324  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
325  scene.then(async (result: Scene) => {
326    if (result) {
327      let anim: Animation = result.animations[0];
328      // Stop playing the animation and set its progress to 0 (not started).
329      anim.stop();
330    }
331  });
332}
333```
334
335### finish
336finish(): void
337
338Finishes the playing of the animation and sets its progress of **1** (finished).
339
340**System capability**: SystemCapability.ArkUi.Graphics3D
341
342```ts
343import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
344  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
345
346function finish() : void {
347  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
348  scene.then(async (result: Scene) => {
349    if (result) {
350      let anim: Animation = result.animations[0];
351      // Finish the playing of the animation and set its progress of **1** (finished).
352      anim.finish();
353    }
354  });
355}
356```
357
358## EnvironmentBackgroundType
359Enumerates the environment background types.
360
361**System capability**: SystemCapability.ArkUi.Graphics3D
362
363| Name| Value| Description|
364| ---- | ---- | ---- |
365| BACKGROUND_NONE | 0 | No background.|
366| BACKGROUND_IMAGE | 1 | Image background.|
367| BACKGROUND_CUBEMAP | 2 | Cubemap background.|
368| BACKGROUND_EQUIRECTANGULAR | 3 | Equirectangular background.|
369
370## Environment
371Environment resource, which inherits from [SceneResource](#sceneresource).
372### Properties
373
374**System capability**: SystemCapability.ArkUi.Graphics3D
375
376| Name| Type| Read Only| Optional| Description|
377| ---- | ---- | ---- | ---- | ---- |
378| backgroundType | [EnvironmentBackgroundType](#environmentbackgroundtype) | No| No| Environment background type.|
379| indirectDiffuseFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Indirect diffuse factor.|
380| indirectSpecularFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Indirect specular factor.|
381| environmentMapFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | No| No| Environment map factor.|
382| environmentImage | [Image](#image) \| null | No| Yes| Environment image. The default value is undefined.|
383| radianceImage | [Image](#image) \| null | No| Yes| Radiance image. The default value is undefined.|
384| irradianceCoefficients | [Vec3](js-apis-inner-scene-types.md#vec3)[] | No| Yes| Irradiance coefficients. The default value is undefined.|
385
386## Image
387Image resource, which inherits from [SceneResource](#sceneresource).
388### Properties
389
390**System capability**: SystemCapability.ArkUi.Graphics3D
391
392| Name| Type| Read Only| Optional| Description|
393| ---- | ---- | ---- | ---- | ---- |
394| width | number | Yes| No| Image width. The value is greater than 0.|
395| height | number | Yes| No| Image height. The value is greater than 0.|
396