Basics

This page focuses on the most fundamental and most frequently used capabilities in the 3D rendering layer.

Camera

Get the Default Camera

const camera = await api.getDefaultCamera();

Note: this refers to the perspective camera used in 3D rendering, not the phone's physical camera hardware.

Read and Update Projection Parameters

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

Also supported:

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

Masks and Transparency

Enable / Disable Object Masks

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

Adjust Transparency-Related Behavior

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

setObjectAlpha() is most useful when you want to adjust transparency or alpha clipping on an existing object.

In addition to blend, the following modes are supported:

• none - opaque
• blend - transparent / semi-transparent
• clip-legacy - legacy transparency clipping behavior from older Kivicube platform versions; kept only for compatibility and not recommended
• clip - standard alpha clipping behavior

The cutOff = 0.5 argument represents the threshold used for alpha clipping.

Material State

setGLState() lets you directly modify a subset of material-level rendering state.

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

Currently supported fields:

• side
• shadowSide
• blending
• transparent
• opacity
• alphaTest
• depthTest
• depthWrite
• colorWrite

When the fourth parameter, recursive, is true, the change is applied recursively to child nodes as well.

When to Use These Basic Capabilities

Good fits:

• special rendering effects
• temporarily disabling depth write or depth test to improve draw order
• applying mask effects to specific objects
• fine-tuning the camera for unusual presentation needs

When Not to Overuse Them

If you find yourself changing lots of low-level rendering state from the host layer, it usually means:

• this part of the content might be better configured ahead of time in the Scene Editor or Content Editor
• you may want a deeper understanding of what these material states mean for rendering before relying on them heavily