Install

You can get it on Bower.

$ bower install pocket.gl --save

Or you can just download a ZIP file.

Loading

You can load it as a browser global using a script tag.

// load it from the dist folder
<script src="dist/pocket.gl.min.js"></script>

// or load it from RawGit
<script src="rawgit-url"></script>

This will register a global object named PocketGL which you can instantiate.

new PocketGL("myContainer");

You can also load it as an AMD module, using require.js.

define(["dist/pocket.gl.min"], function(PocketGL) {  
    new PocketGL("myContainer");
});

Note that, since some of the module dependencies (Three.jsAce and dat.GUI) do not support AMD, some browser globals will still be registered even if you use AMD loading.

Constructor

The constructor takes three parameters, one mandatory and two optional. It will create a sandbox inside a container based on the config parameters and using baseURL for each path inside config.

PocketGL(container, [config], [baseURL]);

container (string or DomEl object, mandatory) an HTML DOM Element ID or an HTML DOM Element Object which will contain the sandbox.

config – (object or string, optional) a javascript object containing some config parameters or a URL string to a file containing the object definition.

baseURL – (string, optional) a URL string specifying the base URL for all the paths defined in the config object. Note that if the config object is passed as a URL to a file, that URL will be used as a base URL for all the paths.

Config

Here is the complete list of the properties available for the config object. Unless specified, all properties are optional.

Shaders

vertexShader – (string) the vertex shader code.

fragmentShader – (string) the fragment shader code.

vertexShaderFile – (string) URL to a file containing the vertex shader code.

fragmentShaderFile – (string) URL to a file containing the fragment shader code.

If you don’t provide any vertex or fragment shader, a basic blinn-phong shader will be added to the sandbox.

Built-in attributes and uniforms

pocket.gl is based on Three.js which will prepend the following uniforms and attributes to the vertex and fragment shader code. The following attributes and uniforms will be pre-declared in your shaders, just use them.

// vertex shader prefix
// = object.matrixWorld
uniform mat4 modelMatrix;

// = camera.matrixWorldInverse * object.matrixWorld
uniform mat4 modelViewMatrix;

// = camera.projectionMatrix
uniform mat4 projectionMatrix;

// = camera.matrixWorldInverse
uniform mat4 viewMatrix;

// = inverse transpose of modelViewMatrix
uniform mat3 normalMatrix;

// = camera position in world space
uniform vec3 cameraPosition;

attribute vec3 position;
attribute vec3 normal;
attribute vec2 uv;
attribute vec2 uv2;

// fragment shader prefix
uniform mat4 viewMatrix;
uniform vec3 cameraPosition;

Note that you can therefore calculate the position of a vertex in the vertex shader by:

gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );

or alternatively

gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4( position, 1.0 );

Fragment-only sandbox

If you provide only a fragment shader, the sandbox will switch to fragment-only mode: your fragment shader will write on a plane covering the entire canvas and a resolution uniform variable will be available in shader, containing the current width and height in pixels of the canvas, use it in combination with the gl_FragCoord variable to obtain a normalized canvas position.

If you want to track mouse position, you can use the mouse uniform variable. It is a vec4 uniform variable, where the xy components contains the current screen mouse coordinates in pixels while the left button is pressed, or the last mouse coordinates when the left mouse button was released. The zw components contain the total amount of relative mouse movement. This means that if you click and move the mouse 10 pixels on the left, then you click in another position and drag another 20 pixels left, the final z value will be 30.

GUI Variables (uniforms)

The uniforms property specifies a set of variables which will be editable on a GUI and will be available in shader as uniform variables. The format for the uniform property is a javascript object containing an object for each uniform variable.

uniforms: [
	{ 
		type: typename, 
		value: defaultValue, 
		min: minValue, 
		max: maxValue, 
		name: variableName,
		GUIName: name
	}
]

type – (string, mandatory) can be “float”, “integer”, “boolean” or “color”. The corresponding GLSL types are: float for “float”, “integer” and “boolean” (a “boolean” will be represented as a float of value 0 or 1), vec3 for “color”.

value – (mixed, mandatory) the default value for the variable. The type is number for “float”, hexadecimal color string for “color” [#RRGGBB or #RGB], javascript true or false for “boolean”.

min – (number, mandatory if float) the min value you can set in the GUI.

max – (number, mandatory if float) the max value you can set in the GUI.

name – (string, mandatory) the uniform variable name passed to the shader.

GUIName – (string, mandatory) the variable name shown in the GUI.

uniforms: [
	{ 
		type: "boolean", 
		value: false, 
		name: "flatShading",
		GUIName: "Flat shading" 
	},

	{ 
		type: "color", 
		value: "#26a00c", 
		name: "diffuseColor",
		GUIName: "Color"
	},

	{ 
		type: "float", 
		value: 0.5, 
		min: 0, 
		max: 1,
		name: "specularGloss", 
		GUIName: "Glossiness"
	},

	{ 
		type: "integer", 
		value: 5, 
		min: 0, 
		max: 10, 
		name: "specularIntensity",
		GUIName: "Specular intensity"
	}
]

You can access these variables in shader code by declaring them as uniforms like this.

uniform float flatShading;
uniform vec3 diffuseColor;
uniform float specularGloss;
uniform float specularIntensity;

Grouping Variables

It is possible to group variables in the GUI. Just wrap them inside an array. The first object of the array must contain a group name (groupName) and an optional opened property to show the group folder opened by default.

uniforms: [
	[
		{ groupName: "Group 1" },
		{ type: "float", value: 0.5, min: 0, max: 1, name: "v1", GUIName: "Var 1" },
		{ type: "boolean", value: true, name: "v2", GUIName: "Var 2" }
	],

	[
		{ groupName: "Group 2" },
		{ type: "float", value: 0.5, min: 0, max: 1, name: "v3", GUIName: "Var 3" },
		{ type: "boolean", value: true, name: "v4", name: "Var 4" }
	],

	[
		{ groupName: "Group 2", opened: true },
		{ type: "float", value: 0.5, min: 0, max: 1, name: "v5", GUIName: "Var 5" },
		{ type: "boolean", value: true, name: "v6", GUIName: "Var 6" }
	]
]

Meshes

You can specify a list of meshes for your sandbox, both from a set of internal procedural meshes or by providing a URL to an external mesh file in OBJ or Collada format. The format for the meshes property is an array containing an object for each mesh.

meshes: [
	{ 
		// Procedural mesh
		type: typename, 
		subdivision: numberOfSubdvisions, 

		// External mesh
		url: meshURL,

		name: nameInTheGUI,
		x: xOffset, y:yOffset, z: zOffset,
		rx: xRotation, ry: yRotation, z: zRotation
		scale: meshScale,
		doubleSided: showBackFaces,
		transparent: useAlphaChannel
	}
]

type – (string) a string ID representing one of the available procedural meshes. Available meshes are: “teapot”, “cube”, “sphere”, “torus”, “cylinder”, “plane”.

subdivision – (integer, optional) the number of subdivisions for a procedural mesh.

url – (string URL) URL to an external mesh file in OBJ or Collada format. You can define only a url or a type property, not both.

name – (string, mandatory) the mesh name shown in the GUI.

xyz – (float, optional) the mesh position offset.

rxryrz – (float, optional) the mesh rotation.

scale – (float) the mesh scale.

doubleSided – (boolean) whether to draw a double sided mesh.

transparent – (boolean) if set to true, the alpha value passed to gl_FragColor will affect the alpha of the rendered pixels.

Pay attention to face ordering in the mesh file, faces with transparencies should be moved at the end of the face list in the mesh file definition.

meshes: [
	{ url: "light-bulb.obj",  name: "Light Bulb (obj)", rx: 90, scale: 0.17},
	{ type: "teapot", name: "Teapot", doubleSided: true},
	{ type: "sphere", name: "Sphere"},
	{ type: "torus", name: "Torus"},
	{ type: "cylinder", name: "Cylinder"},
	{ type: "cube", name: "Cube"},
	{ type: "plane", name: "Plane", doubleSided: true}
]

Materials (mesh viewer)

If you want to use pocket.gl as a generic 3D model viewer, you have to add one or more material definitions along with the mesh definition. Use the materials property inside the mesh definition and assign it an array of material objects. These are the properties for the material object:

color – (string, hexadecimal color [#RRGGBB or #RGB], optional) the material diffuse color.

specular – (string, hexadecimal color [#RRGGBB or #RGB], optional) the specular color.

shininess – (number, optional) the specular glossiness.

diffuseMap – (string, optional) the URL to the diffuse texture.

normalMap – (string, optional) the URL to the normal map.

Multimaterial meshes are not supported. If you want to use multiple materials, arrange your mesh into sub-meshes (see the light bulb example).

meshes: [
	{ 
		url: "dice.obj", name: "Dice", 
		// one material with diffuse and normal map
		materials: [
			{ 
				diffuseMap: "diffuse.jpg", 
				normalMap: "normal.png" 
			}
		]
	},
	
	{
		url: "light-bulb.obj", name: "Light Bulb", 
		// two materials with two colors assigned to each sub-mesh
		materials: [
			{ color: "#aaa" },
			{ color: "#c0a84a" }
		]
	}
]

Textures

The textures property specifies a set of textures which will be available in shader as uniform variables. The format for the textures property is an array containing an object for each texture.

textures: [
	{ 
		url: textureURL, 
		wrap: wrapType,
		filter: filtertype, 
		name: variableName
	}
]

url – (string, mandatory) URL to the texture image in JPEG or PNG format.

wrap – (string, optional) possible values: “repeat” or “clamp”.

filter – (string, optional) possible values: “linear” or “nearest”.

name – (string, mandatory) the name  of the uniform sampler2D variable passed to the shader.

Skyboxes

You can replace the background flat color with a skybox. You can use both a cubemap texture or an equirectangular texture.

skybox – (array of string URLs or a string URL) to define a cubemap skybox you have to specify an array of six images in this order: right, left, top, bottom, front, back. To define an equirectangular skybox, just specify the URL of the single equirectangular image.

When you define a cubemap skybox, a new uniform variable called tCube will be available in shader, representing the cubemap texture.

// cubemap skybox shader uniform
uniform samplerCube tCube;

When you define an equirectangular skybox, a new uniform variable called tEquirect will be available in shader, representing the equirectangular texture.

// equirectangular skybox shader uniform
uniform sampler2D tEquirect;

Cubemap skybox example

// cubemap skybox
skybox: [
	"cubemap/px.jpg", "cubemap/nx.jpg", 
	"cubemap/py.jpg", "cubemap/ny.jpg", 
	"cubemap/pz.jpg", "cubemap/nz.jpg",
]

Equirectangular skybox example

// equirectangular skybox
skybox: "textures/panorama.jpg"

Appearance

width – (integer) the width in pixel of the sandbox.

height – (integer) the height in pixel of the sandbox.

fluidWidth – (boolean) if set to true, the width of the sandbox will adapt to the width of its container.

backgroundColor – (string, hexadecimal color [#RRGGBB or #RGB]) the canvas background color.

tabColor – (string, hexadecimal color [#RRGGBB or #RGB]) the color of the tabs highlight bar.

tabTextColor – (string, hexadecimal color [#RRGGBB or #RGB]) the tabs text color.

GUIClosed – (boolean) if true, the GUI will be closed by default.

copyright – (string) an HTML text to show in the upper left corner of the canvas.

copyrightColor – (string, hexadecimal color [#RRGGBB or #RGB]) the text color for the copyright text displayed on the top left.

copyrightLinkColor – (string, hexadecimal color, #RRGGBB or #RGB) the link color for the anchors inside the copyright HTML text.

{
	width: 800, height: 600, backgroundColor: "#300", 
	tabColor: "#f00", tabTextColor: "#555", GUIClosed: true 
}

Camera

orbiting – (boolean) allows camera orbiting using mouse drag.

autoOrbit – (boolean) allows camera automatic rotation (if set to true, animated will be forced to true).

autoOrbitSpeed – (number) sets the automatic camera rotation speed (a unit equals 6 degrees/sec).

cameraDistance – (number) sets the distance of the camera from the mesh pivot.

cameraPitch – (number) sets the camera pitch orientation in degrees.

cameraYaw – (number) sets the camera yaw orientation in degrees.

cameraFOV – (number) sets the camera field of view in degrees.

zoom – (boolean) allows camera zooming using mouse wheel.

{
	orbiting: true, zoom: true, 
	autoOrbit: true, autoOrbitSpeed: 0.5,
	cameraDistance: 100, cameraPitch: 27, cameraYaw: 0
}

Animation

animated – (boolean) if true, the canvas will be updated at each frame (usually @60fps) and a time uniform variable will be available in shader. If false, the canvas will be repainted only when there is a window resize, thus reducing overhead.

playButtons – (boolean) if set to true and animated is true, some playback control buttons will be shown (play, stop, pause).

Editor

editorTheme – (string, “dark” or “bright”) sets the editor theme. The available options are “dark” and “bright”.

editorWrap – (boolean) if set to true enables text wrapping in the editor.

showTabs – (boolean) if set to false, the tabs will be removed and the editor will be unavailable.

{
	editorTheme: "bright", editorWrap: false, showTabs: true
}