Place 3D Content on the Screen

Related references:

• Scene API / Camera and Photo Capture
• Scene API / Object Hierarchy and Lifecycle
• Scene API / Transform Properties

It is possible to place 3D content "onto the screen", but more precisely, this is not a dedicated API. The usual method is to attach the object under the camera.

The core idea looks like this:

const camera = await api.getDefaultCamera();
await api.addChild(camera, obj);

That makes the object move and rotate together with the camera, which visually feels much closer to "fixed in front of the screen".

The More Recommended Option: Overlay Host-Layer UI

If your goal is a typical HUD or fixed UI, it is still better to:

1. build an HTML / CSS UI in the host page
2. let the Kivicube iframe focus only on 3D / AR content

This is a better fit for:

• titles
• buttons
• explanatory text
• guide arrows
• responsive layouts

The reasons are straightforward:

• it is easier to adapt across devices
• it is easier to align with host-page styling
• it is easier to make clickable, track analytics, and animate
• you do not need to keep adjusting 3D coordinates

When a Screen-Fixed 3D Object Does Make Sense

This works better for content that:

• should remain a real 3D object
• still needs to participate in material, lighting, or transparency effects
• should feel like a 3D decoration floating in front of the lens
• should keep reusing existing object animation or model assets

Basic Implementation

1. Get the Camera and Target Object

const camera = await api.getDefaultCamera();
const obj = await api.getObject('screen-object');

If the object is created at runtime, you can also use the returned handle directly:

const obj = await api.createImage('/assets/tag.png');

2. Attach It Under the Camera

await api.addChild(camera, obj);

3. Adjust Its Position in Camera Space

await api.setPosition(obj, 0, 0, -2);
await api.setScale(obj, 0.5, 0.5, 0.5);

The most important value here is z:

• z is usually negative, meaning the object is placed in front of the lens
• values closer to 0 make it appear closer to the screen
• smaller values make it appear farther away

x and y determine the horizontal and vertical position on screen.

For example:

// Centered but lower
await api.setPosition(obj, 0, -0.6, -2);

// Near the upper-left corner
await api.setPosition(obj, -1.2, 0.8, -2);

4. Adjust Rendering State

// Keep the object on top and disable depth testing / depth-buffer writes.
const recursive = true; // Apply the same settings to all child nodes as well. Default is false.
await api.setGLState(obj, "depthTest", false, recursive);
await api.setGLState(obj, "depthWrite", false, recursive);

Complete Example

iframe.addEventListener('ready', async (event) => {
  const { api } = event.detail;

  const camera = await api.getDefaultCamera();
  const image = await api.createImage('/assets/floating-badge.png');

  await api.addChild(camera, image);

  await api.setPosition(image, 1.1, -0.8, -2);
  await api.setScale(image, 0.35, 0.35, 0.35);

  const recursive = true;
  await api.setGLState(image, "depthTest", false, recursive);
  await api.setGLState(image, "depthWrite", false, recursive);
});

Remove the Screen-Fixed Behavior

If you no longer want the object attached to the camera, remove that parent-child relationship and attach it elsewhere:

await api.removeChild(camera, obj);

If you only want to hide it:

await api.setObjectVisible(obj, false);

Adaptation Recommendations

Although this technique can create a "screen-fixed" effect, it still uses 3D coordinates rather than CSS pixels. So:

• positions may need fine-tuning for different aspect ratios
• visual placement also changes with different FOV values
• if the object is too close to the camera, it may appear oversized or get clipped

A safer approach is:

• start with one baseline coordinate set
• fine-tune only on key target devices
• keep real interactive buttons in host-layer HTML

When This Approach Is Not Recommended

• when you need precise alignment with host-page buttons
• when you need complex responsive layout
• when you need lots of text
• when you need stable hit areas
• when the object must coordinate with page scroll, modals, or forms

In those cases, HTML / CSS is usually a better fit than a 3D solution.