往期鸿蒙全套实战文章必看:
Component3D
3D渲染组件,可以加载3D模型资源并做自定义渲染,通常用于3D动效场景。
说明:
该组件从API Version 11开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
无
接口
Component3D((sceneOptions?: SceneOptions))
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
sceneOptions | SceneOptions | 否 | 3D场景配置选项。 说明: 3D场景配置选项在控件创建后不支持动态修改。 |
SceneOptions对象说明
Component3D组件配置选项。
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
scene | Resource|Scene12+ | 否 | 3D模型资源文件或场景对象,默认值为undefined。 说明: 目前仅支持GLTF格式资源。 |
modelType | ModelType | 否 | 3D场景显示合成方式。 默认值:ModelType.SURFACE 说明: 设置为ModelType.TEXTURE时通过GPU合成显示。 设置为ModelType.SURFACE时通过专有硬件合成显示。 一般开发者可以使用默认值而无需关心此项设置。 |
ModelType枚举说明
名称 | 描述 |
---|---|
TEXTURE | 使用GPU合成显示3D场景。 |
SURFACE | 使用专有硬件显示3D场景。 |
属性
除支持通用属性外,还支持以下属性:
environment
environment(uri: Resource)
设置3D环境资源。目前仅支持GLTF格式资源,模型资源在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
uri | Resource | 是 | 3D环境资源。 |
customRender
customRender(uri: Resource, selfRenderUpdate: boolean)
设置三维场景渲染的渲染管道。管线配置及自渲染属性在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
uri | Resource | 是 | 自定义渲染管线的配置文件。 |
selfRenderUpdate | boolean | 是 | 当设置为true时外部UI没有更新时也能触发动效渲染。 当设置为false时只有外部UI更新才能触发渲染。 |
shader
shader(uri: Resource)
设置自定义渲染的shader文件资源。自定义渲染的shader文件资源在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
uri | Resource | 是 | 自定义渲染的shader文件资源。 |
shaderImageTexture
shaderImageTexture(uri: Resource)
设置自定义渲染用到的纹理资源。若自定义渲染用到多个纹理资源则调用多次,绑定点与调用顺序一致,不支持纹理更换。纹理资源在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
uri | Resource | 是 | 自定义渲染用到的纹理资源。 |
shaderInputBuffer
shaderInputBuffer(buffer: Array<number>)
设置自定义渲染用到的动效参数。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
buffer | Array<number> | 是 | 自定义渲染用到的动效参数。 |
renderWidth
renderWidth(value: Dimension)
设置3D渲染分辨率的宽度。渲染分辨率的长宽可以不同于控件的长宽,若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
不调用此属性时默认渲染分辨率。
渲染分辨率在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | Dimension | 是 | 3D渲染分辨率的宽度。 |
renderHeight
renderHeight(value: Dimension)
设置3D渲染分辨率的长度。渲染分辨率的长宽可以不同于控件的长宽,若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
不调用此属性时默认渲染分辨率。
渲染分辨率在控件创建后不支持动态修改。
系统能力: SystemCapability.ArkUi.Graphics3D
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | Dimension | 是 | 3D渲染分辨率的长度。 |
事件
支持通用事件。
示例
示例效果请以真机运行为准,当前IDE预览器不支持。
GLTF模型加载示例。
// xxx.ets
@Entry
@Component
struct Index {
scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
build() {
Row() {
Column() {
Text('GLTF Example')
Component3D( this.scene )
.environment($rawfile('gltf/Environment/glTF/Environment.gltf'))
.renderWidth('90%').renderHeight('90%')
}.width('100%')
}
.height('100%')
}
}
自定义渲染示例。
import animator, { AnimatorResult } from '@ohos.animator';
class EngineTime {
totalTimeUs = 0;
deltaTimeUs = 0;
};
let engineTime = new EngineTime();
let frameCount: number = 0;
function TickFrame() {
if (frameCount == 10) {
engineTime.totalTimeUs += 1.0;
engineTime.deltaTimeUs += 1.0;
frameCount = 0;
} else {
frameCount++;
}
}
@Entry
@Component
struct Index {
scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
backAnimator: AnimatorResult = animator.create({
duration: 2000,
easing: "ease",
delay: 0,
fill: "none",
direction: "normal",
iterations: -1,
begin: 100,
end: 200,
});
@State timeDelta: number[] = [1.0, 2.0];
create() {
this.backAnimator.onfinish = () => {
console.log('backAnimator onfinish');
}
this.backAnimator.onframe = value => {
TickFrame();
this.timeDelta[0] = engineTime.deltaTimeUs;
}
}
build() {
Row() {
Column() {
Text('custom rendering')
Component3D()
.shader($rawfile('assets/app/shaders/shader/London.shader'))
.shaderImageTexture($rawfile('assets/London.jpg'))
.shaderInputBuffer(this.timeDelta)
.customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true)
.renderWidth('90%').renderHeight('90%')
.onAppear(() => {
this.create();
this.backAnimator.play();
}).width('50%').height('50%')
}.width('100%')
}
.height('100%')
}
}
看完三件事❤️
- 如果你觉得这篇内容对你还蛮有帮助,我想邀请你帮我三个小忙:
- 点赞,转发,有你们的 『点赞和评论』,才是我创造的动力。
- 关注作者,不定期分享原创知识。
- 同时可以期待后续文章ing🚀。