Link Search Menu Expand Document

You are browsing the documentation for v0.x.
Visit here for the newest version.

Getting started

Table of contents

Install VueGL and dependent libraries

See installation guide to know various installation methods.

To load latest libraries from UNPKG, put following codes into the HTML.

<script src="https://unpkg.com/vue"></script>
<script src="https://unpkg.com/three"></script>
<script src="https://unpkg.com/vue-gl"></script>

Register VueGL components to Vue

Vue.js supports global and local component registration. If you are using a module bundler like Webpack or rollup.js, you may prefer local registration. For prototyping, global registration is a more convenient way.

To register all VueGL components, run following script after loading libraries.

Object.keys(VueGL).forEach((name) => Vue.component(name, VueGL[name]));

Create a canvas with VueGL

VglRenderer is a VueGL component that initializes <canvas> element for our drawings. The canvas is created in <div> wrapper container and is responsively resized to container size. To avoid unstable behaviors, apply size constraints enough to the wrapper <div> element.

The VglRenderer component requires a camera and a scene props. These props represent names of VglCamera and VglScene instances. You can define them as child components of the VglRenderer.

Note that VglCamera is an abstract component, so that you should use one of concrete components such as VglPerspectiveCamera.

Following template and CSS create a canvas with specific size and renders an empty scene.

HTML

<vgl-renderer class="getting-started" camera="camera" scene="scene">
  <vgl-perspective-camera name="camera"></vgl-perspective-camera>
  <vgl-scene name="scene"></vgl-scene>
</vgl-renderer>

CSS

.getting-started {
  width: 400px;
  height: 247px;
}

Then create a Vue instance and you will see a black canvas on browser.

new Vue({ el: '.getting-started' });

Here is the result of loading codes so far. To try it in your local environment, copy and save the whole HTML below, then load it on a modern web browser.

<!DOCTYPE html>
<head>
  <meta charset="utf-8">
  <style>
    .getting-started {
      width: 400px;
      height: 247px;
    }
  </style>
</head>
<body>
  <vgl-renderer class="getting-started">
    <vgl-perspective-camera name="camera"></vgl-perspective-camera>
    <vgl-scene name="scene"></vgl-scene>
  </vgl-renderer>
  <script src="https://unpkg.com/vue"></script>
  <script src="https://unpkg.com/three"></script>
  <script src="https://unpkg.com/vue-gl"></script>
  <script>
    Object.keys(VueGL).forEach((name) => Vue.component(name, VueGL[name]));
    new Vue({ el: '.getting-started' });
  </script>
</body>

Draw 3D objects on canvas

To render objects on the canvas, define a scene and a camera in VglRenderer’s default slot.

A scene must be a VglScene component. VglScene component can have components to be rendered as its descendants. Any components of objects can be rendered.

A camera must be one of cameras. The position and rotation of the camera determine where in the scene space to be rendered.

Definition of scene and camera is like below.

<vgl-renderer class="getting-started" camera="camera" scene="scene">
  <vgl-box-geometry name="box"></vgl-box-geometry>
  <vgl-scene name="scene">
    <vgl-mesh geometry="box"></vgl-mesh>
  </vgl-scene>
  <vgl-perspective-camera orbit-position="3 1 0.5" name="camera"></vgl-perspective-camera>
</vgl-renderer>

In the example above, the VglScene component has a VglMesh component as its child. So that the mesh object is rendered.

The VglMesh component gets geometry prop as its geometry’s name. Since VueGL provides namespaces to specify objects by name under the VglRenderer, the geometry created by VglBoxGeometry named ‘box’ is used as geometry of the mesh.

The VglPerspectiveCamera gets a string as the orbit-position prop. The string ‘3 1 0.5’ is parsed as new THREE.Spherical(3, 1, 0.5) because orbit-position prop has type of spherical. Then camera position is set to (radius, phi, theta) = (3, 1rad, 0.5rad) on spherical coordinate system. Props of VueGL components have their specific types. For more information, see the prop types reference.

Installation Namespaces