# Getting started

# Installation

There are two ways to use VueGL.

Loading pre-built scripts on the browser
Easy way to try using the library. You need only a text editor.
Building a script to be loaded with a module bundler
More efficient way for building products. It needs Node.js and npm (Node package manager) to be installed.

# Loading pre-built scripts on the browser

Put <script> tags before your code using VueGL. VueGL depends on Vue.js and Three.js so that you need to load them before VueGL.

<!-- Dependency libraries has to be loaded before VueGL. -->
<script src="path/to/vue.js"></script>
<script src="path/to/three.js"></script>
<!-- Loading VueGL. -->
<script src="path/to/vue-gl.js"></script>

1
2
3
4
5

The global namespace object VueGL is accessible after loading VueGL. For example, <VglRenderer> component is under the VglRenderer property of the VueGL.

// Registering the VglRenderer as a global component.
Vue.component('VglRenderer', VueGL.VglRenderer);

1
2

# Downloads

VueGL and its dependency scripts can be found at following pages.

Vue.js - Installation (opens new window)
Three.js - Releases (opens new window)
VueGL - Releases (opens new window)

# from CDN

You can also load scripts from CDNs. To load them, just replace src attribute of <script> tags.

<!-- Latest versions from UNPKG -->
<script src="https://unpkg.com/vue"></script>
<script src="https://unpkg.com/three"></script>
<script src="https://unpkg.com/vue-gl"></script>

<!-- Latest versions from jsDeliver -->
<script src="https://cdn.jsdelivr.net/npm/vue"></script>
<script src="https://cdn.jsdelivr.net/npm/three"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-gl"></script>

1
2
3
4
5
6
7
8
9

# Building a script to be loaded with a module bundler

VueGL and its dependencies are also available on npm. If you build your app with a module bundler such as Webpack or rollup.js, it is easy to integrate VueGL to your app.

Note that Vue.js and Three.js are peer dependencies of VueGL, then you have to explicitly install them.

npm i vue three vue-gl

Then you can import VueGL components like below.

// CommonJS
const { VglRenderer, VglScene } = require('vue-gl');

1
2

// ECMA Script
import { VglRenderer, VglScene } from 'vue-gl';

1
2

# Registering components

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

# Global registration

Use Vue.component() method to register components.

When using pre-built VueGL script, the global namespace object VueGL has all components as its own properties. For example, the script below registers the <VglRenderer> component.

<script>
  Vue.component('VglRenderer', VueGL.VglRenderer);
</script>

1
2
3

The script below registers all available VueGL components globally.

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

# Local registration

Pass components to components option for the Vue instance.

When using a module bundler, you can import or require only necessary components for the current module.

// CommonJS
const { VglRenderer } = require('vue-gl');

module.exports = {
  components: { VglRenderer },
  // Other component option definitions
};

1
2
3
4
5
6
7

// ECMA Script
import { VglRenderer } from 'vue-gl';

export default {
  components: { VglRenderer },
  // Other component option definitions
};

1
2
3
4
5
6
7

# Drawing a scene with VueGL

Here is a simple example to draw a cube on the WebGL canvas.

<script src="path/to/vue.js"></script>
<script src="path/to/three.js"></script>
<script src="path/to/vue-gl.js"></script>
<vgl-renderer id="canvas">
  <template #scene>
    <vgl-scene>
      <vgl-mesh>
        <template #geometry>
          <vgl-box-geometry />
        </template>
        <template #material>
          <vgl-mesh-standard-material />
        </template>
      </vgl-mesh>
      <vgl-directional-light :position-x="2" :position-y="1.5" :position-z="1" />
    </vgl-scene>
  </template>
  <template #camera>
    <vgl-perspective-camera :position-x="2" :position-y="1.5" :position-z="1" rotation="lookAt" />
  </template>
</vgl-renderer>
<script>
  new Vue({ components: VueGL, el: '#canvas' });
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<VglRenderer> initializes a canvas for our drawings. It requires scene and camera slots to be defined.

The example scene has a mesh object and a directional light.

The mesh is configured its geometry and material via geometry and material slots. Every slot of VueGL components would have appropriate other VueGL components like this.

The directional light is configured its position via position-x, position-y and position-z props. Usually each prop of VueGL component accepts primitive value to configure corresponding Three.js instance.

The perspective camera has position- props like the directional light and also rotation prop. The value of rotation prop represents how to determine the camera direction. When lookAt mode is selected, the camera faces to the specified position. In this case, it faces to (0, 0, 0) since look-at-x, look-at-y and look-at-z props are omitted and their default value is 0.

Reactive drawing →