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