1# SceneResource 2本模块提供3D图形中常用的基本资源类型。 3 4> **说明：** 5> - 本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标标记接口的起始版本。 6 7## 导入模块 8```ts 9import { SceneResourceType, SceneResource, Shader, MaterialType, Material, ShaderMaterial, 10 SubMesh, Mesh, Animation, EnvironmentBackgroundType, Environment, Image } from '@kit.ArkGraphics3D'; 11``` 12## SceneResourceType 13场景资源类型枚举，对场景中的资源进行分类。 14 15**系统能力：** SystemCapability.ArkUi.Graphics3D 16 17| 名称 | 值 | 说明 | 18| ---- | ---- | ---- | 19| UNKNOWN | 0 | 未定义类型。 | 20| NODE | 1 | 结点类型。 | 21| ENVIRONMENT | 2 | 环境类型。 | 22| MATERIAL | 3 | 材质类型。 | 23| MESH | 4 | 网格类型。 | 24| ANIMATION | 5 | 动画类型。 | 25| SHADER | 6 | 着色器类型。 | 26| IMAGE | 7 | 图片类型。 | 27| MESH_RESOURCE<sup>18+</sup> | 8 | 网格资源类型。 | 28 29## SceneResource 30用于表示场景中的资源。 31 32### 属性 33 34**系统能力：** SystemCapability.ArkUi.Graphics3D 35 36| 名称 | 类型 | 只读 | 可选 | 说明 | 37| ---- | ---- | ---- | ---- | ---- | 38| name | string | 否 | 否 | 名称，没有特殊格式要求。 | 39| resourceType | [SceneResourceType](#sceneresourcetype) | 是 | 否 | 场景资源类型，默认值为undefined。| 40| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 是 | 是 | 需要加载的资源，默认值为undefined。| 41 42### destroy 43destroy(): void 44 45销毁场景资源，释放所有关联的资源或引用，一旦被释放，资源就不能被再次使用或访问。 46 47**系统能力：** SystemCapability.ArkUi.Graphics3D 48 49**示例：** 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 // 释放资源 64 shaderResult.destroy(); 65 }); 66 } 67 }); 68} 69``` 70 71## Shader 72着色器，继承自[SceneResource](#sceneresource)。 73 74### 属性 75 76**系统能力：** SystemCapability.ArkUi.Graphics3D 77 78| 名称 | 类型 | 只读 | 可选 | 说明 | 79| ---- | ---- | ---- | ---- | ---- | 80| inputs | Record<string, number \| Vec2 \| Vec3 \| Vec4 \| Image> | 是 | 否 | 着色器输入。 | 81 82## MaterialType 83场景中物体材质类型枚举。 84 85**系统能力：** SystemCapability.ArkUi.Graphics3D 86 87| 名称 | 值 | 说明 | 88| ---- | ---- | ---- | 89| SHADER | 1 | 材质由着色器定义。 | 90 91## Material 92材质类型，继承自[SceneResource](#sceneresource)。 93### 属性 94 95**系统能力：** SystemCapability.ArkUi.Graphics3D 96 97| 名称 | 类型 | 只读 | 可选 | 说明 | 98| ---- | ---- | ---- | ---- | ---- | 99| materialType | [MaterialType](#materialtype) | 是 | 否 | 材质类型。 | 100 101## ShaderMaterial 102着色器材质，继承自[Material](#material)。 103### 属性 104 105**系统能力：** SystemCapability.ArkUi.Graphics3D 106 107| 名称 | 类型 | 只读 | 可选 | 说明 | 108| ---- | ---- | ---- | ---- | ---- | 109| colorShader | [Shader](#shader) | 否 | 是 | 着色器，默认值为undefined。 | 110 111## SubMesh 112子网格类型。 113### 属性 114 115**系统能力：** SystemCapability.ArkUi.Graphics3D 116 117| 名称 | 类型 | 只读 | 可选 | 说明 | 118| ---- | ---- | ---- | ---- | ---- | 119| name | string | 否 | 否 | 名称，没有特殊格式要求。 | 120| material | [Material](#material) | 否 | 否 | 材质。 | 121| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | 是 | 否 | 轴对齐边界盒。 | 122 123## Mesh 124网格类型，继承自[SceneResource](#sceneresource)。 125### 属性 126 127**系统能力：** SystemCapability.ArkUi.Graphics3D 128 129| 名称 | 类型 | 只读 | 可选 | 说明 | 130| ---- | ---- | ---- | ---- | ---- | 131| subMeshes | [SubMesh](#submesh)[] | 是 | 否 | 子网格数组。 | 132| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | 是 | 否 | 轴对齐包围盒。| 133| materialOverride | [Material](#material) | 否 | 是 | 材质，默认为空。 | 134 135## MeshResource<sup>18+</sup> 136网格资源，继承自[SceneResource](#sceneresource)。 137 138**系统能力：** SystemCapability.ArkUi.Graphics3D 139 140## Animation 141动画类型，继承自[SceneResource](#sceneresource)。 142### 属性 143 144**系统能力：** SystemCapability.ArkUi.Graphics3D 145 146| 名称 | 类型 | 只读 | 可选 | 说明 | 147| ---- | ---- | ---- | ---- | ---- | 148| enabled | boolean | 否 | 否 | 动画是否使能。true表示可以播放动画，false表示不可以播放动画。 | 149| duration | number | 是 | 否 | 动画持续时间，取值范围大于等于0。 | 150| running | boolean | 是 | 否 | 动画运行状态。true表示动画正在播放，false表示动画停止播放。 | 151| progress | number | 是 | 否 | 动画进度状态，取值区间为[0, 1]。 | 152 153### onFinished 154onFinished(callback: Callback\<void>): void 155 156动画播放结束时执行的的回调函数，动画播放完成或者finish操作会触发这个回调。 157 158**系统能力：** SystemCapability.ArkUi.Graphics3D 159 160**参数：** 161| 参数名 | 类型 | 必填 | 说明 | 162| ---- | ---- | ---- | ---- | 163| callback | Callback\<void> | 是 | 回调函数，返回值为空。 | 164 165**示例：** 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 onFinished() : void { 171 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 172 scene.then(async (result: Scene) => { 173 if (result) { 174 let anim: Animation = result.animations[0]; 175 // 注册回调函数 176 anim.onFinished(()=>{ 177 console.info("onFinished"); 178 }); 179 } 180 }); 181} 182``` 183 184### onStarted 185onStarted(callback: Callback\<void>): void 186 187当动画开始播放时执行的回调函数，start操作以及restart操作也会触发这个回调。 188 189**参数：** 190| 参数名 | 类型 | 必填 | 说明 | 191| ---- | ---- | ---- | ---- | 192| callback | Callback\<void> | 是 | 回调函数，返回值为空。 | 193 194动画开始时会执行传入的回调函数。 195 196**系统能力：** SystemCapability.ArkUi.Graphics3D 197 198**示例：** 199```ts 200import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 201 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 202 203function onStarted() : void { 204 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 205 scene.then(async (result: Scene) => { 206 if (result) { 207 let anim: Animation = result.animations[0]; 208 // 注册回调函数 209 anim.onStarted(()=>{ 210 console.info("onStarted"); 211 }); 212 } 213 }); 214} 215``` 216 217### pause 218pause(): void 219 220将动画暂停，动画的播放进度保持在当前状态。 221 222**系统能力：** SystemCapability.ArkUi.Graphics3D 223 224**示例：** 225```ts 226import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 227 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 228 229function pause() : void { 230 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 231 scene.then(async (result: Scene) => { 232 if (result) { 233 let anim: Animation = result.animations[0]; 234 // 暂停动画 235 anim.pause(); 236 } 237 }); 238} 239``` 240 241### restart 242restart(): void 243 244从动画的起点开始播放动画。 245 246**系统能力：** SystemCapability.ArkUi.Graphics3D 247 248**示例：** 249```ts 250import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 251 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 252 253function restart() : void { 254 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 255 scene.then(async (result: Scene) => { 256 if (result) { 257 let anim: Animation = result.animations[0]; 258 // 重启动画 259 anim.restart(); 260 } 261 }); 262} 263``` 264 265### seek 266seek(position: number): void 267 268从指定位置开始播放动画。 269 270**系统能力：** SystemCapability.ArkUi.Graphics3D 271 272**参数：** 273| 参数名 | 类型 | 必填 | 说明 | 274| ---- | ---- | ---- | ---- | 275| position | number | 是 | 要重新播放动画的起始位置，取值区间为[0, 1]。 | 276 277**示例：** 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 seek() : void { 283 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 284 scene.then(async (result: Scene) => { 285 if (result) { 286 let anim: Animation = result.animations[0]; 287 // 指定动画的播放进度到10% 288 anim.seek(0.1); 289 } 290 }); 291} 292``` 293 294### start 295start(): void 296 297基于当前进度开始播放一个动画。 298 299**系统能力：** SystemCapability.ArkUi.Graphics3D 300 301**示例：** 302```ts 303import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 304 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 305 306function start() : void { 307 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 308 scene.then(async (result: Scene) => { 309 if (result) { 310 let anim: Animation = result.animations[0]; 311 // 开始动画 312 anim.start(); 313 } 314 }); 315} 316``` 317 318### stop 319stop(): void 320 321停止播放一个动画，并将动画的进度设置到未开始状态。 322 323**系统能力：** SystemCapability.ArkUi.Graphics3D 324 325**示例：** 326```ts 327import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 328 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 329 330function stop() : void { 331 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 332 scene.then(async (result: Scene) => { 333 if (result) { 334 let anim: Animation = result.animations[0]; 335 // 停止播放动画，并将动画的进度设置到未开始状态 336 anim.stop(); 337 } 338 }); 339} 340``` 341 342### finish 343finish(): void 344 345直接跳转到动画的最后，并将动画的进度设置到已结束状态。 346 347**系统能力：** SystemCapability.ArkUi.Graphics3D 348 349```ts 350import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 351 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 352 353function finish() : void { 354 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 355 scene.then(async (result: Scene) => { 356 if (result) { 357 let anim: Animation = result.animations[0]; 358 // 直接跳转到动画的最后，并将动画的进度设置到已结束状态。 359 anim.finish(); 360 } 361 }); 362} 363``` 364 365## EnvironmentBackgroundType 366环境背景类型枚举。 367 368**系统能力：** SystemCapability.ArkUi.Graphics3D 369 370| 名称 | 值 | 说明 | 371| ---- | ---- | ---- | 372| BACKGROUND_NONE | 0 | 无背景。| 373| BACKGROUND_IMAGE | 1 | 图片背景。 | 374| BACKGROUND_CUBEMAP | 2 | 立方体贴图背景。| 375| BACKGROUND_EQUIRECTANGULAR | 3 | 等距矩形背景。 | 376 377## Environment 378环境类型，继承自[SceneResource](#sceneresource)。 379### 属性 380 381**系统能力：** SystemCapability.ArkUi.Graphics3D 382 383| 名称 | 类型 | 只读 | 可选 | 说明 | 384| ---- | ---- | ---- | ---- | ---- | 385| backgroundType | [EnvironmentBackgroundType](#environmentbackgroundtype) | 否 | 否 | 环境背景类型。 | 386| indirectDiffuseFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 间接散射系数。 | 387| indirectSpecularFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 间接反射系数。 | 388| environmentMapFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 环境地图系数。 | 389| environmentImage | [Image](#image) \| null | 否 | 是 | 环境图片，默认为undefined。 | 390| radianceImage | [Image](#image) \| null | 否 | 是 | 辐射图片，默认为undefined。 | 391| irradianceCoefficients | [Vec3](js-apis-inner-scene-types.md#vec3)[] | 否 | 是 | 辐射系数，默认为undefined。 | 392 393## Image 394图片类型，继承自[SceneResource](#sceneresource)。 395### 属性 396 397**系统能力：** SystemCapability.ArkUi.Graphics3D 398 399| 名称 | 类型 | 只读 | 可选 | 说明 | 400| ---- | ---- | ---- | ---- | ---- | 401| width | number | 是 | 否 | 图片宽度，取值范围大于0。 | 402| height | number | 是 | 否 | 图片高度，取值范围大于0。 | 403