General Functions for Virtual Spaces

The general functions provide core functionality for managing rooomSpaces 3D virtual environments. These functions are essential for virtual showrooms, interactive experiences, and immersive environments where users can navigate and interact within 3D spaces.

Core Viewer Control

load

load(spaceId: string, [callback: Function])

Loads a virtual space with the given space ID. This is typically the first function called to initialize a specific virtual environment.

api.load('f7ef4851b8', function(){
  console.log('Virtual space loaded successfully');
});

---

start

start([callback: Function])

Starts the viewer and initializes the 3D environment. This function should be called after the viewer is loaded and configured.

api.start(function(){
  console.log('Viewer started successfully');
});

---

stop

stop([callback: Function])

Stops the viewer and cleans up resources. Use this when you need to completely shut down the viewer instance.

api.stop(function(){
  console.log('Viewer stopped');
});

🎮 Rendering Control

startRender

startRender([callback: Function])

Starts the rendering loop for the 3D scene. This enables continuous updates and animations in the virtual environment.

api.startRender(function(){
  console.log('Rendering started');
});

---

stopRender

stopRender([callback: Function])

Stops the rendering loop to pause all visual updates. This can be used to save performance when the viewer is not actively being viewed.

api.stopRender(function(){
  console.log('Rendering stopped');
});

📸 Screenshot & Visual

getScreenshot(size: [width: number, height: number] | number, callback: Function, [fileType: string])

Takes a screenshot of the current viewer state. Essential for sharing, documentation, and user-generated content.

// High-quality screenshot for sharing
api.getScreenshot([1920, 1080], function(base64) {
  console.log('Screenshot captured:', base64);
  downloadImage(base64, 'space-screenshot.png');
});

// Quick thumbnail
api.getScreenshot([400, 300], function(base64) {
  document.getElementById('thumbnail').src = base64;
}, 'jpg');

---

pickColor

pickColor(position: [x: number, y: number], [callback: Function])

Returns the color value at the specified screen coordinates as a hex color string. Useful for color-based interactions and analysis.

api.pickColor([100, 200], function(color){
  console.log('Color at position:', color); // Result: "#ff0000"
  updateColorPalette(color);
});

🎯 Focus & Interaction

setCanvasFocus

setCanvasFocus([callback: Function])

Sets the focus on the viewer canvas element. Essential for ensuring keyboard and mouse interactions work properly.

api.setCanvasFocus(function(){
  console.log('Canvas focus set - ready for user input');
});

🌐 Coordinate Conversion

getWorldToScreenCoordinates

getWorldToScreenCoordinates(coords: [x: number, y: number, z: number], [callback: Function])

Converts 3D world coordinates to 2D screen coordinates. Essential for UI overlays and interaction positioning.

api.getWorldToScreenCoordinates([1, 1, 1], function(screenCoords) {
  console.log('Screen position:', screenCoords); // [100, 200]
  positionUIElement(screenCoords);
});

---

getScreenToWorldCoordinates

getScreenToWorldCoordinates(coords: [x: number, y: number], [callback: Function])

Converts 2D screen coordinates to 3D world coordinates. Perfect for placing objects based on user clicks.

api.getScreenToWorldCoordinates([100, 200], function(worldCoords) {
  console.log('World position:', worldCoords); // [1, 1, 1]
  placeObjectAt(worldCoords);
});

📋 Best Practices

Essential Functions for Every Implementation:

1. load() - Initialize your space
2. start() - Begin the viewer experience
3. getScreenshot() - Enable content sharing
4. setCanvasFocus() - Ensure proper user interaction

Performance Optimization:

• Use stopRender() when viewer is not visible to save resources
• Call startRender() to resume smooth animations
• Implement coordinate conversion for efficient UI positioning

User Experience:

• Always call setCanvasFocus() after modal interactions
• Use pickColor() for interactive color-based features
• Implement getScreenshot() for user-generated content sharing