基础

这一页聚焦 3D 渲染层最基础、最常用的一组能力。

相机

获取默认相机

const camera = await api.getDefaultCamera();

注意，这是3D渲染中的透视相机概念，不是手机上的摄像头硬件。

读取和修改投影参数

const fov = await api.getCameraFov(camera);
await api.setCameraFov(camera, 55);

const aspect = await api.getCameraAspect(camera);
await api.setCameraAspect(camera, aspect);

await api.updateCameraProjectionMatrix();

还支持：

getCameraNear() / setCameraNear()
getCameraFar() / setCameraFar()
getCameraWorldDirection()

遮罩与透明

开启/关闭对象遮罩

await api.setEnableMask(obj);
await api.setDisableMask(obj);

调整对象透明相关表现

await api.setObjectAlpha(obj, 'blend', 0.5);

setObjectAlpha() 更适合配合已有对象做透明度和裁切相关处理。

除了blend，还支持：

none - 不透明
blend - 透明 / 半透明
clip-legacy - Kivicube平台的旧版本透明裁切实现，仅作兼容，不建议使用
clip - 标准的透明裁切实现

cutOff = 0.5参数，代表裁切透明度的阈值。

材质状态

setGLState() 可以直接修改一部分材质级渲染状态。

await api.setGLState(obj, 'transparent', true, true);
await api.setGLState(obj, 'opacity', 0.6, true);

当前支持的字段有：

side
shadowSide
blending
transparent
opacity
alphaTest
depthTest
depthWrite
colorWrite

第四个参数 recursive 为 true 时，会递归应用到子节点。

何时使用这些基础能力

适合：

特殊渲染效果
临时关闭深度写入或深度测试，优化渲染顺序
给特定对象做遮罩效果
微调camera以适配特殊展示

何时不要过度使用

如果你发现自己在宿主层频繁改很多底层渲染状态，通常意味着：

这部分内容更适合提前在场景编辑器/内容编辑器中配置好素材
可能还不太理解材质状态，对于渲染意味着什么，可以先深入了解一下再决定如何做

基础 ​

相机 ​

获取默认相机 ​

读取和修改投影参数 ​

遮罩与透明 ​

开启/关闭对象遮罩 ​

调整对象透明相关表现 ​

材质状态 ​

何时使用这些基础能力 ​

何时不要过度使用 ​

基础

相机