Menu - Top - Home - Donate to Me

Library Overview

Back to documentation index.

Public-Domain HTML 3D Library

This page will introduce the HTML 3D Library, an open-source JavaScript library that I wrote.

This library contains classes and utility methods to ease the development of HTML 3D applications, such as Web sites, in browsers that support 3D drawing using the HTML5 Canvas.

The library differs from many others because this one is in the public domain, so no permission is required to use it.

This page includes information on how to use the HTML 3D library, an overview of its features, and an example of a simple 3D-enabled Web page.

NOTE: This section and the rest of this page will largely discuss the 2.0.0-beta2 version of the HTML 3D library, which differs considerably from the current release (version 1.5.1) of the library. (See the section "History" for more information.)

Example

Contents

Public-Domain HTML 3D Library
Example
Contents
How to Use
  List of Classes
  H3DU.Scene3D
  The "Camera"
  3D Models
  Shapes
  The Render Loop
A Skeleton for 3D Apps
Demos
  Simple Demos
  Materials
  Shapes and meshes
  Paths
  Curves and Surfaces
  Textures
  Shaders
  Particle Systems
  Loading 3D Models
  Selecting Objects
  Lights
  Text
  Projections
  Miscellaneous
Example
History
  Version 2.0.0-beta2
  Version 2.0.0-beta1:

How to Use

  1. Download the HTML 3D library.
  2. Extract the file "h3du_min.js", and write the following code in every HTML page where you will use the library.

    <script type="text/javascript" src="h3du_min.js"></script>
    
  3. Include an HTML 3D canvas somewhere on the Web page, since drawing 3D objects requires a 3D canvas. You may set its width and height. You should also give it an ID so you can refer to it more easily in your JavaScript code, as shown in this example.

    <canvas width="640" height="480" id="canvas"></canvas>
    
  4. To use the HTML 3D library in JavaScript, either add the JavaScript code to the bottom of the page or use an event listener, as in this example:

    <script>
    window.addEventListener("load",function(){
      var scene=new Scene3D(document.getElementById("canvas"));
      // We have the 3D scene, use it. (See the example code
      // at the bottom of this article for a more complete example.)
    })
    </script>
    

List of Classes

This is an overview of most of the JavaScript classes available in this library:

The following classes concern themselves with the HTML 3D canvas context:

For much more information on all of these classes, see my documentation for the HTML 3D library.

The following sections detail how a 3D application using this library works.

H3DU.Scene3D

The H3DU.Scene3D class is a renderer for a canvas GL context. It renders batches of 3D shapes in the form of H3DU.Batch3D objects. Each Batch3D represents a so-called "scene graph". It holds 3D objects which will be drawn to the screen, as well as the camera's projection, the camera's position, and light sources to illuminate the 3D scene.

To create a H3DU.Scene3D, you first need to find the HTML canvas in your JavaScript, then you need to pass it to new Scene3D(). Once you do so, H3DU.Scene3D will use that canvas to draw 3D objects. Here is an example. You will also need to create a H3DU.Batch3D to hold 3D objects.

// Find the HTML canvas with the ID "canvas".
var canvas=document.getElementById("canvas")
// Create a 3D scene using that canvas.
var scene=new H3DU.Scene3D(canvas);
var batch=new H3DU.Batch3D();

The "Camera"

The H3DU.Batch3D class has a concept of a "projection transform" and a "view transform". If we use the concept of a "camera", the projection is like setting the camera's focus and lens, and the view transform is like setting its position and orientation. H3DU.Batch3D has methods for setting all these attributes of this abstract "camera". Two of them are perspectiveAspect() and setLookAt(), which are shown in the example below.

// Set the perspective view. Camera has a 45-degree field of view
// and will see objects from 0.1 to 100 units away.
batch.perspectiveAspect(45,0.1,100);
// Move the camera back 40 units.
batch.setLookAt([0,0,40]);
// Move the camera back 30 units instead, and turn it so it
// points at (0, 2, 0), that is, up 2 units.
batch.setLookAt([0,0,30], [0,2,0]);

For more information, see The "Camera" and Geometric Transforms.

3D Models

Every 3D scene is made up of "meshes", or the triangles, lines, and points that make up a geometric three-dimensional object. Meshes can be simple, such as a cube, or very complex, such as a town model complete with houses. You create a mesh using the H3DU.Mesh class, or create a built-in geometric shape using a method in the H3DU.Meshes class. The example below shows how you can create a box mesh:

// Create a box mesh 10 units in width, 20 units
// in height, and 25 units in depth
var mesh=H3DU.Meshes.createBox(10,20,25);

Here are some other built-in mesh methods. This page doesn't explain all the features or parameters in the Meshes class; for that, see the Meshes API documentation.

For more information on meshes, see Creating shapes using the Public Domain HTML 3D Library.

Shapes

Once a mesh is created, it needs to be added to the 3D scene in order to be rendered. Use the H3DU.Shape constructor method to convert the mesh to a shape. Then you can set the shape's properties such as color, size, and position. Then, call addShape() to add the shape to the 3D object batch.

// Create a shape based on the mesh
var shape=new H3DU.Shape(mesh);
// Make it red (you can also use the HTML color string
// "#FF0000" instead)
shape.setColor("red");
// Move it 1 unit along the X axis
shape.setPosition(1,0,0);
// Add the shape to the scene
batch.addShape(shape);

The appearance of a 3D shape is known in the 3D graphics world as a "material". It includes textures (images), colors, and light reflection parameters. The Material class holds data on some of these parameters, and is part of the definition of a shape. The PbrMaterial class does the same, but uses physically-based shading algorithms.

Here are details on some of the Shape class's methods.

The Render Loop

An important part of a 3D application is the render loop. The render loop is a block of code that is called many times a second (or many "frames" a second) to redraw the 3D scene. Each frame, the state of the application is updated, and the 3D scene is re-rendered to account for that state. To render a scene, use the H3DU.Scene3D.render() method, passing a batch of shapes to render. Render loops are created using the H3DU.renderLoop() method. Here is an example of a render loop.

// Set up the render loop
H3DU.renderLoop(function(time){
 // This will be called once each frame.
 // Here, we render the scene
 scene.render(batch);
});

The render loop method takes a parameter (here "time"), containing the number of milliseconds since the page was started.  This can be used to implement frame-rate independent animations.

A Skeleton for 3D Apps

The following is a minimal skeleton you can use for writing HTML apps using this library.

<head>
<meta charset=utf-8>
<meta name="viewport" content="user-scalable=no,initial-scale=1,maximum-scale=1">
<script type="text/javascript" src="h3du_min.js"></script>
</head>
<body style="margin:0px">
<canvas id=canvas style="width:100%; height:100%; overflow: hidden;"></canvas>
<script>
// Your script goes here
</script>
</body>

Demos

The following are HTML Web pages showing a variety of features of the HTML 3D library. Each demo includes a link to access source code for that demo.

Simple Demos

Materials

Shapes and meshes

Paths

Curves and Surfaces

Textures

Shaders

Particle Systems

Loading 3D Models

Selecting Objects

Lights

Text

Projections

Miscellaneous

Example

The following is a simple example of an HTML page that uses the HTML 3D library. It sets up the 3D scene, generates a 3D box, colors it red, and rotates it each frame as time passes. Look at the comments; they explain better what each part of the code is doing. Also note the <canvas> element it uses on the page.

<head>
<script type="text/javascript" src="h3du_min.js"></script>
</head>
<body>
<canvas width="600" height="450" id=canvas></canvas>
<script>
 // Create the 3D scene; find the HTML canvas and pass it
 // to Scene3D.
 var scene=new H3DU.Scene3D(document.getElementById("canvas"));
 var sub=new H3DU.Batch3D();
  // Set the perspective view. Camera has a 45-degree field of view
  // and will see objects from 0.1 to 100 units away.
  .perspectiveAspect(45,0.1,100)
  // Move the camera back 40 units.
  .setLookAt([0,0,40]);
sub.getLights().setBasic();
 // Create a box mesh 10 units in size
 var mesh=H3DU.Meshes.createBox(10,20,20);
 // Create a shape based on the mesh and give it a red color
 var shape=new H3DU.Shape(mesh).setColor("red");
 // Add the shape to the scene
 sub.addShape(shape);
 // Create a timer
 var timer={};
 // Set up the render loop
 H3DU.renderLoop(function(time){
  // Update the shape's rotation
  var q=H3DU.Math.quatFromTaitBryan(
    360*H3DU.getTimePosition(timer,time,6000),
    360*H3DU.getTimePosition(timer,time,12000),
    0
  );
  shape.setQuaternion(q);
  // Render the scene
  scene.render(sub);
});
//-->
</script>
</body>

History

Version 2.0.0-beta2

The changes in beta 2 from beta 1 include:

Version 2.0.0-beta1:

See older version history.

Back to documentation index.