1# Component3D 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zzhao0--> 5<!--Designer: @zdustc--> 6<!--Tester: @zhangyue283--> 7<!--Adviser: @ge-yafang--> 8 93D渲染组件，可以加载3D模型资源并做自定义渲染，通常用于3D动效场景。 10 11> **说明：** 12> 13> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## 子组件 16 17无 18 19 20## 接口 21 22Component3D(sceneOptions?: SceneOptions) 23 24**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.ArkUi.Graphics3D 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------------ | ------------------------------------- | ---- | ------------------------------------------------------------ | 32| sceneOptions | [SceneOptions](#sceneoptions对象说明) | 否 | 3D场景配置选项。<br/>**说明：** <br/> 3D场景配置选项在控件创建后不支持动态修改。 | 33 34 35## SceneOptions对象说明 36 37Component3D组件配置选项。 38 39**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUi.Graphics3D 42 43| 名称 | 类型 | 只读 | 可选 | 说明 | 44| --------- | -------------------------------- | ---- | ---- | ---------------------------------------- | 45| scene | [ResourceStr](ts-types.md#resourcestr) \| [Scene](#scene12) | 否 | 是 | 3D模型资源文件或场景对象，默认值为undefined。<br/>**说明：** <br/>目前仅支持GLTF格式资源。 | 46| modelType | [ModelType](#modeltype枚举说明) | 否 | 是 | 3D场景显示合成方式。<br/>默认值：ModelType.SURFACE<br/>**说明：** <br/>设置为ModelType.TEXTURE时通过GPU合成显示。<br/>设置为ModelType.SURFACE时通过专有硬件合成显示。<br/>一般开发者可以使用默认值而无需关心此项设置。 | 47 48## ModelType枚举说明 49 50渲染合成模式类型枚举，用于指定3D场景的渲染输出方式。 51 52**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.ArkUi.Graphics3D 55 56| 名称 | 值 | 说明 | 57| ------- | ---- | ------------------------ | 58| TEXTURE | 0 | 使用GPU合成显示3D场景。 | 59| SURFACE | 1 | 使用专有硬件显示3D场景。 | 60 61## Scene<sup>12+</sup> 62 63type Scene = Scene 64 65设置3D场景。 66 67**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUi.Graphics3D 70 71| 类型 | 说明 | 72| ------------------------------------------------------------ | -------------- | 73| [Scene](../../apis-arkgraphics3d/js-apis-inner-scene.md#scene-1) | 用于设置场景。 | 74 75## 属性 76 77除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 78 79### environment 80 81environment(uri: ResourceStr) 82 83设置3D环境资源。目前仅支持GLTF格式资源，模型资源在控件创建后不支持动态修改。 84 85**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 86 87**系统能力：** SystemCapability.ArkUi.Graphics3D 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| ------ | -------------------------------------- | ---- | ------------ | 93| uri | [ResourceStr](ts-types.md#resourcestr) | 是 | 3D环境资源。 | 94 95### customRender 96 97customRender(uri: ResourceStr, selfRenderUpdate: boolean) 98 99设置三维场景渲染的渲染管道。管线配置及自渲染属性在控件创建后不支持动态修改。 100 101**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 102 103**系统能力：** SystemCapability.ArkUi.Graphics3D 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| ---------------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 109| uri | [ResourceStr](ts-types.md#resourcestr) | 是 | 自定义渲染管线的配置文件。 | 110| selfRenderUpdate | boolean | 是 | 当设置为true时外部UI没有更新时也能触发动效渲染。<br/>当设置为false时只有外部UI更新才能触发渲染。 | 111 112### shader 113 114shader(uri: ResourceStr) 115 116设置自定义渲染的shader文件资源。自定义渲染的shader文件资源在控件创建后不支持动态修改。 117 118**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.ArkUi.Graphics3D 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| ------ | -------------------------------------- | ---- | ---------------------------- | 126| uri | [ResourceStr](ts-types.md#resourcestr) | 是 | 自定义渲染的shader文件资源。详细`.shader`文件格式请参考[.shader资源文件格式要求](../../../graphics3d/arkgraphics3D-shader-resource.md)。 | 127 128### shaderImageTexture 129 130shaderImageTexture(uri: ResourceStr) 131 132设置自定义渲染用到的纹理资源。若自定义渲染用到多个纹理资源则调用多次，绑定点与调用顺序一致，不支持纹理更换。纹理资源在控件创建后不支持动态修改。 133 134**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.ArkUi.Graphics3D 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ------ | -------------------------------------- | ---- | -------------------------- | 142| uri | [ResourceStr](ts-types.md#resourcestr) | 是 | 自定义渲染用到的纹理资源。 | 143 144### shaderInputBuffer 145 146shaderInputBuffer(buffer: Array<number>) 147 148设置自定义渲染用到的动效参数。 149 150**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 151 152**系统能力：** SystemCapability.ArkUi.Graphics3D 153 154**参数：** 155 156| 参数名 | 类型 | 必填 | 说明 | 157| ------ | -------------- | ---- | -------------------------- | 158| buffer | Array<number\> | 是 | 自定义渲染用到的动效参数，数组长度范围为[0, 1048576]。 | 159 160### renderWidth 161 162renderWidth(value: Dimension) 163 164设置3D渲染分辨率的宽度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。 165 166不调用此属性时默认渲染分辨率。 167 168渲染分辨率在控件创建后不支持动态修改。 169 170**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 171 172**系统能力：** SystemCapability.ArkUi.Graphics3D 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| ------ | ------------------------------------ | ---- | -------------------- | 178| value | [Dimension](ts-types.md#dimension10) | 是 | 3D渲染分辨率的宽度，当前仅支持设置Dimension.Percetage，取值范围是[0, 100%]。 | 179 180### renderHeight 181 182renderHeight(value: Dimension) 183 184设置3D渲染分辨率的长度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。 185 186不调用此属性时默认渲染分辨率。 187 188渲染分辨率在控件创建后不支持动态修改。 189 190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUi.Graphics3D 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ------ | ------------------------------------ | ---- | -------------------- | 198| value | [Dimension](ts-types.md#dimension10) | 是 | 3D渲染分辨率的长度，当前仅支持设置Dimension.Percetage，取值范围是[0, 100%]。 | 199 200## 事件 201 202支持[通用事件](ts-component-general-events.md)。 203 204## 示例 205示例效果请以真机运行为准，当前DevEco Studio预览器不支持。<br/> 206GLTF模型加载示例。 <br/> 207```ts 208// xxx.ets 209@Entry 210@Component 211struct Index { 212 scene: SceneOptions = { scene: $rawfile('gltf/DamagedHelmet/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE}; 213 build() { 214 Row() { 215 Column() { 216 Text('GLTF Example') 217 Component3D( this.scene ) 218 .environment($rawfile('gltf/Environment/glTF/Environment.gltf')) 219 .renderWidth('90%').renderHeight('90%') 220 }.width('100%') 221 } 222 .height('100%') 223 } 224} 225``` 226自定义渲染示例。 <br/> 227 228```ts 229import { AnimatorResult } from '@kit.ArkUI'; 230 231class EngineTime { 232 totalTimeUs = 0; 233 deltaTimeUs = 0; 234}; 235 236let engineTime = new EngineTime(); 237let frameCount: number = 0; 238 239function TickFrame() { 240 if (frameCount == 10) { 241 engineTime.totalTimeUs += 1.0; 242 engineTime.deltaTimeUs += 1.0; 243 frameCount = 0; 244 } else { 245 frameCount++; 246 } 247} 248 249@Entry 250@Component 251struct Index { 252 scene: SceneOptions = { scene: $rawfile('gltf/DamagedHelmet/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE}; 253 backAnimator: AnimatorResult = this.getUIContext().createAnimator({ 254 duration: 2000, 255 easing: "ease", 256 delay: 0, 257 fill: "none", 258 direction: "normal", 259 iterations: -1, 260 begin: 100, 261 end: 200, 262 }); 263 @State timeDelta: number[] = [1.0, 2.0]; 264 create() { 265 this.backAnimator.onFinish = () => { 266 console.log('backAnimator onfinish'); 267 } 268 this.backAnimator.onFrame = (value: number) => { 269 TickFrame(); 270 this.timeDelta[0] = engineTime.deltaTimeUs; 271 } 272 273 } 274 build() { 275 Row() { 276 Column() { 277 Text('custom rendering') 278 Component3D() 279 .shader($rawfile('assets/app/shaders/shader/London.shader')) 280 .shaderImageTexture($rawfile('assets/London.jpg')) 281 .shaderInputBuffer(this.timeDelta) 282 .customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true) 283 .renderWidth('90%').renderHeight('90%') 284 .onAppear(() => { 285 this.create(); 286 this.backAnimator.play(); 287 }).width('50%').height('50%') 288 }.width('100%') 289 } 290 .height('100%') 291 } 292} 293```
