• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Component3D (系统接口)
2
33D渲染组件，可以加载3D模型资源并做自定义渲染，通常用于3D动效场景。
4
5>  **说明：**
6>
7>  该组件从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9>  本模块为系统接口。
10
11## 子组件
12
13无
14
15
16## 接口
17
18Component3D((sceneOptions?: SceneOptions))
19
20
21**参数：**
22
23| 参数名          | 参数类型                              | 必填   | 参数描述                                     |
24| ------------ | --------------------------------- | ---- | ---------------------------------------- |
25| sceneOptions | [SceneOptions](#sceneoptions对象说明) | 否    | 3D场景配置选项。<br/>**说明：** <br/> 3D场景配置选项在控件创建后不支持动态修改。 |
26
27
28## SceneOptions对象说明
29
30Component3D组件配置选项。
31
32| 名称        | 类型                               | 必填   | 说明                                       |
33| --------- | -------------------------------- | ---- | ---------------------------------------- |
34| scene     | [Resource](ts-types.md#resource) | 否    | 3D模型资源文件。<br/>**说明：** <br/>目前仅支持GLTF格式资源。 |
35| modelType | [ModelType](#modeltype枚举说明)      | 否    | 3D场景显示合成方式。<br/>默认值：ModelType.SURFACE<br/>**说明：** <br/>设置为ModelType.TEXTURE时通过GPU合成显示。<br/>设置为ModelType.SURFACE时通过专有硬件合成显示。<br/>一般开发者可以使用默认值而无需关心此项设置。 |
36
37## ModelType枚举说明
38
39| 名称      | 描述             |
40| ------- | -------------- |
41| TEXTURE | 使用GPU合成显示3D场景。 |
42| SURFACE | 使用专有硬件显示3D场景。  |
43
44
45## 属性
46
47除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
48
49| 名称                 | 参数类型                                     | 描述                                       |
50| ------------------ | ---------------------------------------- | ---------------------------------------- |
51| environment        | [Resource](ts-types.md#resource)         | 设置3D环境资源。 <br/>**说明：** <br/>目前仅支持GLTF格式资源，模型资源在控件创建后不支持动态修改。 |
52| customRender       | uri: [Resource](ts-types.md#resource)<br/> selfRenderUpdate: boolean | uri:自定义渲染管线的配置文件。<br/> selfRenderUpdate: 当设置为true时外部UI没有更新时也能触发动效渲染，当设置为false时只有外部UI更新才能触发渲染。<br/>**说明：** <br/>管线配置及自渲染属性在控件创建后不支持动态修改。 |
53| shader             | [Resource](ts-types.md#resource)         | 自定义渲染的shader文件资源。 <br/>**说明：** <br/>  自定义渲染的shader文件资源在控件创建后不支持动态修改。 |
54| shaderImageTexture | [Resource](ts-types.md#resource)         | 自定义渲染用到的纹理资源。<br/>**说明：** <br/>若自定义渲染用到多个纹理资源则则调用多次，绑定点与调用顺序一致，不支持纹理更换。纹理资源在控件创建后不支持动态修改。 |
55| shaderInputBuffer  | Array<number\>                           | 自定义渲染用到的动效参数。                            |
56| renderWidth        | [Dimension](ts-types.md#dimension10)     | 3D渲染分辨率的宽度。<br/>**说明：** <br/> 渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。<br/> 不调用此属性时默认渲染分辨率。<br/> 渲染分辨率在控件创建后不支持动态修改。 |
57| renderHeight       | [Dimension](ts-types.md#dimension10)     | 3D渲染分辨率的长度。<br/>**说明：** <br/> 渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。<br/> 不调用此属性时默认渲染分辨率。<br/> 渲染分辨率在控件创建后不支持动态修改。 |
58
59## 事件
60
61支持[通用事件](ts-universal-events-click.md)。
62
63## 示例
64示例效果请以真机运行为准，当前IDE预览器不支持。<br/>
65GLTF模型加载示例。 <br/>
66```ts
67// xxx.ets
68@Entry
69@Component
70struct Index {
71  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
72  build() {
73    Row() {
74      Column() {
75        Text('GLTF Example')
76        Component3D( this.scene )
77          .environment($rawfile('gltf/Environment/glTF/Environment.gltf'))
78          .renderWidth('90%').renderHeight('90%')
79      }.width('100%')
80    }
81    .height('100%')
82  }
83}
84```
85自定义渲染示例。 <br/>
86
87```ts
88import animator, { AnimatorResult } from '@ohos.animator';
89class EngineTime {
90  totalTimeUs = 0;
91  deltaTimeUs = 0;
92};
93
94let engineTime = new EngineTime();
95let frameCount: number = 0;
96
97function TickFrame() {
98  if (frameCount == 10) {
99    engineTime.totalTimeUs += 1.0;
100    engineTime.deltaTimeUs += 1.0;
101    frameCount = 0;
102  } else {
103    frameCount++;
104  }
105}
106
107@Entry
108@Component
109struct Index {
110  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
111  backAnimator: AnimatorResult = animator.create({
112    duration: 2000,
113    easing: "ease",
114    delay: 0,
115    fill: "none",
116    direction: "normal",
117    iterations: -1,
118    begin: 100,
119    end: 200,
120  });
121  @State timeDelta: number[] = [1.0, 2.0];
122  create() {
123    this.backAnimator.onfinish = () => {
124      console.log('backAnimator onfinish');
125    }
126    this.backAnimator.onframe = value => {
127      TickFrame();
128      this.timeDelta[0] = engineTime.deltaTimeUs;
129    }
130
131  }
132  build() {
133    Row() {
134      Column() {
135        Text('custom rendering')
136        Component3D()
137          .shader($rawfile('assets/app/shaders'))
138          .shaderImageTexture($rawfile('assets/London.jpg'))
139          .shaderInputBuffer(this.timeDelta)
140          .customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true)
141          .renderWidth('90%').renderHeight('90%')
142          .onAppear(() => {
143            this.create();
144            this.backAnimator.play();
145          }).width('50%').height('50%')
146      }.width('100%')
147    }
148    .height('100%')
149  }
150}
151```