A simple WebGL library for creating 3D scenes.
Open the index.html file to view a demo of the essential features.
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
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
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
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)
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)
A Mesh consists of both geometry data and a shader program.
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)
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
new Sandbox.Plane(width, height, widthSegments, heightSegments)
new Sandbox.Circle(radius, segments)
new Sandbox.Tetrahedron(size)
new Sandbox.Cube(width, height, depth, widthSegments, heightSegments, depthSegments)
new Sandbox.Sphere(radius, segments)
new Sandbox.Cylinder(radius, height, segments)
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)
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.
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)
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')
The shader initially set on creation of the Mesh can be swapped for an alternate using the 'setShader' method.
mesh.setShader(shader)
Create a volume then add a Mesh using the 'add' method.
const volume = new Sandbox.Volume()
volume.add(mesh)
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)
Documentation and demos for Collections, Color Picking, Lights, Texturing, and Framebuffer Rendering are still in progress.
Licensed under the MIT license.