Kivicube文档

简体中文

English

主题

基础 ​

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

相机 ​

获取默认相机 ​

js
const camera = await api.getDefaultCamera();

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

读取和修改投影参数 ​

js
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()

遮罩与透明 ​

开启/关闭对象遮罩 ​

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

调整对象透明相关表现 ​

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

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

除了blend，还支持：

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

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

材质状态 ​

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

js
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以适配特殊展示

何时不要过度使用 ​

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

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