Sandbox

A simple WebGL library for creating 3D scenes.

Demo

Open the index.html file to view a demo of the essential features.

Getting Started

To create a 3D scene in Sandbox you will need a few things:

A canvas element
A Renderer object
A Camera object
At least one Mesh consisting of both geometry data and a shader program
A Volume to contain meshes

Creating a Renderer object

A Renderer's constructor requires the canvas element as an argument to be the render target. The renderer has a 'resize' method that can be called whenever the canvas dimensions have changed. The 'pixelRatio' attribute can be set to account for high-density displays; by default the pixel ratio is set to either the display's pixel ratio or a value of 2 depending on which is smaller. The 'depthTest' and 'faceCulling' attributes are exposed from the OpenGL implementation for additional customization.

const canvas = document.getElementById('webgl-canvas')
const renderer = new Sandbox.Renderer(canvas)

//Methods and attributes
renderer.resize()
renderer.pixelRatio = 2.0
renderer.depthTest = true
renderer.faceCulling = true

Creating a Camera object

Sandbox includes two types of Camera objects, a Perspective Camera and an Orthographic Camera. Common to both Camera types are a few methods and attributes:

A 'position' object containing 'x', 'y', and 'z' attributes
A 'rotation' object containing 'x', 'y', and 'z' attributes
A 'lookAtEnabled' flag to determine if the current 'lookAt' target should be used
A 'createMatrix' method that regenerates the Camera's local matrix based on current viewing frustum attributes
A 'setViewProjectionMatrix' method that regenerates the viewProjection matrix based on the current local matrix
A 'setNear' method used to set the near plane of the viewing frustum
A 'setFar' method used to set the far plane of the viewing frustum
A 'setPosition' method that takes 'x', 'y', and 'z' arguments
A 'setRotationX' method to set the Camera's X rotation
A 'setRotationY' method to set the Camera's Y rotation
A 'setRotationZ' method to set the Camera's Z rotation
A 'lookAt' method which takes a Mesh target to force the Camera to center the target in its field of view regardless of position

The Perspective Camera

A Perspective Camera requires four arguments:

A 'fieldOfView'
An 'aspectRatio'
A 'near' plane location
A 'far' plane location

const camera = new Sandbox.Perspective(35, 1.85, 0.1, 100)

The Orthographic Camera

A Perspective Camera requires six arguments:

A 'left' plane location
A 'right' plane location
A 'bottom' plane location
A 'top' plane location
A 'near' plane location
A 'far' plane location

const camera = new Sandbox.Orthographic(-1, 1, -1, 1, -1, 1)

Creating a Mesh

A Mesh consists of both geometry data and a shader program.

The base Geometry class

To create a custom Geometry object, pass in an array of position data as 3D positions.

const positions = [
	1, 0, 0, //x, y, z
	0, 1, 0, //x, y, z
	0, 0, 1  //x, y, z
]
const geometry = new Sandbox.Geometry(positions)

The Primitives

While geometry data can be created manually with the Geometry class, various primitives are included as part of Sandbox including:

Plane
Circle
Tetrahedron
Cube
Sphere
Cylinder

Plane

new Sandbox.Plane(width, height, widthSegments, heightSegments)

Circle

new Sandbox.Circle(radius, segments)

Tetrahedron

new Sandbox.Tetrahedron(size)

Cube

new Sandbox.Cube(width, height, depth, widthSegments, heightSegments, depthSegments)

Sphere

new Sandbox.Sphere(radius, segments)

Cylinder

new Sandbox.Cylinder(radius, height, segments)

Shader Programs

A shader program requires that you pass in a reference the Renderer object's 'gl' attribute, a vertex shader string, and a fragment shader string. Sandbox accepts GLSL strings.

const shader = new Sandbox.Program(renderer.gl, vertex, fragment)

The Mesh Object

const mesh = new Sandbox.Mesh(geometry, shader)

The Mesh object has the same 'position' and 'rotation' attributes, as well as the 'setPosition', 'setRotationX', 'setRotationY', and 'setRotationZ' methods that the Camera objects have as well as an additional attribute 'scale' and a 'setScale' method which takes an 'x', 'y', and 'z' value.

Mesh Attributes

Attributes in addition to the 'aPosition' attributed generated by the geometry data can be added through the 'setAttribute' method. Attributes must exist in the vertex shader in order for attribute data to properly work. The 'setAttribute' method takes three arguments:

A 'name' for the attribute that will be referenced in the vertex shader
A Float32Array of attribute data
A size of the data indicating how many array values exist per vertex.

mesh.setAttribute('aColor', new Float32Array(colorData), 3)

Mesh Uniforms

Uniforms can be supplied to Mesh objects through the 'setUniform' method. Uniforms must exist in the vertex shader in order for uniform data to properly work. The 'setUniform' method takes three arguments:

A 'name' for the uniform that will be referenced in the vertex shader
A current value for the uniform. Sandbox supports floats, JavaScript arrays containing 2-4 floats, 3D and 4D matricies, and textures.
A data type for the uniform, either '1f', '2f', '3f', '4f', 'mat3', 'mat4', or 'tex'

mesh.setUniform('uTime', 0, '1f')

Swapping Shaders

The shader initially set on creation of the Mesh can be swapped for an alternate using the 'setShader' method.

mesh.setShader(shader)

Adding a Mesh to a Volume

Create a volume then add a Mesh using the 'add' method.

const volume = new Sandbox.Volume()
volume.add(mesh)

Rendering the Volume

Establish a clear color for the Renderer and then render the Volume with a Camera

renderer.gl.clearColor(0, 0, 0, 0)
renderer.render(volume, camera)

Todos

Documentation and demos for Collections, Color Picking, Lights, Texturing, and Framebuffer Rendering are still in progress.

License

Licensed under the MIT license.

cherupil/Sandbox